Command object base class. More...

#include <GUICommand.h>

Inheritance diagram for CGUICommand:

[legend]

Public Member Functions
void	AddAdditionalCmd (CGUICommandPtr pkCmd, eC_Bool bOneTime=false)

CGUICommandPtr	GetAdditionalCmd (const eC_UInt &uiIndex) const

eC_UInt	GetNumberOfAdditionalCmds () const

eC_UInt	GetPriority () const

eC_UInt	GetTimeUntilNextExecution () const

eC_Bool	IsFinished () const

virtual void	ReadFromStream ()

void	RemoveAdditionalCmd (CGUICommandPtr pkCmd)

void	RemoveAllAdditionalCmds ()
	Removes all additional commands from this command's list.

void	SetPriority (eC_UInt uiPriority)

void	SetTimeUntilNextExecution (eC_UInt uiTime)

virtual void	WriteToStream (const eC_Bool bWriteClassID=false)

Public Member Functions inherited from CGUIStreamableObject
const eC_String &	GetXMLTag () const

virtual void	ReadFromStream ()

void	SetXMLTag (const eC_String &kXMLTag)

virtual void	WriteToStream (const eC_Bool bWriteClassID=false)

Public Member Functions inherited from NSmartPtr::RefCounted
	RefCounted ()
	Create RefCounted object. The reference count is initialized to 0.

virtual	~RefCounted ()
	Destroy reference counted object.

void	AddRef ()
	Increase reference count.

eC_Int	RefCount () const

void	Release ()

bool	Unique () const

Static Public Attributes
static const eC_Char	XMLTAG_ADDITIONALCMDCOUNT []
	XML tag to be used when writing the additional command count into a stream.

static const eC_Char	XMLTAG_COMMANDCLASSID []
	XML tag to be used when writing the command class ID into a stream.

static const eC_Char	XMLTAG_REMOVE_AFTER_EXECUTION []
	XML tag to be used when writing the remove after execution flag.

Static Public Attributes inherited from CGUIStreamableObject
static const eC_Char	XMLTAG_CLASSVERSION []

Protected Member Functions
	CGUICommand (const eC_UInt uiPriority=0, const eC_UInt uiTimeUntilFirstExecution=0, const eC_Bool bFinished=true)

virtual	~CGUICommand ()
	Destructor.

virtual void	Do ()=0

void	SetToBeFinished (eC_Bool bIsFinished)

Protected Member Functions inherited from CGUIStreamableObject
eC_UInt	ReadStreamingHeader (const eC_UInt &uiClassVersion, const eC_UInt &uiClassMinVersion=0) const

void	WriteStreamingFooter (const eC_Bool &bWriteClassID) const

void	WriteStreamingHeader (const eC_Bool &bWriteClassID, const eC_Char *const pkClassIDTag, const eC_Int &iClassID, const eC_UInt &uiClassVersion) const

Friends
class	CGUICommandHandler

Additional Inherited Members
Static Public Member Functions inherited from CGUIStreamableObject
static UUID_t	GenerateUUID ()

Detailed Description

Command object base class.

Command objects are used within Guiliani to represent a certain behaviour in reaction to user input. For example clicking on a button, or moving a slider may execute a command object. You may see a command object as a predefined action (or chain of actions) that will be executed if a certain condition is fulfilled. The command object's Do() method describes this action.

A typical use case for command objects is the communication between the user interface and the underlying application logic. By deploying commands you will gain three major advantages:

Commands are thread safe. They will be serialized and executed in the GUI's thread context.
They decouple GUI and application development. You can start developing the GUI even while the underlying application logic is not available - and vice versa. The typical work flow would be to start off with empty command-stubs whose Do() methods only include debug messages and attach the actual application-binding commands once they are available.
Commands simplify automated testing. You can test the application-API through the respective command-objects without the GUI.

Commands can be executed by calling CGUICommandHandler::Execute(). By default, a command is executed once after that method has been called. To run a command repeatedly (have its Do() method executed in each GUI main loop cycle), you may set it to 'not finished' explicitly by calling SetToBeFinished() with a value of False.

Each command can have zero or more additional commands which are executed when the 'parent' command is finished. The additional commands are not enqueued in the command handler. Instead, their Do() methods are called directly. Only if they are not finished after this first call they are enqueued. Therefore, the priorities of additional commands are initially ignored. Only if they are enqueued because they must run repeatedly the regular command handler mechanisms apply.

Attention: Do not use CGUICommand* and do not delete CGUICommand objects manually! Instead use CGUICommandPtr and let the smart pointer take care of deleting the object once it is no longer referenced.

The following example shows a simple command which receives a message-string during construction which it will later write into a textfield within the GUI.

class CExampleCommand
    : public CGUICommand
{
public:
    // The constructor receives the string which is to be displayed
    CExampleCommand(const eC_String& kMessageString) : m_kMessageString(kMessageString) {};
 
    // Every command-object must have a Do()-method.
    // The code herein will be executed threadsafe within the GUI's thread-context.
    // This example code will output a debug message to the logfile (or debug-window in VS2005) and change the text-label
    // of an object within the GUI.
    void Do()
    {
         GUILOG(GUI_TRACE_DEBUG, m_kMessageString);
         CGUIBaseTextField* pTextField = static_cast<CGUIBaseTextField*>(GETGUI.GetObjectByID(OBJ_TEXTFIELD));
         if (pTextField)
         {
             pTextField->GetLabel()->SetTextString(m_kMessageString);
             pTextField->InvalidateArea();
         }
    }
private:
    eC_String m_kMessageString;
};

The next line shows how to create a command object and how to enqueue it into the GUI's command handler (accessed through the GETCMDHDL helper macro). This could be done anywhere - even in another thread. Don't worry about memory leaks here, as commands are implemented as smart-pointers.

GETCMDHDL.Execute(new CExampleCommand("Hello world!\n"));

The following example shows how to implement a command which gets executed repeatedly after a given time span. This is done via the SetToBeFinished() and SetTimeUntilNextExecution() APIs.

class CRepeatingCommand
    : public CGUICommand
{
public:
    // The constructor receives the string which is to be displayed
    CRepeatingCommand(const eC_String& kMessageString) : m_kMessageString(kMessageString) {};
 
    // The Do method logs the given string to the debug outputs, stays in the queue and gets
    // executed every 1000ms
    void Do()
    {
         GUILOGMESSAGE(m_kMessageString);
         SetToBeFinished(false);
         SetTimeUntilNextExecution(1000);
    }
private:
    eC_String m_kMessageString;
};

Constructor & Destructor Documentation

◆ CGUICommand()

CGUICommand::CGUICommand	(	const eC_UInt	uiPriority = `0`,
		const eC_UInt	uiTimeUntilFirstExecution = `0`,
		const eC_Bool	bFinished = `true`
	)

protected

CGUICommand Constructor.

Attention: Since command-constructors typically get called from another thread they must not call any Guiliani APIs!

Parameters

uiPriority	The command's priority. 0 is the highest priority. In each GUI main loop cycle, all queued commands are executed sorted by their priority (see CGUICommandHandler::Execute()).
uiTimeUntilFirstExecution	Time in milliseconds until the command's first execution.
bFinished	true means that the command will be removed from the queue after execution, false means that the command stays in the queue and will be executed again.

Member Function Documentation

◆ AddAdditionalCmd()

void CGUICommand::AddAdditionalCmd	(	CGUICommandPtr	pkCmd,
		eC_Bool	bOneTime = `false`
	)

Adds an additional command to this command's list. Commands in the list are executed immediately after this command has finished.

Parameters

pkCmd	The command to be added.
bOneTime	Whether the command is executed only one time. If true, the command will be executed once and is then removed from the list of additional commands. If false, it stays in the list and is executed the next time after the 'parent' command.

◆ Do()

virtual void CGUICommand::Do ( )

protectedpure virtual

Action of the command object. Must be implemented in the derived class.

Implemented in CGUICallAPICmd, CGUIDelayCmd, CGUILoadAnimationsCmd, CGUILoadDialogCmd, CGUIPlaybackSoundCmd, CGUIQuitCmd, CGUISetDataPoolCmd, CGUISetObjectStateCmd, CGUISetObjectVisualsCmd, CGUIStartAnimationChainCmd, CGUIStopAnimationChainCmd, CGUISwitchResourceSetsCmd, and CGUITransitionCmd.

◆ GetAdditionalCmd()

CGUICommandPtr CGUICommand::GetAdditionalCmd ( const eC_UInt & uiIndex ) const

Returns the command object of the wanted additional command.

Parameters

uiIndex Index of the additional command.

Returns: The command object of the wanted additional command, or NULL if there is no command at the given index.

◆ GetNumberOfAdditionalCmds()

eC_UInt CGUICommand::GetNumberOfAdditionalCmds ( ) const

inline

Returns the number of additional commands.

Returns: Number of additional commands.

◆ GetPriority()

