GXINE APPEARANCE HOWTO
----------------------

There are four files which specifically control gxine's appearance. These
files will normally be found in /etc/gxine or /usr/local/etc/gxine, but you
can override them in ~/.gxine.

  gtkrc
  toolbar-window.xml
  toolbar-fullscreen.xml
  keypad.xml

gtkrc is a normal GTK RC file and is beyond the scope of this document.

The other three files describe the toolbar panels and the keypad window.

(For the keypad window, you need a top-level <window>; for the others, which
do not use <window>, you should use <hbox>, <vbox> or <table> as the
top-level container.)


Top-level elements
==================

<gettext />
	Top-level element. Used to indicate where to find translations of
	TEXT strings (prefixed with "~") in this XML file.

	domain="STRING"
		Use "gxine.theme.STRING" as the domain. Translations are
		expected to be found below ~/.gxine, much as others are
		found below /usr/share/locale; the files have the same
		format.

	If you omit this element or fail to specify a domain, then the
	default "gxine.theme" is used.

<window>
	Top-level element. Used only for the keypad window.

Widgets
=======

Properties common to all widgets:

	id="NAME"	label for Javascript object representing this widget
	name="NAME"	gtkrc style selection
	tip="TEXT"	tooltip for the widget
	width=PIXELS	widget's requested width
	height=PIXELS	widget's requested height
	onshow="JS"	execute this when the widget is automatically shown
	onhide="JS"	execute this when the widget is automatically hidden
	listen="OBJECT"	listen for changes to OBJECT.v (e.g. settings objects)
	onchange="JS"	execute this when OBJECT.v is changed
	accept-drop=BOOL accept files (or URIs) which are dropped here
	autoplay=BOOL	whether to auto-play the (first) dropped file/URI

	* All on<event> scripts are effectively object methods. This means
	  that you can call set_show() etc. without needing to use the
	  widget.OBJECT prefix.

	* If you use onchange to show or hide widgets, you'll probably also
	  need onshow for those widgets.

<arrow />
	Stock arrow.

	type="TYPE"	arrow direction ("right", "left", "up", "down")
	shadow="SHADOW"	border type ("none", "out", "in", "etched-out",
				     "etched-in")

<button>
	Clickable button.

	stock="STOCK"	stock item, e.g. "gtk-media-forward"
	label="LABEL"	text label for the item (if stock is not present)
	image="STOCK"	stock image for the item (if stock is not present)
		* If none of the above attributes are present, then the
		  button's content is created from child widgets and the
		  button acts as an <hbox>.
	alt="LABEL"	text to use if STOCK is unknown
			(if image is used, label must be undefined)
	relief="RELIEF"	button border style ("normal", "half", "none")
	mnemonic=BOOL	whether the button has an Alt-key shortcut
	onclick="JS"	execute this when the widget is clicked

	* If creating an image button, a named icon will be used if there is
	  no stock item with the given name and there is no alt text.

<control />
	A gxine standard control widget.

	type="TYPE"	widget type (see below)
	mode="MODE"	override for spin buttons and sliders (see below)
	vertical=BOOL	whether the slider is horizontal or vertical
	show-value=BOOL	whether the slider's value is shown
	inverted=BOOL	whether the slider's "increment" direction is reversed
	popup=BOOL	whether the slider is presented in a pop-up

	Widget types:
	    Buttons:
		play, forward, pause
		stop		Hard stop (always stops the stream)
		soft-stop	Soft stop (for vdr MRLs, tells vdr)
		mute
	   Spin buttons:
		audio channel
	   Sliders:
		stream		position within stream (slider)
		compressor, amplifier, a/v sync
		hue, saturation, contrast, brightness
		volume
		eq-30		graphic equaliser, 30Hz
		eq-60		60Hz
		eq-125, eq-250, eq-500, eq-1k, eq-2k, eq-4k, eq-8k, eq-16k
				etc. up to 16kHz

	Spin/slider mode override:
	    slider	render as a slider, using the 'vertical' attribute
	    hslider	render as a horizontal slider
	    vslider	render as a vertical slider
	    spin	render as a spin button

	If the 'popup' property is set, then the slider is presented as a
	button with a pop-up window. As such, the slider acts as a <button>,
	except that you cannot use the 'onclick' property. In addition, the
	following properties are available:

	window-width=INT	the width of the window (default auto)
	window-height=INT	the height of the window (default auto)

	A vertical slider will normally be presented below the button and a
	horizontal slider to one side (according to the normal text direction);
	if it wouldn't be fully on-screen there, it'll be shown on the
	opposite side.

<flipbutton>
	THIS UI ITEM IS NOT CURRENTLY IMPLEMENTED.
	Clickable button, requiring two child widgets for the "off" and "on"
	states (in that order).

	activate="JS"	execute this when the widget is activated
	deactivate="JS"	execute this when the widget is deactivated

<hbox>
<vbox>
	Container widget.

	homogeneous=BOOL	child widgets have the same available space?
	expand=BOOL		whether child widgets get unused space
	fill=BOOL		whether child widgets fill their space
	padding=NUM		spacing between widgets (default is 2 pixels)

	Child widgets may override expand, fill and padding with box-expand,
	box-fill and box-padding. (The naming is to avoid clashes due to
	nested box widgets.)

  <end />
	Special child element of <hbox> or <vbox>. Elements following this are
	packed at the end of the box rather than at the start.

<hseparator />
<vseparator />
	Separator line widget.

<image />
	Stock image.

	stock="STOCK"	image name
	size="SIZE"	image size ("button", "menu", "small-toolbar",
				    "large-toolbar", "dnd" = "drag-drop",
				    "dialogue" = "dialog")
	alt="LABEL"	text to use if STOCK is unknown

	* A named icon will be used if there is no stock item with the given
	  name and there is no alt text.

<label />
	Text label.

	text="TEXT"	label text
	markup=BOOL	whether the label uses Pango markup
	mnemonic="NAME"	whether the label has a shortcut for another widget
			(with an 'id' attribute)
	width-chars=NUM	approximate width in characters
	wrap=BOOL	whether the text is word-wrapped

<table>
	Table widget. It is based on the HTML <table> element.
	Excess child widgets are ignored.

	rows=NUM		number of rows
	cols=NUM		number of columns
	homogeneous=BOOL	child widgets have the same available space?
	spacing=NUM		space between rows and between columns
	x-padding=NUM		default horizontal padding for child elements
	y-padding=NUM		default vertical padding for child elements
				(default = x-padding)
	x-attach="ATTACH"	default horizontal attachment
				(comma-separated list of "expand", "fill",
				 "shrink")
	y-attach="ATTACH"	default vertical attachment
				(default = x-attach)

	The padding and attachment attributes may be overridden in <tr> and
	<td>.

  <tr>
	Table row; child of <table>.

    <td>
	Table cell; child of <tr>.

	colspan=NUM
	rowspan=NUM

<time>
<title>
	Time display and information display.

	small=BOOL		whether the widget is single-line or multi-line
