osd(2)

NAME

osd - Manage the On-Screen Display

SYNOPSIS

osd
-1 osd
-2 osd
n osd
-1 osd n
osd -1 flag
osd n 0 flags ["scheme"] ["x-pos" "y-pos"] ["min-width" "min-depth" "max-wid" "max-dep"] ["default"] [["title-bar-scheme"] ["Text"]] ["resize-command"] ["control-command"] ["init-command"]
osd n i flags ["tab-no"] ["item-scheme"] ["width" "depth"] ["text"] ["argument" "command"]

DESCRIPTION

The osd command manages the On-Screen Display, menu and dialogs. The command takes various forms as defined by the arguments. Each of the argument configurations is defined as follows:-

Main Menu-Bar Status

osd -1 flag

This invocation determines the state of the top main menu bar. The state is set by the argument flag defined as:-

 1 - enable.
 0 - disable.
-1 - disable and destroy.

Dialog Creation and Redefinition

osd n 0 flags ["scheme"] ["x-pos" "y-pos"] ["min-width" "min-depth" "max-wid" "max-dep"] ["default"] [["title-bar-scheme"] ["Text"]] ["resize-command"] ["control-command"] ["init-command"]

This invocation creates or resets the base properties of dialog n. The flags argument determines the arguments and are defined as follows:

A


Defines dialog as an alpha type dialog, items are added according to their string text value. Alpha dialogs may not have separator or child items.

i


Used with the A flag, sets the alpha ordering to be case insensitive.

G


Create a Grid dialog. Every item in the dialog is given a single character boarder around it. If one of the dialogs items is also given a 'G' flag, the boarder is drawn as a box around it, otherwise spaces are used.

N


Create a Note-Book (or tabs) dialog. The dialog can only contain one dialog inclusion item ('I') and Note-Book pages ('P'). Pages added before the Inclusion item (page item number is lass than the inclusion page item number) will be drawn at the top of the note-book, those added after will be drawn at the bottom.

b


Draw boarder, draws a boarder around the outside of the dialog. See also flag t (title) as flag effects the boarder.

a


Defines the absolute start-up position of the dialog in the arguments x-pos and y-pos, which are the column and row positions respectively of the dialog from the top left-hand corner of the display. The arguments must be specified. e.g. the main menu is defined with an absolute position of (0,0). If the dialog can not fully drawn on the screen at the given position it will be moved to a position which shows the most.

s


Sets the size of the dialog. osd automatically resizes a dialog to fit the contents, this flag should be considered as a size hint for osd, and is not guaranteed to be honored. If the dialog has a boarder (flag b) the size given should include the boarder size.

The arguments, min-width, min-depth, max-width and max-depth must be specified, as

+ve


The actual size of the dialog, minimum and maximum sizes.

0


min value should be specified as desired window size, max may be 0 which specifies the screen size.

-ve


min defines the maximum size. max is unlimited.

The following table shows possible combination of the sing parameters and their effect:-

min=0, max=0


Default setting, makes dialog as small as possible, with a maximum size of the screen.

min=0, max=50


Make dialog as small as possible with a max of 50 characters.

min=50, max=0


Make dialog as small as possible, but make it at least 50 characters big and no larger than the screen.

min=30, max=-1


Make dialog at least 30 characters big with no upper limit, very useful for dialogs being used as scrolled children.

min=-1, max=50


Make dialog 50 characters big.

min=-1, max=0


Make dialog the same size as the screen.

min=-1, max=-1


Make dialog as big as possible (do not do this unless you have a large amount of memory to throw away).

S


Sets the main dialog scheme, The default scheme when not specified is $osd-scheme(5) See macro file fileopen.emf for an example.

d


Sets default item to select to "default". This item is selected when the dialog is first opened, if this item is an automatically opened sub-menu then the child menu will also be opened.

t


Title bar is present - draws the title bar. The text argument is optional Also see flags H, c and r.

H


Defines the title bar color scheme if flag t is specified. If t is absent the option is ignored.

c


Centers the title bar text if specified. Option t must be specified, otherwise the option is ignored.

r


Right justifies the title bar text if specified. Option t must be specified, otherwise the option is ignored.

R


Defines the dialog as re-sizable. The resize-command argument must be specified and the command should resize the dialog to the sizes given in $result(5) in the format "wwwwdddd", where w is width and d the depth. If the resize-command is aborted then that resize operation is abandoned.

M


Identifies the dialog as the main menu dialog.

C


Binds a command to the dialog, which is automatically executed when the dialog is opened. When the dialog with a C attribute is opened, it is rendered on the screen and then a command, defined by control-command is invoked, when the command completes the dialog is closed.

The command dialog is typically used to create status messages. e.g. a "Busy - Please Wait" dialog box, such a dialog may be implemented when saving the current buffer then create the simple dialog and sent the control-command to save-buffer(2). The dialog would be defined as:-

osd 200 0 "btcHC" %osd-title-scheme "Saving Buffer" save-buffer 
osd 200 1 "" 
osd 200 2 "" "Busy - Please Wait" 
osd 200 3 "" 
200 osd 

