====== Truetype Widget ======
This widget is available on //graphic displays// only!
The Truetype widget renders the result of an expression with a TrueType font. In contrast to the [[:lcd4linux:widget_text|text widget]], which uses the built-in 6x8 bitmap font, it gives you smooth, anti-aliased text in any size and colour. Internally the text is rendered into an image, so the widget behaves like an [[:lcd4linux:widget_image|image widget]]: it is placed with pixel resolution and may be put on its own layer.
The definition of a Truetype widget looks like this:
Widget myText {
class 'Truetype'
expression
font
size
fcolor
width
height
align
mheight
center <0|1>
debugborder
update
reload <0|1>
visible <0|1>
inverted <0|1>
}
All entries except //class// are expressions and are evaluated at every update.
----
===== Parameters =====
|**expression**|this expression will be evaluated and its result will be displayed|
|**font**|path to the TrueType font file (*.ttf). Required.|
|**size**|font size in points. Default is 0, which means //automatic// (see below).|
|**fcolor**|font color as RRGGBB or RRGGBBAA, default is red 'ff0000'. Note the alpha channel, see below.|
|**width**, **height**|size of the widget in **pixels**. Default is 0, which means: as big as the rendered text.|
|**align**|horizontal alignment of the text inside //width//: 'L' (left), 'C' (center, the default) or 'R' (right). Needs //width// and //height//.|
|**mheight**|how the height of a text line is determined: 'F' (full, the default), 'N' (numbers) or 'O' (old), see below|
|**center**|set to 1 to center the widget horizontally on the display; the X position from the layout is ignored then|
|**debugborder**|color (RRGGBB or RRGGBBAA) of a frame that is drawn around the area given by //width// and //height//. Useful while designing a layout. Default is '000000', which means no frame.|
|**update**|update interval (msec), default is 100. Use 0 (zero) for static text.|
|**reload**|expression controlling whether the text is rendered again at an update. **Default is 0**, see below.|
|**visible**|expression controlling the visibility (for blinking effects)|
|**inverted**|expression controlling the inversion|
----
===== reload =====
The text is rendered when the widget is created. At every following update it is rendered again **only if //reload// evaluates to a value other than zero**. With the default (0) the widget keeps showing the first result of //expression//, only //visible// and //inverted// take effect.
So for everything that changes (a clock, a title, a temperature), set
reload 1
----
===== Size of the text =====
There are three ways to determine the size:
|**size** > 0, no //width/////height//|The text is rendered in the given size, the widget is as big as the text.|
|**size** > 0, //width// and //height// given|The text is rendered in the given size into an area of //width// x //height// pixels and aligned as specified with //align//.|
|**size** 0, //width// and //height// given|//Autosize//: the biggest font size is used with which the text fits into //width// and a text line fits into //height//. Long texts get smaller, short texts get bigger.|
Both //width// and //height// must be given for alignment and autosize; with only one of them the widget behaves as if none was given. With //size// 0 always specify //width// and //height//.
The **mheight** entry selects the characters that are used to measure the height of a line. This matters for autosize and for the vertical position of the text:
|'F'|full: the height is measured with a set of characters with ascenders, descenders and accents. The baseline stays at the same place for every text. This is the default.|
|'N'|numbers: only an upper case umlaut and a lower case letter with descender are used. Oversized characters like brackets are ignored, so digits and normal text can be a bit bigger.|
|'O'|old behaviour: the height is measured with the displayed text itself. The text jumps up and down if it changes between e.g. 'aaa' and 'Ago'.|
----
===== Colors =====
//fcolor// and //debugborder// are RGB values with an optional alpha channel. **Attention:** the alpha channel of this widget works the other way round than in the [[:lcd4linux:colors|other color entries]] of LCD4Linux: '00' is opaque and 'ff' is (nearly) transparent.
|'ffffff'|white, opaque|
|'ffffff00'|white, opaque|
|'ffffff80'|white, half transparent|
The background of the widget is always transparent, so the text can be placed on top of an image on another layer.
----
===== Layout =====
Like the image widget, the Truetype widget is not placed on a row/column basis, but with true pixel resolution:
Layout Default {
Layer 1 {
X10.Y1 'Clock'
}
Layer 2 {
X1.Y1 'Background'
}
}
Note that the number after //X// is the vertical position (the row) and the number after //Y// is the horizontal position (the column), counted in pixels and starting with 1.
----
===== Example =====
A clock that is scaled into an area of 300x80 pixels and centered on the display:
Widget Clock {
class 'Truetype'
expression strftime('%H:%M', time())
font '/usr/share/fonts/DejaVuSans-Bold.ttf'
size 0
width 300
height 80
align 'C'
mheight 'N'
fcolor 'ffffff'
center 1
reload 1
update 1000
}
A title in a fixed size, as wide as the text:
Widget Title {
class 'Truetype'
expression file::readline('/tmp/lcd/event', 1)
font '/usr/share/fonts/DejaVuSans.ttf'
size 24
fcolor 'ffcc00'
reload 1
update 2000
}
----
===== Requirements =====
The Truetype widget is built together with the image widget, if the GD library (libgd 2) is found at build time. libgd must be compiled with FreeType support.
----