#!html
This Plugin is not part of the current lcd4linux. This wiki entry was created for discussion about a plugin prototype.
====== Plugin Layout ======
\\\
====== 1. Description ======
The Plugin "Layout" makes it possible to switch between different layouts while runtime and create simple menus.\\\
The switching may be triggered by the [[:widget_timer|Timer Widget]], [[:widget_keypad|Keypad Widget]] or external controllers by using the [[:plugin_control|Control plugin]].
\\\
\\\
====== 2. Configuration ======
===== 2.1. Basic structure
=====
The basic structure in the config-file looks like this:
Plugin Layout {
active 1
Group1 {
Layout1 {
name = 'Layout_CPU'
}
Layout2 {
name = 'Layout_RAM'
}
}
Group2 {
Layout1 {
name = 'Layout_Clock'
}
...
}
}
"active 1" activates the plugin. If it has not been activated all of its functions will return -1.
The plugin must contain at least 1 group - each group at least 1 layout. Groups and layouts have to be numbered serially starting with 1. All layouts are [[:Layout|defined as usual]] outside the plugin section and are referenced by name. A layout must be unique within the group but the same layout may be referenced in more than one group.
**Main layout**
The layout which is chosen as normal (= main layout) must not contain any visible widgets ([[:widget_text|text]], [[:widget_bar|bar]], [[:widget_icon|icon]], [[:widget_image|image]]). Therefore it is not useful to reference this layout in this plugin section. The main layout may contain invisible widgets: [[:widget_timer|timer]], [[:widget_gpo|gpo]], [[:widget_keypad|keypad]]. These widgets are active (if set active) independently of the currently shown layout.
**Switchable layouts**
Layouts referenced by in this plugin (= switchable layouts) may contain the following widgets: [[:widget_text|text]], [[:widget_bar|bar]], [[:widget_icon|icon]], [[:widget_image|image]], [[:widget_timer|timer]]. Such a widget (inclusive [[:widget_timer|timer]]) will be active if a layout that contains it is active. Switchable layouts must not contain the widgets [[:widget_gpo|gpo]] and [[:widget_keypad|keypad]]. Layout1 of Group1 will be the first active layout per default.
===== 2.2. Section Plugin Layout
=====
**Parameters:**
|**active**|Set to 1 to activate plugin, otherwise the plugin won't work and all of its functions return -1. |
|**initgroup***|Name of the layout group that should be shown initially. (If not set: Group1)|
|**initlayout***|Name of the layout that should be shown initially.(If not set: Layout1 of initgroup)|
|*****|see [[:#actions|Actions]]|
| |* //optional//|
**Subsections**
|**Groups**|see [[:#group|Subsection Group]]|
===== [[:======#group]]2.3. Subsection Group
**Parameters:**
|**name***|Name of the layout group. Default 'Group1' for Group1, ...|
|*****|see [[:#actions|Actions]]|
| |* //optional//|
**Subsections**
|**Layouts**|see [[:#layout|Subsection Layout]]|
===== 2.4. Subsection Layout
=====
**Parameters:**
|**name**|Name of the layout as set in the [[:Layout#Layout|layout definition]]|
|*****|see [[:#actions|Actions]]|
| |* //optional//|
===== [[:======#actions]]2.5. Actions
Actions are parameters whose values are expressions which will be evaluated when the action is triggered.
\\\
\\\
These actions can be used to modify the function of button/timer events dependent on the current layout/group.
|**onenter***|Triggered shortly after enter new group/layout.|
|**onexit***|Triggered shortly before exit new group/layout.|
|**confirm**|Triggered by [[:#functions|layout::confirm()]]|
|**cancel**|Triggered by [[:#functions|layout::cancel()]]|
|**up**|Triggered by [[:#functions|layout::up()]]|
|**down**|Triggered by [[:#functions|layout::down()]]|
|**left**|Triggered by [[:#functions|layout::left()]]|
|**right**|Triggered by [[:#functions|layout::right()]]|
|**action1**|Triggered by [[:#functions|layout::trigger('action1')]]|
|...| |
|**action 20**|Triggered by [[:#functions|layout::trigger('action20')]]|
| |* only in subsection Group and Layout|
The actions "onenter" and "onexit" will be triggered by a layout switch.
Sequence:
1. onexit of old layout
1. onexit of old group
1. switching of group/layout
1. onenter of new group
1. onenter of new layout
If you 'switch' to the current group & layout none of the actions will be triggered.
A group change will always trigged a layout change - even if the name of the layout hasn't changed.
The other actions will be triggered directly by homonymic functions in the following way.
layout level ==> group level ==> plugin level (First matching action found will be triggered.)
Example:
Plugin Layout {
active 1
action5 x = x + 2
Group1 {
Layout1 {
name = 'Layout_1_1'
action5 x = x + 1
}
Layout2 {
name = 'Layout_1_2'
}
}
Group2 {
action5 x = x + 3
Layout1 {
name = 'Layout_2_1'
}
}
}
For instance //layout::action(5)// was called (by a timer/keypad widget or the control plugin).
If the current group/layout is 'Group1'/'Layout_1', //x = x + 1// will be evaluated (layout action found first).\\\
If the current group/layout is 'Group1'/'Layout_2', //x = x + 2// will be evaluated (plugin action found first).\\\
If the current group/layout is 'Group2'/'Layout_1', //x = x + 3// will be evaluated (group action found first).
If //layout::action(17)// was called, no matching action would be found in this example. So no expression would be evaluated.
\\\
\\\
====== [[:======#functions]]3. Functions =
\\\
All functions return -1 on error (e.g. plugin not active, wrong config, wrong indexes, name not found).
\\\
|**Function**|**args**|**Description**|
| || **Layout info/switch** |
|**layout::layout(** //[[:[grp]],lay]// **)**| 0..2 |Switch to layout or get index of current layout. See [[:#fct_layout|below]]|
|**layout::layoutname()**| 0 |name of current layout|
|**layout::layouts()**| 0 |number of layouts in current group|
|**layout::prev(** //loop// **)**| 1 |next layout of current group - no change if last layout of group and //loop// == 0, returns -1 on error, else 0|
|**layout::next(** //loop// **)**| 1 |previous layout of current groupName - no change if first layout of group and //loop// == 0, returns -1 on error, else 0|
| || **Group info/switch** |
|**layout::group(** //[[:grp]]// **)**| 0..1 |Switch to group or get index of current group. See [[:#fct_group|below]]|
|**layout::groupname()**| 0 |name of current group|
|**layout::groups()**| 0 |number of groups|
|**layout::prevgroup(** //loop, first// **)**| 2 |previos group, See [[:#fct_prevgroup|below]]|
|**layout::nextgroup(** //loop, first// **)**| 2 |next group, See [[:#fct_nextgroup|below]]|
| || **Action trigger** |
|**layout::trigger(** arg **)**| 1 |See [[:#actions|Actions]], Examples for value of arg: '' 'action17', 'confirm' '', returns 1 if action found, else 0|
|**layout::confirm()**| 0 |See [[:#actions|Actions]], returns 1 if action found, else 0|
|**layout::cancel()**| 0 |See [[:#actions|Actions]], returns 1 if action found, else 0|
|**layout::left()**| 0 |See [[:#actions|Actions]], returns 1 if action found, else 0|
|**layout::right()**| 0 |See [[:#actions|Actions]], returns 1 if action found, else 0|
|**layout::up()**| 0 |See [[:#actions|Actions]], returns 1 if action found, else 0|
|**layout::down()**| 0 |See [[:#actions|Actions]], returns 1 if action found, else 0|
\\\
{{anchor:fct_layout]**layout::layout(** //[[:[grp]],lay}}// **)**
\\\
|layout::layout()|returns index of current layout within current group|
|layout::layout(//lay//)|switch to layout //lay// within current group, //lay// may be the name or the index of the layout, returns -1 on error, else 0|
|layout::layout(//grp//,//lay//)|switch to layout //lay// within group //grp//, //grp// & //lay// may be the names or the indexes, returns -1 on error, else 0|
\\\
{{anchor:fct_group]**layout::group(** //[grp}}// **)**
\\\
|layout::group()|returns index of current group|
|layout::group(//grp//)|switch to the last active layout (default: first) within group //grp//, //grp// may be the name or the index of the group, returns -1 on error, else 0|
\\\
{{anchor:fct_prevgroup}}**layout::prevgroup(** //loop, first// **)**
\\\
\\\
Switches to the previous group - no change if first group is active and //loop// == 0.\\\
If first == 0, and group isn't active for the first time, the last active layout of this group is shown, otherwise the first layout of the group.
\\\
\\\
{{anchor:fct_nextgroup}}**layout::nextgroup(** //loop, first// **)**
\\\
\\\
Switches to the next group - no change if last group is active and //loop// == 0.\\\
If first == 0, and group isn't active for the first time, the last active layout of this group is shown, otherwise the first layout of the group.
\\\
\\\
====== 4. Examples ======
\\\
All example are written for a [[:Curses|Curses driver]]. So no real LCD is needed for testing. It also allows the use of the keyboard to switch layouts.\\\
If the real display has no keypad, [[:plugin_control|Control plugin]] may be used.
\\\
\\\
Use [[:Manual#USAGE|option -f]] to activate these configuration files.
\\\
\\\
The group and layout indexes are displayed in the upper left corner of all switchable layouts, to make it easy to find the matching part in the config file.
\\\
===== 4.1 Loop layouts by timer
=====
Download: [[::raw-attachment:wiki:plugin_layout:sample_layout_1.conf|sample_layout_1.conf]]
In this example a timer loops over 3 layouts. Every 5 second the next layout is activated. This automatic mode is indicated by a 'a' in the first row of the display.\\\
With the left and right arrow key the layouts can be switch manually ('a' switches to 'm'). This will interupt the automatic mode for one minute after the last of these keys was pressed.
===== 4.2 Simple menu control
=====
Download: [[::raw-attachment:wiki:plugin_layout:sample_layout_2.conf|sample_layout_2.conf]]
The plugin can be used to create simple menus by using [[:#actions|actions]] to achieve variable button functions.\\\
This works well if there are no restrictions regarding where to place the buttons. Menus based on item selection, confirm and arrow buttons can be implemented with the [[:plugin_menu|Menu plugin]].
┌────────────────────┐
│ Main Menu 2/3 │
o │< CPU RAM >│ o
o │< DISK WLAN >│ o
o │< PREV NEXT >│ o
└────────────────────┘
┌────────────────────────────────────────┐
│ Main Menu 2/3 │
│ [[:PREV]] [[:CPU]] [[:RAM]] [[:DISK]] [[:NEXT]] │
└────────────────────────────────────────┘
o o o o o
The linked sample looks like the first design. The keyboard keys are used the following way (up items a marked with '_u' suffix, down items with '_d').
│< UP DOWN >│
│< LEFT RIGHT >│
└────────────────────┘
===== 4.3 Simple timer
=====
See: [[:plugin_run#a4.Example|Example plugin Run]]