Kivy 中文文档指引

标签： Python Kivy Android

[TOC]

官网链接

基于版本 Release 1.0.8-dev

前言

由于个人的原因需要使用到Kivy框架，所以本着学习的态度尝试去翻译Kivy开发文档。第一次翻译英文开发指南类型的文档，翻译内容尽可能做到和原作者表达的内容一致，由于中文和英文某些词汇、语句表达会不同，目前暂时还没做更细致的修正处理。同时翻译如果有错误，请欢迎交流和指正，可以联系zhu603809832@163.com。

第一部分 用户指引

这部分的内容主要是解释Kivy背后设计的基本理念和解释为什么你想要使用Kivy这套框架。然后继续讨论相关的体系结构并展示如何使用这套框架在短时间内创建出出色的应用程序。

第一章 编程理念

如果你想了解Kivy是关于什么内容和它由什么构成的，以下的内容将逐步为你展开

1.1 为什么使用Kivy

为什么使用Kivy呢？毕竟现在有很多现有的免费工具集（框架或者平台等）可以使用。例如Qt和Flash，这两个解决方案现在是被广泛作为应用开发的选择。这些众多的解决方案已经支持了多点触控。那到底是什么造就了Kivy呢？

1.1.1 新颖

Kivy是为了今天和明天而诞生的。日新月异的人机交互方式正在不断的发展。对于多点触控，开发工具对其的支持变得尤为重要。特意为了这种新的交互方式，我们从底层开始重新架构Kivy。相对于以往看起来“建立良好”但带着沉重历史负担的旧开发工具，这样意味着我们能够在人机交互方面能够考虑更加的全面。我们并不打算让计算机处于现有模型的束缚（比如单指针鼠标鼠标交互）。相反，我们想让你探索其中的可能性，这才是Kivy与众不同之处。

1.1.2 高效

Kivy 是高效的。这适用于应用程序的开发速度，也适用于应用程序的执行速度。我们已经使用很多方法去优化Kivy。例如通过充分利用现有编译器的能力，在C语言层级上实现对执行时间非常敏感的功能。更重要的是，我们采用了更加明智的算法去尽可能降低开销。在某些任务和算法的地方，我们也使用GPU，今天的图形显卡的计算能力已经远远超过今天的CPU，这就是为什么我们试图让GPU尽可能的工作，从而大大提高性能。

1.1.3 敏捷灵活

Kivy是灵活的。这样意味着它可以在各种不同的设备上运行，包括Android支持的智能手机或者平板电脑。我们已经支持了主流的操作系统（Window，Linux,OSX）。“敏捷”也说明Kivy的快节奏发展使它能够很快适应新技术。不止一次，我们添加了对新外部设备和软件协议的支持。有时候甚至这些设备还没有正式发布的。Kivy还可以与大量不同的第三方解决方案结合使用。例如在Window系统上，我们支持WM_TOUCH多点触摸，这样意味着任何具有window 7 笔和触摸驱动程序的设备都可以与Kivy一起工作。在苹果OSX系统上，你可以使用苹果的多点触摸设备，比如触控板和鼠标。在Linux系统上，可以使用HID内核输入事件。除此以外，我们还支持了TUIO和一些其他的输入源。

1.1.4 专注

Kivy是专注的。你可以通过几行代码就能实现一个简单的应用程序。Kivy框架使用的是Python语言，而Python是一门通用性强，功能强大，易于使用的编程语言。另外，我们创建了一种新的描述语言——Kivy语言。它用于定义复杂的用户界面。这门语言可以让你快速设置，连接，排列你应用程序的每个元素。我们认为让你专心于应用程序本质功能的实现更甚于聚焦其他繁琐沉重的事情。

1.1.5 资金支持

Kivy是由专业的人员踊跃参与开发的。它是由一个社区和商业支持开发的解决方案，是有资金支持的。我们一些核心人员以开发Kivy作为生计的。Kivy可以说，它不是由一个业余的人员开发的小型实验性项目，它可是认真的。

1.1.6 免费

Kivy可以免费使用。你不必为此付出代价。如果你卖一个使用Kiy框架的应用程序赚钱，你也不必要付出一毛钱。

第二章 安装

我们尽可能不去重复造轮子，而是推出创新的内容。因此，我们将重点是放在了我们自己的代码上，并在可能得情况下使用其他已有第三方高质量的库去搭建Kivy。鉴于Kivy提供了一些丰富特性，我们还是需要一些其他的依赖库。如果你不需要使用某些特定的功能（例如视频播放），是不需要某些依赖。然而Kivy确实需要一种依赖，它就是<font color=#FF0000>Cython</font>。

另外，你需要的是<font color=#FF0000>Python</font> 2.x (不是3.x) 版本的解释器。如果你想启用（例如打开一个Window窗口），音频/视频播放或者拼写矫正等特性，则必须要有额外的依赖。对于这些需求，我们分别推荐使用PyGame，Gst-Python和Enchant。
其他可选的库（可以互换）有：

