Plugin win2tray.spf

File: win2tray.spf
Author: Nicholas Nemtsev
Description: Additional words for manipulating icons in the system tray; they allow to minimize to tray either a particular window or all windows matching a specified mask; to find out if a particular window is minimized to tray; to add any desired icons to system tray (as well as modify or delete them); to use icons in tray to show if Web sites are accessible or not, etc.

New Words:

WIN-TO-TRAY: "win_pattern"

Minimizes a window matching the specified pattern to the system tray .
Word WIN-TO-TRAY can be preceded by modifier ALL:. In this case, all windows matching the pattern will be minimized to the system tray.

Examples:

\ Minimizing to tray a window of  Internet Explorer 
WIN-TO-TRAY: "*Internet Explorer"
\ Minimizing to tray all opened  windows of  Internet Explorer 
ALL WIN-TO-TRAY: "*Internet Explorer"

There also exists a postfix version of this word:

S" win_pattern" WIN-TO-TRAY

ADD-TI ( a u hicon -- id )

This postfix word can be used to add a desired icon to system tray and to specify the text which should appear when a user hovers his mouse over the icon.

Word ADD-TI has the following arguments: a string that should appear in a hint when a mouse pointer is placed over the icon, and so-called icon handle, i.e. the icon which should appear in the tray. To create a icon handle, you can "preload" an icon from a file:

S" iconname.ico" LoadIcon

or else you can use one of the numerous Windows constants:

32512 0 LoadIconA

Here is a list of some numerical values of icon constants which you can use:

IDI_APPLICATION 32512
IDI_ERROR 32513
IDI_QUESTION 32514
IDI_WARNING 32515
IDI_ASTERISK 32516

Word ADD-TI returns an ID of the icon it creates; you can use this ID later to delete or modify the icon (see DEL-TI, MODIFY-TI)

Example:

#( test_long_proc
NoActive
VARIABLE icon_id
Action:
    \ creating an icon in the tray (IDI_WARNING)
    S" nnCron: long process started" 32515 0 LoadIconA ADD-TI
    \ saving icon's  ID in a variable
    icon_id !
    \ ... working
    \ deleting the icon
    icon_id @ DEL-TI
)#

See also Note.

DEL-TI ( id -- )

This postfix word removes an earler created icon from the system tray. It uses the icon's ID (which was received when the icon was created) as its argument.

Example:

#( test_icon
\ creating an icon in the tray
\ (loading the icon from a specified file)
NoActive
VARIABLE my_icon_id
Action:
    S" New Icon" S" ico\my_icon.ico" LoadIcon ADD-TI
    my_icon_id !
    \ ... working
    \ removing the icon from system tray
    my_icon_id @ DEL-TI
)#

Note: it would be a good idea to remove an icon from the tray in the same task which created it in the first place: an icon exists as long as exists the thread which created it. If the task which created a particular icon is completed, the icon becomes a kind of a ghost which disappears when a mouse pointer passes over the system tray. However, it is possible to add an icon to train in the main nnCron thread (from nncron.ini). Then it would be possible to remove the icon from any task.

MODIFY-TI ( a u hicon id -- )

This postfix word can be used to modify an existing icon in the system tray or to change the hint which appears when a mouse is passed over the icon.

Word MODIFY-TI uses the following arguments: a string which will appear in the hint, icon handle, and icon's ID.

Example:

#( test_tray_icons
NoActive
VARIABLE tray_icon_id
Action:
    \ creating an icon in the tray (IDI_APPLICATION)
    S" nnCron: task started" 32512 0 LoadIconA ADD-TI
    \ saving its ID
    tray_icon_id !
    \ ... working
    \ ... changing the icon in tray (IDI_WARNING)
    S" nnCron: task continued" 32515 0 LoadIconA
    tray_icon_id @ MODIFY-TI
    \ ... working
    \ removing the icon
    tray_icon_id @ DEL-TI
)#

ADD-HOST ( a u -- )

This word adds to the system tray an icon which shows whether or not a specified network computer or Web site is available at the moment. The icon will look like this if the host is accessible, or like this if the host is not accessible. A host is considered to be accessible if it can be pinged. By placing the mouse pointer over this icon you can display a hint with the host name. When you quit nnCron, this icon is automatically removed from the system tray. To manually remove this icon from the tray use the word DEL-HOST-ICONS.

Example:

#( test_add-host
WatchLogon: "*"
Action:
    S" strauss" ADD-HOST
    S" www.nncron.ru" ADD-HOST
)#

DEL-HOST-ICONS

This word removes from system tray all the icons added by word ADD-HOST.

Example:

#( test_del-host-icons
WatchLogoff: "*"
Action:
    DEL-HOST-ICONS
)#

IN-TRAY? ( hwnd -- ? )

This word allows to find out if a specified window is minimized to the tray.
Word IN-TRAY? accepts window handle of a window as its argument, and it returns a flag: TRUE (-1) ifa window is minimized to tray and FALSE (0) if it is not.

Example:

#( test_in_tray
NoActive
Action:
    \ starting Notepad
    START-APP: notepad.exe
    PAUSE: 1000
    \ getting  window handle of Notepad
    WIN-EXIST: "*Notepad"
    IF
        \ checking if Notepad's window is minimized to tray
        WIN-HWND IN-TRAY?
        IF
            MSG: "Notepad is minimized to tray"
        ELSE
            MSG: "Notepad is not minimized to tray"
        THEN
        \ minimizing Notepad's window to tray
        WIN-TO-TRAY: "*Notepad"
        PAUSE: 1000
        \ again checking Notepad's window is minimized to tray
        WIN-HWND IN-TRAY?
            IF
                MSG: "Notepad is minimized to tray"
            ELSE
                MSG: "Notepad is not minimized to tray"
            THEN
    THEN
)#

TRAY-LIST

A list of window handles of windows which has been minimized to the system tray. A detailed discussion of how to work with lists can be found in "Forth First Aid".