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）?！懊艚荨币舱f明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，我們提供了我們稱之為“壓縮包”的內容。你不必安裝任何額外的東西，只是解壓和運行：
- 從http://kvy.org/y下載下載最新版本
- 解壓縮包
- 然后，在解壓縮包中，有一個名為KIVY.BAT的腳本，使用它來啟動任何KiVy應用程序，下文會有所描述
啟動一個Kivy應用程序
Send-To的方法
你可以通過使用Send-To菜單去執行一個.py文件
- 創建 一個 kivy.bat的快捷方式
- 打開Explorer資源瀏覽器，切換到Shell:SendTo的位置
- 將Kivy.bat快捷方式移動到該目錄
- （可選）將其重名為Kivy <Kivy-版本號>
然后你可以執行程序通過以下步驟：
- 鼠標右鍵.py文件
- 選擇Send-to Kivy
雙擊啟動的方法
為了雙擊啟動Kivy應用程序，一開始需要做一些操作步驟:
- 右鍵你想要啟動的主要py文件
- 從出現的菜單中，選擇 “打開方式”
- 瀏覽目錄，選擇kivy.bat文件所在的位置，并選擇它
- 勾選始終總是以該打開方式打開py文件（如果你不想每次雙擊py文件重復總要使用該步驟）
- 完成，打開py文件
下次你雙擊py文件的時候，就會以Kivy對應的python版本去啟動py文件。
注意：在Window平臺，我們必須關聯好Phton版本，因為默認情況下它不安裝在Window上（不像Mac或者Linux系統）。通過上面的步驟，你可以給Kivy設置好Python的版本。通常情況，這不是太困難的一件事情。因為它只是Python的正常版本，在模塊搜索路徑中添加了必要的第三方庫。如果您遇到意外問題，請與我們聯系。
命令行啟動的方法
如果你想使用最近穩定的kivy版本去做開發，我們提供了另外一個替代方法——命令行。你需要一個小型的GNU 系統替代你現有的系統。使用msysGit
當你安裝msysGit的時候，你需要注意下內容：
- 不要替代Window自帶的Shell命令行窗口
- Check Out代碼和提交代碼，不要使用CLRF對代碼文件行末進行替換。
安裝完畢以后，就會在你桌面出現"Git Bash"圖標。這既是我們所需要的命令行工具：
- 啟動“Git Bash”
- cd <kivy解壓縮包所在路徑>
- 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，你必須：
- 從http://kivy.org/#downloads下載最近的版本
- 雙擊打開
- 拖拽Kivy.app文件到你應用程序文件夾
- 閱讀Readme.txt里面的內容
啟動任意的kivy應用程序
你可以通過拖拽應用程序的主文件main.py到Kivy.app圖標去啟動Kivy應用程序，你可以嘗試對案例文件夾里面的內容進行這樣的操作。
從命令行啟動
如果你想從命令行啟動Kivy程序，在你拖拽Kivy.app到應用程序文件夾以后，只需要雙擊 Make Symlinks腳本?？梢酝ㄟ^以下測試，查看是否生效：
- 打開Open Terminal.app 運行 Kivy。你應該可以看到Python提示。
- 然后
Import kivy. 如果接著沒有錯誤提示，那就表明已經成功 - 執行
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主目錄創建一個鏈接。例如：
- 從上面的命令行中獲取案例的路徑
- 粘貼到你的控制臺
$ ln -s <path to kivy-examples> ~/
- 然后你可以在你的home主目錄訪問kivy案例了
$ cd ~/kivy-examples
2.1.4 在安卓中進行安裝
注意：目前為止，安卓版本還沒有被完全支持。關于相關的信息可以查看Kivy on Android相關內容
請注意，Kivy是一個框架，在手機上安裝Kivy本身是還無用處的，Kivy不是一個應用程序。
也就是說，我們提供了一個“執行器”，允許你把你的Kivy應用程序推到你的手機上。
通過一個簡單的接口執行它。未來我們將單獨提供打包您KiVy應用程序的指引。
安裝Kivy的執行器Launcher，你按照以下的步驟：
- 在安卓市場中查找Kivy Launcher
- 點擊“安裝”
- 選擇你手機的型號，接著完成
現在你可以把Kivy的應用程序放置到SD卡上Kivy所在的目錄位置。更多內容會在Kivy on Android更多說明。
安裝樣例：
警告：這些案例并不是最終辦法，它們僅僅是用作Kivy在安卓環境中的測試案例
- 下載Kivy Test For Android
- 解壓內容到你的SD卡上到目錄/sdcard/kivy
- 運行執行器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”）覆蓋整個窗口面積。這就是它所有內容。
那這些代碼到底實現了什么功能呢?
- 首先，我們導入Kivy，并檢查當前安裝的版本是否足以滿足我們的應用程序。
如果沒有，將自動啟動異常，并防止應用程序在運行時崩潰。
您可以閱讀kivy.require()函數的文檔以獲取更多信息。 - 我們導入App類，以便能夠對它進行派生。通過對這個類進行子類繼承，增加了一些新的特性，以便能夠被Kivy框架進行處理
- 接下來，我們導入Button類，以便能夠創建帶有自定義標簽的按鈕實例。
- 然后，我們基于App類創建我們的應用程序類。我們實現了build()函數
能夠返回按鈕的實例。此實例將用作控件樹的根對象（因為我們返回這個對象）。 - 最后，我們在應用程序實例中調用Run() 去啟動Kiy進程，這時候我們的應用程序實例已經包含在里面。
3.2 怎么閱讀文檔
文檔是分為兩部分：
- 編程指南：這是一個必讀關于Kivy基礎內容，特別是如果你從來沒有以前做過GUI編程。
- API：解釋所有的函數、類、方法
3.2.1 導入一個類
API部分是從源代碼自動生成的。如果你使用任何類，它會像這樣生成：
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由幾個我們將在下面解釋的構造所組成的。
