= Layout and Widgets =

 * '''[wiki:widget_text Text Widget]'''
 * '''[wiki:widget_bar Bar Widget]'''
 * '''[wiki:widget_icon Icon Widget]'''
 * '''[wiki:widget_image Image Widget]'''
 * '''[wiki:widget_timer Timer Widget]'''
 * '''[wiki:widget_gpo GPO Widget]''' (General Purpose ''Inputs'' and Outputs)
 * '''[wiki:widget_keypad Keypad Widget]'''

----

LCD4Linux 0.10 uses a completely new layout engine, replacing the old token-based engine. The whole Layout consists of several ''Widgets'', which are placed in the ''Layout'' section.

Note that there's no global ''display update event'' or ''display flush'' something. Every widget has its own update interval, and only this widget is re-rendered at this interval. These ''update intervals'' need not to be the same, although it may look a bit cleaner if you use equal intervals. Using variables for this intervals may be a good idea.

LCD4Linux makes extensive use of double-buffering, every widget is first rendered into a layout framebuffer, and this layout buffer is compared to a display framebuffer, and only differences are transferred to the display. So even if a widget is updated very often, unless the value changes, nothing is sent to the display (saving lots of bandwith and CPU cycles).

The ''display framebuffer'' is usually the same size as the display is (makes sense, doesn't it? :-), while the size of the layout framebuffer automatically grows with the layout, and therefore may be larger than the display (Example: if you have a 20x4 Display, and specify ''Row5'' and ''Row6'' in the layout, the display framebuffer will have 4 rows, while the layout framebuffer will have 6 rows). When it comes to a display update, the display framebuffer acts as a ''window'' over the layout framebuffer. At the moment this window is fixed in the top left corner, but it will be moveable in the future (to achieve something similar to the ''virtual rows'' in LCD4Linux-0.9).

Every Widget has a ''name'' (which is the section name) and specific class, which describes the ''type'' of the widget (e.g. text, bar, icon, timer, gpo). You will find a detailed description of each available widget class in the corresponding widget documentation.

Here's an example widget:

{{{
Widget RAM {
    class      'Text'
    expression  meminfo('MemTotal')/1024
    postfix    ' MB RAM'
    width      11
    precision  0
    align     'R'
    update     1000
}
}}}

We define a widget named ''RAM'':
 * which is a text widget (''class 'Text' '')
 * its content is evaluated from the meminfo plugin
 * after the value there's a trailing text (''postfix'')
 * the whole widget is 11 characters long (''width 11'')
 * there are no decimal places (''precision 0'')
 * the value will be aligned to the right (''align 'R' '')
 * the value will be updated every 1000 msec (''update 1000'')

----

= Layout =

If you have defined several widgets, you have to tell LCD4Linux where it should display all your sexy widgets. This is done in the ''Layout'' section.

This is that easy, so let's look at an example:
{{{
Layout L20x2 {
    Row1 {
        Col1  'Busy'
        Col11 'BusyBar'
    }
    Row2 {
        Col1  'Load'
        Col11 'LoadBar'
    }
    Timer1 'PollFan'
    GPO1   'ISDN_connected'
}
}}}

We define a Layout named ''L20x2'', we have two rows (''Row1'', ''Row2''), and we place four widgets at specific columns. We added one timer widget. Our display has a LED connected to it's GPO (General Purpose Output), and we control this LED by a widget. That's all, folks!

Note that you can have as much layout sections as you like, but you have to select one with the ''Layout'' parameter. Maybe someday in the future there will be a possibility for LCD4Linux to switch automatically between layouts (due to a key press, or a timer event, or whatever).

----

= Layers =

LCD4Linux supports ''Layers''. At the moment there are three of them, but this number may increase. Layers can be used to produce overlapping widgets. This is most useful with the [wiki:widget_image image widget], which is available on graphic displays only. As all widgets may have a individual RGBA color, you can use alpha-blending over all layers.

If you don't use Layers in the Layout section, the ''default'' Layer '''1''' is used. Layer 0 is the top layer, this means a opaque widget on Layer 0 will cover all other widgets.

Again, we use an example to explain how things work:

{{{
Layout with_Image {
    Row1 {
	Col1  'OS'
    }
    Layer 0 {
        Row6 {
            Col1  'CPU'
            Col10 'RAM'
        }
    }
    Layer 2 {
	X1.Y1 'my_Image'
    }
}
}}}

The ''OS'' widget uses the default layer 1, while the ''CPU'' and ''RAM'' widgets are placed on layer 0. We place a background image on layer 2, on position X=1 and Y=1.

----