Element listing and documentation

Navigation

• Installation / compatibility
• Initialization
• Actions
• JSON Domain Model
• Localisation
• [Element listing and documentation] (./Element-listing-and-documentation)
  • Notifiers and listeners
  • Element syntax
    • STitleBar
    • SDescription
    • SPane
    • SCheckBox
    • SGeneric
    • SButton
    • SSeekBar
    • SOptionList
    • SColourPicker
    • SLiveLabel

Notifiers and listeners ˄

Notifiers and listeners can be defined as element parameters inside the elements.

A notifier or listener's grammar is defined as:

The on-clause is defined as:

An EVENT is one of following:

• SET: Event at setting of a value in the element.
• RESET: Event at setting of a value to the defined default.
• REFRESH: Event at refreshing of a value from its action.
• APPLY: Event at application of a value.
• CANCEL: Event at cancellation of a value.

The do-clause is defined as:

An ACTION is an action, outside of the DOM and with discarded and non-evaluated return action-value. An action has the following variable tokens available:

• @SET: The set value of the element.
• @SAVED: The saved value of the element.
• @LIVE: The live value of the element. This will be freshly read on action execution.
• @ACTION: The element action identifier.

The to-clause is defined as:

A TARGET is an action identifier that must be defined in the DOM.

The do-clause takes one or more events on which a notification is triggered. For each triggering of an event, the do-clause is fired off. If the do-clause contains more events or actions, they are queued up and executed in the order in which they are defined. Each triggering is propagated to each of the members of the to-clause in the order in which they are defined.

The notify parameter is defined in the element on which the on events are triggered from, and executes the do events in the to elements.

The listen parameter is defined in the element on which the do events are executed on, and is triggered by the on events of the elements defined in to.

Example:

SOptionList:{
    title:"Current governor",
    description:"The governor in charge of CPUFreq scaling",
    default:ondemand-sec,
    action:"generic /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor",
    values:[
        userspace,
        ondemand-sec,
        performance,
    ],
    notify:[
        {
            on:APPLY,
            do:[ REFRESH, CANCEL ],
            to:"/sys/devices/system/cpu/cpufreq"
        },
        {
            on:REFRESH,
            do:REFRESH,
            to:"/sys/devices/system/cpu/cpufreq"
        }
    ]
}

On application of a changed value on the SOptionList, the /sys/devices/system/cpu/cpufreq target element will be sent a REFRESH and a CANCEL event. In this case, the target is an STreeDescriptor which builds governor tunables depending on the current governor. When we change the governor, we tell the STreeDescriptor it should refresh (rebuild) itself. However since a kernel governor does not remember tunables from a previous instance, the new tunables will have values that might differ from Synapse's saved values. As such, the CANCEL event is sent in sequence to "apply" the saved action-values.

The SOptionList has a second notifier defined, this one is triggered on a REFRESH of the element. This is usually caused by resuming the application from the background. Since a governor might have been changed by a third-party, the SOptionList will need to communicate this to the STreeDescriptor to be able to rebuild its nodes.

The example achieves inter-element dependencies and event, and action-chaining.

Element syntax ˄

An element is an object block inside the interface. It is defined inside a sections' elements value array.

All elements follow the following encapsulation syntax:

....
elements:[
            {
               ElementType1:{
                  ....property name/value-pairs....
               }
            },
            {
               ElementType2:{
                  ....property name/value-pairs....
               }
            },
]
....

An element is a JSON object with a single name/value-pair. The pair's name represents the element type, and the value is a JSON object with an arbitrary number of name/value-pairs representing the element's properties.

Below is a list of all current recognized elements.

NOTES: For presentational purposes, the outer braces of the element JSON object in the examples are omitted, but still required.

---

STitleBar ˄

Adds a bolded text-field as an element.

STitleBar:{
    title:"Blinking effect"
}

STitleBar:{
   title:{en:"Blinking effect", fr:"Effet de clignotement"}
}

An STitleBar creates a simple pane with highlighted background and bold, bright text.

Parameters:

• title String/Object @required : The text which appears on the pane.

SDescription ˄

Adds a simple text-field as an element.

