====== Bar Widget ======

The bar widget is used to display all kinds of bars.

LCD4Linux tries to do a quite good job with bar handling. It supports vertical, horizontal and split bars (two independent bars in one line), all bar types can be used simultanously.

At the moment one style is implemented for east and west bars: hollow. It's a frame around the bar, looks very cool ;) (See [[:CoolStuff#LCD4Linuxontwodisplayswithdifferentsize|CoolStuff]] for a sample)

Handling bars is really a tricky job: Most displays only have a limited number of user-defined characters (normally 8 of'em), which is far too less for an exact display of all these bars. If you use icons too, the number of available characters is reduced again. So LCD4Linux does some sort of //error diffusion// by replacing characters with similar ones. Here you have to take another point into account: If you redefine a character which is currently displayed, you will get a lot of ugly flicker on the display. So any currently displayed char will not be redefined, even if it's not used after the next update. Only if the error diffusion fails, such chars will be redefined in a second pass. The result looks quite good!

If you don't believe me that this stuff is weird, take a look at the bar handling code in //drv_generic_text.c//. You win a six-pack if you understand this code :-)

A bar widget looks like this:
<code>
Widget <name> {
    class       'Bar'
    expression  <expr>
    expression2 <expr>
    length      <number>
    min         <number>
    max         <number>
    direction   <char>
    style       <char>
    foreground  <color>
    background  <color>
    update      <number>
    barcolor0   <color>
    barcolor1   <color>
}
</code>


----

===== Parameters: =====

|**expression**|its result is used for the //length// of the (upper half) bar|
|**expression2**|its result is used for the //length// of the lower half bar|
|**length**|size of the whole bar widget|
|**min**|scale: value where the bar starts|
|**max**|scale: value where the bar ends|
|**direction**|'E' (east: from left to right, default), 'W' (west: right to left), 'N' (north: bottom-up) or 'S' (south, top-down)|
|**style**|'H' (hollow: with a frame) default: none|
|**foreground**|color of active pixels (RRGGBBAA or RRGGBB), default is opaque black '000000ff' (see [[:colors]] for details)|
|**background**|color of inactive pixels (RRGGBBAA or RRGGBB), default is transparent 'ffffff00' (see [[:colors]] for details)|
|**update**|update interval (msec) default: 1000 msec (1 sec)|
|**barcolor0**|color of upper (or only) bar, default is foreground color|
|**barcolor1**|color of lower bar, default is foreground color|

----

===== Example: =====

<code>
Widget BusyBar {
    class      'Bar'
    expression  proc_stat::cpu('busy',   500)
    expression2 proc_stat::cpu('system', 500)
    length      10	
    direction  'E'
    style      'H'
    update      100
    BarColor0  'ff0000'
    BarColor1  '00ff00'
</code>



If you omit //expression2//, you will get a //single bar//, controlled by //expression// only. If you specify an //expression2// (and your display supports //split bars//), you will get a //split bar//, the upper half controlled by //expression//, and the lower half by //expression2//.

===== Another Example: =====

<code>
Widget MP3Bar {
    class 'Bar'
    expression  xmms('uSecPosition')
    length 20
    min 0
    max xmms('uSecTime')
    direction 'E'
    update tick
}

</code>



This Widget can be used with the XMMS-Plugin. It displays a progress bar. //length// sets the length of the progress bar (No. of chars).


----

===== Scaling =====

Normally, bars do autoscale, which means they start at a value of 0 (zero), and remember their maximum value, and scale automagically to this maximum.

Sometimes this behaviour is not what you want (e.g. with temperatures). In this case, just specify the minimum and maximum value with the //min// and //max// parameters.

LCD4Linux-0.9 did support logarithmic bars. Of course, LCD4Linux-0.10 does so, too, but there's nothing special to deal with: just specify (any) mathematical function in the expression....

----