Intuition Menu Class - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:36:51Z

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

Show changes

Steven Solie at 18:26, 9 July 2015

2015-07-09T18:26:15Z

Show changes

Steven Solie at 04:38, 9 July 2015

2015-07-09T04:38:14Z

← Older revision		Revision as of 04:38, 9 July 2015
Line 1:		Line 1:
	THE NEW BOOPSI MENU CLASS

	= An overview =		= An overview =

Steven Solie: /* Generating a whole menu (sub-)tree from a single tag list */

2015-07-09T04:37:21Z

Generating a whole menu (sub-)tree from a single tag list

← Older revision		Revision as of 04:37, 9 July 2015
Line 735:		Line 735:
	MM_NEWMENU understands three directives: NM_Menu / NM_Item, indicating to add a new menu or item object at the current level (the tag data is the object's text label), and NM_SubItems, indicating to move down or up by one level before the next item object is added. If the tag data of NM_SubItems is SI_BEGIN, the next item will become a child of the most recent one added (i.e. we move down by one level); if it is SI_END, the next item will become a sibling of the most recent one's parent (i.e. we move up by one level).		MM_NEWMENU understands three directives: NM_Menu / NM_Item, indicating to add a new menu or item object at the current level (the tag data is the object's text label), and NM_SubItems, indicating to move down or up by one level before the next item object is added. If the tag data of NM_SubItems is SI_BEGIN, the next item will become a child of the most recent one added (i.e. we move down by one level); if it is SI_END, the next item will become a sibling of the most recent one's parent (i.e. we move up by one level).

	Note ~~that~~ NM_SubItems is not needed to add menus to a menu strip object, nor to add items to a menu object -- its only purpose is to act as a "delimiter" for a list of sub-items of an item object.		{{Note\|text=NM_SubItems is not needed to add menus to a menu strip object, nor to add items to a menu object -- its only purpose is to act as a "delimiter" for a list of sub-items of an item object.}}

	Any menuclass tag that is encountered in the tag list is passed as an attribute to the most recently added object.		Any menuclass tag that is encountered in the tag list is passed as an attribute to the most recently added object.
Line 825:		Line 825:
	</syntaxhighlight>		</syntaxhighlight>

	Note ~~that this~~ call only disposes of all of the object's children, not of the root object itself. This way you can reuse the object in case you need to build another menu tree with MM_NEWMENU. To free the root object (and its children if you didn't already do that), simply use DisposeObject().		{{Note\|text=This call only disposes of all of the object's children, not of the root object itself. This way you can reuse the object in case you need to build another menu tree with MM_NEWMENU. To free the root object (and its children if you didn't already do that), simply use DisposeObject().}}

Steven Solie: /* Adding and removing menus and menu items */

2015-07-09T04:36:16Z

Adding and removing menus and menu items

← Older revision		Revision as of 04:36, 9 July 2015
Line 565:		Line 565:
	A NULL pointer can safely be passed with MA_AddChild, and is simply ignored.		A NULL pointer can safely be passed with MA_AddChild, and is simply ignored.

	Note ~~that in~~ this example we're using a simple counter variable to generate an unique ID for each new sub-item -- we don't care about the ID value itself, we simply want to take notice if the item gets selected, and be able to retrieve its address with MM_FINDID whenever needed. This requires the new item to have a valid and unique ID number.		{{Note\|text=In this example we're using a simple counter variable to generate an unique ID for each new sub-item -- we don't care about the ID value itself, we simply want to take notice if the item gets selected, and be able to retrieve its address with MM_FINDID whenever needed. This requires the new item to have a valid and unique ID number.}}

	Just like they can be added, menus and menu items can also be removed from the menu tree as needed. This is achieved by passing the MA_RemoveChild tag to the parent menu object via SetAttrs(), with the address of the child as data.		Just like they can be added, menus and menu items can also be removed from the menu tree as needed. This is achieved by passing the MA_RemoveChild tag to the parent menu object via SetAttrs(), with the address of the child as data.

Steven Solie: /* Dynamic menu localization */

2015-07-09T04:34:50Z

Dynamic menu localization

← Older revision		Revision as of 04:34, 9 July 2015
Line 543:		Line 543:
	Your string hook should return the correct catalog string for the passed string ID, or a default string if no catalog is available.		Your string hook should return the correct catalog string for the passed string ID, or a default string if no catalog is available.

	Note~~: all~~ of the above is equally valid for the MA_Key attribute, which can be a string ID instead of an actual string just like MA_Label. Its string ID range is the same one of MA_Label (as defined by MA_MinStringID and MA_MaxStringID).		{{Note\|text=All of the above is equally valid for the MA_Key attribute, which can be a string ID instead of an actual string just like MA_Label. Its string ID range is the same one of MA_Label (as defined by MA_MinStringID and MA_MaxStringID).}}

	Also ~~note: if~~ you don't use a string hook, MA_Label and MA_Key should always be real strings and not numeric IDs, otherwise they'll get converted by menuclass to "????", which isn't very meaningful. The same will happen if the string hook returns a NULL string pointer.		{{Note\|title=Also Note\|text=If you don't use a string hook, MA_Label and MA_Key should always be real strings and not numeric IDs, otherwise they'll get converted by menuclass to "????", which isn't very meaningful. The same will happen if the string hook returns a NULL string pointer.}}

	== Adding and removing menus and menu items ==		== Adding and removing menus and menu items ==