If the dialog has buttons which need to become active then control can be returned to osd by calling osd with no arguments, e.g. in the above example the dialog can be made to stay on the screen until the user selects okay by:

define-macro test-osd 
    save-buffer 
    osd 200 2 "" "Save Complete" 
    osd 200 4 "BcfH" %osd-ebtt-scheme "  &Okay  " f void 
    osd 
!emacro 

osd 200 0 "btcHC" %osd-title-scheme "Saving Buffer" test-osd 
osd 200 1 "" 
osd 200 2 "" "Busy - Please Wait" 
osd 200 3 "" 
osd 200 4 "BcfHS" %osd-dbtt-scheme "  Okay  " 

200 osd 

The above mechanism is how spell-buffer(3) operates.

k


Disables hot-keys for the dialog. All text strings are copied literally. This is useful for dialogs like the tags child dialog as many tags have '&'s in them.

f


Automatically uses the first letter of an item's test as the hot key. Unlike the normal hot keys, the letter is not hi-lighted and when typed by the user the item is only selected, not executed. This flag also disables the normal hot-keys for the dialog, so all text strings are copied literally.

n


Disables '\n' characters in text fields leading to multi lines. By default a text item of "Hello\nWorld" will create an item 5 by 2 characters big.

If "init-command" is given then this function is always called just prior to the dialog being displayed so it can be used to configure the dialog.

Dialog Destruction

-1 osd n

This invocation destructs a dialog n. The dialog is only destroyed if it is not currently being displayed.

Dialog Item Creation and Redefinition

osd n i flags ["tab-no"] ["item-scheme"] ["width" "depth"] ["text"] ["argument" "command"]

This invocation type adds a new item i to a dialog n, the operation of the invocation is controlled by the flags as follows:-

D


Disable item i, the item is ignored and is not rendered in the dialog.

I


Include dialog "argument" into this dialog. If "command" is specified then it is called prior to the child being constructed and can be used to define the child. This is similar to the Ms command. See also flag b.

P


Item is a Note-Book page, the item must have text and have an argument which is the osd dialog to be show when the page is activated.

M


Item is a sub-menu, The argument "argument" specifies the sub-menus osd dialog number. A "command" may also be specified which is executed first, this can actually re-define the item and set the dialog number, e.g.

; To start with the dialog number is unknown 
osd 1 1 "M" f submenu-setup 

define-macro submenu-setup 
    osd 200 0 .... 
    .... 
    ; Now the sub-menu number is known redefine parent item, 
    ; note the setup  command  is not given as we have now set 
    ; it up! 
    osd 1 1 "M" 200 
!emacro 

See also options m, n, e, s, w and d.

m


Sub-menu must be manually opened, using hot-key, the return key or the left mouse button.

n, e, s, w


Specify where a sub-menu is to be placed relative to the parent item. The letter indicates the direction as points on a compass, North, East, South and West, respectively. The default when omitted is East.

d


Display sub-menu type, i.e. ".." for auto opening and " >" for a manual opening sub-menu.

-


Fill a non-defined chars with '-'s instead of ' 's, used to draw the lines across menus, typically with no text given, e.g.

osd 200 5 "-" 

But could also be specified as:

osd 200 5 "-c" "Lined" 

C


Item is a check-box. The setting of the check-box is evaluated when the dialog is first drawn, re-draw and whenever any item is executed. A "command" must be specified which must both return the current setting when the given argument (of 1) is given (!abort if false, !return if true) and change the value if the argument value is negated. The text string must also be specified, the first 6 characters are used in the drawing of the check box. The format can be shown as follows:-

String\State       Off         On 
"123456"            "12356"     "12456" 
" (-+)^"            " (-)"      " (+)" 
"^[ *] "            "[ ] "      "[*] " 
"^^NY^^"            "N"         "Y" 
"^^^^^^"            ""          "" 

Note that no character is rendered when a '^' character is used. See also p for prepending the check-box.

p


Prepend the check-box box. By default a check box is drawn as:

"Check box12?56" 

This option changes it to:

"12?56Check box" 

x


When the item is executed do not exit the dialog. Often used with Check-boxes.

i


The command given is a command line string which is executed in a similar fashion to execute-line(2). Note that if an argument is required it is usually specified in the string, i.e.

osd "i" "text" 5 "1000 ml-write @#" 

writes the argument (i.e. 5) for 1 second.

osd "i" "text" 5 "my-command" 

in this case my-command will not be given an argument,

osd "i" "text" 5 "10 my-command" 

in this case my-command will be given an argument of 10,

osd "i" "text" 5 "@# my-command" 

in this case my-command will be given an argument of 5.

h


Horizontally add the next item, e.g.

osd "h" "1st on line " 
osd ""  "2nd on line" 

Will produce "1st on line 2nd on line". If there is not enough room on a single dialog line to display all the horizontally added items then the line is split and as many lines as needed are used.

c


