1. Summary
  2. Files
  3. Support
  4. Report Spam
  5. Create account
  6. Log in

Xml Widget Format

From qutecsound

Revision as of 19:06, 7 April 2010 by Mantaraya36 (Talk | contribs)
Jump to: navigation, search

Contents

Goals of this Spec

To provide a cross-platform and cross-application format for widgets for musical and sound application control. It is designed for usage with Csound specifically, but should be able to accomodate other possibilities. Presets for widgets can be stored in xml elements explained in XmlPresetFormat .

Panels

All elements must be contained in Panels. Panels are separate and independent display regions, usually separate windows or tabs. A panel element can contain the following elements:

<bsbPanel>
  <label>STRING</label>
  <objectName>STRING</objectName>
  <x>INT</x>
  <y>INT</y>
  <width>INT</width>
  <height>INT</height>
  <visible>true/false</visible>
  <uuid>STRING</uuid>
  <bgcolor mode="background/nobackground">
    <r>DOUBLE 0-255</r>
    <g>DOUBLE 0-255</g>
    <b>DOUBLE 0-255</b>
  </bgcolor>
</bsbPanel>

The label is to be shown as the window title. The uuid and objectName can be used to identify the panel for programatic changes.

Panels can contain groups or individual widgets. If an element is not given, the behavior is undefined.

NOTE: In QuteCsound currently only the first panel present in the file will be used. All others are currently discarded.

Groups

When a widget part of a group, its x and y coordinates are relative to the group's coordinates. Group elements can have the following:

<bsbGroup>
  <label>STRING</label>
  <objectName>STRING</objectName>
  <x>INT</x>
  <y>INT</y>
  <width>INT</width>
  <height>INT</height>
  <visible>true/false</visible>
  <uuid>STRING</uuid>
  <bgimage mode="show/hide">STRING</bgimage>
  <bgcolor mode="background/nobackground">
    <r>DOUBLE 0-255</r>
    <g>DOUBLE 0-255</g>
    <b>DOUBLE 0-255</b>
  </bgcolor>
  <bordermode>noborder/border</bordermode>
  <borderradius>INT</borderradius>
</bsbGroup>

The label is to be shown as the window title. The uuid and objectNamecan be used to identify the panel for programatic changes.

If an element is not present, the behavior is undefined.

If a widget's location is beyond the size of the group, the behavior is undefined, it may or may not not be shown. It should be the user's responsibility to place widgets inside group boundaries. The IDE may provide warnings for this.

NOTE: This feature is scheduled for a future version of QuteCsound

Widgets

All XML widgets should have these sections:

<bsbObject type="BSBType" version="INT">
  <objectName>STRING</objectName>
  <x>INT</x>
  <y>INT</y>
  <width>INT</width>
  <height>INT</height>
</bsbObject>

There are no default values for these attributes and elements and they should always be present (if they are not, the behavoir is undefined). Version number is currently "2", to follow blue's convention. The following are optional tags:

<bsbObject type="BSBType" version="INT">
  <visible>true/false</visible>
  <uuid>STRING</uuid>
  <midichan>INT 0-16</midichan>
  <midicc>INT 0-127</midicc>
</bsbObject>

The widgets should be visible by default. The midicc and midichan tag indicate the MIDI channel and CC number which can control the widget. If midicc is -1, it means that the widget receives pitchbend on the defined channel, instead of a MIDI control change. This is disabled if this tag is not present, there should only be one pair of these MIDI tags. Channel 0 indicates all channels.

bsbObject type

The allowed types are:

BSBLabel

A simple label widget. It can contain the following elements:

<label>STRING</label>
<alignment>left/center/right</alignment>
<font>STRING</font>
<fontsize>INT</fontsize>
<precision>INT</precision>
<color>
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</color>
<bgcolor mode="background/nobackground">
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</bgcolor>
<bordermode>border/noborder</bordermode>
<borderradius>INT</borderradius>

precision determines the number of decimal places that the label text should show from a real number arriving through a widget's double value setting, rather than its string setting. The double value of the widget itself should not be truncated by the value of precision.

BSBSpinBox

A simple text entry widget. It can contain the following elements:

<alignment>left/center/right</alignment>
<font>STRING</font>
<fontsize>INT</fontsize>
<color>
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</color>
<bgcolor mode="background/nobackground">
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</bgcolor>
<resolution>DOUBLE</resolution>
<bordermode>noborder/border</bordermode>
<borderradius>INT</borderradius>
<minimum>DOUBLE</minimum>
<maximum>DOUBLE</maximum>
<value>DOUBLE</value>
<randomizable group="INT">true/false<randomizable>