Steven Solie: /* Handling menu help requests by the user */

2015-07-09T04:33:50Z

Handling menu help requests by the user

← Older revision		Revision as of 04:33, 9 July 2015
Line 294:		Line 294:
	</syntaxhighlight>		</syntaxhighlight>

	Note ~~that the~~ menu help ID value may be NO_MENU_ID, which means the [Help] key was pressed by the user while no menu item or title was highlighted.		{{Note\|text=The menu help ID value may be NO_MENU_ID, which means the [Help] key was pressed by the user while no menu item or title was highlighted.}}

	Menu help doesn't support multiple selection, so you have to deal with just one ID per event. As with menu pick, you can also retrieve the ID value by reading the ExtIntuiMessage.eim_LongCode field.		Menu help doesn't support multiple selection, so you have to deal with just one ID per event. As with menu pick, you can also retrieve the ID value by reading the ExtIntuiMessage.eim_LongCode field.

Steven Solie: /* Handling menu item selections by the user */

2015-07-09T04:33:04Z

Handling menu item selections by the user

← Older revision		Revision as of 04:33, 9 July 2015
Line 227:		Line 227:
	Once all IDs have been retrieved, MM_NEXTSELECT will return NO_MENU_ID which means there are no more selections in the list.		Once all IDs have been retrieved, MM_NEXTSELECT will return NO_MENU_ID which means there are no more selections in the list.

	Note ~~that~~ MM_NEXTSELECT might even return NO_MENU_ID immediately on the first invocation; this would mean the user initiated and terminated a menu session without picking any item. Be prepared to handle this case.		{{Note\|text=MM_NEXTSELECT might even return NO_MENU_ID immediately on the first invocation; this would mean the user initiated and terminated a menu session without picking any item. Be prepared to handle this case.}}

	The MM_NEXTSELECT method uses the following mpNextSelect message structure:		The MM_NEXTSELECT method uses the following mpNextSelect message structure:

Steven Solie: /* Detaching the menu tree from a window */

2015-07-09T04:32:22Z

Detaching the menu tree from a window

← Older revision		Revision as of 04:32, 9 July 2015
Line 219:		Line 219:
	Additionally, as of Intuition V54 it is no longer mandatory to remove the menus with ClearMenuStrip() before closing the window. CloseWindow() itself will take care of clearing the menus if needed (no matter if BOOPSI or old-style).		Additionally, as of Intuition V54 it is no longer mandatory to remove the menus with ClearMenuStrip() before closing the window. CloseWindow() itself will take care of clearing the menus if needed (no matter if BOOPSI or old-style).

	Note~~: it~~ is still required, however, to use ClearMenuStrip() to remove the menu strip of a window before setting a different one with SetMenuStrip().		{{Note\|text=It is still required, however, to use ClearMenuStrip() to remove the menu strip of a window before setting a different one with SetMenuStrip().}}

	== Handling menu item selections by the user ==		== Handling menu item selections by the user ==

Steven Solie: /* Menu item keyboard shortcuts */

2015-07-09T04:31:45Z

Menu item keyboard shortcuts

← Older revision		Revision as of 04:31, 9 July 2015
Line 184:		Line 184:
	If you opt for the latter approach, you may also use a NUL ('\0') character in place of the '\|'. This can prove useful when converting to BOOPSI menu usage an existing application employing such a method to embed shortcuts in its catalog strings.		If you opt for the latter approach, you may also use a NUL ('\0') character in place of the '\|'. This can prove useful when converting to BOOPSI menu usage an existing application employing such a method to embed shortcuts in its catalog strings.

	~~However, note that the~~ NUL byte solution only works for single-letter shortcuts and requires that no item in the menu tree has a label of just one letter, as any such label would be mistaken for a shortcut followed by random bytes. When you have single-letter labels, therefore, you cannot use this feature and must disable it for the whole tree. That's done by passing { MA_EmbeddedKey, FALSE } to the menu root object; this attribute will be inherited by all objects.		{{Note\|text=The NUL byte solution only works for single-letter shortcuts and requires that no item in the menu tree has a label of just one letter, as any such label would be mistaken for a shortcut followed by random bytes. When you have single-letter labels, therefore, you cannot use this feature and must disable it for the whole tree. That's done by passing { MA_EmbeddedKey, FALSE } to the menu root object; this attribute will be inherited by all objects.}}

	== Inheritance of menu attributes ==		== Inheritance of menu attributes ==