Intuition Menus - Revision history

Steven Solie: /* Sharing Menu Strips */

2015-07-09T18:16:16Z

Sharing Menu Strips

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

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

	=== Sharing Menu Strips ===

	A single menu strip may be attached to multiple windows in an application by calling SetMenuStrip() for each window. All of the windows must be on the same screen for this to work. Since menus are always associated with the active window on a given screen, and since only one window may be active on a screen at a time, only one window may display the shared menu strip at any given time.

	When multiple windows share a single menu strip, they will all "see" the same state of the menus, that is, changes made to the menu strip from one window will still exist when a new window is activated. If the application wishes to share menu strips but to have a different flag and enabled status for each window, the program may watch IDCMP_ACTIVEWINDOW for the windows and modify the menu strip to match the active window's requirements at that point. In addition, the application must also set IDCMP_MENUVERIFY to insure that the user can't access the menus of a newly activated window before the application can process the IDCMP_ACTIVEWINDOW message.

	ResetMenuStrip() may also be used to set the menus for the multiple windows as long as SetMenuStrip() is used first to attach the menu strip to any one window and no major changes are made to the menu strip before the calls to ResetMenuStrip() on subsequent windows.

Steven Solie: /* Changing Menu Strips */

2015-07-09T18:15:43Z

Changing Menu Strips

← Older revision		Revision as of 18:15, 9 July 2015
Line 86:		Line 86:

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

	Direct changes to a menu strip attached to a window may be made only after the menu strip has been removed from the window. Use the ClearMenuStrip() function to remove the menu strip. It may be added back to the window after the changes are complete.

	Major changes include such things as adding or removing menus, items and sub-items; changing text or image data; and changing the placement of the data. These changes require the system to completely re-layout the menus.

	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>
	BOOL ResetMenuStrip( struct Window window, struct Menu menu );
	</syntaxhighlight>

	ResetMenuStrip() is called in place of SetMenuStrip(), and may only be called on menus that were previously initialized with a call to SetMenuStrip(). As with SetMenuStrip(), the menu strip must be removed from the window before calling ResetMenuStrip(). Note that the window used in the ResetMenuStrip() call does not have to be the same window to which the menu was previously attached. The window, however, must be on a screen of the same mode to prevent the need for recalculating the layout of the menu.

	If the application wishes to attach a different menu strip to a window that already has an existing menu strip, the application must call ClearMenuStrip() before calling SetMenuStrip() with the new menu strip.

	The flow of events for menu operations should be:

	<ol>
	<li><p>OpenWindowTagList()</p>
	<p>.</p></li>
	<li><p>SetMenuStrip()</p>
	<p>.</p></li>
	<li><p>Zero or more iterations of ClearMenuStrip() and SetMenuStrip() or ResetMenuStrip().</p></li>
	<li><p>ClearMenuStrip()</p>
	<p>.</p></li>
	<li><p>CloseWindow()</p>
	<p>.</p></li>
	</ol>

	=== Sharing Menu Strips ===		=== Sharing Menu Strips ===

Steven Solie: /* Submitting and Removing Menu Strips */

2015-07-09T18:15:18Z

Submitting and Removing Menu Strips

← Older revision		Revision as of 18:15, 9 July 2015
Line 80:		Line 80:

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

	=== Submitting and Removing Menu Strips ===

	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>
	BOOL SetMenuStrip( struct Window window, struct Menu menu );
	</syntaxhighlight>

	SetMenuStrip() always returns TRUE. This function can also be used to attach a single menu strip to multiple windows by calling SetMenuStrip() for each window (see below).

	Any menu strip attached to a window must be removed before the window is closed. To remove the menu strip, call ClearMenuStrip().

	<syntaxhighlight>
	VOID ClearMenuStrip( struct Window *window );
	</syntaxhighlight>

	The menu example below demonstrates how to use these functions with a simple menu strip.

	=== Disabling Menu Operations ===		=== Disabling Menu Operations ===

Steven Solie: /* Setting Up Menus */

2015-07-09T18:14:49Z

Setting Up Menus

← Older revision		Revision as of 18:14, 9 July 2015
Line 80:		Line 80:

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

	The application does not have to worry about handling the menu display. The menus are simply submitted to Intuition and the application waits for Intuition to send messages about the selection of menu items. These messages, along with the data in the menu structures, give the application all the information required for the processing of the user actions.

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

Steven Solie: /* Setting Up Menus */

2015-07-09T18:13:59Z

Setting Up Menus

