Subject: [linux-audio-dev] the new, annotated LADSPA-xml-gui DTD
From: Paul Barton-Davis (pbd_AT_Op.Net)
Date: Tue Nov 28 2000 - 17:57:01 EET
Some small changes since the last version, but more importantly,
annotations to try to explain what it all means. And oh yes, in case
anyone notices, I'm testing out an upcoming legal name change just to
see what it feels like.
--p
----------------------------------------------------------------------
<!--
Copyright (C) 2000 Paul Davis
This is an XML DTD designed to be used when writing an abstract
description of the graphical user interfaces for a LADSPA plugin.
This DTD is made available to you as a free specification; you can
redistribute it and/or modify it under the terms of the GNU
Library General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option)
any later version. This library is distributed in the hope that
it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU Library General Public License for more
details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
-->
<!ELEMENT interface (xml-gui-version,graphics-context?,packing-structure+)>
<!ELEMENT xml-gui-version EMPTY>
<!ATTLIST
major CDATA #REQUIRED
minor CDATA #REQUIRED
micro CDATA #REQUIRED
>
<!-- a graphics context provides a way of specifying the visual
appearance of a number of elements within the interface
that would otherwise use defaults.
the foreground and background attributes are a color
specification of the form
"R,G,B"
where "R", "G" and "B" are floating point numbers between 0 and
1.0. They defines the foreground and background colors used by
the element to which the context is attached.
the bg-pixmap attribute is a quoted string that references an
image to be used as the background of the element to which the
context is attached. it should not be (and cannot be) an absolute
pathname. it will be tiled if it is smaller than the area
occupied by the element, and cropped if larger. at this time,
how the string is interpreted is implementation-dependent.
the font attribute is a quoted string that references the
font to be used when drawing text in the element to which
the context is attached. unfortunately, the contents of
the string are entirely host-specific in this version of
the DTD.
-->
<!ELEMENT graphics-context EMPTY>
<!ATTLIST graphics-context
foreground CDATA #IMPLIED
background CDATA #IMPLIED
bg-pixmap CDATA #IMPLIED
font CDATA #IMPLIED
>
<!-- boxes are packing structures/containers.
a box contains a list of elements, each of
which will be arranged either horizontally
or vertically with respect to each other.
the spacing attribute specifies the number
of pixels between each element.
the border-width attribute specifies the number
of pixels of space that will exist around the
aggregated elements.
the homogenous attribute specifies whether
all elements will be space-packed as if
they were the same size. this only has
an effect if the element's pad and/or expand
attributes are set to true.
-->
<!ELEMENT vbox (box-element+)>
<!ATTLIST vbox
spacing CDATA IMPLIED
border-width CDATA IMPLIED
homogenous (true|false) "true"
>
<!ELEMENT hbox (box-element+)>
<!ATTLIST hbox
spacing CDATA IMPLIED
border-width CDATA IMPLIED
homogenous (true|false) "true"
>
<!-- a box element contains a single widget that
can packed into a box.
the pad attribute controls whether or not the
widget will be space-padded on either side
(in one direction, horizontal or vertical ONLY)
so that it occupies its maximum theoretical
space.
the expand attribute controls whether or not
any extra space that arises from the pad attribute being
"true" is used to actually make the widget larger,
or remains as space padding.
the at-end attribute, if "true", causes the element
to be packed at the end of the box, pushing any
existing end-packed-elements toward the start of the box.
the default packing mode is to pack elements from the start of
the box, pushing any start-packed elements towards the end of the
box.
-->
<!ELEMENT box-element (widget)>
<!ATTLIST box-element
pad (true|false) "true"
expand (true|false) "true"
at-end (true|false) "false"
>
<!-- a grid is a 2-dimensional array, with coordinates
that begin at 0 and extend to row-1 in the horizontal
direction and column-1 in the vertical direction.
a grid element may be attached to the grid, and can cover any
rectangular portion of the grid.
the vertically-homogenous attribute specifies whether or not all
elements will be packed together with space padding that gives
them all the same height. this only has an effect if the elements
pad and or expand options are set to true.
the horizontal-homogenous attribute is analogous to the
vertically-homogenous attribute, but operates
horizontally.
the spacing between each (possibly space-padded) element is
controlled by the vertical-spacing and
horizontal-spacing attributes, which have units of pixels.
the border-width attribute specifies in pixels the space that
will surround the aggregated elements.
-->
<!ELEMENT grid (grid-element+)>
<!ATTLIST grid
rows CDATA #REQUIRED
columns CDATA #REQUIRED
vertically-homogenous (true|false) "true"
horizontal-homogenous (true|false) "true"
vertical-spacing CDATA #IMPLIED
horizontal-spacing CDATA #IMPLIED
border-width CDATA #IMPLIED
>
<!-- a grid-element can be attached to a grid. the attachment points
are specified by two coordindates, given as the *-row, *-col
attributes. these coordindates are zero-based, as indicated
in the description of the grid element itself.
the other attributes operate as for a box-element, except
that because of the 2D nature of a grid, both vertical
and horizontal attributes are possible.
<!ELEMENT grid-element (widget)>
<!ATTLIST grid-element
upper-left-row CDATA #REQUIRED
upper-left-col CDATA #REQUIRED
lower-right-row CDATA #REQUIRED
lower-right-col CDATA #REQUIRED
vertical-padding CDATA #IMPLIED
horizontal-padding CDATA #IMPLIED
vertical-pad (true|false) "true"
vertical-expand (true|false) "true"
horizontal-pad (true|false) "true"
horizontal-expand (true|false) "true"
>
<!ELEMENT packing-structure (hbox|vbox|grid)>
<!ELEMENT widget (label|image|controller|pushbutton|connector)>
<!-- a label is just a piece of text. you can control the font and
color by including a graphics context with the text.
-->
<!ELEMENT label (graphics-context?, #PCDATA)>
<!-- an image is specified with a string that references a file.
At this time, the interpretation of the string is implementation-specific.
-->
<!ELEMENT image EMPTY>
<!ATTLIST image
path CDATA #REQUIRED
>
<!-- a controller is a visual element of the GUI that can be used
in various ways to set the value of a plugin port. it is
anticipated that this be used only for ports where a continuous
value range for the port makes sense.
it has a label, which though strictly optional, should always be
supplied for user-convenience. you can choose from knobs,
horizontal and vertical sliders, a "spinner" which is a screen
button that controls a numeric value. if you wish you can also
chooose the "image" type, and then specify "image-regexp" to
define a set of image files that will be mapped to represent the
possible values of the port (i.e. the minimum value will be
represented by the first (alphanumerically sorted) image and the
maximum value by the last).
-->
<!ELEMENT controller (graphics-context?)>
<!ATTLIST controller
port CDATA #REQUIRED
label CDATA #IMPLIED
label-position (top | bottom | left | right | upper-left | upper-right | lower-left | lower-right) "top"
type (knob | hslider | vslider | spinner | image) "knob"
image-regexp CDATA #IMPLIED
>
<!-- a state is an element that specifies both a value and how
that value should be represented in the GUI. The representation
can either be text or an image, but not both. if the text
attribute is used, it should contain a string which will be used
to represent the value specified in the value attribute. if the
image attribute is used, it should contain a string referencing
an image that will be used to represent the value specified
in the value attribute.
the interpretation of the image string is implementation-specific.
-->
<!ELEMENT state EMPTY>
<!ATTLIST state
value CDATA "0"
text CDATA #IMPLIED
image CDATA #IMPLIED
>
<!-- a push button is an element that can be used to control
a port with a discrete set of values.
it should be provided with a series of state elements,
which will be used by cycling through each value given
in the state elements when some appropriate user action
is taken (e.g. a mouse button click on the push button).
note: it is expected that all states provided use
either a textual representation or an image representation.
mixing the two will lead to undefined results.
-->
<!ELEMENT pushbutton (graphics-context?, state+)>
<!ATTLIST pushbutton
port CDATA #REQUIRED
label CDATA #IMPLIED
label-position (top | bottom | left | right | upper-left | upper-right | lower-left | lower-right) "top"
>
<!-- a connector is an element that will allow the user to
connect one port to another. how it actually does that
is at the discretion of the GUI implementation. Possible
options might include a popdown list of possible ports
to connect to, or draggable patch cords.
you should think of a connector as representing a
port that has no actual controller.
-->
<!ELEMENT connector (graphics-context?)>
<!ATTLIST connector
port CDATA #REQUIRED
label CDATA #IMPLIED
label-position (top | bottom | left | right | upper-left | upper-right | lower-left | lower-right) "top"
direction (input | output) "input"
>
<!-- a value display is an element that can be used to display
the current value associated with a port. it is expected to
be used with output plugin ports.
the style attribute indicates how the value will be displayed.
current values for this attribute are:
hmeter - a horizontal level meter
vmeter - a horizontal level meter
custom - values are mapped to a set of images
if the "custom" value is used, then the images attribute must
contain a regular expression referencing a set of images
to be used.
the interpretation of the regular expression is implementation-specific.
-->
<!ELEMENT value-display (graphics-context?)>
<!ATTLIST value-display
port CDATA #REQUIRED
label CDATA #IMPLIED
label-position (top | bottom | left | right | upper-left | upper-right | lower-left | lower-right) "top"
style (hmeter | vmeter | custom) "vmeter"
images CDATA #IMPLIED
>
This archive was generated by hypermail 2b28 : Tue Nov 28 2000 - 18:59:40 EET