From 4493fcfa9e355cf4c3f811e3f774f773bdd6034b Mon Sep 17 00:00:00 2001 From: Christopher Denter Date: Thu, 27 Jan 2011 23:41:27 +0100 Subject: [PATCH] explain building blocks in architecture overview. needs review --- doc/sources/architecture.rst | 88 ++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/doc/sources/architecture.rst b/doc/sources/architecture.rst index 9eb17dbfd..e8961de62 100644 --- a/doc/sources/architecture.rst +++ b/doc/sources/architecture.rst @@ -8,6 +8,9 @@ If you just look at the code, chances are you will get a rough idea already, but since this approach certainly is daunting for most users, this section explains the basic ideas of the implementation in more detail. +Kivy consists of several building blocks that we will explain in the +following. + Core Providers and Input Providers ---------------------------------- @@ -38,6 +41,91 @@ class that reads your input data from your device and transforms them into Kivy basic events. +Graphics +-------- + +Kivy's graphics API is our abstraction of OpenGL. On the lowest level, +Kivy issues hardware-accelerated drawing commands using OpenGL. Writing +OpenGL code however can be a bit confusing, especially to newcomers. +That's why we provide the graphics API that lets you draw things using +simple metaphors that do not exist as such in OpenGL (e.g. Canvas, +Rectangle, etc.). + +All of our widgets themselves use this graphics API, which is implemented +on the C level for performance reasons. + +Another advantage of the graphics API is its ability to automatically +optimize the drawing commands that your code issues. This is especially +helpful if you're not an expert at tuning OpenGL. This makes your drawing +code more efficient in many cases. + +You can, of course, still use raw OpenGL commands if you prefer that. The +version we target is OpenGL 2.0 ES (GLES2) on all devices, so if you want to +stay cross-platform compatible, we advise you to only use the GLES2 functions. + + +Core +---- + +The code in the core package provides commonly used features, such as: + + Clock + You can use the clock to schedule timer events. Both one-shot timers + and periodic timers are supported + + Cache + If you need to cache something that you use often, you can use our + class for that instead of writing your own. + + Gesture Detection + We ship a simple gesture recognizer that you can use to detect + various kinds of strokes, such as circles or rectangles. You can + train it to detect your own strokes. + + Kivy Language + The kivy language is used to easily and efficiently describe user + interfaces. + + Properties + These are not the normal properties that you may know from python. + It is our own properties class that links your widget code with + the user interface description. + + +UIX (Widgets & Layouts) +----------------------- + +The UIX module contains commonly used widgets and layouts that you can +reuse to quickly create a user interface. + + Widgets + Widgets are user interface elements that you add to your program + to provide some kind of functionality. They may or may not be + visible. Examples would be a file browser, buttons, sliders, lists + and so on. Widgets receive MotionEvents. + + Layouts + You use layouts to arrange widgets. It is of course possible to + calculate your widgets' positions yourself, but often it is more + convenient to use one of our ready made layouts. Examples would be + Grid Layouts or Box Layouts. + You can also nest layouts. + + +Modules +------- + +If you've ever used a modern web browser and customized it with some +add-ons then you already know the basic idea behind our module classes. +Modules can be used to inject functionality into Kivy programs, even if +the original author did not include it. + +An example would be a module that always shows the FPS of the current +application and some graph depicting the FPS over time. + +You can also write your own modules. + + Input Events (Touches) ----------------------