HOW-TO:Write Python Scripts for XBMC

It has been suggested that this article or section be merged into HOW-TO build Python Scripts (|discuss). This article was originally a copy of a python HOW-TO tutorial was prepared by Nelson Minar. The article have since then been reformatted, restructured, modified and updated several times.

=XBMC Python Scripting Tutorial= Note that this article was written with ease of understanding in mind so experienced python developers may be irritated by how much this article been simplified and dumbed down, but this tutorial was not written for them.

Some basic rules - be careful of the snake!
Some features are added with time and so I really advice you to have the very latest version of XBMC or else some python scripts may not work.

The script launcher is based in the parameters settings of XBMC so go there to launch scripts. When you are launching a script the mention 'running' is added next to the script name. If it still running just click on it then it will stop. After the script is stopped, you can notice debug informations by pressing the white button of your pad. You may need internet access to run some scripts so configure XBMC correctly and do not forget to edit the name server (a.k.a. DNS) to resolve domain names.

Always notice the snake behavior
You must know Python coding is based on indentation. So no need of {} to declare the start and end of a function, class, if... Everything is an object. Very nice sometimes but tricky for beginners! A variable is local unless you declare it global. But this will be clearer in the tutorials. The goal of this document is not to teach Python so I just recommend you to read the documentation available on www.python.org

Navigation
This HOWTO assumes you are using an Xbox Controller. Other navigation method (i.e keyboard, Xbox DVD Remote, etc) information can be found in General Navigation

the real work begins
There are two specific libraries for Python only available in XBMC: xbmc and xbmcgui. They are dedicated to the user interface, and keypad management.

Python code will be colored in blue I will only talk about scripts including a graphical interface, as the console ones work without xbmc libraries.

Window
So the first thing to do is to import libraries

After that we create a class including some functions (defined by def)

So after that we initialize the class object and doModal allows to always display the graphical window until we exit it. The del is here to have a clean code and delete the class instance.

If you put all this code in a script (called display.py) you'll see an empty window but as there's no code to exit the Myclass class you'll have to reset the xbox. Also notice the print function only displays infos in debug mode (white button).

pad button
So now we need to implant a way to exit the class. So we will use the pad for that. Here is the full code:

Insert non-formatted text here

So now, each time we push the 'BACK' button, we will exit the class. As you can notice, indentation makes everything clear and it's easy to find where everything start or end. def defines a function but here we have a specific one related to XBMC as onAction defines keypad related actions. self.close will close the window and so the class.

add (and remove) text label
Now it's time to display some text on the window we created. For that we will use the ControlLabel function. ControlLabel has some properties including position, colour, transparency, font size. Here is a 'block' to enable text display on the window:

There's a reason to write 3 lines for strAction but we will see it later. So here : 300 is the X position 520 is the Y position 200,200 is supposed to be size of the element but it seems to not work with text 'font14' is the font, also 'font13' is available 0xFFFFFF00: so here it's the colour value and transparency coded in hexadecimal (from 00 to FF). so read this as 0xTTRRGGBB where T is the transparency value, R is red, G is green and as you guessed B is blue.

So now we add it to the previous code, and show it thanks to the A button of the pad (Use 'Enter' on keyboard)

Don't forget you have to push 'BACK' to stop the script ! (Use 'Esc' on keyboard)

You have to imagine the label as an element over the window and so we were able to add it but we can also remove it by using removeControl. We will use the B button to remove the label :

To add text there's also another feature called ControlFadeLabel which includes a reset function:

init parameters
When the class 'Myclass' is launched we can add elements that will run when the class is initialized. So here it's perfect to put some background image or some text that needs to be always on screen. So we add it in the init function:

We can also add a background image by including in the init function a ControlImage object:

Of course we display the image before the text :) When it's about path in directories, we always have to replace '\' by '\\' as '\' is reserved for special characters.

dialog box
What about a dialog box? So we will create function to add a message box :

And we will call it in another function using self.message

So now if you push 'A' a dialog will appear.

You can also use the message function in a more general way:

So now you know how to call a function inside another function :) Be careful to only send strings in the message function, as to add integers and strings don't work at the same time without conversion!

There's also the very common yes / no dialog box :

buttons
Time to see how buttons work! We have to use the function ControlButton. It takes 5 arguments. xbmcgui.ControlButton(350, 500, 80, 30, "HELLO") 350 is X postion, 500 is Y position, 80 the width, 30 is height and the last one is the text. First we have to create a button and to focus on it:

Then we have to define the action when the button is pushed:

We can also remove the button of the screen using :

As usual here is the code to see Python in action:

We can also add more buttons, but so we have to define in which order they have to react. controlDown, controlUp, controlLeft and controlRight are here to do that. First we hav to create buttons then we have to link the direction between them.

virtual keyboard
Some recent changes added the possibility to input text through a virtual keyboard.

Lists
Since early april, we can add lists to XBMC Python. No need to tell more, so here is an example :

Screen size
As XBMC can handle many different screen sizes, it's useful to get the values of the current one. So we wil see in action getHeight and getWidth

Skin dir and localization
These infos can be useful for international scripts. getLocalizedString was added on april, 6th 2004. It reads infos from the xml language file. And here is an opportunity to introduce a new way to call a function : mydisplay.localinfos The localinfos function is called so you may think only infos of it would be displayed... But as the class MyClass as an init function, all datas from the init call are displayed first.

Language, IP address, DVD state, available memory and CPU temperature functions
These are my first attempt to add functions to the XBMC Python library and i'm proud enough of the result.

How to add a child window?
It's always useful to add a child window when we don't have enough space on the main screen. So we will add another class that will be called when the button A is pressed.

Unrelated XBMC functions
Here is an example on how to download a file through http. Try and Except are methods to test if things can be done, read the Python documentation for more infos.

That is all, we hope this guide will help you to understand more on how Python scripting works in XBMC. Thanks you for reading, and please consider contributing to this article yourself.