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" 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, 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 ( <![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.