The eboxy User's Guide

Paul Eggleton

   Sunday, 4 April 2004

   Abstract

   This manual describes how to use and customise the eboxy
   software package.
     _________________________________________________________

   Table of Contents

   1. Introduction

        Purpose
        Features

   2. Installation

        How to obtain eboxy
        Requirements
        Compiling and installing

   3. Usage

        Keyboard controls
        Actions

              Standard actions
              User actions

        Command line options
        Configuration file

              Available settings
              Example

        LIRC

   4. Customisation

        Introduction
        XML skin files
        Scripting

              Events
              Commands
              Properties & Expressions
              Comparison and boolean operators
              Methods
              Special objects
              Variables
              execwait() and execwaitcapture()
              Conclusion
              Reference

        Plugins

              Usage
              Capabilities

        Miscellaneous

              Using new features
              System XML file
              Controlling video output
              Order of events

   5. Object Reference

        Introduction
        Label

              Properties

        System

              Properties
              Methods
              Events

        Picture

              Properties
              Methods

        ToggleButton

              Properties
              Methods
              Events

        ScrollBar

              Properties
              Methods
              Events

        TextField

              Properties
              Methods
              Events

        ListBox

              Properties
              Methods
              Events

        Timer

              Properties
              Methods
              Events

        Page

              Properties
              Events

   6. Miscellaneous

        Other documentation
        Troubleshooting

              Known problems

        Future
        Author and Updates

   7. Copyright and Disclaimer

   List of Tables

   3.1. Default keyboard key assignments
   3.2. Key names
   3.3. Key modifiers
   3.4. Standard actions
   3.5. User actions
   3.6. Command line options
   3.7. Configuration file settings
   4.1. Script Commands
   4.2. Script character codes
   4.3. Script operators
   4.4. SDL video driver environment variables

Chapter 1. Introduction

   Table of Contents

   Purpose
   Features

Purpose

   eboxy is an application for building simple user interfaces.
   It was originally designed for running a GUI on a set-top box,
   suitable for use on a TV; however, it can be used for many
   other purposes. It reads an XML file describing a simple GUI
   and creates and runs the GUI on the screen.

   I wrote this software for my eBox project (a movie/audio
   playing home entertainment PC), so I could access its various
   functions from the comfort of the couch using a remote. The
   eBox project is as much about helping others build similar
   systems as it is getting a decent entertainment system for
   myself, so for detailed information on the eBox and how you
   can set up such a system using Linux, check out the eBox
   website.

Features

     * Fully skinnable simple GUI interface system
     * Simple scripting language for events (button click, page
       load etc.)
     * Control by mouse, keyboard, or (optional) infra-red remote
       via LIRC
     * Interface plugins for swapping between different
       input/display systems (default SDL+SDL_gui, others
       planned)
     * Generic plugins for custom extension
     * Wide range of image format support (with alpha
       transparency)
     * TrueType font support

Chapter 2. Installation

   Table of Contents

   How to obtain eboxy
   Requirements
   Compiling and installing

How to obtain eboxy

   The latest version of eboxy is always available from the eboxy
   homepage, or from the SourceForge project page for eboxy,
   where you can also grab the latest development version from
   CVS as well as submit bugs, patches, etc.

