Aero All In One

Plugin developement guide


What is an Aero AIO plugin?
It is at least a python file with two variables:
    "plugin_name" : a 'string' which is the name of the plugin that will be displayed in the configuration gui.
    "icon" : a 'string' wich is the filename (without its path: e.g. "network.png") of the image you want to use for your plugin.
    "default_param" : a 'dict' wich contains parameters with their default values (or an empty 'dict' {} if there are no parameters for the plugin).
an "init()" function wich is executed only at the start of Aero AIO and a "Plugin" class wich contains functions to build, update and close plugin's superkaramba page.
You should use the plugin template file "plugin_aio.py" in wich every mandatory variables and functions are described. The end of the filename of this python file must be "_aio.py" because it is how theme recognizes it as a plugin.

But it can also have:
    an icon image in "icons/icons_set_name/" or at least in "icons/default/" directory.
    a configuration gui page python file in "scritps/" directory.
    images in "img/plugin_name/" directory.
Then if it has many files it should be zipped with the ".aiz" extension so that it could be installed automatically with configuration gui. Note: a plugin can be installed with configuration gui (if it is a ".aiz" archive) or simply dropped in Aero AIO directory or in "$HOME/.aero_aio/". But if a plugin contains images (wich must be in "img/plugin_name" conventionaly) it should be dropped in "$HOME/.aero_aio/" or zipped in a ".aiz" archive (wich will be installed automatically in "$HOME/.aero_aio/" by using configuration gui).
Plugin class
It must have at least these six functions defined: "__init__()" (of course), "update()", "shadow()", "commandOutput()", "meterClicked()" and "close()". See plugin template for more information.
The __init__ function takes five arguments: widget, theme, color, titleColor and conf.
    theme is a 'string' of the path to current theme.
    color is an integer 'list' containing text color in this form "[int red, int green, int blue]". You must apply "karamba.changeTextColor(widget, self.karambaText, color[0], color[1], color[2])" on each text created in __init__ excepted self.title.
    titleColor is an integer 'list' containing title color in the same format.
    conf is a 'dict' containing parameters from theme and from all present plugins plus some usefull values. If your plugin has some parameters access them like that: conf["myplugin_parametername"].
Usefull values are:
    conf["icon"] path to current icon set,
    conf["home"] path to user's path (= "echo $HOME"),
    conf["path"] current theme path (= sys.path[1] or karamba.getThemePath(widget)),
    conf["img_dir"] = conf["home"] + ".aero_aio/img/",
    conf["scripts_dir"] path to scripts directory (simply "scripts/" or conf["home"] + ".superkaramba/aero_aio/" if theme is an .skz archive),
    conf["skz"] True if theme is an .skz archive, False if it is unzipped.
__init__ function should start with :
  self.title = karamba.createText(widget, 36, 34, 150, 20, "My Title")
  karamba.changeTextSize(widget, self.title, 20)
  self.line = karamba.createImage(widget, 31, 58, theme + "line.png")
Configuration GUI page
It is a python file whose name must start just like the "_aio.py" file and whose end is "_gui.py" (e.g.: "calendar_aio.py" => "calendar_gui.py"). Moreover it must be in the "scripts/" directory of the plugin. It contains only the "from qt import *" statement and the "Page" class wich is a 'QWidget' subclass.
Page class must have at least two functions : __init__ (of course) and buildParam.
__init__ function has two arguments (parent, conf) and must start with :
  apply(QWidget.__init__, (self, parent)).
conf contains current parameters of theme and plugins and usefull values:
    conf["skz"], conf["home"], conf["theme_path"] : see Plugin class,
    conf["kde_iconPath"] path to user's current kde icons.
".aiz" plugin archive
To make it easier for users to install new plugins you should use "zip" to build a ".aiz" archive (a zip archive renamed with the .aiz extension". "_aio.py" file must be in the root of the archive (icon in at least "icons/default/", images in "img/plugin_name/", scritps and _gui.py files in "scripts/").
Users just have to open configuration dialog and click on "Install/Add a new plugin" to specify path to a plugin (a .aiz file). Then installation script looks for a "_aio.py" file, read plugin name and default_parameters in it (if only one "_aio.py" file is found). If successfull files are extracted to "$HOME/.aero_aio/" then a "_gui.py" file is searched in "scripts/" dir, if it exists a configuration page is built from it.
Icons
Before being created each icon image existence is verified. If a local icon theme is used (e.g.: "icons/default") it is searched in "$HOME/.aero_aio/icons/ICON_SET_NAME", then (if it doesn't exist) in "icons/ICON_SET_NAME" (in theme's archive), then in "$HOME/.aero_aio/icons/default", then in "icons/default" and if no matching image filename was found "icons/default/noicon.png" is used. If an external icon set is used, the image is first searched in its directory then in "default" directories.
Themes
Themes should at least contain these files and directories in the same format:
    theme
    autoswitch.png
    bar_140.png
    bar_grid.png
    bg.png
    border_140.png
    cpu_grid.png
    line.png
    mail.png
    pause.png
    play.png
    preview.png
    selected.png

    acpi/
      battery_bar.png
      battery_bg.png
      battery_bottom.png
      battery_empty.png
      battery_full.png
      battery_mask.png
      battery_top.png
      externalpower.png

    calendar/
      bar.png
      day.png
      next.png
      previous.png

    clock/
      bg.png
      hhand.png
      mhand.png
      shand.png

    network/
      network.png
      off.png
      on.png
      wireless.png