103 lines
4.0 KiB
Plaintext
103 lines
4.0 KiB
Plaintext
|
Hello world!
|
||
|
|
============
|
||
|
|
|
||
|
|
Clementine allows users to load scripts written in Python. These scripts run
|
||
|
|
in a Python interpreter inside Clementine itself and have access to
|
||
|
|
Clementine's internals through a special L{clementine} module. Scripts can
|
||
|
|
create graphical user interfaces using the Python Qt bindings.
|
||
|
|
|
||
|
|
Let's begin by creating a script that shows a dialog box when loaded.
|
||
|
|
|
||
|
|
Creating a simple script
|
||
|
|
========================
|
||
|
|
|
||
|
|
Create a directory called C{helloworld}. All files for this script will live
|
||
|
|
in this directory.
|
||
|
|
|
||
|
|
Inside the C{helloworld} directory create a file called C{main.py}. This will
|
||
|
|
contain all the Python source code for this script.
|
||
|
|
|
||
|
|
>>> from PyQt4.QtGui import QMessageBox
|
||
|
|
...
|
||
|
|
... QMessageBox.information(None, "Hello world!", "My script was loaded!")
|
||
|
|
|
||
|
|
B{Note:} It is possible (and recommended) to split large scripts up into multiple
|
||
|
|
classes stored in separate files, and C{import} them as in a normal Python
|
||
|
|
application. For now we will put all the code into a single file.
|
||
|
|
|
||
|
|
This code imports the C{PyQt4.QtGui.QMessageBox} class from the Python Qt
|
||
|
|
bindings and displays a simple information message box when the script is
|
||
|
|
loaded.
|
||
|
|
|
||
|
|
The script.ini
|
||
|
|
==============
|
||
|
|
|
||
|
|
You now have some Python source code in a directory, but Clementine won't
|
||
|
|
recognise it as being a loadable script. You need to create a C{script.ini}
|
||
|
|
file with some information about your script:
|
||
|
|
|
||
|
|
>>> [Script]
|
||
|
|
... name=Hello world!
|
||
|
|
... description=My first script
|
||
|
|
... author=Fred <fred@example.com>
|
||
|
|
... url=http://www.example.com
|
||
|
|
... icon=:/icon.png
|
||
|
|
...
|
||
|
|
... language=python
|
||
|
|
... script_file=main.py
|
||
|
|
|
||
|
|
Let's look at what each of these fields is for:
|
||
|
|
|
||
|
|
- B{name} - The short name of your script that is displayed to the user in
|
||
|
|
bold in the Script Manager dialog.
|
||
|
|
- B{description} - A longer description of your script. Try to explain
|
||
|
|
briefly what the script does and what the user should do to start using it.
|
||
|
|
- B{author} I{[optional]} - Your name and email address in the format
|
||
|
|
C{Name <email@address>}. This is not currently used, but may be in the
|
||
|
|
future.
|
||
|
|
- B{url} I{[optional]} - A URL of this script's homepage. This is not
|
||
|
|
currently used, but may be in the future.
|
||
|
|
- B{icon} - The filename (relative to the script's directory) of an icon to
|
||
|
|
display next to the script in the Script Manager dialog. You can put an
|
||
|
|
image (.png or .jpg) into the C{helloworld} directory and refer to that
|
||
|
|
here. The image should be at least 64x64 pixels big. Notice in this
|
||
|
|
example we use a filename starting with C{:/}. This is a Qt resource path,
|
||
|
|
and refers to one of the icons embedded within Clementine.
|
||
|
|
- B{language} - The language the script is written in. Currently this must
|
||
|
|
be set to C{python}, but more languages may be supported in the future.
|
||
|
|
- B{script_file} - The Python source file to load for this script. If your
|
||
|
|
script consists of multiple files then the one specified here is the main
|
||
|
|
one that will be loaded first.
|
||
|
|
|
||
|
|
Adding the script to Clementine
|
||
|
|
===============================
|
||
|
|
|
||
|
|
Clementine searches for its scripts in a couple of different places depending
|
||
|
|
on the operating system:
|
||
|
|
|
||
|
|
B{On Windows:}
|
||
|
|
|
||
|
|
- C{%UserProfile%\.config\Clementine\scripts} (where C{%UserProfile%} might be
|
||
|
|
C{C:\Users\YourUsername} on Windows Vista or Windows 7, or
|
||
|
|
C{C:\Documents and Settings\YourUsername} on XP).
|
||
|
|
- C{C:\Program Files\Clementine\scripts}
|
||
|
|
|
||
|
|
B{On Linux:}
|
||
|
|
|
||
|
|
- C{~/.config/Clementine/scripts}
|
||
|
|
- C{/usr/share/clementine/scripts}
|
||
|
|
- C{/usr/local/share/clementine/scripts}
|
||
|
|
- C{$PREFIX/share/clementine/scripts} (if Clementine was installed into a
|
||
|
|
different prefix).
|
||
|
|
|
||
|
|
B{On Mac OS X:}
|
||
|
|
|
||
|
|
- C{~/Library/Application Support/Clementine/scripts}
|
||
|
|
|
||
|
|
For development you should copy your C{helloworld} directory (or create a
|
||
|
|
symbolic link) into one of these locations. Clementine should notice the new
|
||
|
|
script straight away and add it to the Script Manager dialog.
|
||
|
|
|
||
|
|
Load your script by clicking on it in the Script Manager dialog and clicking
|
||
|
|
the C{Enable} button.
|