• OpenCV2.0 ——摄像机输入
• PIL —— 图像和文本显示
• Pycairo —— 文本显示
• PyEnchant —— 拼写校正
• PyGame —— Window创建，图像和文本显示，音频播放(译者：我觉得这是Python为数不多的游戏引擎)
• PyGST —— 音频/视频播放和摄像机输入

不要惊慌！我们不要求你自己安装所有这些东西。相反，我们创建了良好的可移植包，你可以直接使用它们，因为它们已经包含平台所需的包。我们只想让你知道默认的替代方案，并给你一个关于Kiy在内部使用的东西的概述。

2.1 稳定版本

最近稳定的版本可以从Kivy官方网站 http://kivy.org/#downloads 进行获取。请按照安装步骤在你所需要的平台上进行安装。

2.1.1 在Window平台进行安装

对于Windows，我们提供了我们称之为“压缩包”的内容。你不必安装任何额外的东西，只是解压和运行：

1. 从http://kvy.org/y下载下载最新版本
2. 解压缩包
3. 然后，在解压缩包中，有一个名为KIVY.BAT的脚本，使用它来启动任何KiVy应用程序，下文会有所描述

启动一个Kivy应用程序

Send-To的方法
你可以通过使用Send-To菜单去执行一个.py文件

1. 创建 一个 kivy.bat的快捷方式
2. 打开Explorer资源浏览器，切换到Shell:SendTo的位置
3. 将Kivy.bat快捷方式移动到该目录
4. （可选）将其重名为Kivy <Kivy-版本号>

然后你可以执行程序通过以下步骤：

1. 鼠标右键.py文件
2. 选择Send-to Kivy

双击启动的方法
为了双击启动Kivy应用程序，一开始需要做一些操作步骤:

1. 右键你想要启动的主要py文件
2. 从出现的菜单中，选择 “打开方式”
3. 浏览目录，选择kivy.bat文件所在的位置，并选择它
4. 勾选始终总是以该打开方式打开py文件（如果你不想每次双击py文件重复总要使用该步骤）
5. 完成，打开py文件

下次你双击py文件的时候，就会以Kivy对应的python版本去启动py文件。

注意：在Window平台，我们必须关联好Phton版本，因为默认情况下它不安装在Window上（不像Mac或者Linux系统）。通过上面的步骤，你可以给Kivy设置好Python的版本。通常情况，这不是太困难的一件事情。因为它只是Python的正常版本，在模块搜索路径中添加了必要的第三方库。如果您遇到意外问题，请与我们联系。

命令行启动的方法
如果你想使用最近稳定的kivy版本去做开发，我们提供了另外一个替代方法——命令行。你需要一个小型的GNU 系统替代你现有的系统。使用msysGit

当你安装msysGit的时候，你需要注意下内容：

• 不要替代Window自带的Shell命令行窗口
• Check Out代码和提交代码，不要使用CLRF对代码文件行末进行替换。

安装完毕以后，就会在你桌面出现"Git Bash"图标。这既是我们所需要的命令行工具：

1. 启动“Git Bash”
2. cd <kivy解压缩包所在路径>
3. source kivyenv.sh <kivy解压缩包绝对路径>

现在你可以通过命令行 启动 kivy程序：

python <filename.py>

同时，其他脚本或者二进制程序也可以使用了

• cython
• gcc /make ...
• easy_install
• gst-inspect-0.10

最近的Window压缩包包含以下内容：

• 最新稳定版的Kivy
• Python 2.7.1
• Glew 1.5.7
• Pygame 1.9.2
• Cython 0.14
• MingW
• Gstreamer
• SetupTools

2.1.2 在MacOS X平台进行安装

注意：这个方法目前仅仅是在Mac OSX 10.6 Snow Leopard 64-bit上进行过测试。对于更早的版本10.6或者10.6 32位，你需要自己安装一些组件。我们推荐你使用homebrew工具去做这个事情。

对于Mac OS X10.6之后的版本，我们提供了一个已经包含依赖包的Kivy.app。你可以从我们Google代码项目下载。它是一个.dmg文件，包含以下内容：

• Kivy.app
• Readme.txt
• 案例文件夹
• 在shell中使用，安装kivy命令的脚本

安装Kivy，你必须：

1. 从http://kivy.org/#downloads下载最近的版本
2. 双击打开
3. 拖拽Kivy.app文件到你应用程序文件夹
4. 阅读Readme.txt里面的内容

启动任意的kivy应用程序
你可以通过拖拽应用程序的主文件main.py到Kivy.app图标去启动Kivy应用程序，你可以尝试对案例文件夹里面的内容进行这样的操作。

