To create simple but powerful menu to be used in an applications or game development tools. More...

#include <tb_application_menu.hpp>

Public Member Functions
	ApplicationMenu (const MenuIdentifier &menuIdentifier)

	~ApplicationMenu (void)

const MenuIdentifier &	GetIdentifier (void) const

void	AddMenuItem (const MenuItemIdentifier &itemIdentifier, const tbCore::tbString &displayName, const MenuItemIdentifier &parentIdentifier=kInvalidMenuItemIdentifier, const bool isEnabled=true, const bool isChecked=false, const bool isVisible=true)

const tbCore::tbString &	GetDisplayName (const MenuItemIdentifier &itemIdentifier) const

bool	IsEnabled (const MenuItemIdentifier &itemIdentifier) const

bool	IsChecked (const MenuItemIdentifier &itemIdentifier) const

bool	IsVisible (const MenuItemIdentifier &itemIdentifier) const

void	SetDisplayName (const MenuItemIdentifier &itemIdentifier, const tbCore::tbString &displayName)

void	SetEnabled (const MenuItemIdentifier &itemIdentifier, bool isEnabled)

void	SetChecked (const MenuItemIdentifier &itemIdentifier, bool isChecked)

void	SetVisible (const MenuItemIdentifier &itemIdentifier, bool isVisible)

Static Public Member Functions
static void	SetItemSafeForDuplication (const MenuItemIdentifier &itemIdentifier)

Detailed Description

Creates an application menu that multiple menu items can be added to. Each menu item has a name, and a handful of basic states; enabled, visible, checked, and can hold subitems to create a useful menu system that can be added to an application for Window or Context menus.

Warning: Most classes in the Application area are up for a complete redesign of the public facing interface.

