plugin_layout

#!html
<h1 style="text-align: left; color: red">
This Plugin is not part of the current lcd4linux. This wiki entry was created for discussion about a plugin prototype.
<br><br>
</h1>

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 Timer Widget, Keypad Widget or external controllers by using the 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 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 (text, bar, icon, image). Therefore it is not useful to reference this layout in this plugin section. The main layout may contain invisible widgets: timer, gpo, 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: text, bar, icon, image, timer. Such a widget (inclusive timer) will be active if a layout that contains it is active. Switchable layouts must not contain the widgets gpo and keypad. Layout1 of Group1 will be the first active layout per default.

===== 2.2. Section Plugin Layout

Parameters:

activeSet 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)
<actions>*see Actions
* optional

Subsections

Groupssee Subsection Group

===== group2.3. Subsection Group

Parameters:

name*Name of the layout group. Default 'Group1' for Group1, …
<actions>*see Actions
* optional

Subsections

Layoutssee Subsection Layout

===== 2.4. Subsection Layout

Parameters:

nameName of the layout as set in the layout definition
<actions>*see Actions
* optional

===== actions2.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.
confirmTriggered by layout::confirm()
cancelTriggered by layout::cancel()
upTriggered by layout::up()
downTriggered by layout::down()
leftTriggered by layout::left()
rightTriggered by layout::right()
action1Triggered by layout::trigger('action1')
action 20Triggered by 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. \

\

====== functions3. Functions = \

All functions return -1 on error (e.g. plugin not active, wrong config, wrong indexes, name not found). \

FunctionargsDescription
Layout info/switch
layout::layout( [grp,lay] ) 0..2 Switch to layout or get index of current layout. See 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 below
layout::groupname() 0 name of current group
layout::groups() 0 number of groups
layout::prevgroup( loop, first ) 2 previos group, See below
layout::nextgroup( loop, first ) 2 next group, See below
Action trigger
layout::trigger( arg ) 1 See Actions, Examples for value of arg: 'action17', 'confirm' , returns 1 if action found, else 0
layout::confirm() 0 See Actions, returns 1 if action found, else 0
layout::cancel() 0 See Actions, returns 1 if action found, else 0
layout::left() 0 See Actions, returns 1 if action found, else 0
layout::right() 0 See Actions, returns 1 if action found, else 0
layout::up() 0 See Actions, returns 1 if action found, else 0
layout::down() 0 See Actions, returns 1 if action found, else 0

\

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| \
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

\

fct_prevgrouplayout::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. \
\
fct_nextgrouplayout::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 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, Control plugin may be used. \
\
Use 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: 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: sample_layout_2.conf

The plugin can be used to create simple menus by using 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 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

  • plugin_layout.txt
  • Last modified: 2020/07/17 18:33
  • (external edit)