DockWindowShell Class Reference

A plug-in shell class for creating dock windows. More...

#include <DockWindowShell.h>

Inheritance diagram for DockWindowShell:

List of all members.

Public Member Functions

DockWindowShell ()

virtual ~DockWindowShell ()

virtual bool setBatch ()

virtual bool getInputSpecification (PlugInArgList *&pArgList)

virtual bool getOutputSpecification (PlugInArgList *&pArgList)

virtual bool execute (PlugInArgList *pInArgList, PlugInArgList *pOutArgList)

virtual bool serialize (SessionItemSerializer &serializer) const

virtual bool deserialize (SessionItemDeserializer &deserializer)

Protected Slots

void displayDockWindow (bool bDisplay)

Protected Member Functions

virtual QAction * createAction ()=0

QAction * getAction ()

const QAction * getAction () const

virtual QWidget * createWidget ()=0

QWidget * getWidget () const

DockWindow * getDockWindow ()

const DockWindow * getDockWindow () const

Detailed Description

A plug-in shell class for creating dock windows.

This class provides capabilities to create a dock window in the main application window. A dock window plug-in is executed on application startup and when a new session is created. The execute() method creates the dock window with the same name as the plug-in and hides it by default.

Subclasses are only responsible for implementing the following items:

Creating the action that toggles the display of the dock window and adding it to a menu and/or toolbar in an override of the createAction() method.
Creating the widget that is used as the dock window contents in an override of the createWidget() method.
Removing the action from a menu and/or toolbar and deleting it in the subclass destructor.

Subclasses do not need to destroy the contents widget since it is automatically destroyed when the dock window is destroyed.

See also:: ExecutableShell

Definition at line 44 of file DockWindowShell.h.

Constructor & Destructor Documentation

DockWindowShell::DockWindowShell ( )

Creates a dock window plug-in.

The constructor sets the following values on the plug-in:

The type is set to PlugInManagerServices::DockWindowType().
Multiple instances are not allowed.
The plug-in is executed on startup.
The plug-in is not destroyed after executing.
Wizard support is disabled.
The plug-in defaults to execute in interactive mode.

See also:: getType()

virtual DockWindowShell::~DockWindowShell ( ) [virtual]

Destroys the dock window plug-in.

The destructor destroys the dock window. Subclasses should remove the action created in createAction() from the menu and/or toolbar to which it was added and then delete the action. Subclasses do not need to destroy the contents widget created in createWidget() since it is destroyed when the dock window is destroyed.

Member Function Documentation

virtual bool DockWindowShell::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 calls the base class to set the internal flag and returns false indicating that batch mode operation is not supported.

Reimplemented from ExecutableShell.

virtual bool DockWindowShell::getInputSpecification ( PlugInArgList *& pArgList ) [virtual]

Retrieves the plug-in input parameters.

This method queries the plug-in for its input parameters that are needed to execute properly. The input arguments may be different in interactive mode and batch mode.

Parameters:

pArgList

A plug-in arg list pointer that is set to a created input argument list specifying the plug-in input parameters. NULL is a valid pointer value if the plug-in does not require any input arguments.

Returns:: Returns true if the input parameter argument list was successfully created. If the plug-in does not require input arguments, true is returned, but the given plug-in arg list pointer may be NULL.

See also:: PlugInArgList

Default Implementation:: The default implementation sets pArgList to NULL and returns true.

Implements Executable.

virtual bool DockWindowShell::getOutputSpecification ( PlugInArgList *& pArgList ) [virtual]

Retrieves the plug-in output parameters.

This method queries the plug-in for its output parameters that are created during execution. The output arguments may be different in interactive mode and batch mode.

Parameters:

pArgList

A plug-in arg list pointer that is set to a created output argument list specifying the plug-in output parameters. NULL is a valid pointer value if the plug-in does not provide any output arguments.

Returns:: Returns true if the output parameter argument list was successfully created. If the plug-in does not provide output arguments, true is returned, but the given plug-in arg list pointer may be NULL.

See also:: PlugInArgList

Default Implementation:: The default implementation sets pArgList to NULL and returns true.

Implements Executable.

virtual bool DockWindowShell::execute	(	PlugInArgList *	pInArgList,
		PlugInArgList *	pOutArgList
	)			`[virtual]`

Creates the dock window.

This method is called on application startup and when a new session is created. The createAction() method is called for subclasses to create an action and add it to a menu and/or toolbar. If a valid non-NULL action is returned, this method sets the action to be a checkable action, sets the action to not auto-repeat, and connects its triggered() signal to the displayDockWindow() slot.

After initializing the action, the dock window is created by calling DesktopServices::createWindow() with the window name set to the same name as the plug-in. If the dock window already exists, the existing window is used instead of creating a new window. If a new window is created, it is hidden by default.

After the dock window is created or the existing dock window is obtained, the icon which appears in the session explorer is set to the created action's icon, and the createWidget() method is called to create the widget that should be used as the dock window's contents widget. If createWidget() returns a valid non-NULL widget, this method automatically sets it into the dock window by calling DockWindow::setWidget().

