As excited as I am about using and discovering Kivy, current circumstances require me to let go of it and focus on my studies instead. So it may not be a while before I can post new stuff on this site again.
If any one feels like posting here however, just let me know and I add you as editor on this blog.
Cheers.
Tuesday, July 26, 2011
Monday, May 30, 2011
Kivy Window Management on X11
In the previous post we observed the kivy.core.window.Window object and discovered Window management from the Kivy API was quite limited. Since I am working on Linux, and that Linux conventionally use X11 as their window manager, I thought I'd take a look at the Python-Xlib module and see if we could control our Basic Application's geometry. And the good news is: it worked out fine :)
I've not looked into all details; working with X is new for me and I'm not familiar with conventions. Nevertheless, by peeking at some example code here and there on the net, I managed to get hold of our window and change its size.
First, you'll need Python Xlib, which you can get with:
sudo apt-get install python-xlib
Then make a module, which we call kivyXwm.py (for Kivy X Window Manager):
#!/usr/bin/env python
from Xlib.display import Display
from Xlib import X
def resize(title=str, height=int, width=int):
TITLE = title
HEIGHT = height
WIDTH = width
display = Display()
root = display.screen().root
windowIDs = root.get_full_property(display.intern_atom('_NET_CLIENT_LIST'),
X.AnyPropertyType).value
for windowID in windowIDs:
window = display.create_resource_object('window', windowID)
title = window.get_wm_name()
pid = window.get_full_property(display.intern_atom('_NET_WM_PID'),
X.AnyPropertyType)
if TITLE in title:
window.configure(width = WIDTH, height = HEIGHT)
display.sync()
As I said, I am still a novice with X, but let me try to explain the big lines of the above code:
Line 9 & 10: we get the X display and the root window (which I understand is the main window, which is occupied by your desktop usually).
Line 11: get a list of all windows on the display. This list, however will only be known by their IDs, which is an int, so:
Line 12 to 16: we create an abstract object representing each window and find out if their title match our application's title.
Line 17 & 18: we change the height and width value of our window and we update the display.
Then we modify our Basic Application code like so:
#!/usr/bin/env python
import kivy
kivy.require('1.0.6')
from kivy.app import App
from kivy.uix.button import Button
from kivy.logger import Logger
import kivyXwm
class CoolApp(App):
icon = 'custom-kivy-icon.png'
title = 'Basic Application'
def build(self):
return Button(text='Hello World')
def on_start(self):
kivyXwm.resize(self.title, 100, 100)
Logger.info('App: I\'m alive!')
def on_stop(self):
Logger.critical('App: Aaaargh I\'m dying!')
if __name__ in ('__android__', '__main__'):
CoolApp().run()
Now in spite of the default size of your Kivy application (defined in the config file at ~/.kivy/config.ini), we set a new size for the application of 100x100. It's not a pretty thing to do, as you can see, although it's fast, it's a two-step procedure: first, Kivy makes a 600x800 window, then X changes its size to 100x100. Truly, it's a job for the GUI to set the Window size property. But this control through Xlib is good for other stuff, like setting the window "always on top" or "skip taskbar" parameters.
Xlib is able to pick up the application window from its title. I am still a bit confused here as to why title is a class attribute and not an instance attribute, but you have to pass self.title in the kivyXwm.resize() function. This may not be the best solution, I wonder what happens if we'd run two instances of the same application with the same title. Windows have their own IDs, but I'm not sure as to how to find the window we want from the list of windows X displays. I'll have to look for an alternative. The bad news is: Python Xlib is poorly documented, there is not even a docstring in the module :(
Xlib is able to pick up the application window from its title. I am still a bit confused here as to why title is a class attribute and not an instance attribute, but you have to pass self.title in the kivyXwm.resize() function. This may not be the best solution, I wonder what happens if we'd run two instances of the same application with the same title. Windows have their own IDs, but I'm not sure as to how to find the window we want from the list of windows X displays. I'll have to look for an alternative. The bad news is: Python Xlib is poorly documented, there is not even a docstring in the module :(
But that's one small victory, let's see what more can be done next time!
Saturday, May 28, 2011
The App() Class and its Window
The previous post looked into installing Kivy and running a simple button-application. This post will look closer at the App() class and its window to see what more can be done with them. NB: in this post and hereafter, all text between quotes "like this" will be drawn from the Kivy API Documentation. Usually I will link to the section it was quoted from." Also this post originally meant to look at the App() class and at the Button() widget class. After consideration I prefer to focus on the Window() class rather than Button().
Review the Basic Application's Code
First we are going to review the Basic Application's code:
import kivy
kivy.require('1.0.6')
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()Line 1: import Kivy (nothing too hard)
Line 2: specify the version of Kivy required for this program to function. "If a user attempts to run your application with a version of Kivy that is older than the version you specified, an Exception will be raised." You can find out the version you are currently using by merely importing Kivy from a Python Console, which will return an [INFO] log with the current version of Kivy, alternatively you can use kivy.__version__ .
Line 4 & 5: we import the bits and pieces we need. Although it's more work to do so, loading the entire library like from kivy import * "would have the disadvantage of cluttering your namespace and making the start of the application potentially much slower. It’s also not as clear what your application uses. The way we do it is faster and cleaner" (see documentation).
Line 7 & 12: the MyApp() class is derived from the App() class of the kivy.app repository. "The App() class is the base for creating Kivy applications. Think of it as your main entry point into the Kivy run loop. In most cases, you subclass this class and make your own app. You create an instance of your specific App() class and then, when you are ready to start the application’s life cycle, you call your instance’s App().run() method" as in line 12 here.
Line 8 & 9: the build() method "initializes the application [and] returns a widget [that] will be used as [root] and added to the window." This method needs not be called, the App().run() will do that for us. In this instance, the build() method returns a Button() widget with a "Hello World" text (label) displayed on it. We'll look at the button() class with more details in a moment, for now let's look at what other things the App() can do.
More on the App() Class
If we look at the documentation on the App() class, we'll find various methods and properties which we can use, some of these methods are automated, as of now I cannot imagine a situation when one would need to call these oneself. This is the case of the build()method, which, as we have seen, will run itself when calling App().run(). It is also the case of the load_kv() method which will be called as the application is launched with App().run(). The load_kv() method will load a .kv file, of which more later.
The App() class offers two attributes called icon and title. The first is a string referring to the relative path+name of the icon file which will be displayed in the task-bar or dock of your OS.
In our MyApp() class definition, which is derived from the bas App() class, we then can modify the default icon property. The default icon tends to render awfully in my dock (I use Cairo-Dock by the way, it's really cool), so I made my own Kivy icon with Inkscape. Now in our class definition we can add the following:
class MyApp(): icon = 'custom-kivy-icon.png'
While doing this I figured out from the log that Kivy does not support SVG format for the App.icon property, PNG worked fine.
Next we want to change the title property. I was wondering why my application was called "My" by default (look at the title bar when launching the application) and I soon figured out that Kivy is sensitive to the spelling of some of its objects and it naturally derived the application's title from the MyApp() class definition by removing the -App suffix. This makes more sense as one discovers that Kivy does a lot of the job for you, by associating the App() class with its .kv file for instance. Now if we change line 7 and 12 to CoolApp() and CoolApp().run() respectively, the title of our application will change to "Cool". That new title however, will be overridden by whatever string will be passed in the App.title so if we add title = 'Basic Application' to the line following our icon property and run the application again, the title should change accordingly.
Furthermore there is the on_start() and on_stop() methods which will be called when the application will be launched and halted, by the one_start and on_stop events respectively. So for instance we could use a simple print function to print something to the console as we launch the application. But Kivy developers wisely introduced a Logger to the library, which logs and prints all kind of information on the console, it's pretty cool for debugging and it's nice to simply know what's happening inside the box. The Logger not only prints to the console but also writes the stuff that goes through it to a log text file in your ~/.kivy folder so you can still access the log even if you closed the terminal. To add a log, we simply need to add a line where/when we need the message to be logged, check the documentation for proper syntax.
Now we've omitted the App().stop() method, but we'll see that one in the next section, together with the Button widget.
The code, now updated should look like this:
Furthermore there is the on_start() and on_stop() methods which will be called when the application will be launched and halted, by the one_start and on_stop events respectively. So for instance we could use a simple print function to print something to the console as we launch the application. But Kivy developers wisely introduced a Logger to the library, which logs and prints all kind of information on the console, it's pretty cool for debugging and it's nice to simply know what's happening inside the box. The Logger not only prints to the console but also writes the stuff that goes through it to a log text file in your ~/.kivy folder so you can still access the log even if you closed the terminal. To add a log, we simply need to add a line where/when we need the message to be logged, check the documentation for proper syntax.
Now we've omitted the App().stop() method, but we'll see that one in the next section, together with the Button widget.
The code, now updated should look like this:
#!/usr/lib/python
import kivy
kivy.require('1.0.6')
from kivy.app import App
from kivy.uix.button import Button
from kivy.logger import Logger
class CoolApp(App):
icon = 'custom-kivy-icon.png'
title = 'Basic Application'
def build(self):
return Button(text='Hello World')
def on_start(self):
Logger.info('App: I\'m alive!')
def on_stop(self):
Logger.critical('App: Aaaargh I\'m dying!')
if __name__ in ('__android__', '__main__'):
CoolApp().run()The Application's Window
At this point I originally thought I'd focus on the Button() widget class and see what could be done with it. But I got confused by the fact that the Button() is the root object returned by App().build() in the example here above. For instance I found that 600x800 px was quite a size for a single button, so I thought I could resize it with Button().size = int, but that didn't work, because the root object returned by the build() method will take on the entire window's space.
But where is this window then in our code? Well, it seems that Kivy does make the work easy for us, in comparison to some other GUI libraries to which every single action must be instructed by the developer.
Let's try a small experiment: if you import time and add time.sleep(2) in your on_start() callback, then run your application, you will see that the application's black window appears first and then the button is drawn onto it. Now we have seen this window on the screen, let's find it in the code.
If we look at the run() method in the app.py code, we see that the method will first get the widget tree and then append it to a Window() instance imported from kivy.core.window. In the documentation, you will find more about this Window() class, and I wanted to look at it closer before I turn to the content of my application. Let's parse it together.
If we look at the run() method in the app.py code, we see that the method will first get the widget tree and then append it to a Window() instance imported from kivy.core.window. In the documentation, you will find more about this Window() class, and I wanted to look at it closer before I turn to the content of my application. Let's parse it together.
Right at the outset of the documentation we are warned: "Kivy support only one window creation. Don’t try to create more than one". To me this begs the question: what if I want my application to have more than one window? I'm thinking of an application like the Gimp for instance, which has its Toolbox in a separate window from that of the drawing. I haven't tried yet, but I guess that one would need to create two instances of the App() class.
I was concerned about the size of my application, and we find the parameters listed in the documentation fullscreen, height and width, but using them in our App() class won't work because the App().run() method doesn't let us pass size parameters. There are then three ways to customise the Window() size of our application:
- change the configuration file's height and width values (or fullscreen values)
- change the same configuration file from code
- launch our application with a --size=WxH tag where W and H are width and height in pixels.
Of the three options I concluded the third was the best. Why? Because the configuration file, which is placed at ~/.kivy/config.ini is shared by all Kivy applications, and the parameters generated by our application would affect that of another application. I am not sure of what the practical use of these parameters are to be honest. The third option, on the contrary, is friendlier because it is passed along as a parameter for our Window() object to feed on. This means we should launch our application using the Terminal:
$ python ./main.py --size=100x50
Now if we want some form of control on the size of our application, we'll have to launch our Kivy GUI from code like this:
import subprocess subprocess.Popen(['pathtogui', 'main.py', '--size=100x50'], shell=True)
... which is not very handy and being able to pass the window geometry directly into the App() for instance or set its size as a property. However, I haven't found parameters to allow or prevent resizing of the window or set the minimum or maximum window size parameters. There may be a way though, since the Window() class of Kivy is derived from PyGame's. I'll look into that.
Positioning the window on the screen is possible through the configuration file only: set the position parameter to custom and the top and / or left values to the coordinate in pixels where you want the top-left corner of the window to be. Again, be careful while using the configuration file since it is shared by all Kivy applications.
To prevent window decoration from within Kivy's API, is possible through the configuration file and flags. Flags again are preferable since they affect the application's instance only. To prevent decoration can set the flag -k (i.e. 'fake fullscreen'). When the window is undecorated, it cannot me moved or resized with the mouse.
To prevent window decoration from within Kivy's API, is possible through the configuration file and flags. Flags again are preferable since they affect the application's instance only. To prevent decoration can set the flag -k (i.e. 'fake fullscreen'). When the window is undecorated, it cannot me moved or resized with the mouse.
The window background can be changed with the Window().clearcolor property to which colour information should be passed in a tuple containing (r, g, b, a) information. Although I managed to change the background colour of the window, setting alpha to 0 did not make the window transparent as I had expected.
Although I am quite enthusiast about Kivy, I feel quite disappointed by its window management at API level. This is because Kivy was developed for touch-phones in first instance, from what I understood. From the point of view of desktop GUI development however, I want to be able to place my window where I want, with the default, min and max size I want and I want it to be able to talk to the Window Manager (skip the window manager, provide window hints (to tell if the window is a dock or pop-up or splash screen), stay on top or below, sticky, reserved space etc.)
I am looking forward to make a dock/panel-like application, for which such features are indispensable. Perhaps there are work-arounds for that, and Kivy may still offer such features in the future, and I've already been told these features should be considered for further development :)
Basic Application
Alright, there's one thing you need to know about me: I'm quite stupid :) So I will start from the start and play around with Kivy using basics and build up on that. NB: this post may be a bit redundant, Kivy offers a Quickstart already, from which I draw most of the content of this post.
First you'll have to install the Kivy library, there is an installation guide for Ubuntu as well (that's what I use). I've had some problems with the graphic library, preventing some examples included in the library to function. This is due to a bug, but luckily there is a patch to solve the issue for now. The patch's installation is quite long, but it's worth it :)
Then we're ready to start coding. Kivy's Quickstart offers a simple example to run:
Now you should not have problem running this on your system. You could do that from your terminal by running $ python ./main.py in the folder where you saved your Python file. Personally, I use Geany for coding, so I can run it from there. and you should see something like this on your screen:
The window is a black canvas with a large grey button (with rounded corners). The window decoration is not part of the coding and is taken care of by your Window Manager. There may be a way to prevent this decoration by changing a property of the Kivy application, I am not sure of that just yet, but it could also be done by addressing the WM directly (by setting window decoration rules in Compiz for instance).
You can hover and click the button like this:
Now don't forget Kivy is made to function on touch-screen technology, there are three touch events: Down, Move, Up. From what I understand, touch events are passed in a top-down fashion, i.e. from the top-level parent widget, to the children. When the touch-event matches a listener of any of the widgets standing in the way of that event, they will launch their respective callbacks. Events are better explained in the documentation. Down and Up touch-events each match two default event listeners of the Button widget, namely on_press() and on_release(). The default callbacks of the Button widget affect its appearance: the background changes from grey to blue.
If your application does not shut down, you may be affected by the bug mentioned above. Next post will pick up from here and try to tweak this basic application and see what more can be done with App() and Button().
If your application does not shut down, you may be affected by the bug mentioned above. Next post will pick up from here and try to tweak this basic application and see what more can be done with App() and Button().
Subscribe to:
Posts (Atom)