Center the text for the item in the middle of the dialog.

r


Right hand justify the text for the item.

t


Set the items tab order in the dialog.

b


Child inclusion is a scroll box type. By default a child inclusion simply draws the whole child dialog at the position. If this flag is specified then arguments "width" and "depth" must also be supplied and a window displaying "width" by "depth" of the child is created. The size of this item will be "width"+1+ss by "depth"+1+ss where ss is the scroll bar size which is 1 or 2 depending on the setting of $scroll-bar(5). It is up to the user to ensure that the child dialog being displayed is at least "width" by "depth" characters in size, if this is not true then the effect is undefined, (a crash dump is not out of the question).

f


Fix the item size to the given "size", by default an item is expanded to the width of the dialog.

E


Item is an entry box type. Use a string of #'s to set the position and size of the entry text box. Similar to Check-boxes, the command given must both return and set the value depending on value of the argument given. The value must be returned in $result(5) if the given argument (or 1 for 'f') is given, and the value must be set (usually using @ml(4) or @mc(4)) if the argument is negated. The absolute value of the argument is maintained.

set-variable %entry-value "Hello world" 

define-macro my-entry-set 
    !if &equ @# -1 
        set-variable %entry-value @ml "" %entry-value 
    !else 
        set-variable $result %entry-value 
    !endif 
!emacro 

osd 200 1  "S" " &Enter text" 2 
osd 200 2  "ExHf" %osd-entry-scheme "########" 1 my-entry-set 

B


Item is a Button type. Add the last 2 characters of $window-chars(5) to the text string given, one on each side, i.e. if the last two chars are "[]" then:

osd "B" " Okay " 

will be drawn as "[ Okay ]". See also flag T.

T


Item is a repeat type, this is typically used with buttons, altering their execution behavior. By default an item is only executed when the left mouse button is released while over the item. However when this flag is specified the item is executed as soon as the left mouse button is pressed and is repeatedly executed until the button is release or the mouse moves off the item. The delay between repeated executions is determined by the variables $delay-time(5) and $repeat-time(5).

S


Item is a separator type. This is not often required as any item without anything to execute is automatically set to be a separator. Occasionally a mouse-insensitive item which can be executed is required, typically a text string with a hot key, e.g.

osd 200 1  "S" " &Enter text" 2 
osd 200 2  "ExHf" %osd-entry-scheme "########" 1 my-entry-set 

will be drawn as "[ Okay ]"

Item 1 will have a hot-key which executes item 2 (as no command is given), but it will not hi-light if the mouse is placed over it.

R


Redraw dialog. Forces a redraw of the dialog when the item is executed. This is not usually required as osd generally works out for itself whether a redraw is needed, however, sometimes it does not, most notably when the item sets a variable that is displayed by another item as an entry, e.g.

set-variable %entry-value "Hello world" 

define-macro my-entry-set 
    !if &equ @# -1 
        set-variable %entry-value @ml "" %entry-value 
    !else 
        set-variable $result %entry-value 
    !endif 
!emacro 

osd 200 1  "S" " &Enter text" 2 
osd 200 2  "ExHf" %osd-entry-scheme "########" 1 my-entry-set 
osd 200 3  "BxHcfiR" %osd-ebtt-scheme  " &Reset " f "set-variable %entry-value\"\"" 

If item 3 did not have flag R set when executed, osd would not realize that the change to value %entry-value affects the display and the button would not appear to operate.

H


Sets the item color scheme. Note that for scrolled child items this only sets the scroll-box color scheme, the dialog scheme is used for the rest of the boarder.

G


This flag is only applicable in grid dialogs (see flag G in dialog creation). The current item will be drawn with a box around it using $box-chars(5).

z


Sets the item size, arguments "width" and "depth" must be given.

N


This flag only has an effect on entry item types, it selects 'New-line' style text entry which allows the user to enter multiple line of text using the return key and to end the input using the tab key.

Note that for a non-sub-menu item type, if an argument is given with no command then it is assumed that the number given is the item number to be executed, see flag S for an example.

Dialog Exacution

n osd

This invocation with a single positive numeric argument executes the nth dialog.

Returning Command Control

osd

An invocation of osd with no arguments returns control back to the osd from a control-command. Refer to the C flag in the create/reset dialog property for information and an example.

Current Dialog Redraw

-1 osd

Calling osd with an argument of -1 forces the complete redrawing of current dialog and any sub-dialogs. This is very useful when the execution of one item may effect the appearance of another.

Redraw All Active Dialogs

-2 osd

Calling osd with an argument of -2 forces the complete redrawing of all currently active osd dialogs. This is better than calling screen-update(2) when only the osd dialogs need updating as it suffers less from flickering.

EXAMPLE

Refer to osd.emf, user.emf, search.emf, spell.emf and organize.emf for examples of the OSD.

SEE ALSO

$osd-scheme(5), $result(5), $scroll-bar(5). $window-chars(5).

(c) Copyright JASSPA 1999
Last Modified: 1999/08/23
Generated On: 1999/12/01