﻿An information for AOSC preset developes.

At the time of writing, only one preset file azaosc.xml is supported. It is loaded from the directory of executable at the time AOSC starts.
Please note that in case the Confiuration is changed within the application, this file will be overwritten when you close the application.
During development I recommend backup that file frequently.

The file is is standard XML, UTF-8 encoded. Not ASCII characters are allowed in string literals, till restricted by protocol (OSC).
All comparison are case sensitive, so all keywords, type names and option parameters should be verbatim.

There can be up to 4 primary sections in the file.

I. <config> section describes general behaviour.
<osc> element is managed by the Configuration dialog.
<ping osc="/xremote" period=4000/> specify the command to send periodically to the target and the period of sending. Since OSC is not steam based,
end points normally expect some "ping".
I.1. <options> section specify AOSC behaviour in respect to communications
explicit_feedback="yes" in case end point is not sending whole information and all updates automatically, this option instruct AOSC to
ask all values explicitly, once they appear in the application. Note that is still not done on periodic basis, so if some perameters is implicitly
or explicitly changed, from this or other application, it can happened some information is not updates till corresponding controls are re-build.
local_echo="yes" AOSC assumes confirmation replay in case it change some value. If that is not the case, this option assume such reply was received.
tracker="focus" enable Tracker by default.

II. optional <ctrltypes> section allows control types definitions.
Some control parameters are naturally common for many controls, especially data ranges and appearens properties. Instead of specifying these parameters
in each control separately, it can be useful to define a Type and then inherit common properties from that Type. These properties still can be
re-defined for particular controls. Types can be inherited from already defined types, as long as the origin was define early in the file.

The format of type definition is equivalent to control (<ctrl>) definition (see later), with the following exceptions:
- only type, name, range and vtext properties are allowed
- name property defines the type, so it should be unique. This name is used as type value in following types and controls, to indicate the inheritance.
  Not a requirement, but current convention is use capital first character in all user defined type names. Application defined types are guarantied to be
  lower case only.

III. <templates>
Template allow reuse predefined list of controls, page or a tree of pages (see lated for definition of pages and controls), with applied text substitution.
F.e. you have several lists of controls, which differ just in 1-2 characters.

Templates are defined as pages or tree of pages (see later), top level page must have "tmpl" option which defines template name used in references.
Defined in references text substitution is applied to the following options of all controls and pages inside template:
type, name, prefix, suffix, osc, args, nameosc, valueosc, textosc, accel, var and when.
There is no strict rules about template names, keys and values, except as everywhere else quotas and double quotas characters can't be used.
But proposed convention is name templates like "ListOfSomething(par1,par2,par3)" and then use keys "{par1}", "{par2}" and "{par3}" only.
In such notation, each template name mention all required for final reference keys.

III.1 There are 2 ways to use templates. Inline or as pages.
Inline reference is specified by <ctrl> element with type="tmpl", name="<template name>" and replace="<replacement>" (only these options are allowed in references).
In this case the reference is replaced by the list of controls from specified template, with specified by replace substututions. Subpages from the template are ignored.

Page reference is specified by <page> element with name="<template name>" and replace="<replacement>" (only these options are allowed).
Page reference is replaces by the tree of specified template, including all subbages, with specified by replace substitutions.

Page and inline references are allowed in templates, so templates can be constructed from other templates. Substitution happens at the time of parsing.

III.2 "replace" is specified as a list of pairs in form replace="key1=value1;key2=value2;key3=value3". So, every appeares of mentioned keys will be replaces by
corresponding values. As mentioned before, there is no restrictions about keys and value, but there is procosed convention for keys. If you need '=' character
in a key or ';' character in value, you can include key or value into single quotes. Note there is no special interpretation for spaces, so key or value can
start or end with space.
Note: replace option can't be empty. In case you don't really want any substitution, for example to diplicate templates verbatim, use some key which is never
used insite template. F.e. replace="!!=". So, it will replace "!!" by empty string "". But in case "!!" is not used, nothing is replaced in practice.

When you use one template in another, keys will not clash since "replace" option itself is not substituted and substitution is not recursive. F.e. with
<page tmpl="X(i)" name="{i} template"/>
<page tmpl="Y(i)" name="X(i)" replace="{i}=Sub{i}"/>
and following reference (in <pages> section)
<page name="Y(i)" replace="{i}=Page"/>
will produce "SubPage template".

IV. <pages>
All controls in AOSC are organized into tree of pages. The tree is defined inside <pages> section.

IV. <page>
A page define as set of controls presented at once to the user. Only one page can be selected at any particular time.

Pages can have sub-pages, for easy navigation.

Page itself is a button control. In case <osc> parameter is specified for a page, it is sent when the page is selected.

All controls should be defined inside pages.

V. <ctrl> control definition.
One control is defined by one <ctrl> element with attributes.

All controls (and types) must have type and name attributes. All other attributes are optional.

