Next Previous Contents

3. Usage

3.1 General Usage

eboxy's GUI system is defined in terms of widgets and pages. Widgets are things that can be displayed on pages - currently, buttons, pictures and label widgets are supported. Buttons are things that can be selected and pressed in order to perform some action; pages contain the widgets and take up the entire eboxy screen (you can have multiple pages). Buttons are visually defined by several 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.

eboxy needs an XML file that describes how to lay out the GUI, a "skin" file. XML is a language which appears similar to HTML, in that it has tags like <this>. There's a ton of info on the web about XML, and you probably know what it is anyway, so I won't bother going into it here. 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 menus into multiple XML files and use the load action to load one when a button is pressed (see further down in this document). This could be useful for providing custom menus on removable media, eg. CD-ROMs.

If you understand XML DTDs, you can get a good idea of what an eboxy XML file should look like by looking at the file eboxy/eboxy.dtd. Or, you could look at the example skin provided in skins/test. Otherwise, it's 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" pressedimage="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" fontcolor="#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" image="mybutton.png" selectedimage="mybutton-down.png" pressedimage="mybutton-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="mylabeltemplate">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 this will appear in the resulting display.

Notes:

3.2 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, you don't have to put in <event type="onclick">...</event>, 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 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:

CommandDescription
echo "text" Prints the specified text on the standard output. Mainly for testing.
exec "command" Runs the specified command. Control returns to the script immediately.
execwait "command" Runs the specified command, and waits until it has finished executing.
exechide "command" Runs the specified 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 into memory. More about plugins in the Plugins section.
delay "x" Wait for a specified number of milliseconds (1000ms = 1 second).
quit Quits eboxy.

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 on the current page. For example:

button1.caption = "new"

This means the widgets you want to refer to must be named (ie, have a name attribute). Certain properties are read-only.

eboxy scripts know only about strings - numbers and other types of data are all represented as strings eg. to change the colour of a label's text, you'd do the following:

label5.fontcolor = "#13F6CA"

Anywhere you can specify a string, you may instead specify a string expression. String expressions are built up of other strings. You may use property values in expressions as well. For example:

button1.caption = "Activate " + label1.caption
label5.caption = "X " + label2.caption + " X"

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

CodeCharacter produced
\nNewline
\tTab
\\Backslash
\"Double-quote

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

Finally, 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, and currently are not especially useful. "currentpage" refers to the currently visible page "focusedwidget" refers to the currently focused widget. You can use these as if they were the objects themselves, for example:

echo focusedwidget.name

eboxy scripts are fairly simple. They do not provide variables, conditional statements, arithmetic or loops. This is because they aren't meant to be used for programming - they are mainly for controlling and interacting with plugins. 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.

3.3 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, neither do all keys. 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.

KeyDefault function
Left ArrowPrevious widget
Right ArrowNext widget
Up ArrowPrevious list item
Down ArrowNext list item
Page UpPrevious list page
Page DownNext list page
HomeFirst list item
EndLast list item
EnterPress selected button/choose selected list item
EscapeQuit

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

Key nameKey
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 \
rightbracketRight 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:

Key nameKey
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

3.4 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


ActionFunction
prev Previous widget
next Next widget
accept Accept current selection/value. In the case of 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.
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: (a) that these actions do not actually do anything on their own and (b) that you should avoid using an action for anything other than its intended purpose, to avoid confusion. If an appropriately-named action for the purpose you require doesn't exist, please email me and I will add it in.

ActionSuggested 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
prevchannel Previous TV/radio channel/music track
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

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.

3.5 Command line options


ShortLongDescription
-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.
-h --hidecursor Hide the mouse cursor while eboxy is active.
--noaudio Do not try to initialise an audio device.
--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 Show key info when a keyboard key is pressed (useful for testing).
--help Quick command line help screen.
--version Display version info.

3.6 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. For it to work you need to be running lircd and you need to add the following definitions to .lircrc in your home directory:

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 specify 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.


Next Previous Contents