Menu Tools: (Part 1)

commands

sigmacs

$utilities

General Menu Tools:

$menu()

$menu()

Format:

$menu(

#mn_action

arg

)

The full format of the command depends upon which of the #mn_action parameters is specified. In the following table the format for each #mn_action is shown in the first section, followed by a description of the various arguments. The actual function of each #mn_action is discussed later in an appropriate sub-section of Menu Tools.

Argument Description

#mn_action $menu(#ml_load, libname) $menu(#ml_unload, libname) $menu(#mn_boxes, mname) $menu(#mn_clr) $menu(#mn_cmd1, mname, group, seq) $menu(#mn_cmd2, mname, group, seq) $menu(#mn_cmdd, mname, group, seq) $menu(#mn_col, mname [, group, seq ]) $menu(#mn_cols, mname) $menu(#mn_del, mname) $menu(#mn_exec, mname, group, seq) $menu(#mn_group, mname, #mn_full, seq) $menu(#mn_high, mname, group, seq) $menu(#mn_lib, mname) $menu(#mn_load, mname [, xpos, ypos [, mtype ] ]) $menu(#mn_name, mtype) $menu(#mn_oload, mname) $menu(#mn_query) $menu(#mn_redraw) $menu(#mn_row, mname [, group, seq ]) $menu(#mn_rows, mname) $menu(#mn_scset, '', disp) $menu(#mn_setorg, mname, xpos, ypos) $menu(#mn_text, mname, group, seq) $menu(#mn_txtc, mname, group, seq) $menu(#mn_txtj, mname, group, seq) $menu(#mn_txtsp, mname, group, seq) $menu(#mn_txtstr, mname, group, seq) $menu(#mn_txtsz, mname, group, seq) $menu(#mn_type, mname) $menu(#mn_unhigh, mname, group, seq) $menu(#mn_upd) $menu(#mn_xhbox) $menu(#mn_xhmenu) $menu(#mn_xhpos, mname, group, seq) $menu(#mn_xorg, mname [, group, seq ]) $menu(#mn_xsz, mname [, group, seq ]) $menu(#mn_yorg, mname [, group, seq ]) $menu(#mn_ysz, mname [, group, seq ])
$menu(#ms_active) $menu(#ms_load, libname) $menu(#ms_unload)

disp This argument determines how the screen display is managed.

Value Description

0 The screen will be cleared.

1 The screen will be cleared and then redrawn.

-1 The screen will neither be cleared nor redrawn. (Because this is going to be handled by some other section of code momentarily.)

group
This integer argument specifies the group number of the target BOX. See BOX:group for additional information.
The special flag #mn_full may be specified which indicates that all menu boxes, regardless of actual group numbers assigned in their respective BOX records, are to be considered.
Examples:
0 01 101 #mn_full

libname This argument specifies the name of a menu library having a `.ml' suffix, which stores the compiled menus. The suffix must be specified as part of the library name. (See Menu Librarys Tools for additional information.)

mname This argument is a string (enclosed within single quotes) which specifies the name of the target menu.
Examples:
'_MAIN' 'DESKTOP' 'LINE'

mtype This argument is a string (enclosed within single quotes) which specifies the type of the menu. (See NAME:type for additional information.)
Examples:
's' 'Op' 'mps'

seq This integer argument specifies the sequence number of the target BOX within the specified group. The sequence number of a box is implicitly determined by its order within the menu definition file, with the first box in a group being 1, the second 2, etc.
If the special flag #mn_full has been specified for the group, then all of the menu's boxes are considered in the sequence they were defined, regardless of the actual group assigned through their respective BOX records. The counting sequence begins with 1.

xpos This integer argument specifies the menu's origin on the global coordinate grid's X-axis.
Notes:

It is important to remember that this value is expressed for the internal coordinate system which begins at 0 rather than 1. Thus, this should be a number between 0 and 51.

ypos This integer argument specifies the menu's origin on the global coordinate grid's Y-axis.
Notes:

It is important to remember that this value is expressed for the internal coordinate system which begins at 0 rather than 1. Thus, this should be a number between 0 and 38.

Return value:


				

				Varies.  (See individual commands for details.)

Menu Display Tools:

$menu(#mn_clr)

$menu(#mn_clr)

Format:

$menu(#mn_clr)

Return value:

None

$menu(#mn_high)

$menu(#mn_high)

Format:

$menu(#mn_high,

mname

group

seq

)

Return value:

None

Example:


				

				$menu(#mn_high, 'LINE', 001, 02)

Tip:

all

Example:


					

					$menu(#mn_high, 'LINE', 001, 0)

See Also:

$menu() for additional information concerning arguments.
$menu(#mn_unhigh)

$menu(#mn_redraw)

$menu(#mn_redraw)

Format:

$menu(#mn_redraw)

Return value:

None

$menu(#mn_unhigh)

$menu(#mn_unhigh)

Format:

$menu(#mn_unhigh,

mname

group

seq

)

Return value:

None

Example:


				

				$menu(#mn_unhigh, 'LINE', 001, 02)

Tip:

all

Example:


					

					$menu(#mn_high, 'LINE', 001, 0)

See Also:

$menu() for additional information concerning arguments.
$menu(#mn_high)

$menu(#mn_upd)

$menu(#mn_upd)

FILL

HIGH

Format:

$menu(#mn_upd)

Return value:

None

Notes:

The $setvar() utility and :ldf sigmac each automatically refresh the menus, so this command should rarely have to be used.

$mnikon()

$mnikon()

Format:

$mnikon(

riname

mname

group

seq

size

col

load

view

use_color

)

Argument Description

riname This required string argument specifies the name of an existing RI to be used to create the icon. The repeated item library containing the RI must be currently loaded.
Example:
'_ikdoor'

mname This required string argument specifies the name of the target menu which is to receive the icon.
Example:
'_IKON'

group This required integer argument specifies the group number of the target menu box. See BOX:group for additional information.
The special flag #mn_full may be specified which indicates that all menu boxes, regardless of actual group numbers assigned in their respective BOX records, are to be considered.
Examples:
101 #mn_full

seq This required integer argument specifies the sequence number of the target menu box within the specified group. The sequence number of a box is implicitly determined by its order within the menu definition file, with the first box in a group being 1, the second 2, etc.
If the special flag #mn_full has been specified for the group, then all of the menu's boxes are considered in the sequence they were defined, regardless of the actual group assigned through their respective BOX records. The counting sequence begins with 1.

size This optional real numeric argument specifies the size of the icon in relation to the box. The default is 1.0 which automatically sizes the icon to just fit the box with a 1-pixel margin around the perimeter. Specifying a smaller value will reduce the icon size proportionately. A value of -1.0 will fit the icon exactly to the box without the 1-pixel border.
Example:
0.75

col This optional integer argument specifies the color to draw any elements in the RI that were created with color #none. All other RI elements will be drawn in their original colors.

load This optional boolean argument indicates whether the specified menu (mname) is to be automatically loaded. Specify #true (the default) to force the menu to be loaded and #false otherwise.

view This optional integer argument indicates how the specified RI (riname) image is to be displayed. Specifying 0 (the default) will show the RI in plan view while a value of 1 will cause the RI to be displayed in isometric view.

use_color This optional boolean argument controls how colors are interpreted when the high resolution (#tclhigh) colormap is in effect. If set to #true, then the actual color in the colormap position specificed by col will be used without any range translation being done for menu colors, etc.
Notes:

If use_color is set to #true, then colors 512 or 513 cannot be used highlight a menu box and colors greater than 256 cannot be used to unhighlight a menu box. If these effects are desired, then leave use_color set to the default #false.

In the high resolution colormap, the menu colors have been relocated to new positions. However, to display a RI using a menu color, specify the old color number (in the ranges 114-141 or 252-255), and leave use_color set to the default #false. ARRIS will then make the proper translation internally.

Argument	Description
riname	This required string argument specifies the name of an existing RI to be used to create the icon. The repeated item library containing the RI must be currently loaded. Example: `'_ikdoor'`
mname	This required string argument specifies the name of the target menu which is to receive the icon. Example: `'_IKON'`
group	This required integer argument specifies the group number of the target menu box. See BOX:group for additional information. The special flag `#mn_full` may be specified which indicates that all menu boxes, regardless of actual group numbers assigned in their respective BOX records, are to be considered. Examples: `101 #mn_full`
seq	This required integer argument specifies the sequence number of the target menu box within the specified group. The sequence number of a box is implicitly determined by its order within the menu definition file, with the first box in a group being 1, the second 2, etc. If the special flag `#mn_full` has been specified for the group, then all of the menu's boxes are considered in the sequence they were defined, regardless of the actual group assigned through their respective BOX records. The counting sequence begins with 1.
size	This optional real numeric argument specifies the size of the icon in relation to the box. The default is 1.0 which automatically sizes the icon to just fit the box with a 1-pixel margin around the perimeter. Specifying a smaller value will reduce the icon size proportionately. A value of -1.0 will fit the icon exactly to the box without the 1-pixel border. Example: `0.75`
col	This optional integer argument specifies the color to draw any elements in the RI that were created with color #none. All other RI elements will be drawn in their original colors.
load	This optional boolean argument indicates whether the specified menu (mname) is to be automatically loaded. Specify #true (the default) to force the menu to be loaded and #false otherwise.
view	This optional integer argument indicates how the specified RI (riname) image is to be displayed. Specifying 0 (the default) will show the RI in plan view while a value of 1 will cause the RI to be displayed in isometric view.
use_color	This optional boolean argument controls how colors are interpreted when the high resolution (#tclhigh) colormap is in effect. If set to #true, then the actual color in the colormap position specificed by col will be used without any range translation being done for menu colors, etc. Notes: If use_color is set to #true, then colors 512 or 513 cannot be used highlight a menu box and colors greater than 256 cannot be used to unhighlight a menu box. If these effects are desired, then leave use_color set to the default #false. In the high resolution colormap, the menu colors have been relocated to new positions. However, to display a RI using a menu color, specify the old color number (in the ranges 114-141 or 252-255), and leave use_color set to the default #false. ARRIS will then make the proper translation internally.

Return value:

None

Notes:

must

$mnikon()

:ril

:riul

Example:


				

				$mnikon('_ikwin', '_IKON', 001, 08)
				


				$mnikon('_ikdoor', '_IKON', 001, 09, 0.8, 20)
				


				$mnikon('brick', 'DTLS', 102, 01, 1, 29, #true, 1)

Bugs:

The col option does not work properly. Currently, this argument is ignored and all RI elements created in color #none will be drawn using the current color shown on the status line. The workaround for this bug is to temporarily set the desired system color, create the ikon and then reset the original color similar to the following. Assuming that #21 is the desired ikon color:
icol = $getvar(#fcol) /* save current color $setvar(#fcol, 21) /* set color #21 $mnikon(...) /* create menu ikon $setvar(#fcol, icol) /* reset orig. color

$mnslide()

$mnslide()

load

If the menu box is square, or taller than it is wide, the scrollbar will be vertical. If the box is wider than it is tall, the scrollbar will be oriented horizontally.

Format:

$mnslide(

mname

group

seq

pos

size

col

rails

load

)

Argument Description

mname This required argument is a string (enclosed in single quotes) which specifies the name of the target menu. (See $menu:mname for additional information.)
group This required integer argument is the group number of the target BOX. (See $menu:group for additional information.
seq This required integer argument is the sequence number of the target BOX. (See $menu:seq for additional information.)
pos This required real numeric argument is the position of the center of the slide bar within the overall slide area. This is specified as a percentage, expressed as a decimal value between 0.0 (minimum) and 1.0 (maximum). This value should represent the relative position within the scrolling list that is currently being displayed.
size This optional real numeric argument indicates the length of the slide bar proportionate to the overall length of the slide area. This is specified as a percentage, expressed as a decimal value between 0.0 and 1.0. Thus, a value of 0.25 would produce a bar 1/4 the overall length of the slide area.
If -1 (the default) is specified, the slide bar will be made square - unless the scrollbar box itself is square, in which case the slide bar will be shown 1/2 the width.

col This optional integer argument indicates the color of the slide bar as shown in the following table. If #fnone (the default) is specified, the slide bar is rendered in color light green (#131) for non-executable group boxes and light grey (color #124) for executable group boxes.

Group No. Color Code

0 1 3 5

"Always Highlighted" Groups
-1, 101
300-399
400-499 black

#141 dark
grey

#140 light
grey

#139 light
green

#131

All Other Groups dark
grey

#114 white

#115 black

#116 grey

#124

Group No. Color Code

-1 thru -255

"Always Highlighted" Groups
-1, 101
300-399
400-499 Set slide area background to (255 + col). For example, -250 would set background color #5.
The slide bar is always rendered in olive green (color #130).

All Other Groups Set slide area background to the absolute value of col. For example, -252 would set background color #252.
The slide bar is always rendered in light green (color #131).

rails This optional integer argument indicates the number of rails to render along the slide area. If not specified, this defaults to 1.
load This optional boolean argument indicates whether the specified menu ( mname) should be automatically loaded (displayed) when this command is executed. This defaults to #false so that the menu is not loaded. Specify #true to force menu loading.

Return value: (integer)

The length of the sliding bar, expressed in pixels. This information is required by sigmacs which must calculate the bar's location within the overall slide area.

Example:


				

				ibar = $mnslide('EXAMP1', #mn_full, 4, 0.2)
				


				ibar = $mnslide('QRYENT', 100, 1, rpos, rscl, #fnone, 1, #true)

See Also:

:mn_slidebar

:mn_slidebar

:mn_slidebar

Format:

:mn_slidebar;='init';=

;='

mname

';=

group

seq

total

pgsize

:mn_slidebar;='sel';=

:mn_slidebar;='page';=

item1

Argument Prompt/Description

cmd Cmd: |init|sel|page|
Enter one of the commands: init, sel or page.
The init command is used to set-up (initialize) and display the scrollbar on the specified menu. After this call, the maximum number of pages, based upon the specified total and pgsize, is returned in the global variable imn_slide(id, 0).
The sel command is used to adjust the scrollbar based upon the current cursor position within the slide area. After this call, the value of item1, the item number that is now displayed in the first position in the scrolling list, is returned in the global variable imn_slide(id, 0). [Note that the item count begins at 0, not 1.]
The page command is used to adjust the scrollbar based upon item1, the item number being displayed in the first position in the scrolling list.

id Slidebar ID number:
This positive integer argument specifies a unique identifier number for the scrollbar. By assigning different id numbers, multiple scrollbars may be managed concurrently.

mname Menu name:
This string argument is the name (see NAME:name) of the menu receiving the the scrollbar.

group Group ID:
This integer argument is the group number of the target box on the menu that is to receive the scrollbar. (See BOX:group for additional information).

seq Box ID:
This integer argument is the sequence number of the target menu box within the specified group, that is to receive the scrollbar. (See $menu:seq for additional information.)

total Total item count:
This integer argument specifies the total number of items to be displayed in the scrolling list associated with this scrollbar.

pgsize Page size:
This integer argument indicates the page size for the scrolling list associated with this scrollbar. This is the maximum number of items that can be displayed at any one time.

item1 1st item on current page:
Used with the page command, this integer argument indicates which item (between 1 and total) is currently being displayed in the first position of the scrolling list. With this information the scrollbar can properly reposition its slide bar within the slide area.

Argument	Prompt/Description
cmd	`Cmd: \|init\|sel\|page\|` Enter one of the commands: init, sel or page. The init command is used to set-up (initialize) and display the scrollbar on the specified menu. After this call, the maximum number of pages, based upon the specified total and pgsize, is returned in the global variable imn_slide(id, 0). The sel command is used to adjust the scrollbar based upon the current cursor position within the slide area. After this call, the value of item1, the item number that is now displayed in the first position in the scrolling list, is returned in the global variable imn_slide(id, 0). [Note that the item count begins at 0, not 1.] The page command is used to adjust the scrollbar based upon item1, the item number being displayed in the first position in the scrolling list.
id	`Slidebar ID number:` This positive integer argument specifies a unique identifier number for the scrollbar. By assigning different id numbers, multiple scrollbars may be managed concurrently.
mname	`Menu name:` This string argument is the name (see NAME:name) of the menu receiving the the scrollbar.
group	`Group ID:` This integer argument is the group number of the target box on the menu that is to receive the scrollbar. (See BOX:group for additional information).
seq	`Box ID:` This integer argument is the sequence number of the target menu box within the specified group, that is to receive the scrollbar. (See $menu:seq for additional information.)
total	`Total item count:` This integer argument specifies the total number of items to be displayed in the scrolling list associated with this scrollbar.
pgsize	`Page size:` This integer argument indicates the page size for the scrolling list associated with this scrollbar. This is the maximum number of items that can be displayed at any one time.
item1	`1st item on current page:` Used with the page command, this integer argument indicates which item (between 1 and total) is currently being displayed in the first position of the scrolling list. With this information the scrollbar can properly reposition its slide bar within the slide area.

Global Variables:

imn_slide(

)

This two-dimensional integer array stores data related to active scrollbars. The first index is the small positive integer id number of the desired scrollbar which was assigned when the original 'init' command was issued. The second index is one of the values listed in the following table:

2nd Index Array Value

imn_slide(id, 0) Stores the return value.
After a 'sel' operation, this is the value of item1, the item number that is now displayed in the first position in the scrolling list. (See 1 below.)
After an 'init' operation, this is the maximum number of display pages for the current list. (See 2 below.)

imn_slide(id, 1) Stores the value of item1, the item number that is now displayed in the first position in the scrolling list. [Note that the item count begins at 0, not 1.]

imn_slide(id, 2) Stores the maximum number of of display pages for the current list.

imn_slide(id, 3) Stores the slidebar length (in pixels), returned from $mnslide().

imn_slide(id, 4) Stores the integer group number of the box on the menu that displays the scrollbar. (See BOX:group for additional information).

imn_slide(id, 5) Stores the integer sequence number within the specified group, of the box on the menu that displays the scrollbar. The sequence number of a menu box is implicitly determined by its order within the menu definition file, with the first box in a group being 1, the second 2, etc.

imn_slide(id, 6) Stores the total number of items in the scrolling list.

imn_slide(id, 7) stores the display size of the scrolling list. This is the maximum number of items that may be viewed at any one time.

2nd Index	Array Value
imn_slide(id, 0)	Stores the return value. After a 'sel' operation, this is the value of item1, the item number that is now displayed in the first position in the scrolling list. (See 1 below.) After an 'init' operation, this is the maximum number of display pages for the current list. (See 2 below.)
imn_slide(id, 1)	Stores the value of item1, the item number that is now displayed in the first position in the scrolling list. [Note that the item count begins at 0, not 1.]
imn_slide(id, 2)	Stores the maximum number of of display pages for the current list.
imn_slide(id, 3)	Stores the slidebar length (in pixels), returned from $mnslide().
imn_slide(id, 4)	Stores the integer group number of the box on the menu that displays the scrollbar. (See BOX:group for additional information).
imn_slide(id, 5)	Stores the integer sequence number within the specified group, of the box on the menu that displays the scrollbar. The sequence number of a menu box is implicitly determined by its order within the menu definition file, with the first box in a group being 1, the second 2, etc.
imn_slide(id, 6)	Stores the total number of items in the scrolling list.
imn_slide(id, 7)	stores the display size of the scrolling list. This is the maximum number of items that may be viewed at any one time.

Level:

Examples:


				

				:mn_slidebar;='init';=1;='GETFIL';=100;=1;=itot;=30
				


				:mn_slidebar;='sel';=1
				


				:mn_slidebar;='page';=1;=icnt

See Also:

$mnslide()

Menu Execution Tools:

$menu(#mn_exec)

$menu(#mn_exec)

action

Format:

$menu(#mn_exec,

mname

group

seq

)

Return value:

None

Example:


				

				$menu(#mn_exec, 'Y_WALL', 001, 04)

See Also:

$menu() for additional information concerning arguments.

Next:

Menu Tools: (Part 2)