====== Icon Widget ======

The icon widget is used to display user-defined characters (we call them icons). You can only use icons if your display supports user-defined characters (most displays do so) and **you have reserved some characters for icons**, or your display is a graphical one (e.g. T6963). For details see the documentation for your [[:Displays|display driver]].

If, for any reason, the icon cannot be displayed, an asterisk ('*') will be used instead.

The definition of an icon widget is very simple:
<code>
Widget <name> {
    class      'icon'
    speed      <number>
    visible    <expr>
    frame      <expr>
    foreground <color>
    background <color>
    bitmap {
        row1 <string>
        row2 <string>
        ...
        row8 <string>
    }
}
</code>


----

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

|**speed**|animation interval (msec), default: 100 msec, 0 (zero) means never (for static icons)|
|**visible**|expression controlling the visibility (for blinking effects)|
|**frame**|expression controlling which frame to display out of an icon map (useful where 2 or more animated icons need to be synchronised)|
|**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)|
|**bitmap.row***|string that defines the bitmap|

----

===== Examples: =====

static icon:
<code>
Widget Lightning {
    class 'icon'
    bitmap {
        row1 '...***'
        row2 '..***.'
        row3 '.***..'
        row4 '.****.'
        row5 '..**..'
        row6 '.**...'
        row7 '**....'
        row8 '*.....'
    }
}
</code>


animated icon:

<code>
Widget Heartbeat {
    class 'Icon'
    speed  800
    Bitmap {
	Row1 '.....|.....'
	Row2 '.*.*.|.*.*.'
	Row3 '*****|*.*.*'
	Row4 '*****|*...*'
	Row5 '.***.|.*.*.'
	Row6 '.***.|.*.*.'
	Row7 '..*..|..*..'
	Row8 '.....|.....'
    }
}
</code>


I don't think that this need further explanation....
\\\

\\\

\\\



synchronised icons using 'frame' parameter:
(see the attachment at the bottom of this page for a demo)
<code>
Widget MailIcon_left {
    class 'Icon'
    speed  100
    update 100

    # Note that the following bitmap only needs to be half of it's current size,
    #+ as it's a reversing animation, but has been extended for purpose of illustration
    Bitmap {
	Row1 '.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....'
	Row2 '.....|.....|.....|.....|.....|.....|.....|....*|...**|..***|.****|*****|*****|*****|*****|*****|*****|.****|..***|...**|....*|.....|.....|.....|.....|.....|.....|.....|.....|.....'
	Row3 '.....|.....|.....|.....|.....|.....|.....|....*|...*.|..*.*|.*.*.|*.*..|*.*..|*.*..|*.*..|*.*..|*.*..|.*.*.|..*.*|...*.|....*|.....|.....|.....|.....|.....|.....|.....|.....|.....'
	Row4 '.....|.....|.....|.....|.....|.....|.....|....*|...*.|..*..|.*..*|*..*.|*..*.|*..*.|*..*.|*..*.|*..*.|.*..*|..*..|...*.|....*|.....|.....|.....|.....|.....|.....|.....|.....|.....'
	Row5 '.....|.....|.....|.....|.....|.....|.....|....*|...*.|..*..|.*...|*...*|*...*|*...*|*...*|*...*|*...*|.*...|..*..|...*.|....*|.....|.....|.....|.....|.....|.....|.....|.....|.....'
	Row6 '.....|.....|.....|.....|.....|.....|.....|....*|...*.|..*..|.*...|*....|*....|*....|*....|*....|*....|.*...|..*..|...*.|....*|.....|.....|.....|.....|.....|.....|.....|.....|.....'
	Row7 '.....|.....|.....|.....|.....|.....|.....|....*|...**|..***|.****|*****|*****|*****|*****|*****|*****|.****|..***|...**|....*|.....|.....|.....|.....|.....|.....|.....|.....|.....'
	Row8 '.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....'
    }

    # Note that the first call to bar8 increments/decrements the counter
    #+ and that the visibility formula does not need to be so complicated for the purpose of this example.
    visible ( test::bar(8,29,0,1) > 6 & test::bar(8,29,0,0) < 21 ) * ( exec(mailcheck_script,mailcheck_refresh) > 0 )
    # Select which frame we want shown
    frame test::bar(8,29,0,0)
}


Widget MailIcon_right {
    class 'Icon'
    speed  100
    update 100

    # Notes in MailIcon_left apply here, too
    frame test::bar(8,29,0,0)
    Bitmap {
	Row1 '.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|'
	Row2 '.....|.....|....*|...**|..***|.****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|.****|..***|...**|....*|.....|.....|.....|.....|'
	Row3 '.....|.....|....*|...*.|..*.*|.*.*.|*.*..|.*...|*....|....*|...*.|..*.*|..*.*|..*.*|..*.*|..*.*|..*.*|...*.|....*|*....|.*...|*.*..|.*.*.|..*.*|...*.|....*|.....|.....|.....|.....|'
	Row4 '.....|.....|....*|...*.|..*..|.*...|*..*.|..*..|.*...|*..*.|..*..|.*..*|.*..*|.*..*|.*..*|.*..*|.*..*|..*..|*..*.|.*...|..*..|*..*.|.*...|..*..|...*.|....*|.....|.....|.....|.....|'
	Row5 '.....|.....|....*|...*.|..*..|.*...|*...*|...**|..**.|.**..|**...|*...*|*...*|*...*|*...*|*...*|*...*|**...|.**..|..**.|...**|*...*|.*...|..*..|...*.|....*|.....|.....|.....|.....|'
	Row6 '.....|.....|....*|...*.|..*..|.*...|*....|.....|.....|.....|.....|....*|....*|....*|....*|....*|....*|.....|.....|.....|.....|*....|.*...|..*..|...*.|....*|.....|.....|.....|.....|'
	Row7 '.....|.....|....*|...**|..***|.****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|*****|.****|..***|...**|....*|.....|.....|.....|.....|'
	Row8 '.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|.....|'
    }

    # The bar8 counter has already been incremented by MailIcon_left
    visible ( test::bar(8,29,0,0) > 1 & test::bar(8,29,0,0) < 26 ) * ( exec(mailcheck_script,mailcheck_refresh) > 0 )
    frame test::bar(8,29,0,0)
}

</code>

\\\


Where the mailcheck_script might be something like:
<code>
#!/usr/bin/php
<?php
$mbox = imap_open("{localhost/tls/novalidate-cert}", "username", "password", OP_HALFOPEN)
      or die("can't connect: " . imap_last_error());

$status = imap_status($mbox, "{localhost}Inbox", SA_UNSEEN);
if ($status) {
  echo $status->unseen;
} else {
  echo "0";
}
imap_close($mbox);
?>
</code>

----

===== Visibility =====

You can specify an expression for //visible//, which will be evaluated every time the icon is updated (every //speed// msec). If the expression evaluates to 0 (zero), the icon is invisible, and will be replaced by a blank. If the result is not zero, the icon will be displayed. This is useful for blinking effects, or activity display.

----