Parameters:

	pInArgList	This parameter is ignored since the default implementation of getInputSpecification() does not define any input arguments.
	pOutArgList	This parameter is ignored since the default implementation of getOutputSpecification() does not define any output arguments.

Returns:: Returns true if the action has been successfully created and the dock window has been successfully created or the existing window obtained from DesktopServices. Returns false if the plug-in is set to execute in batch mode, if the call to createAction() returns false, or if the dock window does not already exist and it could not be created from DesktopServices.

Implements Executable.

virtual bool DockWindowShell::serialize ( SessionItemSerializer & serializer ) const [virtual]

Saves the current state of the dock window plug-in.

The current displayed state of the dock window is saved so that the check state of the action can be properly initialized when loaded. Subclasses should override this method to save the current state of the contents widget if necessary.

Parameters:

serializer

The object with which to save the item as part of the current session.

Returns:: Returns true if the window display state was successfully saved; otherwise returns false.

Reimplemented from PlugInShell.

virtual bool DockWindowShell::deserialize ( SessionItemDeserializer & deserializer ) [virtual]

Loads the current state of the dock window plug-in.

The displayed state of the dock window is loaded and the check state of the action initialized. Subclasses should override this method to load the current state of the contents widget if necessary.

Parameters:

deserializer

The object from which the item is loaded as part of the current session.

Returns:: Returns true if the window display state was successfully loaded; otherwise returns false.

Reimplemented from PlugInShell.

virtual QAction* DockWindowShell::createAction ( ) [protected, pure virtual]

Creates the action to toggle the display of the dock window.

This method is called from execute() and subclasses must implement it to create an action and add it to a menu and/or toolbar. Typically, the action is created by calling MenuBar::addCommand(). After the action is created, only the action icon, tool tip, and status tip need to be set. The execute() method will set the action to be checkable and to not auto-repeat, and will connect it to the displayDockWindow() slot.

The action should be removed from the menu and/or toolbar and deleted in the subclass destructor.

Subclasses do not need to store a pointer to the created action. It can be retrieved by calling getAction().

Returns:: A pointer to the created action. The dock window will not be created and execute() will return false if NULL is returned.

QAction* DockWindowShell::getAction ( ) [protected]

Returns the action that is used to toggle the display of the dock window.

Returns:: Returns a pointer to the action that was created in createAction(). Returns NULL if createAction() has not yet been called.

See also:: getAction() const

const QAction* DockWindowShell::getAction ( ) const [protected]

Returns read-only access to the action that is used to toggle the display of the dock window.

Returns:: Returns a const pointer to the action that was created in createAction(). Returns NULL if createAction() has not yet been called. The action represented by the returned pointer should not be modified. To modify its values, call the non-const version of getAction() instead.

See also:: getAction()

virtual QWidget* DockWindowShell::createWidget ( ) [protected, pure virtual]

Creates the widget that is added to the dock window as its contents.

This method is called from execute() after the action has been successfully created. Subclasses do not need to destroy the created widget because it is automatically destroyed when the dock window is destroyed.

Returns:: A pointer to the created widget that is set into the dock window. The dock window will still be successfully created if NULL is returned, but the window will be empty.

QWidget* DockWindowShell::getWidget ( ) const [protected]

Returns the widget that is set into the dock window.

This method is a convenience method that calls DockWindow::getWidget().

Returns:: Returns a pointer to the widget that was created in createWidget(). Returns NULL if createWidget() has not yet been called.

DockWindow* DockWindowShell::getDockWindow ( ) [protected]

Returns a pointer to the dock window.

Returns:: Returns a pointer to the dock window that was created in execute(). Returns NULL if the dock window has not yet been created, or if execute() returned false.

See also:: getDockWindow() const

const DockWindow* DockWindowShell::getDockWindow ( ) const [protected]

Returns read-only access to the dock window.

Returns:: Returns a const pointer to the dock window that was created in execute(). Returns NULL if the dock window has not yet been created, or if execute() returned false. The dock window represented by the returned pointer should not be modified. To modify its values, call the non-const version of getDockWindow() instead.

See also:: getDockWindow()

void DockWindowShell::displayDockWindow ( bool bDisplay ) [protected, slot]

Toggles the display state of the dock window.

This slot is called automatically when the user triggers the action created in createAction().

Parameters:

bDisplay Shows the window if the value is true or hides the window if the value is false.


Public Member Functions
	DockWindowShell ()
virtual	~DockWindowShell ()
virtual bool	setBatch ()
virtual bool	getInputSpecification (PlugInArgList *&pArgList)
virtual bool	getOutputSpecification (PlugInArgList *&pArgList)
virtual bool	execute (PlugInArgList pInArgList, PlugInArgList pOutArgList)
virtual bool	serialize (SessionItemSerializer &serializer) const
virtual bool	deserialize (SessionItemDeserializer &deserializer)
Protected Slots
void	displayDockWindow (bool bDisplay)
Protected Member Functions
virtual QAction *	createAction ()=0
QAction *	getAction ()
const QAction *	getAction () const
virtual QWidget *	createWidget ()=0
QWidget *	getWidget () const
DockWindow *	getDockWindow ()
const DockWindow *	getDockWindow () const