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
- %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 + .),
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
- %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
- %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:
# read user input
echo "%INPUT ENABLE Please enter some text:"
echo "%INPUT DISABLE 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
Quick Example iHook Script:
PATH=/bin:/usr/bin; export PATH
# set the background image
echo %BACKGROUND \
# 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.
# find's errors will go to the
# iHook drawer.
find /tmp -user thisuser -print0 \
| xargs -0 rm -f
# update the progress bar
# 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
# update the message in the
# iHook window.
# Finish the progress bar