All control types have the same attribute definitions, but some combination of attributes make no sence for particular control types.
F.e. a toggle can use 2 values only, only numerical values make sense for most control, and so on.

V.1. Control label
Every control and page has a label. Label is constructed from prefix, name and suffix. Prefix and suffix are optional.
Name can be exchanged by response from OSC, specified by nameosc atribute.
For example, <ctrl type=fader name="Channel 1" suffix="volume" nameosc="/ch1/name" osc="/ch/volume"/>
by default will have label "Channel 1 volume". But once "/ch/volume" message received with text, f.e. VOX, the label
will be "VOX volume".

V.2. Control value.
All controls except Pages use some kind of value and have corresponding control which represet it.
The value normally comes from some OSC message, which is specified by "osc" control attribute. That attribute also
specify OSC message to send (once) as the request to report current value (in case "explicit_feedback" configuration option is set).
Any future changes assumed to come without special requests, till "period" is specified (in seconds). In the last
case request message is periodically re-transmited. By default, the message is send without arguments. "req" attribute
can specify different OSC to request, with optional arguments.
V.2.a Text value
Text value is used by "edit" or "label" control. "edit" allows modify the value and send it to end point. "label" is read-only.
All other controls can't use text values.
V.2.b Numerical value
Supported are integers and floating point real numbers, both 32bit. These are standard in OSC. All controls can work with
numerical values.
V.2.c Bit value.
It is working with one bit in integer values, max in range specify the mask for the bit. So bit 0 has mask 1, bit 2 has mask 4.
All controls can work with bit value, but push is not practical for the perpose since it assumes no feedback value.
V.2.d Value from blob.
If "bvalue" attribute is specified, the value is taken from received blob. The value type is specified by the first character,
"iIfFhH" specify integer, float and short, in big endiad or little endian byte order. Shorts are 2 bytes, other are 2 bytes.
Following number specify absolute position inside the blob, in bytes. Separated by +, - or & another position can follow.
Resulting value is then maximum, minimum or an average of two values retrived from the blob (f.e. useful for stereo monitoring).
F.e. bvalue="H8+10" specify that 2 16bit shorts in little endian format shoud be taken from positions 8 and 10 and then
maximum of them is taken. bvalue="f4" means take 32bit float value in big endian format from position 4.

V.3. "range" control attribute.
Range attribute defines which numerical values are expected from end point, and more important which values should send AOSC.
In case any number in the specification has a dot "." character, values are sent as float. They are integers otherwise.
The format is 'range="min,max,default,steps". Min and max define minimum and maximum values, inclusive. Default is used
as default value, till it is received from the end point. There are plans to allow sending default value with special key.
Steps determine the number of ticks for faders, the number of choices in select and have special meaning for push buttons.
Default range for buttons is "0.0,1,0,2", for other controls "0.0,1,0,101". So, push sends "1" then "0", toggle  switch between
"0" and "1" and fader has 101 tick which sends values between "0.0" and "1.0".
For bit value, the format is 'range="0,<bit mask>,default,2". So, min should be 0, steps must be 2. default can be 0
or mask.

V.4. "vtext" control attribute.
VText attribute defines how protocol values should be converted into real world values.
"text" specify that text should be used as a value.
"number[;unit[;min;max]]" converts protocol numbers from "range" into specified "min"..."max" range. When range is not specified,
original protocol values are exposed. Unit text is appended to the value in text form. Numbers are represented "smart", values
over 1000 have suffix "k" and divided by 1000. In case Units starts from "m", f.e. "mSec", when the value is over 1000 "k" is
not added but "m" from Unit is removed in presentation. Smart rules also apply for "exp" and "log".
"log;unit;a;b" maps positive protocol values using formula "a * ln(b * value)", wheare a and b specified there. Such scale
is usual for volume in dB.
"exp;unit;min;max" maps any value using formula "a * exp(b * value)", such way that when range value is minimum the result is min
and when value is maximum the result is max. Such scale is normally used for frequencies, note it is still
called "logarythmic" in literatur, but technically it is exponential.
"pan" maps protocol value range to 100%left - center 100%right. When typing in "edit" control (or fader edit control), negative
values means left, percent can be ommited. So "-50", "50l", "50left", "50%left" all means the same.
"enum;val1;val2;val3[...]" specify text for numerical values. Normally the number of mentioned values should be to range.steps.
Range mapping with steps is applied, f.e. range="2,6,4,3" means val1,val2,val3 are "2","4","6", default "4".
"xlevel" is "log" like function, with fixed "dB" unit. But it is technically 4 linear interpolations of it, for better control.
Some software and hardware use that special scale which produce "-90dB" to "+6dB" for 0. to 1. protocol values.

