Built-in scripting

From Official Kodi Wiki
Jump to navigation Jump to search
Home icon grey.png   ▶ Python development
▶ Add-on development
▶ Skinning
▶ Built-in scripting

Kodi contains several built-in functions that can be accessed from the skin (via a button), from within a python script, or keymap.

General form of built-in Functions

Built-in functions take the form Function(param1,param2,...).

TSome parameters may be required, depending on the function. In parsing built-in functions, Kodi first treats quoted (using double quotes ") character strings as literal, and drops the quotes. Thus, when inside a quote, any otherwise special characters will be ignored until the quote is complete. Parameters are separated by commas and, given that functions may be parameters to other functions (such as with the AlarmClock function), anything within brackets () are treated as a single block as well. Finally, prior to passing parameters into the function, any initial and trailing spaces are removed. This system allows you to pass in functions as parameters (the commas used for the passed function are ignored as they're within a () block), as well as allowing you to ignore whitespace around parameter separators. If you wish to pass commas in directly as part of a parameter, simply put quotes around the parameter string - Kodi will strip off the quotes prior to passing it in. Lastly, to pass in an actual quote character, make sure it's escaped (using the \ character), as in "\".

Some examples:

 ActivateWindow(VideoFiles, path_to_some_files )
 ActivateWindow(VideoFiles,path_to_some_files)
 ActivateWindow(VideoFiles,"path_to_some_files")

will all produce the exact same functionality, under the assumption that path_to_some_files contains no initial or trailing spaces (unlikely) and no unmatched brackets and commas. The "ActivateWindow" function will be called with two parameters: "VideoFiles" (the window to open) and "path_to_some_files" (a starting path for the browsing). If path_to_some_files contains initial or trailing spaces, or contains commas or brackets, then only the last form will function correctly.

Using Built-in Functions from the skin

To have a button (or toggle button) on the skin run a particular function, you just have to add an <onclick> tag (or <onfocus> tag) containing the function you wish to run.
For example, adding the following to a button control will create a stop button.

 <onclick>PlayerControl(Stop)</onclick>

If you want a button in your skin taking you directly to the movie listing, add a parameter to the Window ID as follows:

  <onclick>ActivateWindow(myvideolibrary,movietitles)</onclick>

A list of parameters can be found here:

Using Built-in Functions from python

To run a built-in Kodi function from within a python script, you just need to call executebuiltin() with the function name. For example,

 xbmc.executebuiltin('RunScript(script.myscript)')

will run the script myscript.py located in the Scripts directory. There is an optional second argument, a boolean which requests a blocking call. By default built-on functions are non-blocking and executebuiltin() will return before the built-in function has run to completion. By specifying True, you can request executebuiltin() to wait until the built-in function is finished before returning:

 xbmc.executebuiltin('RunScript(script.myscript)', True)

Using Built-in Functions from keymap.xml

To bind a built-in function to a particular key, you just add the built-in command to the appropriate section and button in keymap.xml

For example, to map the running of an script to the BLACK button, we'd add:

  <gamepad>
    ...
    <black>RunScript(script.myscript)</black>
    ...
  </gamepad>


to whatever window section of keymap.xml is appropriate.
For more information on changing the keymapping with keymap.xml see: Changing the keymapping

List of built-in functions

See: List of built-in functions