tsc_AppMainMenu
Note: This class supercedes tsc_AppMainWindow
The tsc_AppMainmenu class allows the main menu to be defined for a plugin application, since Trimble Access 2018.00 (SCAPI version 4.00).
tsc_AppMainMenu must be subclassed and, as a minimum, the BuildMenu method implemented.
TODO: Add methods for images on the menu items [See header file for details].
Methods related to the Main Menu
virtual tsc_MainMenu* BuildMenu () = 0;
This method must be overridden with a method to build the main menu for the application. This method will be called by the API at startup, and at any time conditions change which may affect a main menu. Calling the Rebuild method will also result in BuildMenu being called.
BuildMenu must create a new tsc_MainMenu instance, add items and/or submenus to it, and return a pointer to the API. The API takes ownership and uses the menu as the plugin's main menu, until it is rebuilt.
Some main menu items are automatic and cannot be removed or changed. These items are placed at the top and at the bottom of the menu, and the items supplied by the plugin using BuildMenu are always placed between them.
void Rebuild();
If a plugin has made changes which affect the main menu, Rebuild() should be called to get the menu rebuilt.
virtual bool OnMenuItemSelected (x_Code item);
When overridden, this method is called when an item on the menu is clicked. It is not called for separators, submenu items, or items that are disabled.
Override this method only if special handling is required when an item is selected. If OnMenuItemSelected is not overridden then any menu item that is clicked will launch a UiTask for the identifier x-code that was specified for the item. In many cases, this will be sufficient and is the preferred way to do it.
Sometimes special handling is required for an item, or perhaps the entire task can be completed immediately. No UI may be done in the OnMenuItemSelected handler. If UI is necessary then a UiTask must be written.
For trivial tasks where, for instance, just a boolean needs to be set, then writing a UiTask can be skipped, the work being done by the OnMenuItemSelected method.
If the click is handled then return true and no further processing is done by TA. For any click that is not handled, return false to get the default action - which is to launch a previously registered UiTask.
Related classes
Other methods
A variety of other methods are available which relate more to the application than the main menu. They end up here because they've been moved, along with the Main Menu methods, from the old tsc_AppMainWindow.
void AttemptShutdown();
Starts the application shutdown process, which closes the menu. If other unsaved windows are still open, the user gets the opportunity to save their data, and/or close the unsaved windows. The user may also cancel the shutdown. AttemptShutdown will close only the plugin's application; if any other applications (such as General Survey) have been started by the user then one of those will be brought to the front.
virtual void OnAppStarted();
Called when the application becomes active (after dismissing any splashscreen or EULA). The application may be started multiple times if the user chooses to switch into and away from the app using the chooser rather than switching directly between the windows of different apps.
virtual void OnAppFinished();
The plugin application is about to be closed, either because the whole application is shutting down, or the user has chosen a different item in the application chooser. This is just a context switch and nothing is actually shut down in the plugin. The application may be started again later.
An example AppMainMenu class
This simple example shows a main menu with the enabled state of an item able to be controlled from elsewhere in the program. In most cases, controlling the enabled state may be more easily done through the tsc_UiTask classes corresponding to the items in the menu.
class MyMainMenu : public tsc_AppMainMenu
{
bool ableToMeasure = false;
public:
MyMainMenu()
{
// Save address in a global so this instance can be referenced.
// Apart from this, a constructor is not usually required.
MyMainMenuPtr = this;
}
// An example of controlling the main menu from code elsewhere.
void SetAbleToMeasure(bool able)
{
if (able != ableToMeasure)
{
ableToMeasure = able; // Set the new value.
Rebuild (); // Rebuild the menu.
}
}
tsc_MainMenu* BuildMenu()
{
tsc_MainMenu measureSubmenu;
measureSubmenu.AddMenuItem (tsc_MainMenuItem (PX_MeasureCurb));
measureSubmenu.AddMenuItem (tsc_MainMenuItem (PX_MeasureCenterLine));
measureSubmenu.AddMenuItem (
tsc_MainMenuItem (X_MenuContinuousTopo).SetText(tsc_SurveyCore::Translate(PX_MeasurePolyline)));
tsc_MainMenu* top = new tsc_MainMenu;
top->AddMenuItem (tsc_MainMenuItem (PX_Setup));
top->AddMenuItem (tsc_MainMenuItem (PX_InstrumentTest));
top->AddMenuItem (tsc_MainMenuItem (PX_Measure).SetEnabled(ableTomeasure).SetSubMenu(measureSubmenu));
top->AddMenuItem (tsc_MainMenuItem (PX_Stakeout));
top->AddMenuItem (tsc_MainMenuItem (X_Map));
return top;
}
};