Requirements

   eboxy requires the following packages to be installed on your
   system:
     * libxml2 2.4.19 or newer - used by many applications,
       available from xmlsoft.org. Note: in 2.5.x, it appears to
       be far less strict about the DTD validation, which can
       lead to confusion as to why certain things in your XML
       file get ignored. This will be rectified in future
       versions of eboxy.
     * SDL 1.2 or newer
     * SDL_ttf (also requires FreeType)
     * SDL_image (its requirements depend on what images you want
       to load - libjpeg and libpng recommended)
     * SDL_gui - see notes below
     * Flex 2.5.4a or later (not actually run, but compilation
       needs FlexLexer.h which comes with flex).

   Apart from SDL_gui, many Linux distributions already include
   these required packages. Make sure you also have the "-devel"
   packages installed for each if your distribution has them.

   Optional:
     * LIRC if you want to use your IR remote

   eboxy was developed and tested on Gentoo Linux 1.4, but if
   you've got the requirements described above installed it
   should work on any Linux system. I would certainly support
   efforts to get eboxy working on other Unix platforms, so if
   you're interested in using it on another Unix platform, give
   it a try and let me know how it goes.

   For Red Hat, Mandrake and other RPM-based systems, SDL_gui
   RPMs are available from the eboxy website. Alternatively it
   can be installed from source. Gentoo Linux now has a working
   ebuild for it (emerge sdl-gui to install).

   Note: When installing SDL_gui from source, to make things
   easiest you should make sure it is installed into the same
   location (prefix) as SDL. This means if SDL is installed into
   /usr/lib, SDL_gui must be installed into /usr/lib as well
   (same goes for the other SDL support libraries). Normally, if
   you compile both SDL and SDL_gui from source, or install both
   from binary packages, this is not an issue. However if it's
   half and half (which it very well might be as most
   distributions don't have binaries for SDL_gui) you need to
   take care that this is done properly. The easiest way is to
   make sure any SDL packages you compile from source go into
   /usr/lib, by passing --prefix=/usr/lib to ./configure.

Compiling and installing

   In order to compile and install eboxy on your system, type the
   following in the base directory of the eboxy distribution
   (you'll need to be root to run the last command):
./configure
make
make install

   If you get errors from configure then there's probably
   something wrong with your paths or you don't have one of the
   required libraries. Firstly, make sure you have a line
   /usr/local/lib in your /etc/ld.so.conf file. Then (as root)
   run ldconfig which makes sure all installed libraries are
   accessible. Try running ./configure again and see if this
   fixed it. If not, have a look at config.log and see if that
   suggests anything. If not, email me at
   <bluelightning@bluelightning.org> including a copy of
   config.log and details of the problem you're having.

   To test eboxy, simply cd into the skins/test directory and run
   eboxy. A simple test menu should appear for you to try out.

Chapter 3. Usage

   Table of Contents

   Keyboard controls
   Actions

        Standard actions
        User actions

   Command line options
   Configuration file

        Available settings
        Example

   LIRC

Keyboard controls

   Listed below are the default keyboard controls. You can change
   them to your liking by editing the file ~/.eboxy/keys. This
   file contains entries consisting of the key name and action to
   be performed, separated by tab(s) or space(s), one entry per
   line. Not all actions have to be bound, and neither do all
   keys.

   Table 3.1. Default keyboard key assignments
   Key Default function
   Shift+Tab Previous widget
   Tab Next widget
   Up Arrow / Left Arrow Previous list item
   Down Arrow / Right Arrow Next list item
   Page Up Previous list page
   Page Down Next list page
   Home First list item
   End Last list item
   Enter Press selected button/choose selected list item
   Escape Quit

   The keyboard key names used in the keys file are as follows:

   Table 3.2. Key names
   Key name           Key
   backspace          Backspace
   tab                Tab
   enter              Enter
   pause              Pause
   escape             Escape
   space              Space bar
   quote              Quote '
   comma              Comma ,
   minus              Minus -
   dot                Full stop .
   slash              Forward slash /
   0 to 9             Number keys (not the keypad)
   semicolon          Semi-colon ;
   equals             Equals =
   leftbracket        Left bracket (
   backslash          Backslash \
   rightbracket       Right bracket )
   backquote          Backquote `
   a to z             Alphabetic keys a-z
   delete             Delete
   keypad0 to keypad9 Keypad number keys
   keypaddot          Keypad .
   keypadslash        Keypad /
   keypadstar         Keypad *
   keypadminus        Keypad -
   keypadplus         Keypad +
   keypadenter        Keypad enter
   keypadequals       Keypad =
   uparrow            Up cursor key
   downarrow          Down cursor key
   rightarrow         Right cursor key
   leftarrow          Left cursor key
   insert             Insert
   home               Home
   end                End
   pageup             Page Up
   pagedown           Page Down
   f1 to f15          Function keys F1-F15
   numlock            Num Lock
   capslock           Caps Lock
   scrolllock         Scroll Lock
   rshift             Right Shift
   lshift             Left Shift
   rctrl              Right Control
   lctrl              Left Control
   ralt               Right Alt
   lalt               Left Alt
   lwin               Left Windows key
   rwin               Right Windows key
   menu               Context menu key
   printscreen        Print Screen

   In addition, you can use the following modifier key prefixes:

   Table 3.3. Key modifiers
   Key name Key
   lshift   Left Shift
   rshift   Right Shift
   shift    Shift (left or right)
   lctrl    Left Ctrl
   rctrl    Right Ctrl
   ctrl     Ctrl (left or right)
   lalt     Left Alt
   ralt     Right Alt
   alt      Alt (left or right)

   To use these modifiers, just prefix your keys with one or more
   of them, separating keys and modifiers with plus signs, eg.:
alt+x              exit
shift+ctrl+enter   accept

   Note: when entering text in a textfield widget, eboxy will
   pass through normal letter, number and punctuation keys as
   normal. If you don't want this to happen (ie, you want to
   remap the keyboard completely) you will need to pass the
   --nokeypassthrough command line option to eboxy when you run
   it.

Actions

   eboxy actions are the basis for controlling eboxy. They are
   used for standard key and LIRC remote button bindings for
   things such as navigating among the widgets on the screen or
   items in a list (standard actions), and for binding keys or
   remote buttons to GUI buttons (user actions).

Standard actions

   Table 3.4. Standard actions
   Action Function
   prev Previous widget
   next Next widget
   accept Accept current selection/value. This presses buttons.
   For textfields, this jumps to the next widget. For listboxes,
   it generates an OnChoose event.
   quit Quit eboxy
   item_prev Previous list item
   item_next Next list item
   item_first First list item
   item_last Last list item
   item_prevpage Previous page of items in a list
   item_nextpage Next page of items in a list
   textinput_backspace When editing text in a textfield, deletes
   the character to the left of the cursor and moves the cursor
   one place to the left.
   textinput_delete When editing text in a textfield, deletes the
   character to the right of the cursor.
   textinput_digitn Enter a text character into a textfield,
   using number pad based input. This is similar to entering in
   text messages on a mobile phone. n is a number from 0 to 9.
   Pressing the same key repeatedly cycles through the available
   characters for that key. If you wait more than a second
   between presses, the key will be repeated instead. This is
   useful for entering alphanumeric text from a remote that only
   has number keys. Note that if the textfield you are entering
   text into is restricted using the validchars property, and
   that restriction results in only one character being valid for
   a button, then you won't have to wait between presses (eg. if
   validchars is set to [0-9], you will be able to repeat numeric
   digits without waiting).
   textinput_char Enter a text character into a textfield. Append
   the character to type into the textfield (alphanumeric
   characters only, localised characters should be OK). For
   symbols, use the following names appended to textinput_:
exclamation  !
at           @
hash         #
dollar       $
percent      %
caret        ^
ampersand    &
star         *
openbracket  (
closebracket )
underscore   _
minus        -
plus         +
equals       =
opensquarebracket  [
closesquarebracket ]
openbrace    {
closebrace   }
pipe         |
backslash    \
colon        :
semicolon    ;
quote        '
doublequote  "
slash        /
question     ?
lessthan     <
greaterthan  >
comma        ,
dot          .
tilde        ~
backquote    `
space

   Examples: textinput_j Inserts a letter j, textinput_plus
   inserts a + sign.

User actions

   User actions are similar to the standard actions, except that
   they don't do anything by themselves. They are meant to allow
   you to bind keys or LIRC remote buttons to GUI buttons. The
   reason these are used rather than just binding the
   keys/buttons directly is to ensure similar functionality
   across different skins and systems (ie. you can download a new
   skin and it should work with your existing key bindings and
   LIRC configuration).

   Please note that these actions do not actually do anything on
   their own. Also, you should avoid using an action for anything
   other than its intended purpose, to avoid confusion. The list
   of user actions is fixed in order to provide a standard. If an
   appropriately-named action for the purpose you require doesn't
   exist, please email <bluelightning@bluelightning.org> and it
   will be added into the next version.

   Table 3.5. User actions
   Action Suggested purpose
   add Add item
   edit Edit item
   delete Delete item
   play Play
   record Record
   stop Stop
   pause Pause
   rewind Rewind
   fastforward Fast forward
   jumptostart Jump to beginning
   jumptoend Jump to end
   eject Eject media
   nextchannel Next TV/radio channel/music track/DVD chapter
   prevchannel Previous TV/radio channel/music track/DVD chapter
   frequencyup Increase frequency
   frequencydown Decrease frequency
   volumeup Increase volume
   volumedown Decrease volume
   mute Mute audio toggle
   shutdown Shut down machine
   restart Restart machine
   restartserver Restart display (eg. X server)
   up Move up (navigating something positional, eg. a map)
   down Move down
   left Move left
   right Move right
   zoomin Zoom in
   zoomout Zoom out
   yes Quick yes/ok/accept
   no Quick no
   cancel Cancel/back out
   tv Jump to TV watching
   radio Jump to radio listening
   dvd Jump to DVD viewing
   rectimer Jump to setting up a timed recording
   mail Jump to email
   web Jump to web browser
   photos jump to photo album
   videos Jump to video library
   music Jump to music library
   number0 Number pad 0
   number1 Number pad 1
   number2 Number pad 2
   number3 Number pad 3
   number4 Number pad 4
   number5 Number pad 5
   number6 Number pad 6
   number7 Number pad 7
   number8 Number pad 8
   number9 Number pad 9
   menu1 Menu 1 (possibly for DVD)
   menu2 Menu 2 (possibly for DVD)
   menu3 Menu 3 (possibly for DVD)
   viewmode Change screen size / list viewing mode / aspect ratio
   (etc.)
   nextaudio Next audio channel
   prevaudio Previous audio channel
   nextsubtitle Next subtitle language
   prevsubtitle Previous subtitle language
   nextangle Next angle (DVD)
   prevangle Previous angle (DVD)
   deinterlace Toggle deinterlacing
   snapshot Capture a snapshot image of video
   help Jump to help page
   trackinfo Show information on the currently playing
   track/stream
   tracksearch Incremental search for track
   systeminfo Jump to system information / stats screen
   setup Go to setup page
   showclock Show clock

   To bind a user action to a GUI button, simply add an
   action="actionname" attribute to the button in the XML file.
   Then, pressing a key or LIRC button bound to this action when
   the GUI button is on screen will cause the button to be
   pressed.

   Note: the number* user actions are separate from digit input
   for entering text with the number pad.

Command line options

   Table 3.6. Command line options
   Short Long Description
   -f --fullscreen Causes eboxy to run in full-screen mode.
   -x w --width w Sets the window/full-screen width to w.
   -y h --height h Sets the window/full-screen height to h.
     --bpp b Set bits per pixel (colour depth) to b. Usually not
   needed, but if your display supports 24-bit colour then you
   should probably specify --bpp 24 for slightly faster
   operation.
   -i h --interfaceplugin ifplugin Uses ifplugin as the interface
   plugin (defaults to sdl_gui).
   -h --hidecursor Hide the mouse cursor while eboxy is active.
     --nolirc Do not use the LIRC device (can only be used if
   LIRC support is compiled in, see the LIRC section).
     --nokeypassthrough Do not pass keyboard keys directly
   through to textfields (allows full keyboard remapping).
     --nokeyrepeat Disable keyboard repeat.
     --showkeys Print key info on the console when a keyboard key
   is pressed - useful for testing.
     --help Display short command line help.
     --version Display version information.

Configuration file

   eboxy reads the configuration file ~/.eboxy/eboxy.conf on
   startup if it exists. The file consists of one setting per
   line, with setting name and value separated by an equals
   character.

Available settings

   Table 3.7. Configuration file settings
   Setting Description Default
   width Width of the output 640
   height Height of the output 480
   depth Bit depth of the output (bpp) 16
   interfaceplugin Interface plugin to use sdl_gui
   fontpath Search path for fonts. Multiple paths separated by
   colons. n/a
   imagepath Search path for images. Multiple paths separated by
   colons. n/a

   If a command line option is specified that has an equivalent
   in the configuration file, the command line option takes
   precedence.

   For the font and image paths, eboxy always looks in the
   directory where the XML file is located first, before
   searching in the specified path(s).

Example

width=800
height=600
fontpath=/usr/X11R6/lib/X11/fonts/truetype:/home/paul/eboxy-skin
imagepath=/usr/share/pixmaps:/usr/share/images:/home/paul/eboxy-skin

LIRC

   If LIRC (Linux Infra-Red Control) is installed on your system
   at compile-time, the configure script will detect it and eboxy
   will attempt to use your LIRC device when run, so that you can
   control eboxy using your infra-red remote. For it to work you
   need to be running lircd and you need to associate the remote
   keys with actions in the .lircrc file in your home directory.
   Here is a template:
begin
  remote =
  prog = eboxy
  button =
  repeat = 1
  config = prev
end

begin
  remote =
  prog = eboxy
  button =
  repeat = 1
  config = next
end

begin
  remote =
  prog = eboxy
  button =
  repeat = 0
  config = accept
end

begin
  remote =
  prog = eboxy
  button =
  repeat = 1
  config = item_next
end

begin
  remote =
  prog = eboxy
  button =
  repeat = 1
  config = item_prev
end

begin
  remote =
  prog = eboxy
  button =
  repeat = 0
  config = quit
end

   You'll need to fill in the remote name (as defined in
   /etc/lircd.conf) and the button name (ie, the button on the
   remote you want to assign, also defined in /etc/lircd.conf)
   for each function above. The actions referred to here (accept,
   item_prev etc.) are documented in the Actions section.

   Note: if you are running eboxy under X, LIRC events will be
   ignored when the eboxy window does not have focus. This allows
   you to use the remote with other programs when eboxy is in the
   background.

Chapter 4. Customisation

   Table of Contents

   Introduction
   XML skin files
   Scripting

        Events
        Commands
        Properties & Expressions
        Comparison and boolean operators
        Methods
        Special objects
        Variables
        execwait() and execwaitcapture()
        Conclusion
        Reference

   Plugins

        Usage
        Capabilities

   Miscellaneous

        Using new features
        System XML file
        Controlling video output
        Order of events

Introduction

   eboxy's GUI system is fairly simple, and is defined in terms
   of widgets and pages. Widgets (known as controls or components
   in other systems) are things that can be displayed and
   interacted with on pages - eg. buttons, labels etc. Pages
   contain the widgets and take up the entire eboxy screen, and
   you can have multiple pages. Buttons are visually defined by
   several bitmap image files (normal, selected (highlighted),
   and pressed) and optionally a font, font size, font colour and
   some text to display a caption on the button. Each page can
   have its own background image, which will be tiled if it is
   smaller than the screen size. Label and picture widgets allow
   you to decorate the page a bit more without needing to merge
   more stuff into your background image.

XML skin files

   eboxy uses an XML file to describe how to lay out the GUI (a
   skin file). eboxy expects either to find eboxy.xml in the
   current directory, or you can specify an XML file on the
   command line and it will use that. If you wish, you can split
   up your menu system into multiple XML files and use the load
   script command to load one when a button is pressed (see later
   in this document). This could be useful for providing custom
   menus on removable media, eg. CD-ROMs.

   To get a good idea of what an eboxy XML file should look like,
   you can look at the examples provided in skins/test.
   Otherwise, the format is fairly straightforward. At the very
   least, you need to define one page and one button. Here's an
   example:
<?xml version="1.0"?>
<!DOCTYPE eboxy SYSTEM "eboxy.dtd">
<eboxy>
  <pages>
    <page name="mypage" background="mybackground.png">
      <button image="mybutton.png" selectedimage="mybutton-down.png" pr
essedimage="mybutton-down.png" x="10" y="10">
        echo "hello world!"
      </button>
      <button image="mybutton2.png" selectedimage="mybutton2-down.png"
pressedimage="mybutton2-down.png" x="10" y="100">
        quit
      </button>
    </page>
  </pages>
</eboxy>

   This defines two buttons, each using their own set of images,
   the first of which displays a message on the console when
   pressed, and the second quits the application.

   If you're using the same set of images and fonts for more than
   one button and differentiating each button using a caption
   instead, eboxy supports things called templates that make
   things easier. Using a button template means you don't have to
   waste time typing or copying and pasting the same attributes
   for each button. Label templates are also supported. Here's an
   example:
<?xml version="1.0"?>
<!DOCTYPE eboxy SYSTEM "eboxy.dtd">
<eboxy>
  <templates>
    <buttontemplate name="mytemplate" font="arial.ttf" fontsize="18" fo
ntcolor="#FFAABB" image="mybutton.png" selectedimage="mybutton-down.png
" pressedimage="mybutton-down.png" />
  </templates>
  <pages>
    <page name="mypage" background="mybackground.png">
      <button caption="Hello" template="mytemplate" x="10" y="10">
        echo "hello world!"
      </button>
      <button caption="Test" template="mytemplate" x="10" y="100">
        quit
      </button>
    </page>
  </pages>
</eboxy>

   As mentioned before, eboxy also supports picture and label
   widgets as well as buttons. Here's an example:
<?xml version="1.0"?>
<!DOCTYPE eboxy SYSTEM "eboxy.dtd">
<eboxy>
  <templates>
    <buttontemplate name="mytemplate" font="arial.ttf" fontsize="18" im
age="mybutton.png" selectedimage="mybutton-down.png" pressedimage="mybu
tton-down.png" />
    <labeltemplate name="mylabeltemplate" font="arial.ttf" fontsize="12
" textalign="right" wordwrap="true" />
  </templates>
  <pages>
    <page name="mypage" background="mybackground.png">
      <label x="10" y="200" autosize="true" font="arial.ttf" fontsize="
24">Page Title</label>
      <label x="300" y="100" autosize="true" width="250" template="myla
beltemplate">This is an example of a word-wrapped label</label>
      <button caption="Hello" template="mytemplate" x="100" y="50">
        echo "hello world!"
      </button>
      <button caption="Test" template="mytemplate" x="100" y="150">
        quit
      </button>
      <picture x="200" y="200" image="logo.png" />
    </page>
  </pages>
</eboxy>

   Labels allow you to specify the text alignment/justification
   (textalign="left", "right" or "center", default is left),
   autosizing on/off (autosize="true" or "false", default is
   false) and auto-word wrapping on/off (wordwrap="true" or
   "false", default is false). Note that with word wrapping on,
   autosizing will only adjust the height, because the width
   needs to be constant so the label knows where to wrap the
   text, so you need to specify the width. One other important
   thing about labels: text is formatted as-is - if you put line
   breaks or indenting, these will appear in the resulting
   display.

   Notes:
     * The first page that eboxy displays is the first one
       defined in the file.
     * Templates don't have to define all the attributes - you
       can define some and specify the rest in each widget that
       uses the template.
     * You can specify an attribute in a template and override it
       in a widget that uses that template.
     * If you want to specify the characters & < > ' or " in
       text, you should use the entities &amp; &lt; &gt; &apos;
       or &quot; respectively instead, just like HTML.
       Alternatively if you are using a lot of these in one block
       (eg. a script) you can enclose them in an XML standard
       CDATA section ( <![CDATA[ ... ]]> ).
     * The order of the attributes is not important.
     * The templates don't actually have any "content", so if you
       want you can do as above and put / at the end of the tag
       instead of using a closing tag. (ie. <template... />
       instead of <template...></template>).
     * eboxy does not pay any attention to the DTD specified at
       the top of the file (indeed, you can leave out the
       <!DOCTYPE...> directive entirely, it's just there for
       completeness - I recommend you leave it in though so you
       can tell easily what the XML file is for). eboxy always
       validates the XML file against eboxy.dtd, which is
       installed in /usr/local/share/eboxy by default.
     * The syntax for colour attributes (eg. fontcolor) is the
       same as that used in HTML - #rrggbb where each digit is a
       hex value for the colour component (red, green, blue).
       Examples: #FFFFFF is completely white, #0000FF is blue,
       #FAB100 is light orange etc. Some nice colour charts are
       available at http://www.igrin.co.nz/petersim/bcolour.html.
     * If the visual centre of your button images is not the
       actual centre of the image (eg. a button with a drop
       shadow on the bottom and right hand edges) then you can
       move the button's caption by using the captionx and
       captiony attributes, ie. to move the caption 10 pixels to
       the left, add captionx="-10" or for 2 pixels down,
       captiony="2". These two attributes are optional and
       separate, and can be used in buttons or button templates.
     * Buttons also have optional captiondropx and captiondropy
       attributes. These control how much (if at all) the
       button's caption moves when the button is pressed. The
       default is 2 pixels down, and 2 pixels right, but
       depending on your images, you may want to change these
       values so that the buttons look good when pressed.
     * When running an external program (using the exec command)
       eboxy loses focus, but continues running. If eboxy was
       running in full-screen mode then it will go into windowed
       mode. (This is an automatic feature of SDL, the library
       that eboxy uses for displaying graphics). If you want to
       completely hide the GUI, use the exechide command instead.
     * Names (of templates and pages) can only consist of letters
       and numbers and the underscore (_) character. Reserved
       words used in the scripting language are also not allowed.
       Each template and page must have a unique name.

Scripting

   eboxy provides a simple scripting system for defining what
   should happen when an event occurs (eg., a button is pressed).
   Events for each type of object are defined in the Object
   Reference section.

Events

   To respond an event, you use the <event> tag within the body
   of the item you want to attach the event to. For example:
...
<page ...>
  <event type="OnLoad">
    echo "the page is loading"
  </event>
  <event type="OnShow">
    # this is a comment
    echo "the page has been shown"
    echo "you can have as many commands as you like in a script"
  </event>
  ...
  <button ...>
    <event type="OnClick">
      echo "button clicked"
      exec "ls -l"
    </event>
    <event type="OnGotFocus">
      echo "button focused!"
    </event>
  </button>
  ...
</page>
...

   Since system events aren't associated with a page, they are
   kept in a separate section in the XML file - the system
   section. This must appear before the templates section (if it
   exists, otherwise before the pages section) and is optional.
   For example:
...
<system>
  <event type="OnLoad">
    echo "eboxy is loading"
  </event>
  ...
</system>
...
<pages>
...
</pages>

   Be warned that you will not get an error if the event you
   define a handler for does not exist - it will just never
   happen, so make sure you type the name correctly. Also, with
   buttons, there is a shortcut as you've already seen - if you
   only need to do something when the button is clicked, the
   <event type="onclick">...</event> is optional - if you wish,
   you can just put the script you want to run when the button is
   clicked inside the <button> tag body.

   There is one other attribute to events, and that is the wait
   attribute. This tells eboxy whether the execution of the event
   should be threaded or not - in simple terms, whether eboxy
   should wait while your script runs or not. wait="false" by
   default if it is not specified, but you may wish to set it to
   true for some of your event scripts depending on the
   situation. Note that with wait="true" eboxy's GUI will
   effectively be frozen while your script runs, so this is not a
   good choice if your script will take a long time to run. Note:
   all system events and the page OnUnload event are always
   waited on - setting wait to false for these will have no
   effect.

Commands

   The commands available to you in a script are as follows:

   Table 4.1. Script Commands
   Command Description
   echo "text" Prints the specified text on the standard output.
   Mainly for testing.
   exec "command" Runs the specified shell command. Control
   returns to the script immediately.
   execwait "command" Runs the specified shell command, and waits
   until it has finished executing.
   exechide "command" Runs the specified shell command, hiding
   the GUI while the program executes.
   page pagename Jump to the page specified by pagename. (This
   corresponds to the name attribute for the page). Note the lack
   of quotes - this is intentional, because pages are objects.
   load "filename" Loads the XML file specified by filename. Note
   that all pages from the current file are purged from memory at
   this point, so you'll need to load the old file again if you
   want to jump back.
   loadplugin "plugin" Loads a plugin. More about plugins in the
   Plugins section
   delay "x" Wait for a specified number of milliseconds (1000ms
   = 1 second)
   quit Quits eboxy.

   There are two other commands in addition to those above - the
   function version of execwait, and execwaitcapture. These will
   be described below.

   You may also put in comments - any line that starts with a #
   will be ignored. Also, whitespace at the start of a line is
   ignored.

Properties & Expressions

   You may set the values of properties on any widget in the
   system (including those on other pages, as names are unique
   system-wide). For example:
button1.caption = "new"

   This means the widgets you want to refer to must be named (ie,
   have a name attribute assuming they are created from within
   the XML file). Certain properties are read-only.

   eboxy scripts know about strings and integer numbers, and
   these can (most of the time) be used interchangeably. As you
   have seen, strings must be enclosed in quotes. Colours are
   represented as specially formatted strings - eg. to change the
   colour of a label's text, you'd do the following:
label5.fontcolor = "#13F6CA"

   Anywhere you can specify a value, you may instead specify an
   expression. Expressions are built up of other strings and/or
   numbers. You may use property values and variables (more on
   that below) in expressions as well. For example:
button1.caption = "Activate " + label1.caption
label5.caption = "X " + label2.caption + " X"
something = (1 + 5) / 2 * 3

   As you may have noticed, the + operator has a double purpose -
   it is used for addition of numbers and concatenating strings
   together. The rule is, if one or both of the two things either
   side of the + symbol is a string, then a string concatenation
   is performed, otherwise the two are both numbers and will be
   added together numerically. The other arithmetic operators (-,
   *, /, %, ^) and the numeric conditional operators (>, <, >=,
   <=) convert their arguments to a number first before
   operating. Note that you can use the latter in order to work
   around the former if you need to: say you have obtained a
   number from somewhere, except it came in as a string (say, the
   value of the text property of a textfield). Just subtract zero
   from the string and it will be converted to a number. For
   example, "1" + 5 results in 15 as a string, whereas ("1" - 0)
   + 5 results in 6 as a number.

   The order of operations in expressions is generally what you'd
   expect, but you can make use of brackets ( ) to control it if
   you need to. Sometimes you may wish to put in extra brackets
   to make it clear what you are doing.

   You may include special characters in strings by using a
   backslash. The special characters you can use are:

   Table 4.2. Script character codes
   Code Character produced
   \n   Newline
   \t   Tab
   \\   Backslash
   \"   Double-quote

Comparison and boolean operators

   eboxy's scripting language supports the most commonly-used
   boolean operators (and, or, not, xor) and comparison operators
   (==, !=, >, <, >=, <=), and the boolean literals true and
   false are allowed. This allows you to perform some rudimentary
   conditional operations. For example:
button1.enabled = label1.text == "hello" and not checkbox1.checked
button2.enabled = true

   Note that the equality operator == is distinct from the
   assignment operator =. Fortunately, unlike some other
   languages the assignment operator is not allowed in any
   situations where it could be confused with the equality
   operator, and attempting to use it as such will result in an
   error.

   Unfortunately, because the scripts are in an XML file, you
   need to encode the > and < characters as &gt; and &lt; when
   using them in the comparison operators. For example:
echo 72 &gt; 78
echo 44 &lt;= 30

   Alternatively, you can enclose your script in an XML standard
   CDATA section and then use the characters as normal. A CDATA
   section starts with <![CDATA[ and ends with ]]>. For example
<![CDATA[
echo 72 > 78
echo 44 <= 30
]]>

   You can't mix the two however - inside a CDATA section, the
   &lt; and &gt; entities will not be expanded and you will get a
   script error.

Methods

   Some object types have methods. Buttons have a single method,
   "click", which you can invoke like this:
topbutton.click()

   This does the same as if the button was clicked by the user.
   Note that the brackets on the end are actually optional if you
   are just calling the method and aren't passing any parameters
   to the method, however you should always put them in for
   clarity. Some methods take parameters, for instance the
   additem method of a listbox widget:
mylist.additem("this is a list item")

   Methods are also capable of returning values, and taking
   multiple arguments. Multiple arguments are separated by
   commas. No methods exist in eboxy's standard widgets that
   returns a value, but it is possible to build one into a
   plugin. An example of using such a method would be:
echo anobject.testmethod(15, "example")

Special objects

   There are a few "special" objects that you can refer to in
   scripts. The first is system, which provides access to a few
   global functions. The other two special objects are really
   just references - currentpage refers to the currently visible
   page and focusedwidget refers to the currently focused widget.
   You can use these as if they were the objects themselves, for
   example:
echo focusedwidget.name

Variables

   eboxy's scripting language has support for variables. All you
   need to do is assign a value to a variable to begin using it.
   You can assign any expression to a variable. Once a variable
   has been assigned you can use it anywhere an expression is
   accepted, and its value will be substituted in.
myvariable = "hello"
anumber = 5
echo myvariable
echo anumber + 2

   Note that unlike shell scripts, attempting to refer to a
   variable which you have not previously assigned a value to
   will result in an error - this is because the variable won't
   actually exist. Most of the time eboxy's scripting language
   does not care whether a string or a number is supplied, and
   variables do not externally have any particular type (although
   internally they do - but you don't need to worry about this
   most of the time). This is known as a "loosely-typed"
   language, and it keeps things simple. Currently, variables are
   always globally available once assigned, and exist until eboxy
   quits (this may change in future). The rules for variable
   naming are the same as for widgets.

execwait() and execwaitcapture()

   If you wish to get something back from an executed program,
   you will need to use these commands. Both of them wait while
   the program executes, and return only when it finishes.
   execwait() returns the result code from the program (usually 0
   unless an error occurred) and execwaitcapture() returns the
   output of the program as a string (and does not print it to
   the terminal, unlike all of the other exec* commands).
resultcode = execwait("someprocess")
button1.enabled = (resultcode == 0)
dirsize = execwaitcapture("du -sh /mnt/files/incoming | cut -f 1")
label1.caption = dirsize

   In the above example, two things are done. First it runs the
   command "someprocess", and if it ran successfully then button1
   is enabled. Next, it gets the total size of the
   /mnt/files/incoming directory in human readable format and
   displays it in label1.

Conclusion

   eboxy scripts are fairly simple. They do not provide
   conditional statements or loops, or support floating point
   numbers. This is partially because they aren't meant to be
   used for general programming - they are mainly for simple
   control of and interaction with plugins; but also because the
   current code is not capable of any kind of jumps (which are
   required for conditional statements, loops etc) and would
   require substantial changes to do so. If you need to do more
   than the scripting system allows, you should probably consider
   writing a plugin to do what you want. See the Plugins section.

Reference

   Table 4.3. Script operators
   Operator Function
   =        Assign
   +        Add / concatenate
   -        Subtract
   *        Multiply
   /        Divide
   %        Remainder
   ^        Raise to power
   ==       Equal to
   !=       Not equal to
   <        Less than
   >        Greater than
   <=       Less than or equal to
   >=       Greater than or equal to
   and      Boolean AND
   or       Boolean OR
   xor      Boolean exclusive OR
   not      Boolean NOT

Plugins

   eboxy can be extended with external plugins, allowing anyone
   with the inclination and a moderate knowledge of C programming
   to add functionality to eboxy. Plugins are special shared
   libraries (.so files in Linux) which you can direct eboxy to
   load in your skin file.

Usage

   Plugins are loaded by either using the loadplugin script
   command or alternatively by putting a <plugin> element into
   the XML file. The latter is the recommended method, because it
   is simpler and allows you to attach event scripts to objects
   that the plugin registers. Here's a simple example of loading
   a plugin using a <plugin> element:
...
<page ...>
        <plugin module="myplugin"/>
        ...
</page>
...

   eboxy will look for plugins in LIBDIR/eboxy only (where LIBDIR
   is picked up at compile time, usually /usr/local/lib). Also,
   the .so extension is always omitted. So in the above example,
   when the page is loaded eboxy will attempt to load the plugin
   file /usr/local/lib/eboxy/myplugin.so into memory. What
   happens after that is up to the plugin developer.

   When you put the <plugin> element inside a page, the plugin is
   only loaded while that page is visible. If you want the plugin
   to be loaded all of the time, put the <plugin> element into
   the <system> section of the XML file.

Capabilities

   Basically, plugins can manipulate on-screen widgets, and
   create objects that you can access in scripts. For example,
   you could make a music player plugin that exposes a
   "musicplayer" object. The plugin could be used like this:
musicplayer.file = "test.mp3"
musicplayer.play

   It is possible for plugins to fire events on objects they
   create. To respond to these events, you add an event into the
   loading element for the plugin, for example:
...
  <plugin module="myplugin">
    <pluginobject name="anobject">
      <event type="OnSomething">
        echo "Something happened"
      </event>
      <event type="OnSomethingElse">
        echo "Something else happened"
      </event>
    </pluginobject>
  </plugin>
...

   The events and objects associated with plugins are defined
   entirely by the plugins themselves. Check the documentation
   for the plugin for further information.

   Plugins can even go as far as automating a page entirely for
   you. All you need to do is to set up the page visually for the
   plugin to work with, using names for the widgets that the
   plugin expects to find. This means you can change the visual
   interface independently of how it operates.

   More technical details of how eboxy plugins work are described
   in the eboxy Extension guide. There are two plugins included
   with eboxy: simplemusic, which enables you to play music files
   (MP3, OGG, MOD, MIDI, etc.) in much the same way as proposed
   above; and filebrowser, which works in conjunction with a
   listbox widget to provide a file browsing interface. Have a
   look in plugins/simplemusic and plugins/filebrowser.

Miscellaneous

Using new features

   You may often use features in eboxy that have only just been
   made available in the latest release. If a user of a previous
   version attempts to use a skin you have made that uses a new
   feature, and they are using an older version, they may not
   realise why it doesn't work. To solve this, add a minversion
   attribute to the top level node of your XML file, ie:

<?xml version="1.0"?>
<!DOCTYPE eboxy SYSTEM "eboxy.dtd">
<eboxy minversion="0.4.0">
...
</eboxy>

   Instead of receiving some cryptic error message (eg. a script
   error, because you have used a new scripting language
   feature), the user of a version of eboxy which is older than
   the minimum version specified will be informed that they need
   to upgrade.

System XML file

   Upon starting, eboxy will look for system.xml in the .eboxy
   subdirectory of your home directory. If it exists, it will be
   loaded first before loading the XML file specified on the
   command line. You can use this to set up templates or pages,
   or load plugins that you can re-use in other XML files.

Controlling video output

   As eboxy uses SDL for video output, you can control which
   output type it uses with environment variables just as you can
   with any SDL-based application.

   Table 4.4. SDL video driver environment variables
   Variable Description
   SDL_VIDEODRIVER Driver used for video output. In Linux,
   possible values include x11, fbcon, directfb, and svgalib. If
   you set this to a particular driver, SDL must have been
   compiled with the specified driver enabled. If you do not set
   this, SDL will auto-detect it, using the best available
   driver.
   SDL_FBDEV Framebuffer device to use if using framebuffer
   (fbcon) output. Default is /dev/fb0.
   SDL_FBACCEL Set to 0 to disable framebuffer acceleration (when
   using framebuffer).

   For further details, see
   http://sdldoc.csn.ul.ie/sdlenvvars.php.

Order of events

   In some situations it may be useful to know the order of
   events as they are executed by eboxy. The following lists
   should give you an idea of what happens when.

Startup

    1. Read configuration file ~/.eboxy/eboxy.conf
    2. Check command-line options
    3. Read key configuration file ~/.eboxy/keys
    4. Load interface plugin
    5. Read system XML file ~/.eboxy/system.xml
    6. Read user-specified XML file (or eboxy.xml in current
       directory)
    7. Initialise LIRC (if enabled)
    8. Fire System.OnLoad event
    9. Initialise system-level plugins
   10. Start system-level timers
   11. Notify all plugins that first page is about to be loaded
   12. Load page-level plugins for first page
   13. Fire page OnLoad event
   14. Display first page
   15. Fire page OnShow event
   16. Start page-level timers
   17. Notify all plugins that page has finished loading
   18. Fire system OnShow event
   19. (... process events ...)

Switch page

    1. Notify all plugins that page is going to be changed
    2. Fire current page's OnUnload event
    3. Stop any timers owned by current page
    4. Unload any plugins owned by current page
    5. Load page-level plugins for new page
    6. Fire page OnLoad event
    7. Display new page
    8. Fire page OnShow event
    9. Start page-level timers
   10. Notify all plugins that page has finished loading
   11. (... process events ...)

Switch file

    1. Notify all plugins that file is going to be changed
    2. Unload all pages/objects/plugins that belong to current
       file except for current page
    3. Load new XML file
    4. Initialise system-level plugins from new file
    5. Notify all plugins that page is going to be changed
    6. Fire current page's OnUnload event
    7. Stop any timers owned by current page
    8. Unload any plugins owned by current page
    9. Load page-level plugins for first page from new file
   10. Fire page OnLoad event
   11. Display page
   12. Fire page OnShow event
   13. Start page-level timers
   14. Notify all plugins that page has finished loading
   15. Notify all plugins that file has finished loading
   16. (... process events ...)

Quit

    1. Fire system OnQuit event
    2. Fire current page's OnUnload event
    3. Unload all pages/objects/plugins
    4. Uninitialise interface plugin
    5. Exit

Chapter 5. Object Reference

   Table of Contents

   Introduction
   Label

        Properties

   System

        Properties
        Methods
        Events

   Picture

        Properties
        Methods

   ToggleButton

        Properties
        Methods
        Events

   ScrollBar

        Properties
        Methods
        Events

   TextField

        Properties
        Methods
        Events

   ListBox

        Properties
        Methods
        Events

   Timer

        Properties
        Methods
        Events

   Page

        Properties
        Events

Introduction

   This section provides a reference for all of the types of
   widgets and objects available in eboxy (from scripts or within
   plugin code).

Label

   Label widgets are for displaying text.

Properties

   Label widgets have the following attributes/properties:
   Property Description Required In template Default Script
   name The name of the widget No N/A _labelnn Read-only
   x Horizontal screen position Yes No N/A Yes
   y Vertical screen position Yes No N/A Yes
   width Width of the widget No Yes None Yes
   height Height of the widget No Yes None Yes
   template Template to base the widget on No N/A N/A No
   caption Text to display in the label No No None Yes
   visible Whether or not the widget is shown No N/A True Yes
   font Truetype font file to use Yes* Yes N/A Yes
   fontcolor Colour to use for the text No Yes #FFFFFF Yes
   fontsize The size of the text (in points) No Yes 16 No
   textalign Text alignment No Yes left Yes
   autosize Autosize the widget to the text or not No Yes false
   Yes
   wordwrap Automatically wrap the text to multiple lines No Yes
   false Yes

   *: Must be specified either in the template or in widget
   itself

   Label widgets have no methods or events.

System

   System is a special object, of which there is only one
   instance. It provides access to some global functions in
   eboxy. The System object has a section in the XML, but no
   attributes.

Properties

   The System object has the following properties:
   Property     Description                              Script
   name         The name of the object (always "System") Read-only
   screenwidth  Width of the eboxy screen                Read-only
   screenheight Height of the eboxy screen               Read-only
   currentfile  Currently loaded XML skin file           Read-only
   version      eboxy version string (eg. 0.4.0)         Read-only
   pagecount    Number of loaded pages                   Read-only

Methods

   The following methods are supported by the system object:
   Method Description
   focusnext() Jumps to the next widget
   focusprevious() Jumps to the previous widget
   performaction(actionname) Perform the specified action.
   Accepts the same actions as for used for key bindings.
   printpluginlist() Prints out a list of loaded plugins to the
   console
   quit() Quits eboxy
   getpage(index) Gets the name of the page at the specified
   index in the list (0 to system.pagecount)
   gotopage(pagename) Jumps to the specified page. Alternative to
   the page command for instances where you already have a string
   with the page name to go to.
   selectfocused() Presses the focused button/chooses the
   selected item in a listbox

Events

   The following events are triggered by the system object:
   Event Description
   OnLoad Occurs when the file is loaded (just before the first
   page is shown)
   OnShow Occurs just after the first page has been displayed,
   and after eboxy is unhidden
   OnHide Occurs just before eboxy is hidden (with the exechide
   script command)
   OnUnload Occurs just before eboxy is unloaded

Picture

   Picture widgets are for displaying static images loaded from a
   file. Their width and height are set to the size of the image
   file.

Properties

   Picture widgets have the following attributes/properties:
   Property Description Required In template Default Script
   name The name of the widget No N/A _picturenn Read-only
   x Horizontal screen position Yes N/A N/A Yes
   y Vertical screen position Yes N/A N/A Yes
   image The image file to display Yes N/A None Yes
   visible Whether or not the widget is shown No N/A True Yes

Methods

   The following methods are supported by picture widgets:
   Method        Description
   reloadimage() Reloads the image file from disk.

ToggleButton

   Togglebuttons provide a way for a user to set a boolean value
   (also known as checkboxes in other systems). Of course these
   don't have to look like checkboxes - just something with two
   states. There is no built-in text caption - use in conjunction
   with a label if you need this.

Properties

   Property Description Required In template Default Script
   name The name of the widget No N/A _togglebuttonnn Read-only
   x Horizontal screen position Yes No N/A Yes
   y Vertical screen position Yes No N/A Yes
   width Width of the widget No Yes None Yes
   height Height of the widget No Yes None Yes
   template Template to base the widget on No N/A N/A No
   visible Whether or not the widget is shown No N/A True Yes
   normalimage The image file to display when the togglebutton is
   unchecked No Yes None Yes
   normalfocusimage The image file to display when the
   togglebutton is unchecked and has the focus No Yes None Yes
   checkedimage The image file to display when the togglebutton
   is checked No Yes None Yes
   checkedfocusimage The image file to display when the
   togglebutton is checked and has the focus No Yes None Yes
   enabled Whether or not the button is enabled (not currently
   used) No No true Yes
   checked Whether or not the togglebutton is checked No No false
   Yes
   action User action to bind to the togglebutton No No None No

Methods

   The following methods are supported by togglebutton widgets:
   Method     Description
   setfocus() Give focus to the togglebutton.

Events

   The following events are triggered by togglebutton widgets:
   Event       Description
   OnClick     Occurs when the button is clicked.
   OnGotFocus  Occurs when the button receives focus.
   OnLostFocus Occurs when the button loses focus.

ScrollBar

   Scrollbar widgets allow the user to slide a knob along a
   vertical or horizontal track in order to select a numeric
   value. eboxy scrollbars currently do not have buttons, so they
   are equivalent to "sliders" in some other systems. The
   combination of the width and height attributes determines if
   the scrollbar behaves horizontally or vertically (horizontally
   if the scrollbar is wider than it is high, vertically if it is
   higher than it is wide).

Properties

   Scrollbar widgets have the following attributes/properties:
   Property Description Required In template Default Script
   name The name of the widget No N/A _scrollbarnn Read-only
   x Horizontal screen position Yes No N/A Yes
   y Vertical screen position Yes No N/A Yes
   width Width of the widget Yes Yes None Yes
   height Height of the widget Yes Yes None Yes
   template Template to base the widget on No N/A N/A No
   visible Whether or not the widget is shown No N/A True Yes
   background The image file to display as the scrollbar
   background No Yes None Yes
   backgroundstyle How to draw the image (tiled or normal) No Yes
   normal Yes
   knob The image file to display as the scrollbar knob No Yes
   None Yes
   knobfocus The image file to display as the scrollbar knob when
   the scrollbar has the focus. If specified, must be the same
   size as the normal knob image. No Yes None Yes
   reversed Whether or not to reverse the display direction
   (normal meaning left or top being the minimum value). No Yes
   false Yes
   maximum The maximum value of the scrollbar No Yes 100 Yes
   minimum The minimum value of the scrollbar No Yes 0 Yes
   pagestep The amount to step the value by when paging up/down
   No Yes 10 Yes
   value The position of the scrollbar Not in XML N/A 0 Yes

Methods

   The following methods are supported by scrollbar widgets:
   Method     Description
   setfocus() Give focus to the scrollbar.

Events

   The following events are triggered by scrollbar widgets:
   Event       Description
   OnChange    Occurs when the value of the scrollbar is changed.
   OnGotFocus  Occurs when the scrollbar receives focus.
   OnLostFocus Occurs when the scrollbar loses focus.

TextField

   Textfield widgets allow the user to enter text.

Properties

   Textfield widgets have the following attributes/properties:
   Property Description Required In template Default Script
   name The name of the widget No N/A _textfieldnn Read-only
   x Horizontal screen position Yes No N/A Yes
   y Vertical screen position Yes No N/A Yes
   width Width of the widget No Yes None Yes
   height Height of the widget No Yes None Yes
   template Template to base the widget on No N/A N/A No
   visible Whether or not the widget is shown No N/A True Yes
   background The image file to display as the textfield
   background No Yes None Yes
   backgroundfocus The image file to display as the textfield
   background when the textfield has the focus No Yes None Yes
   backgroundstyle How to draw the image (tiled/normal) No Yes
   normal Yes
   font Truetype font file to use Yes* Yes N/A Yes
   fontcolor Colour to use for the text No Yes #FFFFFF Yes
   fontsize The size of the text (in points) No Yes 16 No
   borderx Horizontal amount of border to leave around the
   outside of the textfield No Yes 0 Yes
   bordery Vertical amount of border to leave around the outside
   of the textfield No Yes 0 Yes
   maxlength The maximum length of the text No Yes 255 Read-only
   validchars Regular expression to verify entered characters,
   eg. [0-9] would allow only numbers to be entered. Does not
   affect setting the text property directly. If empty, no
   validation is done. No Yes (empty) Yes
   text The text entered into the textfield Not in XML N/A
   (empty) Yes
   cursorpos Cursor position (0 to length of text). If set to
   greater than the length of the text, the cursor will be placed
   at the end of the text. Not in XML N/A N/A Yes

   *: Must be specified either in the template or in widget
   itself

Methods

   The following methods are supported by textfield widgets:
   Method     Description
   setfocus() Give focus to the textfield.

Events

   The following events are triggered by textfield widgets:
   Event       Description
   OnChange    Occurs when the text is changed.
   OnGotFocus  Occurs when the textfield receives focus.
   OnLostFocus Occurs when the textfield loses focus.

ListBox

   Listboxes are for providing the user with a choice from a list
   of text items.

Properties

   Listbox widgets have the following attributes/properties:
   Property Description Required In template Default Script
   name The name of the widget No N/A _listboxnn Read-only
   x Horizontal screen position Yes No N/A Yes
   y Vertical screen position Yes No N/A Yes
   width Width of the widget No Yes None Yes
   height Height of the widget No Yes None Yes
   template Template to base the widget on No N/A N/A No
   visible Whether or not the widget is shown No N/A True Yes
   font Truetype font file to use for the list items Yes* Yes N/A
   Yes
   fontcolor Colour to use for the text No Yes #FFFFFF Yes
   fontsize The size of the text (in points) No Yes 16 No
   background The image file to display behind the list No Yes
   None Yes
   backgroundfocus The image file to display behind the list when
   the listbox has the focus No Yes None Yes
   backgroundstyle How to draw the image (tiled/normal) No Yes
   normal Yes
   selitembackground The image file to display behind the
   selected item No Yes None Yes
   selitembackgroundfocus The image file to display behind the
   selected item when the list has the focus No Yes None Yes
   selitembackgroundstyle How to draw the image (tiled/normal) No
   Yes normal Yes
   selitemfontcolor The colour of the selected item's text No Yes
   #FFFF00 Yes
   scrollbar Whether or not to show the scrollbar (on/off/auto)
   No Yes auto Yes
   scrollbarbackground The image file to use for the scrollbar
   background No Yes None Yes
   scrollbarbackgroundstyle How to draw the image (tiled/normal)
   No Yes normal Yes
   scrollbarknob The image file to use as the knob (handle) of
   the scrollbar No Yes None Yes
   scrollbarwidth The width of the scrollbar No Yes 16 Yes
   borderx Horizontal amount of border to leave around the
   outside of the list No Yes 0 Yes
   bordery Vertical amount of border to leave around the outside
   of the list No Yes 0 Yes
   itemborderx Horizontal amount of border to leave around the
   text of each item No Yes 0 Yes
   itembordery Vertical amount of border to leave around the text
   of each item No Yes 0 Yes
   itemheight Height of each item in the list No Yes (height of
   text) Yes
   selectedindex Index of selected item Not in XML N/A N/A Yes
   selectedtext Text of selected item Not in XML N/A N/A
   Read-only
   count Number of items in list Not in XML N/A N/A Read-only

   *: Must be specified either in the template or in widget
   itself

Methods

   The following methods are supported by listbox widgets:
   Method                   Description
   setfocus()               Give focus to the listbox.
   additem(text)            Add an item to the list
   removeitem(index)        Remove an item from the list
   removelastitem()         Remove the last item from the list
   clear()                  Remove all items from the list
   setitemtext(index, text) Set the text of an item in the list

Events

   The following events are triggered by listbox widgets:
   Event Description
   OnSelectionChange Occurs when the selected item changes in the
   listbox.
   OnEmpty Occurs when the listbox becomes empty.
   OnChoose Occurs when the user chooses an item from the list
   (by pressing the enter key or double-clicking with an item
   selected).
   OnGotFocus Occurs when the listbox receives focus.
   OnLostFocus Occurs when the listbox loses focus.

Timer

   Timers, while not widgets strictly speaking, are defined in
   the same way as widgets. They allow you to define a recurring
   timed event. Timers may be associated with pages or the system
   object - the difference being that timers associated with
   pages are only able to be running when that page is visible.

Properties

   Timers have the following attributes/properties:
   Property Description Required In template Script
   name The name of the timer No _timernn Read-only
   interval Number of milliseconds between each OnTimer event Yes
   N/A Yes
   enabled Whether the timer is running or not No false Yes

Methods

   The following methods are supported by timers:
   Method Description
   start() Start the timer. Equivalent to setting the enabled
   property to true.
   stop() Stop the timer. Equivalent to setting the enabled
   property to false.

Events

   The following events are triggered by timers:
   Event Description
   OnTimer Occurs each time the specified interval has elapsed
   (when the timer is enabled/started). You can make it a
   one-shot timer by just stopping the timer within this event.

Page

   Pages are the "screens" or "forms" of eboxy. The current page
   is accessible to scripts using the currentpage special object.

Properties

   Pages have the following attributes/properties:
   Property Description Required Default Script
   name The name of the page Yes N/A Read-only
   background The image file to display in the background No None
   Yes

Events

   The following events are triggered by pages:
   Event    Description
   OnLoad   Occurs when the page is loaded
   OnShow   Occurs just after the page has been displayed
   OnUnload Occurs just before the page is unloaded

Chapter 6. Miscellaneous

   Table of Contents

   Other documentation
   Troubleshooting

        Known problems

   Future
   Author and Updates

Other documentation

     * ChangeLog - briefly describes changes between each
       version.
     * ReleaseNotes - describes the impact of changes in each
       version. Worth reading if you are upgrading from a
       previous version of eboxy.
     * TODO - lists planned and possible changes to eboxy in
       future versions.
     * Manpage - type man eboxy to get a description of eboxy's
       command line options.
     * eboxy Extension Guide - developers' manual for creating
       extensions to eboxy.

Troubleshooting

     * eboxy cannot determine what resolution fullscreen should
       use, so if you want anything other than 640x480 (the
       default) you will need to specify it with the --width (or
       -x) and --height (or -y) options. You can also specify
       this in the configuration file. With --fullscreen (or -f)
       specified, eboxy will attempt to change to the specified
       screen resolution if it isn't already active, if the
       resolution is supported by your system. Note that SDL will
       use the best available output method (X11, framebuffer,
       etc.). See also Controlling video output.
     * If you are using eboxy full-screen with LIRC in X, there
       is a problem that you may need to work around. With
       certain window managers, or no window manager at all,
       focus may not be correctly passed to other applications
       when you use any of the exec* script commands, and so LIRC
       commands won't be ignored while the external program is
       running, which could be bad if you use some of the same
       remote buttons in external applications as you do in
       eboxy. So far the only workaround for this is to use a
       window manager that transfers the focus properly - twm
       does not work, but fvwm2, papuawm and KDE's kwm are known
       to work. If you use fvwm2, you will need to use a
       configuration similar to the following (in ~/.fvwm2rc):
Style * NoTitle, BorderWidth 0, HandleWidth 0, ClickToFocus
       ClickToFocus is the most important setting - the others
       just reduce the interruption a second or two after eboxy
       regains focus, as it becomes full-screen again
       (unfortunately the transition is still visible, however).
     * The mouse cursor may interfere with your GUI whether
       you're using it or not. If the GUI starts with the cursor
       over the top of a button then that button will be selected
       first. If you don't like this (you probably won't if
       you're not using the mouse) then specify the --hidecursor
       (or -h) command line option, which both hides the mouse
       cursor and moves it to the top left hand corner of the
       graphics area before bringing up the GUI.
     * If you modify an image file that eboxy is using while it
       is running, eboxy will not reload that image even if you
       reassign the image property of the widget that is
       displaying it - images are cached, as are fonts. The only
       time the cache is reloaded is if you use the "exechide"
       command. However, if you wish to reload an image being
       displayed in a picture widget, you only need to call its
       reloadimage() method in a script and the image will be
       reloaded from disk.

Known problems

     * If you overlap two button images, you won't see PNG
       transparency working the way you might expect. Images are
       transparent onto the background only. It's generally best
       to avoid overlapping widgets at the moment.
     * Newer versions of libxml2 do not seem to validate against
       the DTD properly (ie, invalid elements are allowed).
       Future versions of eboxy will do the validation
       internally.
     * The script parser produces somewhat unhelpful error
       messages.
     * eboxy does not use the attribute defaults defined in the
       DTD - these are hardcoded into the application.
     * There have been some reports of flickering when using
       eboxy with framebuffer output. This is due to drawing
       issues with SDL_gui, and will be fixed when eboxy changes
       over to a different GUI library.
     * When eboxy hides its GUI (ie, when exechide is used in a
       script) it in fact unloads everything from memory,
       deinitialises the graphics library and then waits while
       the program runs. When the program finishes, eboxy loads
       itself back up. You will always get back to the correct
       page, but the "state" will be lost. I hope to correct this
       in the future if I can figure out a better way of doing
       the hiding.
     * eboxy does not purge its image/font cache while running
       unless exechide is called. This could be an issue if you
       are designing an image browsing screen and load lots of
       images.
     * The autoconf/automake build setup for eboxy is slightly
       broken, in that make dist doesn't really work properly and
       the --enable-debug option to configure doesn't work
       either. To build with debugging symbols, just run the
       following:
        dwdd

Future

   The listing below (a copy of the TODO file) should give you
   some idea of the general direction I'd like to take eboxy in
   the future. There are certainly plenty of things that could be
   improved and extended, and suggestions are welcome.

eboxy 0.4.0 todo list
=====================

Current:
- Test usage of system.xml file
- Test external plugins
- Remove -ggdb from plugin makefiles
- Do a build check on Fedora, Knoppix

Planned for next release:
- Listbox: methods to set/retrieve entire list
- Better range/validity checks for property values
- aedGUI-based interface plugin
- Allow enumeration of widget types
- Joystick support
- Global actions
- External control plugin
- Capslock/numlock for digit input
- Allow configuration of digit input key characters
- Fix synchronisation on changePage/changeFile
- Code tidy-ups
  - Fix warnings
  - Tidy up code for OwnerObject/ObjectContainer/Notify
  - Tidy up any remaining old code (main, pluginmanager, utils)
  - Remove relative paths from includes?

Planned for future releases:
- Default templates
- Document code
- Purge image/font cache
- 640x480 version of eBox skin
- Validate XML internally
- C++ plugin wrapper
- Provide "event" object within event scripts to get source etc.
- Add "either" alt,ctrl,shift,win (non-modifier) key aliases
- Enable use of numlock & capslock as key modifiers
- Directional widget navigation (up, down, left, right)
- Additional widgets: progressbar, spinedit?
- Make mouse auto-focus optional
- Better example skin(s)
- Improvements to exechide - more persistent information?
- Scrollbar buttons
- Plugin communication
- Testing/fixing with framebuffer and other SDL-supported graphics outp
uts
- Better support for overlapping widgets
- Background music and event sounds
- Video file browser plugin
- TV recording plugin
- Web control plugin
- Improved error handling/messages for scripts
- Proper packaging (RPM, etc.)

Possible future features: (email bluelightning@bluelightning.org if any
 of
these interest you)
- Allow config files in /etc/eboxy/
- Python bindings for plugin development
- i18n support through GNU gettext
- Config file for plugins to access
- Flat-colour macros as image substitutes
- Default system templates
- Page templates
- Custom widgets
- Tools for verifying/converting/querying skin files
- Optionally scale widget positions to screen size, given native resolu
tion
  of page
- Static rectangular border widgets
- Optional background image stretching
- Other input/control devices
- System stats plugins (use uptime, uname, lm_sensors, etc.)
- Animated/video backgrounds
- In-GUI shell prompt/output
- Listen for keypresses in the console as well
- Built-in configuration/setup plugins/skins/features
- Serialisation
- Page editor plugin

Author and Updates

   eboxy was written Paul Eggleton, with small contributions from
   others. I welcome any comments, questions, suggestions, or
   patches that people might have. Email me at
   <bluelightning@bluelightning.org> or post a message to the
   eboxy-users mailing list at
   <eboxy-users@lists.sourceforge.net>. There is also an online
   discussion forum at eboxy.sourceforge.net/forum.

   You can download updated versions of eboxy and get the latest
   news by visiting the eboxy homepage at eboxy.sourceforge.net.

Chapter 7. Copyright and Disclaimer

   eboxy is Copyright 2004 Paul Eggleton
   <bluelightning@bluelightning.org>. See the file AUTHORS for a
   list of contributors; individual source files may contain
   other attributions.

   This program is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public License as
   published by the Free Software Foundation; either version 2 of
   the License, or (at your option) any later version.

   This program is distributed in the hope that it will be
   useful, but WITHOUT ANY WARRANTY; without even the implied
   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
   PURPOSE. See the GNU General Public License for more details.

   You should have received a copy of the GNU General Public
   License along with this program; if not, write to the Free
   Software Foundation, Inc., 59 Temple Place - Suite 330,
   Boston, MA 02111-1307 USA, or get it online at
   http://www.fsf.org.

   Note: the sample skin contains neuropol.ttf, a freeware font
   by Ray Larabie which has its own (very reasonable) licence
   conditions. Please see the file neuropol.txt for details.
