MB_COLUMN

Create a new column

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
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)

Discussion

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 following 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.

Note

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:

If you use D_NOLOAD or D_NOPLC, you can later load and/or place the column with M_LDCOL and M_COLUMN. See 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 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