tsc_CurrentJob

This static class is used to control the Current Job.  There can be only one current job at a time, and it is accessed by default for most General Survey user tasks, along with any plugin applications that the user may be running. For this reason it is necessary to be careful about closing the current job.

In addition to survey data, the current job holds much of the current configuration, such as the current coordinate system, units of measurement, instrument setup, site calibration, atmospheric conditions, target and antenna heights, and so forth.  Very little can be achieved in General Survey without a current job.  

On the other hand, a plugin is able to interact somewhat with jobs that are not the current one although functionality is limited.

tsc_CurrentJob has only static methods, since there can be only one current job.  These methods all deal with opening, closing, and querying the current job.  When the current job is closed, it is closed for all applications.  When a current job is opened, the file is loaded and the database and configuration within the job become the database and configuration for all applications.

For methods dealing with the job itself, please see tsc_Job.

Public static methods

static tsc_Job Get ();
Returns the currently open job.  If there is no current job then a closed job is returned (its IsOpen method will return false).

static bool IsOpen ();
Returns true if there is a currently open job.

static bool ShowOpenDialog ();
Displays the job open dialog and allows the user to choose a job to be opened as the current job.  The open dialog also allows the user to create a new job and/or a new folder, or to cancel out.  There is no control over what the user chooses to do.  The return value is true if a job is open at the end of the process regardless of how that occurred.

static bool Enforce ();
Shows the standard job open dialog if there isn't a job open already. If a job is already open, Enforce does nothing and returns true. If no job is open then the user is presented with the standard open dialog, in which they may open a job, create a new job (and open it), or cancel out.

static void EnforceErrorMessage (x_Code message);
Any UiTask that requires an open job will automatically display the standard Job Open dialog if no job is open when the task is started. If this automatic behaviour is undesirable, use this function to prevent the automatic Job Open dialog from displaying.  After EnforceErrorMessage has been called, launching any UI Task that requires a job (and no job is open) generates a message dialog displaying the supplied error message.  The UI task is prevented from running. To revert to the normal behaviour, call EnforceErrorMessage with a message of X_NULL.

The message should explain why the task is not being run; the name of the task is displayed in the message's title.

static bool ShowNewJobDialog ();
Shows the dialog for creating a new job in the default project directory.  If this was successful the return value is true.  If the user cancels or some other error occurs (unlikely) then the return value is false.

static bool ShowNewJobDialog (const char* project);
Shows the dialog for creating a new job in the given project directory.  If this was successful the return value is true.  If the user cancels or some other error occurs (unlikely) then the return value is false.  The project directory must already exist.

static x_Code Open (const char* project, const char* jobName);
Opens an existing job file as the current job. This function will fail immediately if there is already a current job; the plugin should always call Close() before attempting to open another file. Returns X_NULL on success, otherwise an error code.  See the table of possible errors at the bottom of this page.

static x_Code Close ();

static x_Code Close (x_Code message);

static x_Code Close (const char* message);

These three  methods all close the current job, provided there are no dependencies on it, or there are dependencies and the user agrees to close it anyway. A dependency is any window or other system that requires the job to be open in order to continue to function.  These can be further divided into those that have unsaved data (like an unsaved form or an uncompleted station setup) and those that can be closed with no data loss (such as the map).  Any running window or system that does not belong solely to the calling application will trigger display of the dialog, stating that this application has requested the job be closed and gives the user the option of continuing with the close, or cancelling it.  Unsaved data items will be listed in a separate window which allows the user to save or discard each item.

The return value is X_NULL if the close was successful, or an error code otherwise.  See the table at the bottom of this page for details of errors.

Important: Avoid calling Close other than as a result of user interaction.  For instance, the plugin may automatically open a job when the user moves to a new work site, in which case the plugin could close the current job and open a new one when the user chooses something like "Start new site".

Important: The user may cancel the close, in which case the original job remains open. Always check the return value.