从命令行启动
如果你想从命令行启动Kivy程序，在你拖拽Kivy.app到应用程序文件夹以后，只需要双击 Make Symlinks脚本。可以通过以下测试，查看是否生效：

1. 打开Open Terminal.app 运行 Kivy。你应该可以看到Python提示。
2. 然后Import kivy. 如果接着没有错误提示，那就表明已经成功
3. 执行 kivy youapplication.py

2.1.3 在Ubuntu进行安装

下面的说明是针对Ubuntu的，但是对于其他Linux发行版（例如，Debian、opensuse、fedora等），它们应该以类似的方式工作。显然，你也需要调整命令。

Ubuntu 10.10 (Maverick)
非常遗憾的是，目前没有kivy包在Ubuntu的仓库里面。我们正在努力改变，暂时你可以用以下的方法解决

$ sudo apt-get install python-setuptools python-pygame python-opengl \ python-gst0.10 python-enchant gstreamer0.10-plugins-good cython python-dev \ build-essential libgl1-mesa-dev libgles2-mesa-dev 
$ sudo easy_install kivy

如果你之前已经安装kivy了，你可以通过以下的方法进行升级

$ sudo easy_install --upgrade kivy

从命令行进行启动
我们正在酝酿一些演示案例。这些案例是打包在压缩包里面的。首先你也要了解easy_install 已经在你当前的Kivy包里面已经安装了。接着运行以下指令

$ python -c "import pkg_resources; print pkg_resources.resource_filename(’kivy’, ’../share/kivy-examples’)"

你应该有一个类似的这样的路径： /usr/local/lib/python2.6/dist-packages/Kivy-1.0.4_beta-py2.6-linux-x86_64.egg/share/kivy-examples/

切换到案例所在的文件夹，按照以下步骤进行操作：

# launch touchtracer 
$ cd <path to kivy-examples> 
$ cd demo/touchtracer 
$ python main.py
# launch pictures 
$ cd <path to kivy-examples>
$ cd demo/pictures 
$ python main.py

如果你不太了解Unix系统和符号链接相关内容，为了方便访问，你可以在你的home主目录创建一个链接。例如：

1. 从上面的命令行中获取案例的路径
2. 粘贴到你的控制台

$ ln -s <path to kivy-examples> ~/

3. 然后你可以在你的home主目录访问kivy案例了

$ cd ~/kivy-examples

2.1.4 在安卓中进行安装

注意：目前为止，安卓版本还没有被完全支持。关于相关的信息可以查看Kivy on Android相关内容

请注意，Kivy是一个框架，在手机上安装Kivy本身是还无用处的，Kivy不是一个应用程序。
也就是说，我们提供了一个“执行器”，允许你把你的Kivy应用程序推到你的手机上。
通过一个简单的接口执行它。未来我们将单独提供打包您KiVy应用程序的指引。

安装Kivy的执行器Launcher，你按照以下的步骤：

1. 在安卓市场中查找Kivy Launcher
2. 点击“安装”
3. 选择你手机的型号，接着完成
   现在你可以把Kivy的应用程序放置到SD卡上Kivy所在的目录位置。更多内容会在Kivy on Android更多说明。

安装样例：

警告：这些案例并不是最终办法，它们仅仅是用作Kivy在安卓环境中的测试案例

1. 下载Kivy Test For Android
2. 解压内容到你的SD卡上到目录/sdcard/kivy
3. 运行执行器launcher，选择对应的kivy测试案例

2.2 开发版本

开发版本是针对开发人员和测试人员的。注意，当运行开发版本时，
你自己冒着一些风险在运行潜在的有问题的代码。要使用开发版本，您将首先需要安装依赖项。然后你必须在电脑上设置Kivy便于开发。为此，请阅读Contributing相关内容。

2.2.1 安装依赖

要安装Kivy的依赖项，请按照下面的指南为您的平台进行相关的操作。

Ubuntu
对于Ubuntu，只需输入以下命令即可安装所有必要的包：

$ sudo apt-get install python-setuptools python-pygame python-opengl \
python-gst0.10 python-enchant gstreamer0.10-plugins-good cython python-dev \
build-essential libgl1-mesa-dev libgles2-mesa-dev

2.2.2 安装Kivy用于开发

现在您已经安装了所有所需的依赖项，现在是下载和编译Kivy的开发版本的时候了：

$ # Download Kivy from GitHub
$ git clone git://github.com/tito/kivy.git
$ cd kivy
$ # Compile:
$ python setup.py build_ext --inplace -f

如果你有make命令可用，你也可以使用下面的快捷方式编译（与上面最后命令相同）：

$ make

如果要修改KiVy代码本身，请将Python PATH环境变量设置为指向在你的复制出来的备份。这样你就不必在每一个微小修改之后安装（setup.py安装）。Python会把Kivy从你的备份中导入。

