tsc_AppMainWindow (deprecated)

This class is no longer in use

This class is a plugin application's main window.  It is only required if the plugin has registered as an application by calling the RegisterApplication method of the tsc_SurveyCore class.  There is an example of usage at the bottom of this page.

Note: The Visual Studio project wizard for SCAPI plugins will generate a basic Main Window automatically; Trimble recommends this path be taken.

To create a main window, tsc_AppMainWindow must be subclassed and initialization and event handlers implemented.

The tsc_AppMainWindow instance that is returned by tsc_Application::MakeMainWindow is retained for the entire life of the loaded plugin, please be aware that during this time the plugin application may be stopped and started multiple times, in this case the OnAppStarted and OnAppFinished events will be called.

Like a tsc_Form, the main window class represents a window with a number of controls on it.  Unlike a form, the main window may only have two control types - tsc_MenuButton and tsc_SoftkeyControl.  Others may be implemented in a future API if a need exists.  Controls on the main window are organised in a grid; the caller specifies the number of equally-sized cells horizontally and vertically and each control is centered in a specified cell.  For further control, four margins may be specified to place the grid in a specific part of the window.

The window size is also controllable - it may fill just the usual "form" area with the status panel and the status and softkey area both visible, or it may be full-width, full-height, or full-screen.

tsc_AppMainWindow public members

tsc_AppMainWindow();

The constructor takes no arguments.  tsc_AppMainWindow should be allocated on the heap and returned in the MakeMainWindow() function of the tsc_Application class.  There is no need to delete the instance; this will occur when the API shuts down.

virtual ~tsc_AppMainWindow();

The destructor may overidden and used to clean up in the usual fashion.

void SetSizing (tsc_WindowSizeMode sizeMode);

tsc_WindowSizeMode GetSizing ();

The size of the window may be specified.  This is best done before the form is created.  The default value if SetSizing is not called is Size_Normal.  If your window sizing obscures the softkey windows then they will not be enabled.

void SetGridDimensions (int columns, int rows);

The number of grid cells can be specified by this method.  The cells are divided equally across the space remaining in the specified window size after margins are subtracted.  A large number of cells may be specified to permit fine placement of controls, or one cell per control if they are to be organised in a simple grid layout.

void SetMarginsPercent (int top, int right, int bottom, int left);

Use this function to set the four margins, which are used to constrain the area available to the grid.  They are specified as percentages of the inside dimension of the window.  (The order of parameters is the same as the order of margins in a CSS statement.)

tsc_FormControlList Controls;

The controls to be displayed on the window are kept in a list which should be populated by the plugin in the OnCreate() callback method.  The list may be modified at other times though this is discouraged - the main window should generally be static and guide the user by enabling and disabling the buttons rather than by adding or removing them.  Use the Add and Remove functions of the tsc_FormControlList class to add and remove controls, and control their enabled/disabled status either with the functions in the tsc_MenuButton class or here on the tsc_AppMainWindow class.  Softkey controls may also be added if the window is not full-height.  These will be displayed as usual in the softkey area.

Note: Buttons which are members of the Controls list when the window is destroyed will be freed from memory; there is no need to delete these controls yourself.

void EnableButton (x_Code button);

void DisableButton (x_Code button);

bool Enabled (x_Code button);

To quickly and easily change or determine the enabled state of a button use these functions.  The buttons are addressed by their x-codes.

Event handlers

virtual void OnCreate ();

When the main window is in the process of creation, this event method is called to allow the window to be configured and controls added to it.  Note that this is equivalent to the OnLoad event of a tsc_Form.

virtual tsc_String OnDrawTitle ();

tsc_String TitleForJobName() const;

The content of the title bar is requested by Survey Core when the bar is redrawn.  This may occur often.  Override OnDrawTitle and return a string to be displayed in the title bar.  The TitleForJobName() method may be called to obtain the standard main window title containing the job name, which may be used as-is or modified.

virtual void OnButtonClick (x_Code button);

When a button is clicked or otherwise selected, the OnButtonClick handler is called.  The typical response to this would be to call tsc_SurveyCore::Launch() for some task to handle the request.  Avoid doing large amounts of processing within the handler itself as this will tend to lock the entire application.  Performing UI (eg, using forms) should likewise be avoided within this function, and placed instead within a UITask which can then be launched.  The x-code of the button is passed into OnButtonClick to identify the button clicked - and with suitable design, the x-code of the button can be the same as a run code for the task to do the processing, so Launch can simply be called with the button x-code as the parameter.  Both softkeys and menu buttons will trigger OnButtonClick.

virtual bool OnEscapeShutdown ();

When the main window is displayed, the Escape button (bottom-left) has a number of uses.  If the main window is covering some UITask then "Esc" is displayed and pressing the button (or the Esc key) will bring the task underneath to the front.  When there is no task underneath, it either does nothing or it exits the application - depending on the OnEscapeShutdown function.  Returning true means the application will shut, false means the key is ignored.  This same function is used to determine what to display on the button - either "Exit" or nothing.

void AttemptShutdown();

Starts the application shutdown process, which closes the main window.  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. If the plugin is the only running Survey Core application, then Survey Core may not terminate but instead hide itself and go into a "hibernation" mode.  From this mode it may be shut down by the O/S or the user, or awakened to display the main window of some application. 

virtual void OnAppStarted();

Called when your application becomes active (including any splashscreens or EULA).  You may be started several times if the user chooses to close and open your app rather than switch to and from it.

virtual void OnAppFinished();

Your application is about to be closed.  You may be started again later.

Example use of tsc_AppMainWindow

static const char* myName   = "Example"; static const char* APP_GUID = "6f5a7707-5e45-4294-871e-2310649cb8d5"; static x_Code  x_Example;  class MyMainWindow : public tsc_AppMainWindow {     virtual void OnCreate ()     {         this->SetSizing (Size_Wide);         this->SetGridDimensions (3, 1);         this->SetMarginsPercent (20, 20, 10, 20);          this->Controls.Add (new tsc_MenuButton (PX_Open, IDB_OpenNorm));         this->Controls.Add (new tsc_MenuButton (PX_Measure, IDB_MeasNorm));         this->Controls.Add (new tsc_MenuButton (PX_Close, IDB_CloseNorm));          this->Controls.Add (new tsc_SoftkeyControl(X_Map));     }      virtual tsc_String OnDrawTitle ()     {         tsc_String title = tsc_String::Format("%s: %s", myName, TitleForJobName());         return title;     }      virtual void OnButtonClick (x_Code button)     {         tsc_SurveyCore::Launch (button);         this->DisableButton (button);  // Allow each button to be pressed only once.  Tough!     }      virtual bool OnEscapeShutdown ()     {         return true;      } };  class MyApplication : public tsc_Application {     virtual tsc_String  GetProductGuid           () const { return APP_GUID; };     virtual tsc_String  GetProductName           () const { return myName; }     virtual tsc_String  GetProductDescription    () const { return "Usage example application."; }     virtual tsc_String  GetProductSupportString  () const { return "www.trimble.com"; }     virtual tsc_String  GetProductEula           () const { return ""; }     virtual bool        ShowSplashScreen         () const { return true; }     virtual tsc_String  GetHelpIndexName         () const { return ""; }     virtual bool        OnCloseConfirm           () const { return false; }     virtual bool        IsAutoConnectRequired    () const { return true; }     virtual bool        IsOpenJobRequired        () const { return true; }     virtual bool        HasInstrumentInteraction () const { return true; }       virtual tsc_AppMainWindow* MakeMainWindow () const     {         return new MyMainWindow();     } };  extern void tsc_RegisterPlugin (const char*& name,                                  const char*& optionalTdbRelativePath) {     name = myName; }  extern void tsc_InitializePlugin () {     x_Example = tsc_SurveyCore::AddXCode (myName);     tsc_SurveyCore::RegisterApplication (new MyApplication); }  extern void tsc_FinalizePlugin () { }