====== Layout and Widgets ======

  * **[[:widget_text|Text Widget]]**
  * **[[:widget_bar|Bar Widget]]**
  * **[[:widget_icon|Icon Widget]]**
  * **[[:widget_image|Image Widget]]**
  * **[[:widget_timer|Timer Widget]]**
  * **[[:widget_gpo|GPO Widget]]** (General Purpose //Inputs// and Outputs)
  * **[[: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:

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


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:
<code>
Layout L20x2 {
    Row1 {
        Col1  'Busy'
        Col11 'BusyBar'
    }
    Row2 {
        Col1  'Load'
        Col11 'LoadBar'
    }
    Timer1 'PollFan'
    GPO1   'ISDN_connected'
}
</code>


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 [[: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:

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


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.

----