SDescription:{
   description:"The notification LED has two brightness modes, depending on the external brightness detected by the light sensor."
}

SDescription:{
   description:{ 
      en:"The notification LED has two brightness modes, depending on the external brightness detected by the light sensor.",
      fr:"L'LED de notification a deux modes de luminosité, en fonction de la luminosité extérieure détectée par le capteur de lumière."
   }
}

An SDescription creates a simple text element with secondary dimmer textcolour.

Parameters:

• description String/Object @required : The given text which appears.

NOTES:

• The element will parse and correctly display hyperlinks. The format is standard HTML anchor tags; <a href='http://www.google.com'>Google</a>.

SPane ˄

Adds a separator between elements. The background is highlighted and text is bolded white. The element consists of a TitleBar and Description as sub-elements.

SPane:{
   title:"Brightness",
   description:"The notification LED has two brightness modes, depending on the external brightness detected by the light sensor."
}

An SPane creates combines an STitleBar with an SDescription for simplicity's sake.

Parameters:

• title String : The text which appears on the pane.
• description String : The given text which appears.

SCheckBox ˄

Adds a checkbox with label as an element.

SCheckBox:{
   title:"Brightness",
   description:"Enables mono output",
   label:"Mono mixer",
   default:0,
   action:"generic /sys/class/misc/wolfson_control/switch_hp_mono"
}

Parameters:

• title String : The text which appears on the pane.
• description String : The given text which appears.***
• default Integer [ 0, 1 ] : The default action-value to which the element may be reset to.
• action Integer [ 0, 1 ] @required : The element's action identifier.

Events:

• SET: Triggered and propagated from UI when value is changed.
• REFRESH: Will refresh the action-value from the action. Triggered and propagated from application life-cycle.
• APPLY: Will apply the current state. Triggered and propagated from UI.
• CANCEL: Will cancel the changed state to the saved one. Triggered and propagated from UI.
• RESET: Will reset to the default value. Triggered and propagated from UI.

SGeneric ˄

SGeneric:{
   title:"Brightness",
   description:"Enables mono output",
   default:0,
   action:"generic /sys/class/misc/wolfson_control/switch_hp_mono"
}

An SGeneric creates a simple EditText with keyboard support.

Parameters:

• title String : The text which appears on the pane.
• description String : The given text which appears.***
• default String : The default action-value to which the element may be reset to.
• action String @required : The element's action identifier.

Events:

• SET: Triggered and propagated from UI when value is changed.
• REFRESH: Will refresh the action-value from the action. Triggered and propagated from application life-cycle.
• APPLY: Will apply the current state. Triggered and propagated from UI.
• CANCEL: Will cancel the changed state to the saved one. Triggered and propagated from UI.
• RESET: Will reset to the default value. Triggered and propagated from UI.

SButton ˄

SButton:{
   label:"Detect live charging source",
   action:"charge-source"
}

Adds a button with label as an element.

Parameters:

• label String : The text which appears on the button.
• action Void @required : The element's action identifier.

Events:

• APPLY: Will execute action. Triggered and propagated from UI.

NOTES:

• Buttons action-scripts are not stored nor remembered by the application. They serve as simple triggers which are only activated by pressing on them, and any return value is only handled by being output via toast message to the user.

SSeekBar ˄

SSeekBar:{
   title:"Low light environment brightness",
   min:1,
   max:120,
   unit:"mA",
   weight:0.125,
   default:5,
   action:"generic /sys/class/sec/led/led_lowpower_current"
}

SSeekBar:{
   title:"Fade-in time period",
   description:"Sets the time period of the rising slope.",
   unit:"mA",
   weight:0.125,
   action:"generic /sys/class/sec/led/led_fade_in_time"
}

An SSeekBar creates a progress-bar with a seeking element, optional title and description, and fine-tuning step decrease and increase buttons.

Title and description are inherited from STitleBar and padded on the left-side of the element to point out to which element they belong.

Parameters:

• title String : The text which appears on the pane.

• description String : The given text which appears.

• max Integer @required : The maximum value in the seek range.

  NOTE: Only required if in arbitrary value mode, meaning if no values parameter is given, except if in combination listBound:false.

