The eboxy User's Guide Paul Eggleton Sunday, 16 May 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 Controls Keyboard Joystick Actions Standard actions User actions Remote controls Command line options Configuration file Available settings Example 4. Customisation Introduction XML skin files Scripting Events Commands Properties & Expressions Comparison and boolean operators Methods Special objects Variables execwait() and execwaitcapture() Conclusion Reference Actionhandlers 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. Joystick key names 3.5. Standard actions 3.6. User actions 3.7. Command line options 3.8. 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. 2.6.7 or later recommended. * 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 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 Controls Keyboard Joystick Actions Standard actions User actions Remote controls Command line options Configuration file Available settings Example Controls Keyboard 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 Backspace Cancel (cancel user action) 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 Modifier name Modifier 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. Joystick Joystick events are handled in the same way as key presses. The following "key names" are used for joystick events (the bracketed button names only apply to some joysticks and gamepads, yours may be different): Table 3.4. Joystick key names Key name Joystick event joystickbutton1 Joystick Button 1 (A) joystickbutton2 Joystick Button 2 (B) joystickbutton3 Joystick Button 3 (X) joystickbutton4 Joystick Button 4 (Y) joystickbutton5 Joystick Button 5 (left trigger) joystickbutton6 Joystick Button 6 (right trigger) joystickbutton7 Joystick Button 7 joystickbutton8 Joystick Button 8 joystickbutton9 Joystick Button 9 joystickup Joystick Up joystickdown Joystick Down joystickleft Joystick Left joystickright Joystick Right joystickhatup Joystick Hat Up joystickhatdown Joystick Hat Down joystickhatleft Joystick Hat Left joystickhatright Joystick Hat Right Actions eboxy actions are the basis for controlling eboxy. They are used for standard key, joystick, 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.5. 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 and it will be added into the next version. Table 3.6. 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 (usually bound to a button that jumps to the previous page) 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. Alternatively if you don't need a button, or you want the action to be active no matter what page is showing, you can use an actionhandler. Note: the number* user actions are separate from digit input for entering text with the number pad. Remote controls 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. Command line options Table 3.7. 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. --nojoystick Disable joystick input. --nolirc Disable use of 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.8. 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 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 Actionhandlers 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: 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: As mentioned before, eboxy also supports picture and label widgets as well as buttons. Here's an example: 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 & < > ' or " 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 ( ). * 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. instead of ). * eboxy does not pay any attention to the DTD specified at the top of the file (indeed, you can leave out the 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 tag within the body of the item you want to attach the event to. For example: ... echo "the page is loading" # this is a comment echo "the page has been shown" echo "you can have as many commands as you like in a script" ... ... ... 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: ... echo "eboxy is loading" ... ... ... 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 ... is optional - if you wish, you can just put the script you want to run when the button is clicked inside the