eC_UInt CGUICommand::GetPriority ( ) const

inline

Gets the priority of the command. The smaller the value of m_uiPriority, the higher the priority. Thus, 0 is the highest.

Returns: The priority of the command

◆ GetTimeUntilNextExecution()

eC_UInt CGUICommand::GetTimeUntilNextExecution ( ) const

inline

Gets the remaining time until this command should be executed again.

Returns: Time in milliseconds until next execution.

◆ IsFinished()

eC_Bool CGUICommand::IsFinished ( ) const

inline

Returns whether this command object's execution is completely finished.

Returns: True if command execution is completed, otherwise False.

◆ ReadFromStream()

virtual void CGUICommand::ReadFromStream ( )

virtual

Reads attributes from the streaming file. Only for use with GUIFactoryManager.

See also: CGUIObject::ReadFromStream()

Reimplemented from CGUIStreamableObject.

Reimplemented in CGUICallAPICmd, CGUIDelayCmd, CGUILoadAnimationsCmd, CGUILoadDialogCmd, CGUIPlaybackSoundCmd, CGUIQuitCmd, CGUISetDataPoolCmd, CGUISetObjectStateCmd, CGUISetObjectVisualsCmd, CGUIStartAnimationChainCmd, CGUIStopAnimationChainCmd, CGUISwitchResourceSetsCmd, and CGUITransitionCmd.

◆ RemoveAdditionalCmd()

void CGUICommand::RemoveAdditionalCmd ( CGUICommandPtr pkCmd )

Removes an additional command from this command's list.

Parameters

pkCmd The command to be removed.

◆ SetPriority()

void CGUICommand::SetPriority ( eC_UInt uiPriority )

Sets the priority of the command

Parameters

uiPriority is the priority of the command

◆ SetTimeUntilNextExecution()

void CGUICommand::SetTimeUntilNextExecution ( eC_UInt uiTime )

Sets the remaining time until this command should be executed (again). If the command is executed repeatedly (i.e. its IsFinished-Flag is set to false) you need to call SetTimeUntilNextExecution() during each call to Do(). Note that for the first call to CGUI::Run() or CGUI::RunOnce(), the time since creation of the GUI is taken as the time since the last command processing.

See also: IsFinished(), SetToBeFinished()

Parameters

uiTime Time in milliseconds until next execution.

◆ SetToBeFinished()

void CGUICommand::SetToBeFinished ( eC_Bool bIsFinished )

inlineprotected

Set the command as 'finished' or not. By default, a command is 'finished' which results in a single execution of its Do() method after it has been added to the command handler by calling CGUICommandHandler::Execute(). To keep a command running (have its Do() method executed in each GUI main loop cycle), mark it as 'not finished'.

Parameters

bIsFinished Pass true to mark the command as finished, false to mark it as unfinished.

◆ WriteToStream()

virtual void CGUICommand::WriteToStream ( const eC_Bool bWriteClassID = false )

virtual

Writes attributes to the streaming file. A CGUIStreamWriter has to be initialized.

Parameters

bWriteClassID This flag is used to switch writing of the class ID, leading and trailing tags. When implementing a new streamable object, check this flag. If it is true, first write the class ID, then continue with this object's attributes, and finally call the base class implementation with this flag set to false (this is the default).

Reimplemented from CGUIStreamableObject.

Reimplemented in CGUICallAPICmd, CGUIDelayCmd, CGUILoadAnimationsCmd, CGUILoadDialogCmd, CGUIPlaybackSoundCmd, CGUIQuitCmd, CGUISetDataPoolCmd, CGUISetObjectStateCmd, CGUISetObjectVisualsCmd, CGUIStartAnimationChainCmd, CGUIStopAnimationChainCmd, CGUISwitchResourceSetsCmd, and CGUITransitionCmd.

Friends And Related Function Documentation

◆ CGUICommandHandler

friend class CGUICommandHandler

friend

The documentation for this class was generated from the following file:

GUICommand.h

Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ CGUICommand()

Member Function Documentation

◆ AddAdditionalCmd()

◆ Do()

◆ GetAdditionalCmd()

◆ GetNumberOfAdditionalCmds()

◆ GetPriority()

◆ GetTimeUntilNextExecution()

◆ IsFinished()

◆ ReadFromStream()

◆ RemoveAdditionalCmd()

◆ SetPriority()

◆ SetTimeUntilNextExecution()

◆ SetToBeFinished()

◆ WriteToStream()

Friends And Related Function Documentation

◆ CGUICommandHandler