GadTools Menus - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:18:03Z

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

← Older revision		Revision as of 19:18, 26 January 2025
Line 20:		Line 20:
	With GadTools, it takes only one structure, the NewMenu structure, to specify the whole menu bar, For instance, here is how a typical menu strip containing two menus might be specified:		With GadTools, it takes only one structure, the NewMenu structure, to specify the whole menu bar, For instance, here is how a typical menu strip containing two menus might be specified:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct NewMenu mynewmenu[] =		struct NewMenu mynewmenu[] =
	{		{
Line 58:		Line 58:
	The NewMenu structure used to specify GadTools menus is defined in <libraries/gadtools.h> as follows:		The NewMenu structure used to specify GadTools menus is defined in <libraries/gadtools.h> as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct NewMenu		struct NewMenu
	{		{
Line 138:		Line 138:
	The functions used to set up and control GadTools menus are discussed in the next section. Before looking at these functions in detail, it may be helpful to look at a brief example.		The functions used to set up and control GadTools menus are discussed in the next section. Before looking at these functions in detail, it may be helpful to look at a brief example.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* gadtoolsmenu.c		/* gadtoolsmenu.c
	** Example showing the basic usage of the menu system with a window.		** Example showing the basic usage of the menu system with a window.
Line 300:		Line 300:
	The CreateMenus() function takes an array of NewMenus and creates a set of initialized and linked Intuition Menu, MenuItem, Image and IntuiText structures, that need only to be formatted before being used. Like the other tag-based functions, there is a CreateMenusA() call that takes a pointer to an array of TagItems and a CreateMenus() version that expects to find its tags on the stack.		The CreateMenus() function takes an array of NewMenus and creates a set of initialized and linked Intuition Menu, MenuItem, Image and IntuiText structures, that need only to be formatted before being used. Like the other tag-based functions, there is a CreateMenusA() call that takes a pointer to an array of TagItems and a CreateMenus() version that expects to find its tags on the stack.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Menu CreateMenusA( struct NewMenu newmenu, struct TagItem *taglist );		struct Menu CreateMenusA( struct NewMenu newmenu, struct TagItem *taglist );
	struct Menu CreateMenus( struct NewMenu newmenu, Tag tag1, ... );		struct Menu CreateMenus( struct NewMenu newmenu, Tag tag1, ... );
Line 340:		Line 340:
	The Menu and MenuItem structures returned by CreateMenus() contain no size or positional information. This information is added in a separate layout step, using LayoutMenus(). As with the other tag-based functions, the program may call either LayoutMenus() or LayoutMenusA().		The Menu and MenuItem structures returned by CreateMenus() contain no size or positional information. This information is added in a separate layout step, using LayoutMenus(). As with the other tag-based functions, the program may call either LayoutMenus() or LayoutMenusA().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	BOOL LayoutMenusA( struct Menu firstmenu, APTR vi, struct TagItem taglist );		BOOL LayoutMenusA( struct Menu firstmenu, APTR vi, struct TagItem taglist );
	BOOL LayoutMenus( struct Menu *firstmenu, APTR vi, Tag tag1, ... );		BOOL LayoutMenus( struct Menu *firstmenu, APTR vi, Tag tag1, ... );
Line 365:		Line 365:
	For example, a single MenuItem can be created by calling CreateMenus() with a two-entry NewMenu array whose first entry is of type NM_ITEM and whose second is of type NM_END. The menu strip may then be removed and this new item linked to the end of an extensible menu by placing its address in the NextItem field of the last MenuItem in the menu. LayoutMenuItems() can then be used to to recalculate the layout of just the items in the extensible menu and, finally, the menu strip can be reattached to the window.		For example, a single MenuItem can be created by calling CreateMenus() with a two-entry NewMenu array whose first entry is of type NM_ITEM and whose second is of type NM_END. The menu strip may then be removed and this new item linked to the end of an extensible menu by placing its address in the NextItem field of the last MenuItem in the menu. LayoutMenuItems() can then be used to to recalculate the layout of just the items in the extensible menu and, finally, the menu strip can be reattached to the window.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	BOOL LayoutMenuItemsA( struct MenuItem firstitem, APTR vi, struct TagItem taglist );		BOOL LayoutMenuItemsA( struct MenuItem firstitem, APTR vi, struct TagItem taglist );
	BOOL LayoutMenuItems( struct MenuItem *firstitem, APTR vi, Tag tag1, ... );		BOOL LayoutMenuItems( struct MenuItem *firstitem, APTR vi, Tag tag1, ... );
Line 384:		Line 384:
	The FreeMenus() function frees all the memory allocated by the corresponding call to CreateMenus().		The FreeMenus() function frees all the memory allocated by the corresponding call to CreateMenus().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID FreeMenus( struct Menu *menu );		VOID FreeMenus( struct Menu *menu );
	</syntaxhighlight>		</syntaxhighlight>
Line 402:		Line 402:
	If a GadTools-created menu strip is not currently attached to any window, the program may change the text in the menu headers (Menu->MenuName), the command-key equivalents (MenuItem->Command) or the text or imagery of menu items and sub-items, which can be reached as:		If a GadTools-created menu strip is not currently attached to any window, the program may change the text in the menu headers (Menu->MenuName), the command-key equivalents (MenuItem->Command) or the text or imagery of menu items and sub-items, which can be reached as:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	((struct IntuiText *)MenuItem->ItemFill)->IText		((struct IntuiText *)MenuItem->ItemFill)->IText
	</syntaxhighlight>		</syntaxhighlight>
Line 408:		Line 408:
	or		or

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	((struct Image *)MenuItem->ItemFill)		((struct Image *)MenuItem->ItemFill)
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie: /* Restrictions on GadTools Menus */

2015-11-03T23:03:11Z

Restrictions on GadTools Menus

← Older revision		Revision as of 23:03, 3 November 2015
Line 398:		Line 398:
	==== Restrictions on GadTools Menus ====		==== Restrictions on GadTools Menus ====

	GadTools menus are regular Intuition menus. Once the menus have been laid out, the program may do anything with them, including attaching them or removing them from windows, enabling or disabling items, checking or unchecking checkmarked menu items, etc. See the documentation for SetMenuStrip(), ClearMenuStrip(), ResetMenuStrip(), OnMenu() and OffMenu() in [[Intuition_Menus\|Intuition Menus]] ~~chapter~~ for full details.		GadTools menus are regular Intuition menus. Once the menus have been laid out, the program may do anything with them, including attaching them or removing them from windows, enabling or disabling items, checking or unchecking checkmarked menu items, etc. See the documentation for SetMenuStrip(), ClearMenuStrip(), ResetMenuStrip(), OnMenu() and OffMenu() in [[Intuition_Menus\|Intuition Menus]] for full details.

	If a GadTools-created menu strip is not currently attached to any window, the program may change the text in the menu headers (Menu->MenuName), the command-key equivalents (MenuItem->Command) or the text or imagery of menu items and sub-items, which can be reached as:		If a GadTools-created menu strip is not currently attached to any window, the program may change the text in the menu headers (Menu->MenuName), the command-key equivalents (MenuItem->Command) or the text or imagery of menu items and sub-items, which can be reached as:

Steven Solie: /* Introduction */

2013-06-04T21:34:07Z

Introduction

← Older revision		Revision as of 21:34, 4 June 2013
Line 49:		Line 49:

	The NewMenu arrays are designed to be read easily. The elements in the NewMenu array appear in the same order as they will appear on-screen. Unlike the lower-level menu structures described in [[Intuition_Menus\|Intuition Menus]], there is no need to specify sub-menus first, then the menu items with their sub-menus, and finally the menu headers with their menu items. The indentation shown above also helps highlight the relationship between menus, menu items and sub-items.		The NewMenu arrays are designed to be read easily. The elements in the NewMenu array appear in the same order as they will appear on-screen. Unlike the lower-level menu structures described in [[Intuition_Menus\|Intuition Menus]], there is no need to specify sub-menus first, then the menu items with their sub-menus, and finally the menu headers with their menu items. The indentation shown above also helps highlight the relationship between menus, menu items and sub-items.

			=== New Look Menus ===

			GadTools fully supports Intuition's NewLook menus. To make GadTools use the NewLook color scheme for a window's menus, an application needs to do two things. First, it needs to tell Intuition that it wants NewLook menu imagery for the window. It does this when opening the window by passing the {WA_NewLookMenus, TRUE} tag/value pair to OpenWindowTags(). Second, the application needs to remind GadTools that the window uses NewLook imagery for its menus. The application does this by passing the {GTMN_NewLookMenus, TRUE} tag/value pair to LayoutMenus().

	=== The NewMenu Structure ===		=== The NewMenu Structure ===

Steven Solie: /* Layout of the Menus */

2013-06-04T21:28:20Z

Layout of the Menus

← Older revision		Revision as of 21:28, 4 June 2013
Line 341:		Line 341:
	</syntaxhighlight>		</syntaxhighlight>

	Set firstmenu to a pointer to a Menu structure returned by a previous call to CreateMenus(). The vi argument is a a VisualInfo handle obtained from GetVisualInfo(). See the documentation of GadTools gadgets below for more about this call. For the tag arguments, tag1 or taglist, LayoutMenus() recognizes a ~~single~~ ~~tag~~:		Set firstmenu to a pointer to a Menu structure returned by a previous call to CreateMenus(). The vi argument is a a VisualInfo handle obtained from GetVisualInfo(). See the documentation of GadTools gadgets below for more about this call. For the tag arguments, tag1 or taglist, LayoutMenus() recognizes the following tags:

	; GTMN_TextAttr		; GTMN_TextAttr
	: A pointer to an openable font (TextAttr structure) to be used for the menu item and sub-item text. The default is to use the screen's font.		: A pointer to an openable font (TextAttr structure) to be used for the menu item and sub-item text. The default is to use the screen's font.

			; GTMN_NewLookMenus
			: A boolean value indicating whether you want the 3D menu look or not. Defaults to FALSE for compatibility.

	LayoutMenus() fills in all the size, font and position information for the menu strip. LayoutMenus() returns TRUE if successful and FALSE if it fails. The usual reason for failure is that the font supplied cannot be opened.		LayoutMenus() fills in all the size, font and position information for the menu strip. LayoutMenus() returns TRUE if successful and FALSE if it fails. The usual reason for failure is that the font supplied cannot be opened.

Steven Solie at 18:40, 5 April 2013

2013-04-05T18:40:06Z

← Older revision		Revision as of 18:40, 5 April 2013
Line 1:		Line 1:
	{{CodeReview}}
	=== Introduction ===		=== Introduction ===

Steven Solie: /* GadTools Menus Example */

2013-04-05T18:39:44Z

GadTools Menus Example

Show changes

Steven Solie: /* Restrictions on GadTools Menus */

2013-04-05T18:29:38Z

Restrictions on GadTools Menus

← Older revision		Revision as of 18:29, 5 April 2013
Line 401:		Line 401:
	If a GadTools-created menu strip is not currently attached to any window, the program may change the text in the menu headers (Menu->MenuName), the command-key equivalents (MenuItem->Command) or the text or imagery of menu items and sub-items, which can be reached as:		If a GadTools-created menu strip is not currently attached to any window, the program may change the text in the menu headers (Menu->MenuName), the command-key equivalents (MenuItem->Command) or the text or imagery of menu items and sub-items, which can be reached as:

			<syntaxhighlight>
	<pre>
	((struct IntuiText *)MenuItem-~~>~~ItemFill)-~~>~~IText		((struct IntuiText *)MenuItem->ItemFill)->IText
			</syntaxhighlight>
	</pre>

	or		or

			<syntaxhighlight>
	<pre>
	((struct Image *)MenuItem-~~>~~ItemFill)		((struct Image *)MenuItem->ItemFill)
			</syntaxhighlight>
	</pre>

	The application may also link in or unlink menus, menu items or sub-items. However, do not add sub-items to a menu item that was not created with sub-items and do not remove all the sub-items from an item that was created with some.		The application may also link in or unlink menus, menu items or sub-items. However, do not add sub-items to a menu item that was not created with sub-items and do not remove all the sub-items from an item that was created with some.
Line 415:		Line 415:
	Any of these changes may be made, provided the program subsequently calls LayoutMenus() or LayoutMenuItems() as appropriate. Then, reattach the menu strip using SetMenuStrip().		Any of these changes may be made, provided the program subsequently calls LayoutMenus() or LayoutMenuItems() as appropriate. Then, reattach the menu strip using SetMenuStrip().

	Some of these manipulations require walking the menu strip using the usual Intuition-specified linkages. Beginning with the first Menu structure, simply follow its FirstItem pointer to get to the first MenuItem. The MenuItem-~~>~~SubItem pointer will lead to the sub-menus. MenuItems are connected via the MenuItem-~~>~~NextItem field. Successive menus are linked together with the Menu-~~>~~NextMenu pointer. Again, see [[Intuition_Menus\|Intuition Menus]] for details.		Some of these manipulations require walking the menu strip using the usual Intuition-specified linkages. Beginning with the first Menu structure, simply follow its FirstItem pointer to get to the first MenuItem. The MenuItem->SubItem pointer will lead to the sub-menus. MenuItems are connected via the MenuItem->NextItem field. Successive menus are linked together with the Menu->NextMenu pointer. Again, see [[Intuition_Menus\|Intuition Menus]] for details.

	=== Language-Sensitive Menus ===		=== Language-Sensitive Menus ===

Steven Solie: /* Freeing Menus */

2013-04-05T18:28:05Z

Freeing Menus

← Older revision		Revision as of 18:28, 5 April 2013
Line 383:		Line 383:
	The FreeMenus() function frees all the memory allocated by the corresponding call to CreateMenus().		The FreeMenus() function frees all the memory allocated by the corresponding call to CreateMenus().

			<syntaxhighlight>
	<pre>
	VOID FreeMenus( struct Menu *menu );		VOID FreeMenus( struct Menu *menu );
			</syntaxhighlight>
	</pre>

	Its one argument is the Menu or MenuItem pointer that was returned by CreateMenus(). It is safe to call FreeMenus() with a NULL parameter, the function will then return immediately.		Its one argument is the Menu or MenuItem pointer that was returned by CreateMenus(). It is safe to call FreeMenus() with a NULL parameter, the function will then return immediately.

Steven Solie: /* Layout for Individual Menus */

2013-04-05T18:27:45Z

Layout for Individual Menus

← Older revision		Revision as of 18:27, 5 April 2013
Line 364:		Line 364:
	For example, a single MenuItem can be created by calling CreateMenus() with a two-entry NewMenu array whose first entry is of type NM_ITEM and whose second is of type NM_END. The menu strip may then be removed and this new item linked to the end of an extensible menu by placing its address in the NextItem field of the last MenuItem in the menu. LayoutMenuItems() can then be used to to recalculate the layout of just the items in the extensible menu and, finally, the menu strip can be reattached to the window.		For example, a single MenuItem can be created by calling CreateMenus() with a two-entry NewMenu array whose first entry is of type NM_ITEM and whose second is of type NM_END. The menu strip may then be removed and this new item linked to the end of an extensible menu by placing its address in the NextItem field of the last MenuItem in the menu. LayoutMenuItems() can then be used to to recalculate the layout of just the items in the extensible menu and, finally, the menu strip can be reattached to the window.

			<syntaxhighlight>
	<pre>
	BOOL LayoutMenuItemsA( struct MenuItem firstitem, APTR vi, struct TagItem taglist );		BOOL LayoutMenuItemsA( struct MenuItem firstitem, APTR vi, struct TagItem taglist );
	BOOL LayoutMenuItems( struct MenuItem *firstitem, APTR vi, Tag tag1, ... );		BOOL LayoutMenuItems( struct MenuItem *firstitem, APTR vi, Tag tag1, ... );
			</syntaxhighlight>
	</pre>

	Set firstitem to a pointer to the first MenuItem in the linked list of MenuItems that make up the Menu. (See [[Intuition_Menus\|Intuition Menus]] for more about these structures.) Set vi to the address of a VisualInfo handle obtained from GetVisualInfo(). The tag arguments, tag1 or taglist, may be set as follows:		Set firstitem to a pointer to the first MenuItem in the linked list of MenuItems that make up the Menu. (See [[Intuition_Menus\|Intuition Menus]] for more about these structures.) Set vi to the address of a VisualInfo handle obtained from GetVisualInfo(). The tag arguments, tag1 or taglist, may be set as follows:

Steven Solie: /* Layout of the Menus */

2013-04-05T18:27:18Z

Layout of the Menus

← Older revision		Revision as of 18:27, 5 April 2013
Line 342:		Line 342:
	The Menu and MenuItem structures returned by CreateMenus() contain no size or positional information. This information is added in a separate layout step, using LayoutMenus(). As with the other tag-based functions, the program may call either LayoutMenus() or LayoutMenusA().		The Menu and MenuItem structures returned by CreateMenus() contain no size or positional information. This information is added in a separate layout step, using LayoutMenus(). As with the other tag-based functions, the program may call either LayoutMenus() or LayoutMenusA().

			<syntaxhighlight>
	<pre>
	BOOL LayoutMenusA( struct Menu firstmenu, APTR vi, struct TagItem taglist );		BOOL LayoutMenusA( struct Menu firstmenu, APTR vi, struct TagItem taglist );
	BOOL LayoutMenus( struct Menu *firstmenu, APTR vi, Tag tag1, ... );		BOOL LayoutMenus( struct Menu *firstmenu, APTR vi, Tag tag1, ... );
			</syntaxhighlight>
	</pre>

	Set firstmenu to a pointer to a Menu structure returned by a previous call to CreateMenus(). The vi argument is a a VisualInfo handle obtained from GetVisualInfo(). See the documentation of GadTools gadgets below for more about this call. For the tag arguments, tag1 or taglist, LayoutMenus() recognizes a single tag:		Set firstmenu to a pointer to a Menu structure returned by a previous call to CreateMenus(). The vi argument is a a VisualInfo handle obtained from GetVisualInfo(). See the documentation of GadTools gadgets below for more about this call. For the tag arguments, tag1 or taglist, LayoutMenus() recognizes a single tag: