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:
#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._
) character. Reserved words used in the scripting language
are also not allowed. Each template and page must have a unique name.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.
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.
The commands available to you in a script are as follows:
Command | Description |
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.
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:
Code | Character produced |
\n | Newline |
\t | Tab |
\\ | Backslash |
\" | Double-quote |
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")
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.
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.
Key | Default function |
Left Arrow | Previous widget |
Right Arrow | Next widget |
Up Arrow | Previous list item |
Down 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:
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:
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
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).
Action | Function |
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: |
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.
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 |
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.
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. | |
-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. |
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.