← Older revision		Revision as of 18:13, 9 July 2015
Line 84:		Line 84:

	The application does not have to worry about handling the menu display. The menus are simply submitted to Intuition and the application waits for Intuition to send messages about the selection of menu items. These messages, along with the data in the menu structures, give the application all the information required for the processing of the user actions.		The application does not have to worry about handling the menu display. The menus are simply submitted to Intuition and the application waits for Intuition to send messages about the selection of menu items. These messages, along with the data in the menu structures, give the application all the information required for the processing of the user actions.

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

	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.

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

Steven Solie: /* About Menus */

2015-07-09T18:09:28Z

About Menus

← Older revision		Revision as of 18:09, 9 July 2015
Line 14:		Line 14:
	== About Menus ==		== About Menus ==

	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 systems provide 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 ===		=== Types of Menu Choices ===
Line 20:		Line 20:
	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.		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.		Attributes are analogous to adjectives. An attribute stays in effect until cancelled. 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:		For instance, in a word processor, menus could be used to control the following types of features:
Line 36:		Line 36:
	=== The Menu System ===		=== 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.		To activate the menu system, the user presses the menu button (the right mouse button). This most often 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]]		[[File:LibFig2-4.png\|frame\|center\|Screen with Menu Bar Displayed]]
Line 44:		Line 44:
	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.		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]].		Unlike some other systems, the Amiga has no "standard menu" that appears in every menu bar. In fact, a window or gadget need not have any menus at all, thus holding down the mouse menu button does not guarantee the appearance of a menu. 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 ====		==== Selecting Menu Items ====
Line 61:		Line 61:
	==== Menu Item Imagery ====		==== 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~~.		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.

	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.		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.
Line 67:		Line 67:
	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.		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.		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 most often 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 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 items or whole menus may be enabled or disabled. Disabling an item prevents the user from selecting it. Disabled items are ghosted 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 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.

Steven Solie: /* Intuition Menus */

2015-07-09T18:03:21Z

Intuition Menus

← Older revision		Revision as of 18:03, 9 July 2015
Line 4:		Line 4:

	The Intuition menu system handles all of the menu display without intervention from the application. The program simply submits an initialized list of data structures to Intuition and waits for menu events.		The Intuition menu system handles all of the menu display without intervention from the application. The program simply submits an initialized list of data structures to Intuition and waits for menu events.

			There are three basic types of menu subsystems in Intuition:
			# [[Intuition_Classic_Menus\|Classic or Traditional Menus]]
			# [[Intuition_Menu_Class\|BOOPSI Menu Class Menus]]
			# [[Intuition_Context_Menus\|Context Menus]]

			Programmers are urged to use the [[Intuition_Menu_Class\|BOOPSI Menu Class Menus]] which should be able to cover a vast majority of their needs.

	== About Menus ==		== About Menus ==

Steven Solie: /* Intuition Menus */

2015-07-09T17:53:56Z

Intuition Menus

← Older revision		Revision as of 17:53, 9 July 2015
Line 1:		Line 1:
	== Intuition Menus ==		== Intuition Menus ==

	Menus are command and option lists associated with an application window that the user can bring into view at any time. These lists provide the user with a simple way to access features of the application without having to remember or enter complex character-based command strings.		Menus are command and option lists associated with an application window or gadget that the user can bring into view at any time. These lists provide the user with a simple way to access features of the application without having to remember or enter complex character-based command strings.

	The Intuition menu system handles all of the menu display without intervention from the application. The program simply submits an initialized list of data structures to Intuition and waits for menu events.		The Intuition menu system handles all of the menu display without intervention from the application. The program simply submits an initialized list of data structures to Intuition and waits for menu events.

	This section shows how to set up menus that allow the user to choose from your program's commands and options.

	Editors Note: Need to refer to the classic, menu class and context menus in this section. Also need to remove any common text from the Classic Menus section.

	== About Menus ==		== About Menus ==

Steven Solie: /* Intuition Menus */

2015-07-09T04:55:27Z

Intuition Menus

← Older revision		Revision as of 04:55, 9 July 2015
Line 7:		Line 7:
	This section shows how to set up menus that allow the user to choose from your program's commands and options.		This section shows how to set up menus that allow the user to choose from your program's commands and options.

	~~TBD~~: Need to refer to the classic, menu class and context menus in this section.		Editors Note: Need to refer to the classic, menu class and context menus in this section. Also need to remove any common text from the Classic Menus section.

	== About Menus ==		== About Menus ==

Steven Solie: /* Intuition Menus */

2015-07-09T04:54:52Z

Intuition Menus

← Older revision		Revision as of 04:54, 9 July 2015
Line 6:		Line 6:

	This section shows how to set up menus that allow the user to choose from your program's commands and options.		This section shows how to set up menus that allow the user to choose from your program's commands and options.

			TBD: Need to refer to the classic, menu class and context menus in this section.

	== About Menus ==		== About Menus ==