ExecutableShell Class Reference
[Plug-In Shells]

A base class for plug-in shells or plug-in instances. More...

#include <ExecutableShell.h>

Inheritance diagram for ExecutableShell:

Inheritance graph

List of all members.

Public Member Functions

 ExecutableShell ()
virtual ~ExecutableShell ()
bool isExecutedOnStartup () const
bool isDestroyedAfterExecute () const
const std::vector< std::string > & getMenuLocations () const
bool setBatch ()
bool setInteractive ()
bool initialize ()
bool abort ()
bool hasAbort ()
bool isBackground () const
bool isBatch () const
bool isAborted () const
bool hasWizardSupport () const

Protected Member Functions

void executeOnStartup (bool bExecute)
void destroyAfterExecute (bool bDestroy)
void setMenuLocation (const std::string &menuLocation)
void addMenuLocation (const std::string &menuLocation)
void setAbortSupported (bool bSupported)
void setBackground (bool bBackground)
void setWizardSupported (bool bSupported)

Protected Attributes

bool mAborted

Detailed Description

A base class for plug-in shells or plug-in instances.

This class provides a default implementation of the Executable plug-in interfaces and serves as an optional base class for specialized plug-in shell classes and/or custom plug-ins.

See also:
PlugIn, Executable
Examples:

Tutorial/Tutorial1.h, Tutorial/Tutorial2.h, Tutorial/Tutorial3.h, Tutorial/Tutorial4.h, and Tutorial/Tutorial5.h.

Definition at line 32 of file ExecutableShell.h.

Constructor & Destructor Documentation

ExecutableShell::ExecutableShell (  ) 

Creates the plug-in.

The constructor initializes the plug-in as follows:

See also:
ConfigurationSettings::getVersion()

virtual ExecutableShell::~ExecutableShell (  )  [virtual]

Destroys the plug-in.

Member Function Documentation

bool ExecutableShell::isExecutedOnStartup (  )  const [virtual]

Queries whether the plug-in is automatically executed when the application starts.

Returns:
Returns true if the plug-in is automatically executed when the application is created; otherwise returns false.

Implements Executable.

bool ExecutableShell::isDestroyedAfterExecute (  )  const [virtual]

Queries whether the plug-in is automatically destroyed after it is successfully executed.

Plug-ins which are not successfully executed are automatically destroyed by the application.

After a plug-in is successfully executed, it can be destroyed by the application or stay resident in memory. A plug-in may need to exist after execution, such as those containing modeless GUI components that require user interaction or continually display data.

Returns:
Returns true if the plug-in is automatically destroyed after it is successfully executed; otherwise returns false.
See also:
execute()

Implements Executable.

const std::vector<std::string>& ExecutableShell::getMenuLocations (  )  const [virtual]

Returns the menu locations and names of the commands from which the plug-in is executed.

Returns:
A vector of strings representing the menu locations and names of the commands that are used to execute the plug-in.

Each string is formatted with brackets ([,]) to specify a toolbar and a slash (/) to indicate submenus. The toolbar name appears first in the string, followed by an optional slash, and then the menus, submenus and command name separated by slashes. If the optional slash appears following the toolbar name, this indicates that the submenus and command should be added to the default toolbar menu, which has the same name as the toolbar. If a slash does not follow the toolbar name, the menus and command are added directly to the toolbar. If the string does not include a toolbar name, the menus and command are added to the main menu bar. The string cannot end with a slash, and the name after the last slash indicates the command name.

Examples of the menu string include the following:
  • [Geo]/Georeference
  • &Tools/Flicker Window

An empty vector is returned if the plug-in should not be executed from the menus.

Implements Executable.

bool ExecutableShell::setBatch (  )  [virtual]

Sets the plug-in to execute in batch mode.

This method is used to set the plug-in to execute in a non-GUI mode.

Returns:
Returns true if batch mode is supported and the plug-in was successfully set to execute in a non-GUI mode. Returns false if the plug-in does not support batch mode, or if batch mode cannot currently be set on the plug-in.
See also:
setInteractive()

Default Implementation:
The default implementation sets an internal flag that can be queried with isBatch() and returns true.

Implements Executable.

Reimplemented in DockWindowShell, and AlgorithmPlugIn.

bool ExecutableShell::setInteractive (  )  [virtual]

Sets the plug-in to execute in interactive mode.

This method is used to set the plug-in to execute in a GUI mode.

Returns:
Returns true if interactive mode is supported and the plug-in was successfully set to execute in a GUI mode. Returns false if the plug-in does not support interactive mode, or if interactive mode cannot currently be set on the plug-in.
See also:
setBatch()

Default Implementation:
The default implementation sets an internal flag that can be queried with isBatch() and returns true.

Implements Executable.

Reimplemented in AlgorithmPlugIn.

bool ExecutableShell::initialize (  )  [virtual]

Initializes the plug-in before execution.

This method is used by the plug-in manager to initialize the plug-in before it is executed.

Returns:
Returns true if the plug-in initialization was sucessful; otherwise returns false.

Default Implementation:
The default implementation does nothing and returns true.

Implements Executable.

bool ExecutableShell::abort (  )  [virtual]

Aborts the plug-in during execution.

This method may be called by the application to attempt to gracefully abort a plug-in. Depending on the specific plug-in implementation of this method, it may simply initiate the abort process and return or it may attempt to complete the abort process before returning.

Returns:
Returns true if the plug-in was successfully aborted or transformed to an aborted state, which does not necessarily mean that the plug-in has completed aborting. Returns false if the plug-in could not abort successfully or if the plug-in does not support aborting.
See also:
hasAbort()

Default Implementation:
If hasAbort() returns true, the default implementation sets an internal flag that can be queried with isAborted() and returns true. If hasAbort() returns false, the default implementation returns false.

Implements Executable.

Reimplemented in ViewerShell, and AlgorithmPlugIn.

bool ExecutableShell::hasAbort (  )  [virtual]

Queries whether the plug-in can be aborted.

This method may be called to determine if the plug-in can be aborted. This can be useful in GUI applications where the user may not be given the chance to cancel.

Returns:
Returns true if the plug-in supports the ability to abort, otherwise returns false. Plug-ins that do not have significant processing or loops can also return false.

Default Implementation:
The default implementation returns the value that was passed into setAbortSupported(). If setAbortSupported() has not yet been called, false is returned.

Implements Executable.

bool ExecutableShell::isBackground (  )  const [virtual]

Queries whether the plug-in performs background processing.

This method is called by the application after executing the plug-in to determine if the plug-in should be unloaded or should wait until processing is finished. This method is called before isDestroyedAfterExecute() is called, so a return value of false does not necessarily mean that the plug-in will be destroyed.

Returns:
Returns true if the plug-in performs background processing. Destruction and possible unloading of the plug-in will be delayed until the plug-in indicates that background processing has ended. Returns false if the plug-in does not support background processing or is not performing background processing during this instance.
See also:
DesktopServices::registerCallback()

Default Implementation:
The default implementation returns the value that was passed into setBackground(). If setBackground() has not yet been called, false is returned.

Implements Executable.

bool ExecutableShell::isBatch (  )  const

Queries whether the plug-in is set to execute in batch mode.

Returns:
Returns true if the plug-in is set to execute in batch mode or false if the plug-in is set to execute in interactive mode.
See also:
setBatch(), setInteractive()

bool ExecutableShell::isAborted (  )  const

Queries whether the plug-in is in an aborting state.

Returns:
Returns true if the plug-in is currently aborting, otherwise returns false. Also returns false if aborting is not supported.
See also:
hasAbort(), abort()

bool ExecutableShell::hasWizardSupport (  )  const [virtual]

Queries whether the plug-in supports being added as a wizard item.

Returns:
Returns true if the user should be able to add this plug-in to the wizard builder. Returns false if the user should NOT be able to add this plug-in to the wizard builder.
See also:
setWizardSupported

Implements Executable.

void ExecutableShell::executeOnStartup ( bool  bExecute  )  [protected]

Sets whether the plug-in is automatically executed when the application starts.

Parameters:
bExecute Set this value to true if the plug-in should be automatically executed, otherwise false.

void ExecutableShell::destroyAfterExecute ( bool  bDestroy  )  [protected]

Sets whether the plug-in is automatically destroyed after it is successfully executed.

Plug-ins which are not successfully executed are automatically destroyed by the application.

After a plug-in is successfully executed, it can be destroyed by the application or stay resident in memory. A plug-in may need to exist after execution, such as those containing modeless GUI components that require user interaction or continually display data.

Parameters:
bDestroy Set this value to true if the plug-in should be automatically destroyed after it is successfully executed, otherwise false.
See also:
execute()

void ExecutableShell::setMenuLocation ( const std::string &  menuLocation  )  [protected]

Sets a single menu location and command name from which the plug-in is executed.

This method sets the location and name of a single menu command that is used to execute the plug-in. Any existing menu command locations are removed to set the given location. Additional menu commands can be specified to execute this plug-in by calling the addMenuLocation() method instead.

Parameters:
menuLocation The menu location and name of the menu commmand used to execute the plug-in.

The string should be formatted with brackets ([,]) to specify a toolbar and a slash (/) to indicate submenus. The toolbar name appears first in the string, followed by an optional slash, and then the menus, submenus and command name separated by slashes. If the optional slash appears following the toolbar name, this indicates that the submenus and command should be added to the default toolbar menu, which has the same name as the toolbar. If a slash does not follow the toolbar name, the menus and command are added directly to the toolbar. If the string does not include a toolbar name, the menus and command are added to the main menu bar. The string cannot end with a slash, and the name after the last slash indicates the command name. An empty string indicates that the plug-in does not have a menu location, and that it should not be executed from the menus.

Examples of the menu string include the following:
  • [Geo]/Georeference
  • &Tools/Flicker Window
See also:
addMenuLocation()

void ExecutableShell::addMenuLocation ( const std::string &  menuLocation  )  [protected]

Adds a menu location and command name from which the plug-in is executed.

This method adds an additional menu command that is used to execute the plug-in. Derived plug-ins that call this method should specify the following input arg in getInputSpecification():

  • Name: "Menu Command"
  • Type: "string"

When the execute() method is called, this plug-in arg in the input arg list should be populated with the command name that was used to execute the plug-in.

Parameters:
menuLocation The menu location and name of the menu commmand used to execute the plug-in.

The string should be formatted with brackets ([,]) to specify a toolbar and a slash (/) to indicate submenus. The toolbar name appears first in the string, followed by an optional slash, and then the menus, submenus and command name separated by slashes. If the optional slash appears following the toolbar name, this indicates that the submenus and command should be added to the default toolbar menu, which has the same name as the toolbar. If a slash does not follow the toolbar name, the menus and command are added directly to the toolbar. If the string does not include a toolbar name, the menus and command are added to the main menu bar. The string cannot end with a slash, and the name after the last slash indicates the command name. An empty string indicates that the plug-in does not have a menu location, and that it should not be executed from the menus.

Examples of the menu string include the following:
  • [Geo]/Georeference
  • &Tools/Flicker Window
See also:
setMenuLocation()

void ExecutableShell::setAbortSupported ( bool  bSupported  )  [protected]

Sets whether the plug-in supports aborting.

Parameters:
bSupported If this value is true, aborting is enabled and the default implementation of hasAbort() will return true. If this value is false, aborting is disabled and the default implementation of hasAbort() will return false.

void ExecutableShell::setBackground ( bool  bBackground  )  [protected]

Sets whether the plug-in performs background processing.

Parameters:
bBackground If this value is true, the plug-in is set to perform background processing. Destruction and possible unloading of the plug-in will be delayed until the plug-in indicates that background processing has ended.
See also:
isBackground(), DesktopServices::registerCallback()

void ExecutableShell::setWizardSupported ( bool  bSupported  )  [protected]

Sets whether the plug-in supports being added to a wizard.

Parameters:
bSupported If this value is true, then a user will be able to add this plug-in to a wizard in the wizard builder. If this value is false, then a user will not be able to add this plug-in to a wizard in the wizard builder.
See also:
hasWizardSupport()

Member Data Documentation

bool ExecutableShell::mAborted [mutable, protected]

Set to true if the plug-in has been aborted.

Subclasses should typically use isAborted(). This is only made available for the case where a pointer or reference to an abort flag is passed into other code.

Definition at line 294 of file ExecutableShell.h.

Software Development Kit - Opticks 4.9.0 Build 16218