• min Integer : The minimum value in the seek range. Defaults to 0 if not supplied.

• step Integer : Step size the in which values are seekable. Defaults to 1 if not supplied.

• unit String : The unit measure to be appended to the value labels.

• weight Float : An arbitrary multiplier applied only to the value labels for presentational purposes.

• listBound Boolean [ true , false ] : A flag which sets label-matching of arbitrary mode with given values object parameters. Defaults to true if values is passed.

• values :

  • Array : [ Integer, Integer, ... ]

    An array of integer values. The SeekBar will divide the snap-points to the amount of values given. It will also snap in relative position of given values between the minimal and maximal value.

    The max, min, step parameters are ignored in this mode.

  • Object : { Integer : String, Integer : String, ... }

    A JSON object is given. Its parameters are treated as the value:key pairs for the SeekBar. The SeekBar acts the same as if it was given an array of integers, but also binds a specific label to each value.

    The max, min, step, unit, weight parameters are ignored in this mode, unless listBound:false is given. If so, SeekBar will behave the same as in arbitrary mode, but it will match values' labels to the ones given in the values parameter. For those who do not have a match, the generic unit label will apply.

• absolute Boolean [ true, false ] : If a values parameter is given, an absolute option of true may override the relative positioning of snap-points.

• default String : The default action-value to which the element may be reset to.

• action String @required : The element's action identifier.

Events:

• SET: Triggered and propagated from UI when value is changed.
• REFRESH: Will refresh the action-value from the action. Triggered and propagated from application life-cycle.
• APPLY: Will apply the current state. Triggered and propagated from UI.
• CANCEL: Will cancel the changed state to the saved one. Triggered and propagated from UI.
• RESET: Will reset to the default value. Triggered and propagated from UI.

SOptionList ˄

SOptionList:{
   title:"GPU max freq",
   description:"Set the maximum freqency the GPU scales up to.",
   default:480,
   unit:"MHz",
   action:"generic /sys/devices/platform/pvrsrvkm.0/sgx_dvfs_max_lock",
   values:[
      700,
      640,
      600,
      532,
      480,
      350,
      266,
      177,
   ]
}

An SOptionList creates a drop-down option list with arbitrary values, optional title and description, and fine-tuning step decrease and increase buttons.

Title and description are inherited from STitleBar and padded on the left-side of the element to point out to which element they belong.

Parameters:

• title String : The text which appears on the pane.
• description String : The given text which appears.***
• unit String : The unit measure to be appended to the value labels.
• weight Float : An arbitrary multiplier applied only to the value labels for presentational purposes.
• values :

  • Array : [ String, String, ... ]

    An array of string values.

  • Object : { String : String, String : String, ... }

    A JSON object is given. Its parameters are treated as the value:key pairs for the OptionList. The OptionList acts the same as if it was given an array of strings, but also binds a specific label to each value.

    The unit parameter is ignored in this mode.

• default String : The default action-value to which the element may be reset to.
• action String @required : The element's action identifier.

Events:

• SET: Triggered and propagated from UI when value is changed.
• REFRESH: Will refresh the action-value from the action. Triggered and propagated from application life-cycle.
• APPLY: Will apply the current state. Triggered and propagated from UI.
• CANCEL: Will cancel the changed state to the saved one. Triggered and propagated from UI.
• RESET: Will reset to the default value. Triggered and propagated from UI.

SColourPicker ˄

SColourPicker:{
   default:"#F71100",
   action:"colour scr_red"
}

Adds an element which shows a colour element. Upon pressing the element, an advanced colour editor is called upon to be able to edit the colour value.

Parameters:

• title String : The text which appears on the pane.
• description String : The given text which appears.***
• default Hex colour : The default action-value to which the element may be reset to.
• action Hex colour @required : The element's action identifier.

Events:

• APPLY: Will apply the current state. Triggered and propagated from UI.
• CANCEL: Will cancel the changed state to the saved one. Triggered and propagated from UI.
• RESET: Will reset to the default value. Triggered and propagated from UI.

SLiveLabel ˄

