Intuition Classic Menus - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:16:21Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:16, 26 January 2025
Line 17:		Line 17:
	Once the application has set up the proper menu structures, linked them into a list and attached the list to a window, the menu system completely handles the menu display. The menu strip is submitted to Intuition and attached to the window by calling the function SetMenuStrip().		Once the application has set up the proper menu structures, linked them into a list and attached the list to a window, the menu system completely handles the menu display. The menu strip is submitted to Intuition and attached to the window by calling the function SetMenuStrip().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	BOOL SetMenuStrip( struct Window window, struct Menu menu );		BOOL SetMenuStrip( struct Window window, struct Menu menu );
	</syntaxhighlight>		</syntaxhighlight>
Line 25:		Line 25:
	Any menu strip attached to a window must be removed before the window is closed. To remove the menu strip, call ClearMenuStrip().		Any menu strip attached to a window must be removed before the window is closed. To remove the menu strip, call ClearMenuStrip().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID ClearMenuStrip( struct Window *window );		VOID ClearMenuStrip( struct Window *window );
	</syntaxhighlight>		</syntaxhighlight>
Line 37:		Line 37:
	The example works with all versions of the Amiga OS however it assumes that the Workbench screen is set up with the the Topaz 8 ROM font. If the font is different, the example will exit immediately since the layout of the menus depends on having a monospaced font with 8*8 pixel characters.		The example works with all versions of the Amiga OS however it assumes that the Workbench screen is set up with the the Topaz 8 ROM font. If the font is different, the example will exit immediately since the layout of the menus depends on having a monospaced font with 8*8 pixel characters.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	** simplemenu.c: how to use the menu system with a window		** simplemenu.c: how to use the menu system with a window
Line 269:		Line 269:
	An additional function, ResetMenuStrip(), is available to let the application make small changes to the menus without the overhead of SetMenuStrip(). Only two things in the menu strip may be changed before a call to ResetMenuStrip(), they are: changing the CHECKED flag to turn checkmarks on or off, and changing the ITEMENABLED flag to enable/disable menus, items or sub-items.		An additional function, ResetMenuStrip(), is available to let the application make small changes to the menus without the overhead of SetMenuStrip(). Only two things in the menu strip may be changed before a call to ResetMenuStrip(), they are: changing the CHECKED flag to turn checkmarks on or off, and changing the ITEMENABLED flag to enable/disable menus, items or sub-items.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	BOOL ResetMenuStrip( struct Window window, struct Menu menu );		BOOL ResetMenuStrip( struct Window window, struct Menu menu );
	</syntaxhighlight>		</syntaxhighlight>
Line 315:		Line 315:
	The following code fragment shows the correct way to process a menu event:		The following code fragment shows the correct way to process a menu event:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct IntuiMessage *msg;		struct IntuiMessage *msg;
	struct Menu *menuStrip;		struct Menu *menuStrip;
Line 333:		Line 333:
	Intuition specifies which item or sub-item was selected in the IDCMP_MENUPICK event by using a shorthand code known as a ''menu number''. Programs can locate the MenuItem structure that corresponds to a given menu number by using the ItemAddress() function. This function translates a menu number into a pointer to the MenuItem structure represented by the menu number.		Intuition specifies which item or sub-item was selected in the IDCMP_MENUPICK event by using a shorthand code known as a ''menu number''. Programs can locate the MenuItem structure that corresponds to a given menu number by using the ItemAddress() function. This function translates a menu number into a pointer to the MenuItem structure represented by the menu number.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MenuItem ItemAddress( struct Menu menuStrip, ULONG menuNumber );		struct MenuItem ItemAddress( struct Menu menuStrip, ULONG menuNumber );
	</syntaxhighlight>		</syntaxhighlight>
Line 361:		Line 361:
	For example:		For example:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	if (menuNumber == MENUNULL)		if (menuNumber == MENUNULL)
	/* no menu selection was made */ ;		/* no menu selection was made */ ;
Line 532:		Line 532:
	The OffMenu() and OnMenu() functions may be used to enable or disable items while a menu strip is attached to the window.		The OffMenu() and OnMenu() functions may be used to enable or disable items while a menu strip is attached to the window.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID OffMenu( struct Window *window, ULONG menuNumber );		VOID OffMenu( struct Window *window, ULONG menuNumber );
	VOID OnMenu( struct Window *window, ULONG menuNumber );		VOID OnMenu( struct Window *window, ULONG menuNumber );
