User Tools

Site Tools


doc:rfc_onion
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


doc:rfc_onion [2014/03/02 07:37] (current) – created admin
Line 1: Line 1:
 +====== The Onion Data Structures ======
 + 
 +
 +To commonize all the different type of data flow inside the program, a generic data type have been defined, which contains all this. Its a nested hash array structure, the so called Onion.
 +
 +This page collects the different keys and their meanings
 +===== The Principle =====
 + 
 +
 +An Onion is an collection of paths and their values. All these paths starts at the onion root level, which means relative paths statements are not allowed. This paths are made by the list of the names of the different levels, seperateted by an "/", which is quite simular to a directory path:
 +
 +  this/is/a/possible/path
 +
 +In opposite to a valid directory path, an Onion path must '''not''' start with a leading "/".
 +
 +Each path contains a value.
 +
 +This value can be either a basic type like string, integer, boolean or float, a collection of Onions or a (sub-) Onion. The Onion class supports methods to get, set and delete these paths  and values.
 +
 +
 +As the value of a path can be an Onion, a path can be splitted into a left leading part, which returns a (sub-)onion as value, where this sub onion then contains the remaining (right) part of the path.
 +
 +This means taking e.g. "this/is" from the path "this/is/a/possible/path" returns an Onion, which contains itself the content of "a/possible/path". This is used to easily include and extract subparts in and out an Onion.
 +
 +
 +===== The Naming Convention =====
 + 
 +A part of such a path consist of the following characters [a-zA-Z0-9_-] and must start with a letter. Normal parts are written in lowercase, root parts (see below) in upper case. Collections, which are internally represent by a key/value hash array, are indexed by a leading "_", followed by an continious increased integer value, starting with 0. The number of included elements is an integer value, indexed by "_nr"
 +
 +===== The Root Names =====
 + 
 +As it is their indention, Onions can represent a wide range of possible datasets. These datasets are quite equal to what in C is called a struct, or record in Pascal: A structure of different static data, which may contain other sub- structs.
 +
 +
 +Just to make the handling easier, the following convention must be used:
 +
 +the name of that struct is used as the root part of the path, written in uppercase letters. As an example we use a date structure, first in C syntax:
 +
 +  struct date{
 +     year : integer = 2010;
 +     month : integer = 1 ;
 +     day   : integer = 11 ;
 +     dayofweek : string = "Monday ";
 +  }
 +
 +would be written in onion syntax
 +
 +  DATE/year = 2010
 +  DATE/month = 1
 +  DATE/day = 1
 +  DATE/dayofweek = "Monday"
 +
 +===== The different Roots (datatypes) =====
 + 
 +
 +To guarantee a seamless cooperation between all different internal program modules, the following data structure definitions must be followed:
 +
 +==== ID ====
 + 
 +The ID struct contains all data to identify a module in the system.
 +
 +details to be defined
 +
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +| name | String | | Id of the Module |
 +
 +==== CONFIG ====
 + 
 +The CONFIG struct is used to request the core to ask the user to config something
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +| owner |  ID  | | Id of the sending Module |
 +| param |  Collection of PARAM  | | Parameter set |
 +
 +====  PARAMSET ====
 + 
 +The PARAMSET struct is used to tell a module to use the given set of parameters. This could be either the result of a CONFIG request or e.g. an initial configuration, read by the Core out of settings and sent to the modules during startup
 +
 +^  Name ^ Type ^ opt. ^ Meaning ^
 +| owner |  ID  | | Id of the receiving Module
 +| param |  Collection of PARAM  | | Parameter set |
 +
 +==== PARAM ====
 + 
 +The PARAM struct is used to transfer configuration data. The optional data helps to define the user interface for the configuration window and is not needed when some configuration data is send to a module.
 +
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +|  name  |  string  |    Name of that parameter  |
 +|  type  |  string  |  x  | f=float, i = integer , s = string , sf = filename , c = combobox , radiobutton = like a combobox, but with a different presentation, cm = combobox with multiple selection, b = boolean (checkbox), a = alert |
 +|  actValue  |  base type  |  | representation of the actual value(s), seperated by ; in case of a multiselect element  |
 +|  loRange  |  base Type  |  x  | lowest value of the allowed range. For comboboxes, this field contains the possible selections, seperated by %%|%%. For strings this field might include a RegEx, which describes the allowed result. For alerts, this may contain the answer button texts, seperated by %%|%%. |
 +|  upRange  |  base type  |  x  | highest value of the allowed range  |
 +|  tooltip  |  String  |  x  | some additional text which might give the user some help for this parameter  |
 +|  fileexist  |  Boolean  |  x  | in case type=fn for FileSelectDialogs: The file must already exist for opening a File  |
 +
 +==== VALUE ====
 + 
 +The VALUE struct contains a value to show
 +
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +|  sender  |  ID  |   | sender of this value  |
 +|  to  |  ID  |   | receiver of this value  |
 +|  type  |  string  |   | f=float, i = integer , s = string , c = combobox , radiobutton = like a combobox, but with a different presentation, cm = combobox with multiple selection, b = boolean (checkbox)  |
 +|  rawValue  |  base type  |   | representation of the actual value(s), seperated by ; in case of a multiselect element  |
 +|  Unit  |  String  |    | Unit of the value  |
 +|   ValueString  |  String  |  | string representation of the value + unit  |
 +|  loRange  |  base Type  |  x  | lowest value of the allowed range. For comboboxes, this field contains the possible selections, seperated by %%|%%. For strings this field might include a RegEx, which describes the allowed result  |
 +|   upRange  |  base type  |  x  | highest value of the allowed range  |
 +|  step  |  base type  |  x  | step rate in which the value can be changed (e.g. for slider boxes) |
 +
 +==== PAGE ====
 + 
 +The PAGE struct is used to request the UI to create a "landing surface" to place some visualizers onto. 
 +
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +|  owner  |  ID  |   | Id of the sending Module |
 +|  name  |  String  | | title of the requested page |
 +
 +==== PAGEDONE ====
 + 
 +The PAGEDONE struct is used to tell the UI that the placement of the visualizers is done. 
 +
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +|  owner  |  ID  |  | Id of the sending Module |
 +
 +==== UPDATE ====
 + 
 +The UPDATE struct tells the owner of a visualizer that the user has requested an update by e.g. pressing a button or do a double click on an value 
 +
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +|  vis  |  ID  |  | Id of the sending visualizer |
 +|  to  |  ID  |   | name of the owner of the visualizer |
 +|  actValue  |  String  | | actual shown value|
 +|  updType  |  int  |  | type of the update (like request came from user or it is a periodic update)|
 +|  optid  |  String  |  X  | optional ID as add. identification, if needed |
 +
 +==== UPDEVENT ====
 + 
 +The UPDEVENT tells the visualizer which events are allowed to send an update request. If not set, the visualizer sends only an update request on manual user request. UPDEVENT is a set of events, which are seperated by |
 +
 +^  Event  ^  Meaning  ^
 +|  UPDATE  | the update request is send when the user request a global list update|
 +|  TIMER   | the update request is send in an interval if the global timer is active |
 +
 +==== VISUALIZE ====
 + 
 +The VISUALIZE struct is used to request the UI to create a visualizer. It then up to the implementation of this visualizer to add that visualization to an already existing visualizer (in a listview for example) or to create a new object (as for a button)
 +
 +^  Name  ^  Type  ^  opt.  ^ Meaning  ^
 +|  owner  |  ID  | | Id of the sending Module |
 +|  name  |  String  | | name of the requested visualizer |
 +|  type  |  String  | | type of the requested visualizer |
 +|  theme |  String  |     | name of the theme to be used, if different from default theme |
 +|  canvas  |  String  |   | name of the canvas, on which that visualizer should appear |
 +|  value  |  VALUE  | | initial value |
 +|  tooltip  |  String  | | some additional text which might gives some information about this value |
 +|  updevent  |  UPDEVENT  |     | allowed update events of this visualizer  |
 +|  optid  |  String  |     | optional ID as add. identification, if needed |
  
doc/rfc_onion.txt · Last modified: 2014/03/02 07:37 by admin