![[me]](logo/logo.png)
osd(2)
[Home]
[Commands]
[Variables]
[Macro-Dev]
[Glossary]
NAME
SYNOPSIS
-4 osd
-3 osd
-2 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-button"] ["initial-item"] [["title-bar-scheme"] ["Text"]] ["resize-command"] ["control-command"] ["init-command"]
osd n i flags ["item-scheme"] ["width" "depth"] ["text"] ["argument" "command"]
n osd
DESCRIPTION
The osd command manages the On-Screen Display, menu and dialogs. For information about the main menu see
Top Main Menu.
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:
Dialog Creation and Redefinition
osd n 0 flags ["scheme"] ["x-pos" "y-pos"] ["min-width" "min-depth" "max-wid" "max-dep"] ["default-button"] ["initial-item"] [["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 be fully drawn on the screen at the given position it will be moved to a position which shows the most.
o
Specifies an offset to the dialog position calculated by MicroEmacs in the arguments x-pos and y-pos, which are the column and row offsets. This flag is ignored when flag a is also specified. If the dialog can not be fully drawn on the screen at the new 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-button" to be the button executed when the return key is pressed and no other button has the focus. The current default button is typically denoted by "> Button <", other buttons are denoted by "[ Button ]" or have no denoting characters, this is configured via the
$window-chars(5) variable.
I
Set "initial-item" to be selected when the dialog first opens, 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 " \HOkay " f void
-4 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
B
Makes the mouse right Button have the same behaviour as the left, by default the right mouse button simply closes the dialog. This is useful for some dialogs which are opened using the right mouse button.
f
Automatically uses the first letter of an item's text 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 ["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, s and d.
m
Sub-menu must be manually opened, using hot-key, the return key or the left mouse button.
s
Specifies the sub-menu is to be placed to the south (under) the parent item, The default when omitted is to the right of the parent.
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 item to be in the tab order of the dialog. The order of tab items in the dialog is auto-generated, based on item i numbers.
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 the 'z' flog or set the text to a string of #'s to set the 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" " \HEnter text" 2
osd 200 2 "ExHf" %osd-entry-scheme "########" 1 my-entry-set
O
Item is a read-only Combo-box type of entry. As with entry items (type E) the command given must return the current value to be displayed in the entry box when it is called with a non-negated argument. However, when the entry box is selected the item behaves like a sub-menu (type M), the command is called (with a negated argument) which can be used to create the sub-menu. The type of item is often used with a button item (type B) to the right of it which also opens the sub-menu by executing this item.
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" " \HEnter text" 2
osd 200 2 "ExHf" %osd-entry-scheme "########" 1 my-entry-set
will be drawn as "[ Okay ]". The hot-key is denoted by \H so for osd item 1 then this is the E of Enter.
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" " \HEnter text" 2
osd 200 2 "ExHf" %osd-entry-scheme "########" 1 my-entry-set
osd 200 3 "BxHcfiR" %osd-ebtt-scheme " \HReset " 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.
u
Disables the high-lighting of the item when the mouse is over it.
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 Execution
Returning Command Control
-4 osd
An invocation of osd with an argument of -4 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
-2 osd
Calling osd with an argument of -2 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
-3 osd
Calling osd with an argument of -3 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, userstp.emf, search.emf, spell.emf and organize.emf for examples of the OSD.
NOTES
In December 2004 the d default item flag in dialog creation was replaced with two new flags, D and I. At the same time the dialog tab order was changed to an automated calculation so a tab index value is no longer required with the item tab t flag.
SEE ALSO
Ref: osd(2) File: m2cmd066.2 Date: 2026/01/12
(c) Copyright JASSPA 2026