Guiliani  Version 2.4 revision 5970 (build 3)
CGUICommand Class Referenceabstract

Command object base class. More...

#include <GUICommand.h>

Inheritance diagram for CGUICommand:

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
 
void SetXMLTag (const eC_String &kXMLTag)
 
- 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 [] = "AdditionalCmdCount"
 XML tag to be used when writing the additional command count into a stream.
 
static const eC_Char XMLTAG_COMMANDCLASSID [] = "CommandClassID"
 XML tag to be used when writing the command class ID into a stream.
 
static const eC_Char XMLTAG_REMOVE_AFTER_EXECUTION [] = "RemoveAfterExecution"
 XML tag to be used when writing the remove after execution flag.
 
- Static Public Attributes inherited from CGUIStreamableObject
static const eC_Char XMLTAG_CLASSVERSION [] = "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
 

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:

  1. Commands are thread safe. They will be serialized and executed in the GUI's thread context.
  2. 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.
  3. 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);
}
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
uiPriorityThe 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()).
uiTimeUntilFirstExecutionTime in milliseconds until the command's first execution.
bFinishedtrue 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
pkCmdThe command to be added.
bOneTimeWhether 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

◆ GetAdditionalCmd()

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

Returns the command object of the wanted additional command.

Parameters
uiIndexIndex 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()

void CGUICommand::ReadFromStream ( )
virtual

◆ RemoveAdditionalCmd()

void CGUICommand::RemoveAdditionalCmd ( CGUICommandPtr  pkCmd)

Removes an additional command from this command's list.

Parameters
pkCmdThe command to be removed.

◆ SetPriority()

void CGUICommand::SetPriority ( eC_UInt  uiPriority)

Sets the priority of the command

Parameters
uiPriorityis 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
uiTimeTime 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
bIsFinishedPass true to mark the command as finished, false to mark it as unfinished.

◆ WriteToStream()

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

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

Parameters
bWriteClassIDThis 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 CGUITransitionCmd, CGUISetObjectVisualsCmd, CGUILoadDialogCmd, CGUILoadAnimationsCmd, CGUISetObjectStateCmd, CGUISetDataPoolCmd, CGUICallAPICmd, CGUIPlaybackSoundCmd, CGUIStopAnimationChainCmd, CGUIStartAnimationChainCmd, CGUIDelayCmd, CGUISwitchResourceSetsCmd, and CGUIQuitCmd.

Friends And Related Function Documentation

◆ CGUICommandHandler

friend class CGUICommandHandler
friend

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