Disable.item

The disable.item command grays out a menu item and disables it so it cannot be selected.

Syntax

disable.item(ctl cA);

Remarks

This command will disable all menu items that match controller cA. Disabled items are 'grayed out' when the menu is displayed, so the player cannot select them. Use the enable.item command to enable a menu item that is disabled.

If the item is already disabled, or the controller is not assigned to a menu item, this command has no effect.

If multiple menu items use controller cA, all of them will be disabled when using the disable.item command.

All menu items are re-enabled whenever a game is restarted. Any menu items that need to be disabled permanently (such as separators) will need to be disabled again after a game is restarted.

Don't forget to properly handle keyboard controllers that may be assigned to the same controller number; the disable.item command does not disable keyboard controllers.

Possible Errors

Do not use the disable.item command unless a menu has already been created. AGI will attempt to read invalid data, which at best will have no effect, but could potentially crash AGI.

Example

Code:

[ build a simple menu system
set.menu("Info");
set.menu.item("About   ", c0);
set.menu.item("Help    ", c1);
set.menu("File");
set.menu.item("Save Game      <F5>", c2);
set.menu.item("Restore Game   <F7>", c3);
set.menu.item("-------------------", c20);
set.menu.item("Restart Game   <F9>", c4);
set.menu.item("-------------------", c20);
set.menu.item("Quit        <Alt Z>", c5);

set.key(19, 0, c2); [ CTRL+S assigned to 'save game' controller
disable.item(c20);  [ disable the separators
disable.item(c2);   [ also disable saving
[ submit menu to agi
submit.menu()
[ menu item for 'Save Game' is disabled, but if user 
[ presses CTRL+S, controller c2 will be set to TRUE

Technical Information

Required Interpreter Version:	Available in version 2.411 and above.
Byte-Code Value:	160 (0xA0 hex)

The menu commands were actually added in version 2.272, but the commands did not do anything - they were all null functions. Code to support menus was not added to the commands until version 2.411.

See Also

enable.item