M_DISABLE

Disable an item

xcall M_DISABLE([D_ENTRY,] col_id, ent_name[, ...])
xcall M_DISABLE(D_LIST, col_id, list_name[, ...])
xcall M_DISABLE(D_COLUMN, col_id[, ...])
xcall M_DISABLE(D_SUB, sub_name, ent_name[, ...])

Arguments

D_ENTRY

(optional) Disables a menu entry on a placed menu column. (default)

D_LIST

Disables a list of menu entries on a placed menu column.

D_COLUMN

Disables a placed primary column.

D_SUB

Disables a submenu entry, pop-up menu entry, or entry in a submenu to a pop-up menu on a loaded menu column.

col_id

The ID of the column to be disabled or the column in which the entry or list is located. Col_id is returned by the M_LDCOL and MB_END subroutines. (n)

ent_name

The name of the entry to disable. Ent_name is an entry name from the .ENTRY script command or MB_ENTRY. (a)

list_name

The name of the list of entries to disable. List_name is a list name from the .LIST script command or MB_LIST. (a)

sub_name

The name of the submenu, pop-up menu column, or submenu to a pop-up menu that contains the menu entries or submenu columns to disable. (a)

Discussion

M_DISABLE disables menu entries, lists of menu entries, menu columns or subcolumns, entries in pop-up menu columns, or entries in submenus to pop-up menu columns. It has the four forms listed above.

You can specify more than one ent_name or more than one list_name. You can also specify more than one col_id if the qualifier is D_COLUMN. But M_DISABLE can have no more than nine arguments.

Note the following:

Col_id must be the ID of a loaded and placed column. An unloaded column will cause a fatal Toolkit error.
Sub_name must be a valid menu column name. (Sub_name can be the name of an unplaced column or an unloaded column created using MB_COLUMN with the D_NOLOAD option.)
If you’re using D_SUB to enable a pop-up menu entry or a submenu to a pop-up menu, placing the column on the menu bar will cause the entry or submenu to be reset to its default state. An entry in a submenu to a pop-up menu, however, will remain enabled when the column that references the submenu is placed on the menu bar.

While your application is running, if the user selects a disabled entry in a primary column or submenu column, or if the user selects a submenu column, M_PROCESS will stay active but will return to the menu bar. If the user selects a disabled pop-up menu entry, M_PROCESS will no longer be active; control will return to the calling routine. In this case, g_select will be false and g_entnam will be blank.

On Windows, disabled menu entries can be highlighted, but the user will not be able to select them.

Examples

In the following example, the entries “ar” and “ap,” located in the column whose ID is stored in colid(i), are disabled.

xcall m_disable(colid(i), "ar", "ap")

In the next example, the entries in the list sysmgr in the column stored in colid(i) are disabled.

xcall m_disable(D_LIST, colid(i), "sysmgr")

In the following example, the column whose ID is stored in colid(i) is disabled.

xcall m_disable(D_COLUMN, colid(i))

In the following example, the submenu entry “o_owner” is disabled in the submenu named “admin.”

xcall m_disable(D_SUB, "admin", "o_owner")