SLiveLabel:{
   title:"CPU temperature",
   description:"Temperature sensor data as read from the A15 cores. The A7 cores do not have dedicated sensors."
   refresh:250,
   action:"echo $(echo $(cat /sys/devices/platform/exynos5-tmu/curr_temp | tr , \" \") | { read C0 C1 C2 C3; echo \"Core 0:${C0%?}C° Core 1:${C1%?}C°@nCore 2:${C2%?}C° Core 3:${C3%?}C°\"; })"
}

The SLiveLabel will display an auto-refreshing label element.

Parameters:

• title String : The text which appears as a title label.
• description String : The given text which appears.
• refresh Integer : The refresh rate in milliseconds of the element. Has a fixed minima of 50ms. Defaults to 2500 if not supplied. Supplying a value of 0 will make the element static and only read out its value at application start.
• style String : [ "bold", "italic", "italic bold" ]. Defaults to normal if not supplied.
• action String @required : The element's action identifier.

NOTES:

• If an action is provided as in-line bash script, as in the example, please be aware of additional need of character escaping due to JSON formatting.
• Due to limitations in how actions are handled, \n newlines are omitted. Use @n to create a newline in the resulting TextView.

STreeDescriptor ˄

STreeDescriptor:{
	path:"/sys/devices/system/cpu/cpufreq",
	generic: {
		directory: {
			STreeDescriptor:{
				generic: {
					directory: {},
					element: {
						SGeneric: { title:"@NAME" }
					}
				},
				matched: {
					elements: [
						{ "sampling_rate" : {
							SSeekBar: {
								title:"Sampling rate",
								description:"Controls the frequency in which the governor polls for frequency changes.",
								min:10000, max:100000, step:10000, unit:"ms"
							}
						}}
					]
				},
				exclude: [
					"cpu_utilization",
					"sampling_rate_min",
					"up_threshold_h",
					"up_threshold_l"
				]
			}
		}
	},
	exclude: [ "ondemand", "iks-cpufreq" ]
}

The STreeDescriptor is given a root path, and parses the directory of that path. It is provided generic and matched element descriptors, with which it builds new elements for each leaf in the tree.

Parameters:

• path String @required : The tree's root path. If the tree is a sub-tree, this will be automatically populated with the directory path of the parent's leaf.
• generic :
  • directory Element: The generic directory descriptor. All sub-directories in the current level will be an instance of this element. In almost all circumstances, a child STreeDescriptor element.
  • element Element: The generic element descriptor. All leaf nodes in the tree will be an instance of this element.
• matched :
  • directories Array [ { MatchingName : Element }, ... ] : If a sub-directory matches the given name, then take that as the descriptor element.
  • elements Array [ { MatchingName : Element }, ... ] : If a leaf node matches the given name, then take that as the descriptor element.
• exclude Array [ String, ... ]: A list of given leafs that should be ignored in the tree, no elements will be generated for them.

Events:

• REFRESH: Will cause a collapse and rebuilding of the STreeDescriptor.
• APPLY: Will propagate the event to all child elements.
• CANCEL: Will propagate the event to all child elements.
• RESET: Will propagate the event to all child elements.

An STreeDescriptor may have STreeDescriptor sub-elements defined in the directory and directories parameters. The path of such sub-elements are automatically populated and is not required to be defined.

Elements created by the descriptor may choose to define custom actions, or to choose to be populated by a default one. A custom action will be appended the current leaf's absolute path as an added parameter at element generation. If no action is defined, then the application defaults to generic <path>.

Generic elements may make use of the @BASENAME (basename of file), @NAME (basename of file with underscores replaced by spaces), and @PATH (full absolute path of file) as variables in the descriptor definition fields of action and title.

Matched elements may use them in the action field of their descriptor.

NOTES:

The STreeDescriptor currently appends all elements in a section at the end of a section. As such, the STreeDescriptor should be defined at the end of a section to avoid separation between elements. This applies at initial parsing and also on a collapse/rebuild caused by REFRESH

If a tree and its elements are dependent on another element in the DOM, then that element must be defined before the STreeDescriptor for the applying on boot of the element values to work, otherwise element values of an invalid tree will be applied before the valid tree comes to life. I.E: A governor must already be switched/applied before the values of the tunables are applied, otherwise the tuneables will not yet exist.