randomizable specifies whether the widget's value should be changed when a randomized action is executed. A group value of 0 means it shouldn't be randomized. A different value specifies randomization group, so that only a subset of randomizable widgets is modified. a value of -1 indicates it should always be randomized.

BSBScrollNumber

A simple number widget which can be changed by dragging the mouse. It can contain the following elements:

<alignment>left/center/right</alignment>
<font>STRING</font>
<fontsize>INT</fontsize>
<color>
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</color>
<bgcolor mode="background/nobackground">
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</bgcolor>
<value>DOUBLE</value>
<resolution>DOUBLE</resolution>
<minimum>DOUBLE</minimum>
<maximum>DOUBLE</maximum>
<bordermode>noborder/border</bordermode>
<borderradius>INT</borderradius>
<randomizable group="INT">true/false<randomizable>
<mouseControl act="press/continuous/release"></mouseControl>

BSBTextEdit

A simple text entry widget. It can contain the following elements:

<label>STRING</label>
<alignment>left/center/right</alignment>
<font>STRING</font>
<fontsize>INT</fontsize>
<precision>INT</precision>
<color>
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</color>
<bgcolor mode="background/nobackground">
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</bgcolor>

BSBCheckBox

A Checkbox with a label to the right. It has the following optional elements:

<selected>true/false</selected>
<label>STRING</label>
<value>DOUBLE</value>
<randomizable group="INT">true/false<randomizable>

the value tag specifies the value the widget holds when it is selected or checked. Its state is stored by the selected tag.

BSBSlider

A Slider widget. It will be vertical if height > width and horizontal otherwise. It MUST have the following elements:

<minimum>DOUBLE</minimum>
<maximum>DOUBLE</maximum>
<value>DOUBLE</value>
<mode>lin/exp</mode>
<mouseControl act="press/continuous/release">jump/relative/none</mouseControl>
<resolution>DOUBLE</resolution>
<randomizable group="INT">true/false<randomizable>

It is suggested that the DOUBLE text has at least 8 decimal places. Scientific notation is allowed. For compatibility with Blue, this type can also be written as "BSBHSlider" or "BSBVSlider". However, the direction of the slider is determined by the rellation between the width and height of the widget.

BSBKnob

A Knob widget. It is suggested that its height and width be equal, but it's not a requirement. It MUST have the following elements:

<minimum>DOUBLE</minimum>
<maximum>DOUBLE</maximum>
<value>DOUBLE</value>
<mode>lin/exp</mode>
<mouseControl act="press/continuous/release">jump/relative/none</mouseControl>
<mode circular="true/false">hor/vert/round</mode>
<resolution>DOUBLE</resolution>
<randomizable group="INT">true/false<randomizable>

<mouseControl> determines mouse value generation. jump makes the value jump to the value in the position of the mouse. relative will cause relative changes to the value and release will only produce a value when the mouse button is released. <mode> refers to the interaction with the mouse with respect to vslue control. The circular attribute refers to whether the knob can jump from its maximum value to its minimum in a circular way.

BSBButton

A button. It should have the following elements:

<type>event/value/pictevent/pictvalue/pict</type>
<value>DOUBLE</value>

The <type> determines the behavior of the button.

* event: Only "execute" the text given by <eventLine>, but value behavior is undefined.
* value: Don't "execute" the text given by <eventLine>, but change value between 0 and <value>.
* pictevent/pictvalue: The same as before, but display a the picture from <image>
* pict: only display a picture. Other behavior undefined. (Should this be removed? Maybe all these categories should be removed?)

Buttons can have two values a number and a string, only the first one will be affected by the button's state. <stringvalue> contains the string value. It is suggested that the DOUBLE text has at least 8 decimal places. Scientific notation is allowed.

These are some options tags:

<stringvalue>STRING</stringvalue>
<text>STRING</text>
<image>STRING</image>
<eventLine>STRING</eventLine>
<latch>true/false</latch>

The <text> contains the text displayed inside the button. <image> contains the image filename (relative or absolute). <eventLine> contains the text to be executed (in the case of Csound a score event).

BSBDropdown

A menu or combobox widget.