Line 675:		Line 675:
	Here is the specification for a Menu structure:		Here is the specification for a Menu structure:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Menu		struct Menu
	{		{
Line 724:		Line 724:
	Here is the specification:		Here is the specification:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct MenuItem		struct MenuItem
	{		{
Line 832:		Line 832:
	=== menulayout.c ===		=== menulayout.c ===

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	** menulayout.c - Example showing how to do menu layout in general. This example		** menulayout.c - Example showing how to do menu layout in general. This example

Steven Solie: /* Other Menu Macros */

2015-11-09T19:48:32Z

Other Menu Macros

← Older revision		Revision as of 19:48, 9 November 2015
Line 1,376:		Line 1,376:
	== Other Menu Macros ==		== Other Menu Macros ==

	The MENUNEM(), ITEMNUM() and SUBNUM() macros let an application break a menu number down into its component parts: the specific menu number, the item number and the sub-item number. (See ~~the~~ ~~section on "~~Menu Numbers~~" earlier in this chapter for details~~.) Intuition also supplies macros that allow an application to construct a menu number given its components:		The MENUNEM(), ITEMNUM() and SUBNUM() macros let an application break a menu number down into its component parts: the specific menu number, the item number and the sub-item number. (See [[#Menu Numbers\|Menu Numbers]].) Intuition also supplies macros that allow an application to construct a menu number given its components:

	; SHIFTMENU(n)		; SHIFTMENU(n)

Steven Solie: /* How Menu Numbers Really Work */

2015-11-09T19:47:47Z

How Menu Numbers Really Work

← Older revision		Revision as of 19:47, 9 November 2015
Line 385:		Line 385:
	The following is a description of how menu numbers really work. It should clarify why there are some restrictions on the number of menu components Intuition allows. Programs should not rely on the information given here to access menu number information directly though. Always use the Intuition menu macros to handle menu numbers.		The following is a description of how menu numbers really work. It should clarify why there are some restrictions on the number of menu components Intuition allows. Programs should not rely on the information given here to access menu number information directly though. Always use the Intuition menu macros to handle menu numbers.

	For convenience you should use the menus supplied. For example, to extract the item number from the menu number, call the macro ITEMNUM(menu_number); to construct a menu number, call the macro FULLMENUNUM(menu, item, sub). See the section at the end of this ~~chapter~~ for a more complete description of the menu number macros.		For convenience you should use the menus supplied. For example, to extract the item number from the menu number, call the macro ITEMNUM(menu_number); to construct a menu number, call the macro FULLMENUNUM(menu, item, sub). See the section at the end of this article for a more complete description of the menu number macros.

	Menu numbers are 16-bit numbers with 5 bits used for the menu number, 6 bits used for the menu item number, and 5 bits used for the sub-item number. The three numbers only have meaning when used together to determine the position of the item or sub-item selected.		Menu numbers are 16-bit numbers with 5 bits used for the menu number, 6 bits used for the menu item number, and 5 bits used for the sub-item number. The three numbers only have meaning when used together to determine the position of the item or sub-item selected.

Steven Solie: /* Simple Menu Example */

2015-11-09T19:47:27Z

Simple Menu Example

← Older revision		Revision as of 19:47, 9 November 2015
Line 33:		Line 33:
	=== Simple Menu Example ===		=== Simple Menu Example ===

	Menu concepts are explained in great detail later in this ~~chapter~~; for now though it may be helpful to look at an example. Here is a very simple example of how to use the Intuition menu system. The example shows how to set up a menu strip consisting of a single menu with five menu items. The third menu item in the menu has two sub-items.		Menu concepts are explained in great detail later in this article; for now though it may be helpful to look at an example. Here is a very simple example of how to use the Intuition menu system. The example shows how to set up a menu strip consisting of a single menu with five menu items. The third menu item in the menu has two sub-items.

	The example works with all versions of the Amiga OS however it assumes that the Workbench screen is set up with the the Topaz 8 ROM font. If the font is different, the example will exit immediately since the layout of the menus depends on having a monospaced font with 8*8 pixel characters.		The example works with all versions of the Amiga OS however it assumes that the Workbench screen is set up with the the Topaz 8 ROM font. If the font is different, the example will exit immediately since the layout of the menus depends on having a monospaced font with 8*8 pixel characters.

Steven Solie: /* MenuItem Structure */

2015-11-09T19:47:12Z

MenuItem Structure

← Older revision		Revision as of 19:47, 9 November 2015
Line 757:		Line 757:
	: This points to the data used in rendering this MenuItem. It can point to either an instance of an IntuiText structure with text for this MenuItem or an instance of an Image structure with image data. The program tells Intuition the type of data pointed to by this variable by setting or clearing the MenuItem flag bit ITEMTEXT. (See "MenuItem Flags" below for more details about ITEMTEXT.)		: This points to the data used in rendering this MenuItem. It can point to either an instance of an IntuiText structure with text for this MenuItem or an instance of an Image structure with image data. The program tells Intuition the type of data pointed to by this variable by setting or clearing the MenuItem flag bit ITEMTEXT. (See "MenuItem Flags" below for more details about ITEMTEXT.)

	: Note that the IntuiText or Image data need not be simple imagery, either of them may consist of multiple objects of the same type chained together as described in ~~the chapter "~~Intuition Images, Line Drawing and Text". By chaining multiple IntuiText structures, the application may "fine tune" the positioning of text within each item. This is especially important for proportional fonts, where the width of the individual characters is not constant. This also allows items to have part of the text left justified and part right justified.		: Note that the IntuiText or Image data need not be simple imagery, either of them may consist of multiple objects of the same type chained together as described in [[Intuition_Images,_Line_Drawing_and_Text\|Intuition Images, Line Drawing and Text]]. By chaining multiple IntuiText structures, the application may "fine tune" the positioning of text within each item. This is especially important for proportional fonts, where the width of the individual characters is not constant. This also allows items to have part of the text left justified and part right justified.

	; SelectFill		; SelectFill

Steven Solie: /* Setting Up Menus */

2015-11-09T19:45:46Z

Setting Up Menus

← Older revision		Revision as of 19:45, 9 November 2015
Line 9:		Line 9:
	Menus should be set up with the [[GadTools_Library\|GadTools library]]. Since GadTools makes menu set up easier and handles much of the detail work of menu processing (including adjusting to the current font selection), it should be used whenever possible.		Menus should be set up with the [[GadTools_Library\|GadTools library]]. Since GadTools makes menu set up easier and handles much of the detail work of menu processing (including adjusting to the current font selection), it should be used whenever possible.

	Under older versions of the OS, GadTools was not available. To set up menus that work with these older systems, you use the Menu and MenuItem structures. In general, for each menu in the menu bar, you declare one instance of the Menu structure. For each item or sub-item within a menu, you declare one instance of the MenuItem structure. Text-based menus like the kind used in this ~~chapter~~ require an additional IntuiText structure for each menu, menu item and sub-item. All these structures are defined in <intuition/intuition.h>.		Under older versions of the OS, GadTools was not available. To set up menus that work with these older systems, you use the Menu and MenuItem structures. In general, for each menu in the menu bar, you declare one instance of the Menu structure. For each item or sub-item within a menu, you declare one instance of the MenuItem structure. Text-based menus like the kind used in this article require an additional IntuiText structure for each menu, menu item and sub-item. All these structures are defined in <intuition/intuition.h>.

	The data structures used for menus are linked together to form a list known as a ''menu strip''. For all the details of how the structures are linked and for listings of Menu and MenuItem, see ~~the "~~Menu Structures~~" section later in this chapter~~.		The data structures used for menus are linked together to form a list known as a ''menu strip''. For all the details of how the structures are linked and for listings of Menu and MenuItem, see [[#Menu_Data_Structures\|Menu Data Structures]].

	=== Submitting and Removing Menu Strips ===		=== Submitting and Removing Menu Strips ===

Steven Solie: /* Disabling Menu Operations */

2015-07-09T18:17:59Z

Disabling Menu Operations

← Older revision		Revision as of 18:17, 9 July 2015
Line 260:		Line 260:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	=== Disabling Menu Operations ===

	If an application does not use menus at all, it may set the WFLG_RMBTRAP flag, which allows the program to trap right mouse button events for its own use.

	By setting the WFLG_RMBTRAP flag with the WA_Flags tag when the window is opened, the program indicates that it does not want any menu operations at all for the window. Whenever the user presses the right button while this window is active, the program will receive right button events as normal IDCMP_MOUSEBUTTONS events.

	=== Changing Menu Strips ===		=== Changing Menu Strips ===

Steven Solie: /* Menu Limitations */

2015-07-09T18:17:40Z

Menu Limitations

← Older revision		Revision as of 18:17, 9 July 2015
Line 2:		Line 2:

	Intuition's menu system provides applications with a convenient way to group together and display the commands and options available to the user. In most cases menus consist of a fixed list of text choices however this is not a requirement. Items in the menu list may be either graphic images or text, and the two types can be freely used together. The number of items in a menu can be changed if necessary.		Intuition's menu system provides applications with a convenient way to group together and display the commands and options available to the user. In most cases menus consist of a fixed list of text choices however this is not a requirement. Items in the menu list may be either graphic images or text, and the two types can be freely used together. The number of items in a menu can be changed if necessary.

	=== Menu Limitations ===

	Menus are not layered so they lock the screen while they are displayed. While the screen is locked, applications cannot render graphics into that screen; any rendering will be suspended until the menus are no longer displayed.

	Menus can only display a limited number of choices. Each window may have up to 31 menus, each menu may have up to 63 items, and each item may have up to 31 sub-items.

	Menus always appear at the top of the screen and cannot be repositioned or sized by the user. Moving the pointer to the menu bar may be inconvenient or time consuming for the user. (This is why it is generally a good idea to provide keyboard alternatives for menu items.) If some application has a function that the user will be performing repeatedly, it may be better to use a series of gadgets in the window (or a separate window) rather than a menu item.

	==== Alternatives to Menus ====

	You may want to use a requester or a window as an alternative to menus. A requester can function as a "super menu" using gadgets to provide the commands and options of a menu but with fewer restrictions on their placement, size and layout. See [[Intuition_Requesters\|Intuition Requesters]] for more information.

	A window, also, could be substituted for a menu where an application has special requirements. Unlike menus, windows allow layered operations so that commands and options can be presented without forcing all other window output in the active screen to halt.

	Windows may be sized, positioned and depth arranged. This positioning flexibility allows the user to make other parts of the screen and other windows visible while they are entering data or selecting operations. The ability to access or view other data may be important in the user's choice of actions or attributes. See [[Intuition_Windows\|Intuition Windows]] for more details.

	=== Setting Up Menus ===		=== Setting Up Menus ===

Steven Solie: /* The Menu System */

2015-07-09T18:17:26Z

The Menu System

← Older revision		Revision as of 18:17, 9 July 2015
Line 2:		Line 2:

	Intuition's menu system provides applications with a convenient way to group together and display the commands and options available to the user. In most cases menus consist of a fixed list of text choices however this is not a requirement. Items in the menu list may be either graphic images or text, and the two types can be freely used together. The number of items in a menu can be changed if necessary.		Intuition's menu system provides applications with a convenient way to group together and display the commands and options available to the user. In most cases menus consist of a fixed list of text choices however this is not a requirement. Items in the menu list may be either graphic images or text, and the two types can be freely used together. The number of items in a menu can be changed if necessary.

	=== The Menu System ===

	To activate the menu system, the user presses the menu button (the right mouse button). This displays the menu bar in the screen's title area. The menu bar displays a list of topics (called menus) that have menu items associated with them (see figure). The menu bar and menu items only remain visible while the menu button is held down.

	[[File:LibFig2-4.png\|frame\|center\|Screen with Menu Bar Displayed]]

	When the mouse pointer is moved onto one of the menus in the menu bar, a list of menu items appears below the menu. The user can move the pointer within the list of menu items while holding down the menu button. A menu item will highlight when the pointer is over it and, if the item has a sub-item list, that list will be displayed.

	The specific menu that is displayed belongs to the active window. Changing the active window will change the menu bar and the choices available to the user.

	Unlike some other systems, the Amiga has no "standard menu" that appears in every menu bar. In fact, a window need not have any menus at all, thus holding down the mouse menu button does not guarantee the appearance of a menu bar. Although there is no "standard menu", the AmigaOS development team does have a well-defined set of standards for menu design. These standards are covered in the [[User_Interface_Style_Guide\|Amiga User Interface Style Guide]].

	==== Selecting Menu Items ====

	To select a single menu item, the user releases the menu button when the pointer is over the desired item. Intuition can notify your program whenever the user makes a menu selection by sending an IDCMP message to your window's UserPort. Your application is then responsible for carrying out the action associated with the menu item selected. Action items lead to actions taken by the program while attribute items set values in the program for later reference.

	Menu selection is restricted to the most subordinate item. Top level menus are never selected. A menu item can be selected as long as it has no sub-items, and a sub-item may always be selected. (Of course, disabled menu items and sub-items cannot be selected.)

	Intuition menus allow the user to select multiple items by:

	* Pressing and releasing the select button (left mouse button) without releasing the menu button. This selects the item and keeps the menus active so that other items may be selected.
	* Holding down both mouse buttons and sliding the pointer over several items. This is called drag selecting. All items highlighted while dragging are selected.

	Drag selection, single selection with the select button and releasing the mouse button over an item can all be combined in a single operation. Any technique used to select a menu item is also available to select a menu sub-item.

	==== Menu Item Imagery ====

	Menu items can be graphic images or text. There is no conceptual difference between menus that display text and menus that display images, in fact, the two techniques may be used together. The examples in this chapter use text based menus to avoid the extra code required to define images.

	When the user positions the pointer over an item, the item can be highlighted through a variety of techniques. These techniques include a highlighted box around the selected item, complementing the entire item and replacing the item with an alternate image or alternate text.

	Attribute items can have an image rendered next to them, usually a checkmark, to indicate whether they are in effect or not. The checkmark is positioned to the left of the item. If the checkmark is present, the attribute is on. If not, the attribute is off.

	On the right side of menu items, command key alternatives may be displayed. Command key alternatives allow the user to make menu selections with the keyboard instead of the mouse. This is done by holding down the right Amiga key and then pressing the single character command key alternative listed next to the menu item. Command key alternatives appear as a reverse video, fancy "A", followed by the single character command key.

	Menu items or whole menus may be enabled or disabled. Disabling an item prevents the user from selecting it. Disabled items are ghosted (overwritten with a pattern of dots making the image less distinct) in order to distinguish them from enabled items.

	Menu help allows the application to be notified when the user presses the help key at the same time the menu system is activated. This allows applications to provide a help feature for every item in its menus. Menu help may be requested on any level of a menu.

	=== Menu Limitations ===		=== Menu Limitations ===

Steven Solie: /* Types of Menu Choices */

2015-07-09T18:16:59Z

Types of Menu Choices

← Older revision		Revision as of 18:16, 9 July 2015
Line 2:		Line 2:

	Intuition's menu system provides applications with a convenient way to group together and display the commands and options available to the user. In most cases menus consist of a fixed list of text choices however this is not a requirement. Items in the menu list may be either graphic images or text, and the two types can be freely used together. The number of items in a menu can be changed if necessary.		Intuition's menu system provides applications with a convenient way to group together and display the commands and options available to the user. In most cases menus consist of a fixed list of text choices however this is not a requirement. Items in the menu list may be either graphic images or text, and the two types can be freely used together. The number of items in a menu can be changed if necessary.

	=== Types of Menu Choices ===

	Menu choices represent either actions or attributes. Actions are analogous to verbs. An action is executed and then forgotten. Actions include such things as saving and printing files, calculating values and displaying information on the program.

	Attributes are analogous to adjectives. An attribute stays in effect until canceled. Attributes include such things as pen type, color, draw mode and numeric format.

	For instance, in a word processor, menus could be used to control the following types of features:

	* File loading and saving (action).
	* Editing functions (action).
	* Formatting preferences (attributes).
	* Printing functions (action).
	* Current font and style (attributes).

	Menus can be set up such that some attribute items are mutually exclusive (selecting an attribute cancels the effects of one or more other attributes). For example, a drawing or graphics package may only allow one color to be active at a time; selecting a color cancels the previous active color.

	The program can also allow a number of attributes to be in effect at the same time. A common example of this appears in most word processing programs, where the text style may be bold, italic or underlined. Selecting bold does not rule out italic or underlined, in fact, all three may be active at the same time.

	=== The Menu System ===		=== The Menu System ===