或者，如果您不想对KiVy本身做任何更改，您也可以运行（用管理员权限执行，例如SUDO）：

$ python setup.py install

如果你想为KiVy代码库贡献代码（补丁，新的特性），请阅读Contributing相关内容。

第三章 编程指南

3.1 快速开始

这个章节解释了如何创建一个简单的Kiy“Hello World”程序。假设你已经
安装了KiVy。如果不这样，就转到安装章节。我们这次使用的是Python 2.x 的版本。

3.1.1 创建应用程序

import kivy
kivy.require(’1.0.6’) # replace with your current kivy version !

from kivy.app import App
from kivy.uix.button import Button

class MyApp(App):
    def build(self):
        return Button(text=’Hello World’)
        
if __name__ in (’__android__’, ’__main__’):
    MyApp().run()

保存为文件名main.py。
若要运行应用程序，请按照相关操作系统的说明进行操作：
Linux系统

$ python main.py

Windows系统

$ python main.py
# or
C:\appdir>kivy.bat main.py

Mac OS X系统

$ kivy main.py

安卓系统
Android应用程序需要一些补充文件才能在Android上运行。
一个窗口应该打开，显示一个唯一的按钮（标签“helloWorld”）覆盖整个窗口面积。这就是它所有内容。

QQ图片20181026132053.png

那这些代码到底实现了什么功能呢?

1. 首先，我们导入Kivy，并检查当前安装的版本是否足以满足我们的应用程序。
   如果没有，将自动启动异常，并防止应用程序在运行时崩溃。
   您可以阅读kivy.require()函数的文档以获取更多信息。
2. 我们导入App类，以便能够对它进行派生。通过对这个类进行子类继承，增加了一些新的特性，以便能够被Kivy框架进行处理
3. 接下来，我们导入Button类，以便能够创建带有自定义标签的按钮实例。
4. 然后，我们基于App类创建我们的应用程序类。我们实现了build()函数
   能够返回按钮的实例。此实例将用作控件树的根对象（因为我们返回这个对象）。
5. 最后，我们在应用程序实例中调用Run() 去启动Kiy进程，这时候我们的应用程序实例已经包含在里面。

3.2 怎么阅读文档

文档是分为两部分：

• 编程指南：这是一个必读关于Kivy基础内容，特别是如果你从来没有以前做过GUI编程。
• API：解释所有的函数、类、方法

3.2.1 导入一个类

API部分是从源代码自动生成的。如果你使用任何类，它会像这样生成：

QQ图片20181026151035.png

Button类 在“Kiyy.uix.button”模块中。所以如果你想在代码中导入该类，可以这样

from kivy.uix.button import Button

3.3 配置环境

许多环境变量可用于控制KiVy的初始化和行为。例如，用于设置Cairo为文本渲染方式，通过以下实现：

$ KIVY_TEXT=cairo python main.py

环境变量可以在导入Kivy之前进行设置

import os
os.environ[’KIVY_TEXT’] = ’cairo’
import kivy

3.3.1 配置

KIVY_USE_DEFAULTCONFIG 如果在Envion中找到此名称，Kivy将不会读取用户配置文件。

3.3.2 路径配置

这是1.0.7的新特性。你可以控制扩展或者模块的默认位置，以及kivy数据存储位置。

• KIVY_DATA_DIR Kivy的数据位置，默认是<kivy path>/data
• KIVY_EXTS_DIR Kivy扩展的位置，默认是<kivy path>/extensions
• KIVY_MODULES_DIR Kivy的模块位置，默认是<kivy path>/modules

3.3.3 控制内核的实现

kivy.core 尝试为你的平台选择最合适的实现。对于测试或者自定义安装，你可能想设置选择器为指定的实现。

• KIVY_WINDOW 用于创建窗口的实现，值：pygame
• KIVY_TEXT 用于渲染文本的实现，值：pil，cairo，pygame
• KIVY_VIDEO 用于渲染视频的实现，值：gstreamer，pyglet
• KIVY_AUDIO 用于播放音频的实现，值：gstreamer，pygame
• KIVY_IMAGE 用于渲染图片的实现，值：pil，pygame
• KIVY_CAMERA 用于获取摄像机的实现，值：gstreamer，opencv，videocapture
• KIVY_SPELLING 用于拼写的实现，值：enchant，osxappkit
• KIVY_CLIPBOARD 用于剪贴板的实现，值：pygame，dummy

3.4 架构预览

我们想花费一些时间去阐述是如何从软件工程的角度设计Kivy的。这是理解所有内容协同工作的关键。如果只是查看代码，只会理解一个非常粗略的看法。但是因为这个方法对大多数用户来说都是令人畏惧的。
第二节详细说明了实现的基本思路。您可以跳过本节并迟些再参考。但我们建议至少略读一下粗略的概述。
KiVy由几个我们将在下面解释的构造所组成的。