enum ProjectMenuIdentifiers
{
  kMyWindowMenu = 1
};
enum ProjectMenuItems
{
  kMenuFile = 1,
  kMenuFileNew,
  kMenuFileOpen,
  kMenuFileSave,
  kMenuFileExit,
  kMenuEdit,
  kMenuEditUndo,
  kMenuEditRedo,
};
void main(int argumentCount, char* argumentValues[])
{
    TurtleBrains::Application::ApplicationMenu myMenu(kMyWindowMenu);
    myMenu.AddMenuItem(kMenuFile, tb_string("File");
    myMenu.AddMenuItem(kMenuFileNew, tb_string("New"), kMenuFile);
    myMenu.AddMenuItem(kMenuFileOpen, tb_string("Open"), kMenuFile);
    myMenu.AddMenuItem(kMenuFileSave, tb_string("Save"), kMenuFile);
    myMenu.AddMenuItem(kMenuFileExit, tb_string("Exit"), kMenuFile);
    
    myMenu.AddMenuItem(kMenuEdit, tb_string("Edit"));
    myMenu.AddMenuItem(kMenuEditUndo, tb_string("Undo"), kMenuEdit);
    myMenu.AddMenuItem(kMenuEditRedo, tb_string("Redo"), kMenuEdit);
    return 0;
}

Constructor & Destructor Documentation

TurtleBrains::Application::ApplicationMenu::ApplicationMenu ( const MenuIdentifier & menuIdentifier )

explicit

When you create an ApplicationMenu object with a MenuIdentifier, you can later create another ApplicationMenu object with that same MenuIdentifier value and BOTH of those menu objects will refer to and edit the same menu settings.

TurtleBrains::Application::ApplicationMenu::~ApplicationMenu ( void )

This will destruct the ApplicationMenu object, but will not destroy resources or remove the menu settings from memory or the Window or Context areas. Creating another ApplicationMenu object with the same MenuIdentifier value will give access to these settings once again.

Note: this does not cause the menu to be destroyed, or even cause any settings to be removed from memory, as creating another ApplicationMenu object with the same MenuIdentifier will provide access again. To remove the menu from the Window or Context areas you will need to use the primary RealtimeApplication object.

Member Function Documentation

void TurtleBrains::Application::ApplicationMenu::AddMenuItem	(	const MenuItemIdentifier &	itemIdentifier,
		const tbCore::tbString &	displayName,
		const MenuItemIdentifier &	parentIdentifier = `kInvalidMenuItemIdentifier`,
		const bool	isEnabled = `true`,
		const bool	isChecked = `false`,
		const bool	isVisible = `true`
	)

This will add a menu item to the menu, and it is possible to a sub-menu within by supplying a parentIdentifier.

Parameters

itemIdentifier	The identifier that will be used to signal that the item has been clicked/activated. Every menu item must have a unique identifier value, even if the items are in different menu systems.
displayName	The text of the new menu item that will be displayed, empty string represents a seperator.
parentIdentifier	To add a menu item as a subitem of another menu item, the parentIdentifier can can be set to kInvalidMenuItemIdentifier to cause the item to be added directly to the menu instead of as a submenu to another item.
isEnabled	Disabled menu items are grayed out and unselectable, defaults to enabled.
isChecked	When true a checkmark will be placed next to the menu item, defaults to false.
isVisible	If this is false, the menu item will not appear in the menu, defaults to true.

const tbCore::tbString& TurtleBrains::Application::ApplicationMenu::GetDisplayName ( const MenuItemIdentifier & itemIdentifier ) const

Retrieve the current display name setting on the specified menu item. The value returned may not be the value that is actually displayed in the menu if SetWindowMenu() / SetContextMenu() has not been called recently to update the menu with the latest settings.

Parameters

itemIdentifier The identifier of the menu item that should be used when retrieving the name.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

const MenuIdentifier& TurtleBrains::Application::ApplicationMenu::GetIdentifier ( void ) const

Retrieves the MenuIdentifier as specified when the object was created, this identifier cannot change for an ApplicationMenu object.

bool TurtleBrains::Application::ApplicationMenu::IsChecked ( const MenuItemIdentifier & itemIdentifier ) const

Retrieve the current enabled / disabled state of the specified menu item. The state returned may not be the state that is actually displayed in the menu if SetWindowMenu() / SetContextMenu() has not been called recently to update the menu with the latest settings.

Parameters

itemIdentifier The identifier of the menu item that should be used when retrieving the state.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

bool TurtleBrains::Application::ApplicationMenu::IsEnabled ( const MenuItemIdentifier & itemIdentifier ) const

Retrieve the current enabled / disabled state of the specified menu item. The state returned may not be the state that is actually displayed in the menu if SetWindowMenu() / SetContextMenu() has not been called recently to update the menu with the latest settings.

Parameters

itemIdentifier The identifier of the menu item that should be used when retrieving the state.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

bool TurtleBrains::Application::ApplicationMenu::IsVisible ( const MenuItemIdentifier & itemIdentifier ) const

Retrieve the current enabled / disabled state of the specified menu item. The state returned may not be the state that is actually displayed in the menu if SetWindowMenu() / SetContextMenu() has not been called recently to update the menu with the latest settings.

Parameters

itemIdentifier The identifier of the menu item that should be used when retrieving the state.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

void TurtleBrains::Application::ApplicationMenu::SetChecked	(	const MenuItemIdentifier &	itemIdentifier,
		bool	isChecked
	)

Add or remove a checkmark on a menu item which is useful for menu items that have an on/off state that can be toggled when interacted with. To toggle the setting, call SetChecked(id, !IsChecked(id)) where id is the itemIdentifier of the menu item.

Parameters

itemIdentifier	The identifier of the menu item that should have the checkmark added or removed.
isChecked	The new checked/unchecked setting of the menu item, a value of false will remove any checkmark previously added, and a value of true will make the menu item display a checkmark like it is selected or in an active state.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

void TurtleBrains::Application::ApplicationMenu::SetDisplayName	(	const MenuItemIdentifier &	itemIdentifier,
		const tbCore::tbString &	displayName
	)

Change the name setting of the specified menu item. The item's name will not be changed until the next SetWindowMenu() / SetContextMenu call.

Parameters

itemIdentifier	The identifier of the menu item that should have the display name setting changed.
displayName	The new display name setting of the menu item. An empty string will cause the menu item to become a seperator item.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

void TurtleBrains::Application::ApplicationMenu::SetEnabled	(	const MenuItemIdentifier &	itemIdentifier,
		bool	isEnabled
	)

Change the enabled settings for the specified menu item. A disabled menu item is visible, but the menu item cannot be interacted with unless it is enabled. Typically the operating system shows disabled menu items as grayed out. The item will not be changed until the next SetWindowMenu / SetContextMenu call.

Parameters

itemIdentifier	The identifier of the menu item that should become enabled or disabled.
isEnabled	The new enabled/disabled setting of the menu item, a value of false will cause the menu item to remain visible, usually grayed by the operating system, but not allow user interaction.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

static void TurtleBrains::Application::ApplicationMenu::SetItemSafeForDuplication ( const MenuItemIdentifier & itemIdentifier )

static

Sometimes you don't care to modify or retrieve information from a menu item, mainly separators. Since each item must have an identifier value attached to it, this allows you to create an identifier that is safe for duplicating. Once an identifier is made safe for duplication it can not be made unsafe and access to any menu items with the identifier will be lost. Calling accessor / modifier functions like IsEnabled() or SetEnabled() for an identifier safe for duplication will trigger errors.

Parameters

itemIdentifier The identifier value that is safe for duplication, no menu items created with this identifier can be modified or accessed after creation.

Note: Once an identifier is set safe for duplication, that value can not be used to access or modifiy any menu items with that identifier, and the value cannot be later removed from safe for duplication. This effects any menu using an item with the identifier.

void TurtleBrains::Application::ApplicationMenu::SetVisible	(	const MenuItemIdentifier &	itemIdentifier,
		bool	isVisible
	)

Change the visibility settings for the specified menu item. When changing the settings for a a menu item, the menu will not be updated until calling SetWindowMenu / SetContextMenu again.

Parameters

itemIdentifier	The identifier of the menu item that should have the visibility setting changed.
isVisible	The new visibility setting of the menu item, a value of false will cause the menu item, and any possible sub items, to not be added to the system menu during the next update.

Note: an error will be triggered if itemIdentifier is invalid, or the menu does not have an item with the specified identifier.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation