tsc_MainMenuItem

Usage

Use this class to define line items in the application's main menu.  Each tsc_MainMenuItem should be added to a tsc_MainMenu, which can be the top level menu or a submenu.

As soon as a tsc_MainMenuItem has been added to a menu, it may be discarded. Do not add the same tsc_MainMenuItem to multiple menus.

Note that most property methods return a reference to the item object, which allows calls to be chained without creating a specific object, like this:

mymenu.AddMenuItem (tsc_MainMenuItem (X_MenuContinuousTopo).SetText (tsc_SurveyCore::Translate(PX_MeasurePolyline)).SetAutoClickIfSoleItem().SetImage(polyIcon));

or, easier to read:

tsc_MainMenuItem item (tsc_MainMenuItem (X_MenuContinuousTopo)

    .SetText(tsc_SurveyCore::Translate(PX_MeasurePolyline))

    .SetAutoClickIfSoleItem()

    .SetImage(polyIcon));

mymenu.AddMenuItem (item);

See the example in tsc_AppMainMenu for ways to use this class.

Constructor

tsc_MainMenuItem (x_Code identifier);
Constructs a menu line item.  The identifier is used for the translated text of the item, and is also passed to the click event handler on the tsc_AppMainMenu  class, if overridden. The same x_Code may be used more than once in a menu, however there is no way to determine which one was clicked, so it is often better to use different identifying x-codes in these cases.

Methods

tsc_MainMenuItem&   SetIdentifier (x_Code ident);
Changes the identifier associated with this item, used for the x_Code of the UITask to be run and in the click handler. This call does not affect the text of the item.

tsc_MainMenuItem&   SetText (const char* text);
Changes the text for the item. The translation of the identifier given in the constructor is used if the text is never set.

tsc_MainMenuItem&   SetImage (tsc_Image image);

For top-level menu items only, displays this icon to the left of the text. The image will be downsized if necessary.

tsc_MainMenuItem&   SetEnabled (bool enabled);
For non-UiTask items, enables (the default) or disables the item. A disabled item is grayed-out on the menu and clicking the item does nothing.

If a UiTask has been registered for this item's x-code, then the Enabled state is instead controlled by the EnableOnMenu method on the UITask.

tsc_MainMenuItem&   SetChecked (bool checked);
Adds a tick icon to the left of the item 's text if true. By default items are not ticked.

If a UiTask has been registered for this item's x-code, then the Checked state is instead controlled by the TickOnMenu method on the UITask.

tsc_MainMenuItem&   SetAutoClickIfSoleItem (bool autoClick);
When true, automatically clicks this item if it is the only item in a submenu.  In other words, clicking a submenu which contains only one item with AutoClickIfSoleItem set is the same as clicking the item. By default, the single-item submenu is shown.

tsc_MainMenuItem&   SetSubMenu (tsc_MainMenu& subMenu);
When called on any menu item, it changes the item to display the supplied submenu when selected.  It is generally simpler to create the submenu with all its items (and sub-submenus) before adding it to a menu.

tsc_MainMenuItem&   SetSurveySubMenu (tsc_MainMenu& surveyingTasks);
Calling this method on a main menu item changes it to a submenu item containing the supplied tasks.

tsc_MainMenuItem&   SetSurveySubMenu (
tsc_MainMenu& surveyingTasks,
tsc_MainMenu& surveyStartTasks,
tsc_MainMenu& surveyChangeTasks);
When called on a menu item, it changes the item to display the supplied items in a submenu. The submenu is created to allow the user to select a survey style and tasks to start a survey which is appropriate to the items that are included in surveyingTasks. If a survey is already running then all surveyingTasks items that are compatible with the currently running survey are shown in the menu, along with any appropriate surveyChangeTasks (such as switching to an integrated survey or ending the survey).

virtual bool IsMenuItem () const override
Can be used to distinguish this object from a tsc_MainMenu when dealing with the common base class, tsc_MainMenuBase.