Layout and Widgets

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 20×4 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)


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).


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

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