Command: hint

Syntax

hint { <file> }

or

hint {
    <menu_block>
}

Description

Display a pop-up message and wait for a mouse hit.

Parameters

• <file>
  A text file containing details of the hint text. The default file extension is .men. If this parameter is not present, text details will be expected to appear in a language block following the command line.

• <menu_block>
  A language block, each line providing details of one line of hint text.

Switches

• -aw
  Only mouse hits within alpha windows will be accepted. Mouse hits elsewhere on the display are ignored unless the -m option is present. This option is ignored if the -iw switch is present.

• -bcol=<color>
  The color of the off bits in a monochrome image file (if applicable). If omitted, white is used.

• -but
  Precede any numbered text options by a pictorial button image (alpha text hints only).

• -col=<color>
  The color of the pop-up box. If omitted, a default color is used.

• -cr=<file>
  Display an image file as the hint rather than alpha text (the default).

• -cur=<cursor>
  The interactive cursor to be used during mouse operation. If omitted, a system cursor will be used.

• -e=<string>
  An echo string to be appended to the hint message. During mouse movement, the string expression will be re-evaluated and displayed at every new mouse position.

• -fcol=<color>
  The color of the on bits in a monochrome image file (if applicable). If omitted, black is used.

• -fo=<font>
  The font to be used for text in the pop-up message. This must be a fixed font. If omitted, a default system font is used.

• -gw
  Only mouse hits within graphic windows will be accepted. Mouse hits elsewhere on the display are ignored unless the -m option is present. This option is ignored if the -iw switch is present.

• -iw=<window>
  Only mouse hits within <window> will be accepted. <window> must be a graphic or alpha window. Mouse hits elsewhere on the display are ignored unless the -m switch is present.

• -m{p}
  Permit the operator to choose from the master menus as an alternative to using the hint mechanism.

• If -mp is used, all commands selected from master menus will be executed in-line, i.e. control will return to the pop-up menu after execution.

• If -m is used then only master menu commands beginning with a | character will be executed in-line, and commands without a leading | will abort the hint before being executed.

• -ocol=<color>
  The other color for use in the pop-up box, e.g. for text. If omitted, a default color is used.

• -pos=<screen_xy> The position of the hint box in screen coordinates. If omitted, the value of the system numeric menu_position is used.

• -th=<num>
  Draw a line of thickness <num> around hint image. The color used is the menu other color (-ocol). This option is relevant only when the -cr switch is present.

• -tit=<string>
  The text to be displayed in the menu window frame. If omitted, the program name is displayed.

Block

The format of each line within menu_block or file is:

<num>: { <message> } { <command_block> }

where:

• <num>
  A zero value will indicate a normal line of text to appear in the hint. Any other value will indicate a mouse button number and should be unique within the block.

• <message>
  The text to be displayed in the hint option. When the -but switch is present, text on lines with a non-zero <num> value will be preceded by a pictorial image of the corresponding button number, thus providing the user with information regarding button functionality.

• <command_block>
  A block of commands to be executed when mouse button <num> is pressed. The block must be enclosed within braces. If the first command within <command_block> is preceded by a | character, then the commands are executed while keeping the hint active. If no <command_block> is present, the hint operation is terminated.

Notes

The button used to terminate the mouse action can be examined via the system numeric button.

When an image file is used for the hint, neither the title nor pictorial button images (-but) are displayed.

If none of the switches -aw, -gw or -iw is present, then a mouse hit in any graphic or alpha window will be accepted.

Examples

Prompt for a point selection (in graphic windows only).

hint -col=grey, -gw {
    0: 'Indicate a 3-D Point'
}
if (button != 2) {
    uncursor; # Reuse mouse point.
    tell <'Point selected:',pcur>
}

Crude window manager hint with button indications.

hint -but, -e=mouse_window {
    1: 'Select Window' {
        | wexpose mouse_window
        current_window = mouse_window
    }
    2: '*** QUIT ***'
    3: 'Move Window' { | wmove mouse_window }
    4: 'Hide Window' { | whide mouse_window }
    5: 'Resize Window' { | wsize mouse_window }
    6: 'Repaint Window' { | wpaint mouse_window }
    7: 'Iconise Window' { | wclose mouse_window }
    8: '*** QUIT ***'
    9: 'Delete Window' { | wdelete mouse_window }
}

Raster file hint (note the empty menu block).

hint -cr='my_file.ras' { }

See Also