|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall MB_COLUMN(control, column, text, [D_GLOBAL], [D_NOLOAD|D_NOPLC], [disabled], & [justification] [, quick_select])
Arguments
control
The menu control structure. (a)
column
The name of the menu column to create (a maximum of 15 characters). (a)
text
The heading text for the menu column. (a)
D_GLOBAL
(optional) The global column flag. (n)
D_NOLOAD
(optional) Don’t load the column (which implies D_NOPLC; see the Discussion below). (n)
D_NOPLC
(optional) Don’t place the column. (n)
disabled
(optional) The true/false flag that indicates whether the column will be initially disabled. (n)
justification
(optional) One of the following justification flags: (n)
0 = Left-justified beneath heading. (default)
1 = Right-justified beneath heading.
2 = Centered beneath heading.
quick_select
The quick-select character for the column. (a)
MB_COLUMN begins a menu column specification. This subroutine is used when building a new menu column at runtime.
The control argument must be large enough to include all of your column information. We recommend that control be several hundred bytes, but the size you’ll need depends on the column information in your application. For example, a column with nine entries, one blank line, one horizontal line, and one text line would need 850 bytes. You can use this example as a guideline, but there is no simple algorithm to determine what you’ll need for control. If the control area is too small for the column you’re defining, Toolkit generates the error “overflow of column build array.”
As another example, the size of the control space used by the Script program is 24,540. This setting accommodates the largest possible menu column.
|
The maximum available memory for all loaded columns (including columns created with MB_COLUMN) is 65,565 bytes on Windows and Unix and 8,192 bytes on OpenVMS. If your application exceeds this, Toolkit will generate an error. Note that this limit includes all information about the columns: information you’ve specified and internal information. If you get this error, you must reduce the amount of information in the columns. For example, you might be able to reduce user text or shortcuts associated with the menu entries. |
If you pass a null string (“ ”) for column, Toolkit assigns a unique column name in the form _W_nnn, where nnn is the column ID.
If you pass D_GLOBAL, the column is classified as global rather than local.
By default the column will be loaded and placed. You can, however, can pass D_NOLOAD to prevent the column from being loaded, and D_NOPLC to prevent the column from being placed on the menu. If you are creating pop-up columns or submenu columns, or if you are creating a column just to save it to a window library, the D_NOLOAD option can save space in the memory control structure (see note above). D_NOLOAD implies D_NOPLC, but you can pass both by combining them with the bitwise operators .BOR. and |. Additionally, note the following restrictions for unloaded columns:
- You can’t pass the column ID (column_id returned by MB_END) of an unloaded column to M_COLUMN or %M_TEXT. This will cause a fatal error.
- You can’t pass the column ID (column_id returned by MB_END) of an unloaded column to M_ENABLE or M_DISABLE when using D_ENTRY, D_LIST, or D_COLUMN. This will cause a fatal error. You can, however, use an unloaded column with M_ENABLE and M_DISABLE when using D_SUB.
If you use D_NOLOAD or D_NOPLC, you can later load and/or place the column with M_LDCOL and M_COLUMN.
If disabled is present and non-zero, the column will initially be disabled when it is placed.
Use the quick_select argument to specify the quick-select character (case-insensitive) for the menu column. If quick_select is passed with more than one character, the first character becomes the quick-select character. If you don’t pass quick_select, Toolkit won’t establish a quick-select character for the column header.
To create a submenu column, define the column, and then define the parent menu column (the menu from which the submenu will cascade). In the submenu column’s definition, use the D_NOPLC argument. In the parent menu column’s definition, use the D_SUBMENU argument for the menu entry that will cause the submenu to be displayed, and use the submenu column’s name (the column argument for this routine, MB_COLUMN) as the entry name (the entry argument for MB_ENTRY) for the menu entry. You must define the submenu before you define its parent menu. See the example below.
See also
.COLUMN script command for information on beginning a menu column definition
Examples
For a complete example, see the MB_BLANK Examples, which use all the “MB_xxx” subroutines.
The following example program has one subcolumn, “MYSUB”, that appears when a user selects “My sub” from the File menu.
.include 'WND:tools.def'
.include 'WND:inpctl.def'
record ids
menu_id ,i4
sub_id ,i4
record
control ,a1000
proc
xcall u_start
xcall mb_column(control,"MYSUB","My Sub",,D_NOPLC)
xcall mb_entry(control,"SUB1","Sub1")
xcall mb_entry(control,"SUB2","Sub2")
xcall mb_entry(control,"SUB3","Sub3")
xcall mb_end(control,sub_id)
xcall mb_column(control,"FILE","File")
xcall mb_entry(control,"O_EXIT","Exit",F4_KEY)
xcall mb_entry(control,"MYSUB","My Sub",D_SUBMENU)
xcall mb_end(control,menu_id)
repeat
begin
xcall m_process
using (g_entnam) select
("O_EXIT"), exitloop
(""), xcall u_message("Menu Entry: "+g_entnam)
endusing
end
xcall u_finish
.end