<bsbDropdownItemList>
  <bsbDropdownItem mode="value/string">
    <name>Menu1</name>
    <value>DOUBLE</value>
    <stringvalue>STRING</stringvalue>
  </bsbDropdownItem>

 ...

  <bsbDropdownItem mode="value/string">
    <name>MenuX</name>
    <value>DOUBLE</value>
    <stringvalue>STRING</stringvalue>
  </bsbDropdownItem>
</bsbDropdownItemList>
<selectedIndex>INT</selectedIndex>
<randomizable group="INT">true/false<randomizable>

Any number greater than 0 of <bsbDropdownItem> elements may be included. <selectedIndex> must contain a valid index (i.e. be smaller than the number of <bsbDropdownItem> elements), the consumer application need not check the validity of it.

BSBGraph

A graphics widget to display graphs from the Csound graphs callback (f-tables, and graphs from display and dispfft). It should contain the following:

<value>INT</value>

A positive value indicates the index of the graphs (according to the order in which they were created). Negative values indicate f-table number.

Optional:

<all>true/false</all>
<zoomx>DOUBLE</zoomx>
<zoomy>DOUBLE</zoomy>
<dispx>DOUBLE</dispx>
<dispy>DOUBLE</dispy>
<modex>linear/db</modex>
<modey>linear/db</modey>

Should display a single graph unless the all tag is true. When a BSBGraph widget receives a value, it must switch to the index number of the table it holds (if it exists). Negative numbers are used to switch acording to f-table numbers.

Zoom values refer to the times the displayed size fits in the original size. For example a size of two will display half of the original. <dispx> and <dispy> set the start section of the graph to be displayed (always less than 1 and should be less than 1 - zoom value). For example if it is 0.75 it will show from the third quarter of the graph on.

BSBController

Recommended tags:

<objectName2>STRING</objectName2>
<xMin>DOUBLE</xMin>
<xMax>DOUBLE</xMax>
<yMin>DOUBLE</yMin>
<yMax>DOUBLE</yMax>
<xValue>DOUBLE</xValue>
<yValue>DOUBLE</yValue>
<type>fill/llif/line/crosshair/point</type>

Optional:

<mouseControl act="press/continuous/release">jump/relative/none</mouseControl>
<color>
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</color>
<bgcolor mode="background/nobackground">
  <r>DOUBLE 0-255</r>
  <g>DOUBLE 0-255</g>
  <b>DOUBLE 0-255</b>
</bgcolor>
<pointsize>INT</pointsize>
<fadeSpeed>DOUBLE</fadeSpeed>
<randomizable mode="x/y/both" group="INT">true/false<randomizable>

Should be vertical if height > width.

BSBScope

A scope widget. It should contain:

<type>scope/lissajou/poincare</type>

Optional:

<chan>INT</chan>
<zoomx>DOUBLE</zoomx>
<zoomy>DOUBLE</zoomy>
<dispx>DOUBLE</dispx>
<dispy>DOUBLE</dispy>
<mode>linear/db</mode>

A value for <chan of 0 means no channels, positive numbers indicate single channel numbers. Negative numbers are bit-and combinations of channels. For example -13 means use channels 1,3 and 4 (0001 & 0100 & 1000).

Zoom values refer to the times the displayed size fits in the original size. For example a size of two will display half of the original. <dispx> and <dispy> set the start section of the graph to be displayed (always less than 1 and should be less than 1 - zoom value). For example if it is 0.75 it will show from the third quarter of the graph on.

Widget Presets

Widget Presets can be stored like this:

<bsbPresets>
  <preset name="preset1" number="INT">
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
...
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
  </preset>
  <preset name="preset2" uuid="UUID STRING">
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
...
    <value id="UUID STRING" mode="1/2/3">DOUBLE/STRING</value>
  </preset>

</bsbPresets>

All presets have a name and a UUID. They contain the settings for a certain widget identified by UUID. Modes can be 1 for value1 (DOUBLE), 2 for value2 (DOUBLE) and 3 for STRING value.

TO DO

* Modes for knob: horiz/vert/round.
* Centered knob (with sticky center)
* Knob edge lock (para que no pase de 1 a 0 saltando, o de 0 a 1)
* Knob resolution (para que pueda saltar de uno en uno)
* Knob has height only, to be square always.
* Get the signal for a scope from a named audio channel, to probe in parts of a synthesis algorithm.
* Console widget with text size, font and color. Console background color.

Ideas

* Matrix widget? (matrix patcher)
* Panels should store necessary preferences (to allow standalone applications)
* Add Buttons bank and slider bank widgets
Personal tools