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.