Usenet News
  Mail Routing
  Text Paging

University of Michigan IT Central Services

iHook - Lexicon

iHook understands a number of Directives. When the script or other executable writes an iHook Directive to stdout, iHook interprets the Directive and modifies its interface accordingly. iHook Directives are prefixed with a percentage sign (%).

The following are the Directives iHook currently understands:

  • %BEGINPOLE -- starts an indeterminate progress bar (barberpole) in the iHook window. If no progress bar was previously in the window, iHook adds one.

  • %ENDPOLE -- stops an indeterminate progress bar in the iHook window. %ENDPOLE removes the progress bar from the window, as well.

  • %<0-100> -- sets a determinate progress bar to a level of completion between 0% and 100%. %0 adds the progress bar to iHook window, if necessary, and sets the bar to 0% complete; %100 fills a determinate progress bar, and removes it from the iHook window. Example: 'echo %50' sets the progress bar to half full. In iHook 0.9.3 and subsequent releases, anything after the directive is displayed in a small field above the progress bar. 'echo %50 Finding changes...' would set the progress bar half full and display "Finding changes..." above it. iHook rejects values < 0 and > 100, logging an error to the drawer.

  • %BACKGROUND /path/to/Image -- sets the background of the iHook window to Image. This may be used as many times as the script writer desires. If the Image is not a valid image, iHook logs an error to the drawer. If the parameter is IHOOKDEFAULT, the background image is set to a transcript iHook graphic.

  • %SHOWTIMER -- displays a field containing the elapsed time of the script at the upper right hand corner of the iHook window. The timer is displayed by default.

  • %HIDETIMER -- hides the iHook timer. The elapsed time is still calculated in the background.

  • %OPENDRAWER -- opens the log drawer.

  • %CLOSEDRAWER -- closes the log drawer.

  • %BECOMEKEY -- causes iHook to become active disregarding other applications. iHook steals the focus from the current active application, becoming the key application.

  • %RESIGNKEY -- causes iHook to give up its active application status. If iHook is not the active application when %RESIGNKEY is called, this directive has no effect.

  • %WINDOWLEVEL <HIGH/NORMAL> -- changes iHook window level. Passing HIGH as the argument sets the window's level to (NSScreenSaverWindowLevel - 1); NORMAL sets the windowlevel to NSNormalWindowLevel. When the windowlevel is set to HIGH, the iHook window appears above all other windows. Sending %WINDOWLEVEL without an argument has no effect.

  • %WINDOWSIZE <WIDTH> <HEIGHT> -- changes the iHook window size, recentering the window as it resizes. <WIDTH> and <HEIGHT> are positive integers corresponding to the width and height of the iHook window. The maximum window dimension allowed by iHook is that of the screen size. The script may set the iHook window to this size by calling %WINDOWSIZE MAX. Likewise, a script may set the minimum window size, 200 x 200, by calling %WINDOWSIZE MIN. If the width or height values are invalid, iHook logs an error in the iHook window drawer. A %WINDOWSIZE message missing one or both of the required parameters will be ignored.

  • %WINDOWPOSITION <TOP/BOTTOM/CENTER> <RIGHT/LEFT> -- changes the position of the iHook window on the screen. E.g., %WINDOWPOSITION TOP LEFT would place the iHook window at the upper lefthand corner of the screen. %WINDOWPOSITION CENTER recenters the iHook window on the screen.

  • %CANCEL <ENABLE/DISABLE/REMOVE> -- methods for cancelling the current script iHook is running. %CANCEL ENABLE places a button titled "Cancel" at the lower lefthand corner of the iHook window. %CANCEL DISABLE does likewise, except that the button is disabled (i.e., greyed out). %CANCEL REMOVE removes the Cancel button from the iHook window, if applicable. When the user presses the Cancel button, or uses the keyboard shortcut (command + .), iHook sends SIGTERM to the script's process group. Scripts using the %CANCEL directives should set up traps or handlers to catch SIGTERM, and exit appropriately. (See the hook examples for a demonstration of this).

  • %TITLE Title String -- sets the text in a text field near the top of the iHook window to "Title String". A %TITLE directive with no parameters will clear the same text field.

  • %DEBUG -- causes iHook to log every subsequent directive received to the iHook drawer.

  • %BEEP -- plays the system beep.

  • %SOUND /path/to/supported/soundfile -- plays soundfile.

  • %TEXTCOLOR <COLOR> -- sets the color of the text in the stdout and TITLE fields to COLOR.

  • %WINDOWZOOM <ENABLE/DISABLE> -- turns on or off the animated resizing or repositioning of the iHook window.

  • %WINDOWMINIATURIZE -- miniaturize the iHook window. If the window is already miniaturized or there is now console user (and therefore no Dock) when this directive is issued, the directive is ignored.

  • %WINDOWDEMINIATURIZE -- deminiaturize the iHook window. If the window is not miniaturized when this directive is issued, the directive is ignored.

  • %UIMODE <AUTOCRATIC/SELFISH/NORMAL> -- sets the system UI mode. AUTOCRATIC hides the Dock and the menu bar, disables application switching with command-tab, disables force-quit and disables logout. SELFISH disables force-quit and logout. NORMAL sets the UI mode to normal. Anything other than these parameters causes iHook to log an error to the drawer, and the UI mode is set to NORMAL.

  • %LOG <OPEN/APPEND/CLOSE> -- iHook output logging. OPEN and APPEND open logfile, creating if it does not exist, and cause all subsequent output from the script iHook is running to be written to logfile. If logfile exists when %LOG OPEN logfile is called, it is overwritten (O_TRUNC). APPEND will append output logfile rather than overwriting. CLOSE stops writing output to logfile. When sending an APPEND after an OPEN, or vice versa, there is an implicit CLOSE between them. The last OPEN or APPEND message sent determines the logfile. If no path is included with any of the %LOG directives, the directive is ignored. Introduced in iHook 1.0.2.

  • %INPUT <ENABLE/DISABLE/REMOVE> [prompt title] -- iHook script input support. ENABLE displays an editable input field in the iHook window, over which is the optional prompt title passed as any additional text following the ENABLE option. DISABLE is identical to ENABLE, except that the input field is not editable. REMOVE removes the input field from the window. When a user hits the Enter or Return keys after entering input, iHook write that input to the running script's stdin. Immediately following any %INPUT ENABLE line, the script is expected to be prepared to receive and process the user input, as in this bourne shell script example:

    #! /bin/sh

    # read user input
    echo "%INPUT ENABLE Please enter some text:"
    read input
    echo "%INPUT DISABLE Processing input..."
    do_input_processing ${input}
    echo %INPUT REMOVE

    The %INPUT family of directives was introduced in iHook 1.1.0.

James Reynolds of the University of Utah gives an overview of iHook in a lab setting. This presentation covers the basic setup of iHook as a logout progress interface, then goes into more depth describing tricks and customizations.

Quick Example iHook Script:
#! /bin/sh

PATH=/bin:/usr/bin; export PATH

# set the background image

# Messages to stdout appear
# in the iHook window
echo Cleaning up temp files...

# ...except iHook Directives,
# which modify the interface.
# This starts a progress bar.
echo %0

# find's errors will go to the
# iHook drawer.
find /tmp -user thisuser -print0 \
| xargs -0 rm -f

# update the progress bar
echo %30

# update the message in the
# iHook window.
echo Finding all .c files...

# We want find's output
# in the drawer, so
# redirect it to stderr.
find / -name \*.c 1>&2

# update the progress bar
echo %90

# update the message in the
# iHook window.
echo Sleeping.

sleep 5

# Finish the progress bar
echo %100