For all specification except "enum", an extra attributes can be appended. Note, for that all optional attributes for the type
must be given first. Currently defined:
* fof - Freeze On Focus. Effective for 'label' control only, do not update control on incoming OSC when control is in focus.
Pressing Enter key updates the control. In case "fofmin" or "fofmax" is specified, minimum or maximum skipped value is set
on update next time, effectively remembering pikes between updates. Pike modes work with numerical values only.
* minf - use -inf character for text representing minimum value

An extra option "tap" specify that the value can be tapped by space, numerical result is in milliseconds so the range
should support corresponding numbers. Currently works in fader controls only.

V.5. "textosc" currently has old behaviour, feedback is appeneded to label. This parameters supposed to be end point driven
real world text. But it can't be edited for back convertion into protocol value. So for the moment I think it is "obsolete".

V.6. control types.
"label" and "edit", represet value specified by "vtext" (so can be text or numerical). "edit" allow changing the value.
"fader" is a trackbar control with range.steps ticks. In future version real world value will be auidable, at the moment it
is reported always from 0 to 100. Pressing "Enter" key opens edit field with real world value, pressing any character also
opens edit field but with value removed. "Enter" in the edit field submit the value, "Escape" cancel.
"push" currently checkbox which sends value, no feedback expected. If range.min and range.max are different, two messages
are sent, first range.max and then range.min. Othewise only one message is sent, with range.max.
"toggle" checkbox for toggle between range.min and range.max. If there is just one step specified, it always send range.max,
and indicate if feedback value is range.max.
"rtoggle" checkbox for toggle between range.max (not checked) and range.min (checked). If there is just one step specified,
it always send range.max and indicate if feedback value is not range.max.
"select" is a droplist of choices. Most usefull with "enum" style vtext, but it always represet range.steps choices and so
can be used with other vtext types.

V.7. dynamic control deactivation.
Any control which has integer value can declire "var" option, with format var="var_name". That declire global variable,
which integer value will change every time the value of any control which declair it (can be several) changes. Note that
variable change does not change the value of each such control.
Any control or page can have "when" option, with format when="var_name==<integer>" or when="var_name!=<integer>".
With such option specified, control is Active in case specified condition is true. So, when specified variable is
equal to value or not equal to value respectively.
The condition specified for page is propageted to all its controls, till they have own condition. It is not propageted to subpages.
Conditions specified in inline references are propagated and overwrite page conditions for template.
In current version the page itseld will not disappear from the tree when deactivated, but effectively it will have no controls.
Current intepded use is with specific controls or inline templates.

V.8. tracking.
AOSC can track external changes and focus corresponding control, effectively providing voice feedback for external operations.
Tracker prefer to keep current focused control, followed by control on the same page as current, followed by control priority set in XML.
Controls, pages and templates may have "track" option with positive numerical value. For pages, it specify default priority for
all controls in this page. Default priority is 50, current page bump it by 100, current control by 200. Proority 0 means that
control is not participating in election.

V.9. presets and clipboard
A preset is a list of controls from one page or page tree with corresponding values. Preset for page tree is called recursive preset.
Preset can be saved temporary and applied later using AOSC local clipboard, with copy/paste operations. Presets can be saved into and
loaded from files, from the Edit top menu.
Two pages are preset compatible in case there are the same or created from the same template. Which pages are preset compatible is up
to XML definitions author. Paste item in the Edit top menu indicate clipboard compatibility with current page.
In some configurations sub-pages should be avoided in recursive presets, that can be indicated by norp="" option, meaning Not in Recursive Preset, in the page or template
definition, this option can not be used in template instanciation. That option also influence Clipboard. The page marked such way still can be
copied or saved alone.

V.10. accelerators (shortcuts)
accel="[<level>]<scope><type><device>:<shortcut>[;<next acceleartor>[;...]]" parameter can specify accelerators for controls and pages.
Optional level is the number from 0 to 9, it means the accelerator is defined in parent page of that level. Default for controls is 0 and for pages is 1,
so controls accelerators are added to the page where control is defined, page accelerator is added to the parent page.
The scope defines when that accelerator is effective:
* 'l' for local,  works when focus is on page where this control or page is defined
* 'g' for global, works everywhere
* 't' for tree, works in current page and all subpages
The type defines what accelerator should do:
* 'n' for navigate, focus this page or control
* 'c' for click, should be used for buttons or toggles only
The only known device at the moment is 'k' for keyboard.
The shortcut for keyboard is key combination specification. Modification keys are 'a' 'c' 's' for alt, control or shift,
when used should be followed by '+'. The next lower case character specify the key. Upper case characted start key specification
by world, currently defined are F1 to F12 only.

Examples:
accel="gnk:s+t" means global navigate shortcut Shift+t
accel="tck:ac+F7" means tree click shortcut Alt+Control+F7.

When accelerators clash, local accelerators owerwrite global. System defined accelerators can't be redefined.
The list of currently active accelerators can be found in "Go to" and "Do" top menus, for navigation and operation acceleratos respectively.

Note that operation accelerators currently provide no notification. And they have no effect in case parameter was not synced yet.
