Guiliani  Version 2.4 revision 5970 (build 3)
CGUIHotkeysBehaviour Class Reference

Maps key codes to object IDs and 'clicks' on objects. More...

#include <GUIHotkeysBehaviour.h>

Inheritance diagram for CGUIHotkeysBehaviour:

Classes

struct  HotKeyMap_t
 Definition of one hot key mapping with all necessary parameters. More...
 

Public Member Functions

 CGUIHotkeysBehaviour (eC_Bool bMarkAlwaysAsHandled=false)
 
 CGUIHotkeysBehaviour (const CGUIHotkeysBehaviour &kSource)
 
void AddHotKeyMap (GUIKeyIdentifier_t eKeyIdentifier, eC_UInt uiModifiers, eC_Bool bCheckForModifiers, ObjectHandle_t eMappedObjID, eC_Bool bAbstractObj, CGUICommandPtr pCommand=NULL, eC_Bool bActivated=true)
 
virtual CGUIBehaviourDecoratorClone () const
 
eC_Bool GetHotKey (GUIKeyIdentifier_t &reKeyIdentifier, eC_UInt &ruiModifiers, ObjectHandle_t eMappedObjID) const
 
CGUIHotkeysBehaviouroperator= (const CGUIHotkeysBehaviour &kSource)
 
void ReadFromStream ()
 
void SetActivated (GUIKeyIdentifier_t eKeyContent, eC_UInt uiModifiers, eC_Bool bActivated)
 
void SetMarkAlwaysAsHandled (eC_Bool bMarkAlwaysAsHandled)
 
void SetModifiers (GUIKeyIdentifier_t eKey, eC_UInt uiModifiers, eC_Bool bCheckForModifiers)
 
void WriteToStream (const eC_Bool bWriteClassID=false)
 
- Public Member Functions inherited from CGUIBehaviourDecorator
virtual ~CGUIBehaviourDecorator ()
 
virtual eC_Bool IsCompositeBehaviour () const
 
- Public Member Functions inherited from CGUIBehaviour
virtual eC_Bool DoUserEvent (CGUIEvent *const pEvent)
 
virtual void OnCreate ()
 
virtual void OnDelete ()
 
virtual void OnHide ()
 
virtual void OnShow ()
 
virtual eC_Bool DoClick (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoLongClick (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoDoubleClick (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoButtonDown (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoButtonUp (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoDrag (const eC_Value &vDeltaX=eC_FromInt(-1), const eC_Value &vDeltaY=eC_FromInt(-1), const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoDragEnd (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoMouseEnter (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoMouseLeave (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool DoMouseMove (const eC_Value &vAbsX=eC_FromInt(-1), const eC_Value &vAbsY=eC_FromInt(-1))
 
virtual eC_Bool FocusPrevious (CGUIObject *const pRefObj=NULL, const eC_Bool &bSubTreeOfRefObjDone=false)
 
virtual eC_Bool FocusNext (CGUIObject *const pRefObj=NULL, const eC_Bool &bSubTreeOfRefObjDone=false)
 
virtual void GetFocus ()
 
virtual void LoseFocus ()
 
virtual eC_Bool Decrease ()
 
virtual eC_Bool Increase ()
 
virtual eC_Bool DoChar (const eC_UInt &uiKey, const GUIKeyIdentifier_t &eKeyIdentifier, const eC_UInt &uiModifiers)
 
virtual eC_Bool DoScrollUp (const eC_Value &vAbsX, const eC_Value &vAbsY)
 
virtual eC_Bool DoScrollDown (const eC_Value &vAbsX, const eC_Value &vAbsY)
 
virtual eC_Bool DoScrollLeft (const eC_Value &vAbsX, const eC_Value &vAbsY)
 
virtual eC_Bool DoScrollRight (const eC_Value &vAbsX, const eC_Value &vAbsY)
 
- Public Member Functions inherited from CGUIStreamableObject
const eC_String & GetXMLTag () const
 
void SetXMLTag (const eC_String &kXMLTag)
 

Static Public Member Functions

static eC_String MapKeyToString (GUIKeyIdentifier_t eKeyIdentifier)
 

Protected Member Functions

virtual eC_Bool DoKeyDown (const GUIKeyIdentifier_t &eKeyIdentifier, const eC_UInt &uiModifiers)
 
virtual eC_Bool DoKeyUp (const GUIKeyIdentifier_t &eKeyIdentifier, const eC_UInt &uiModifiers)
 
- Protected Member Functions inherited from CGUIBehaviourDecorator
 CGUIBehaviourDecorator (CGUIObject *const pObject=NULL)
 
 CGUIBehaviourDecorator (const CGUIBehaviourDecorator &kSource)
 
virtual void AssociatedObjectChanges (CGUIObject *const pNewAssociatedObject)
 
CGUIObjectGetAssociatedObject () const
 
- 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
 

Protected Attributes

eC_TListDoubleLinked< HotKeyMap_tm_kHotKeyMapList
 The hot key mappings are saved in this list.
 

Additional Inherited Members

- Static Public Attributes inherited from CGUIBehaviour
static const eC_Char XMLTAG_BEHAVIOURCLASSID [] = "BehaviourClassID"
 XML tag to be used when writing a behaviour class ID into a stream.
 
- Static Public Attributes inherited from CGUIStreamableObject
static const eC_Char XMLTAG_CLASSVERSION [] = "ClassVersion"
 

Detailed Description

Maps key codes to object IDs and 'clicks' on objects.

This behaviour maintains a list that maps key codes (hot keys) to object IDs or commands. Whenever one of the key codes is received in an ET_KEYDOWN event in DoKeyDown(), this behaviour searches the object it is attached to for the corresponding object ID and, if found, checks for an attached behaviour decorator. If one is there, its DoClick method is called; if there is none, the object's own DoClick method is called.

Additionally, in case of a hotkey match, an optional CGUICommand is executed, which is assigned to the hotkey also.

Note
This command is not used when streaming this behaviour, i.e. ReadFromStream() and WriteToStream() ignore the command.

Objects of this behaviour class must be attached to a composite object. Otherwise an exeception is thrown.

The following example demonstrates the use of this behaviour:

If a hotkey behaviour has a command that is executed, the event slots always return true, i.e. no other objects are invoked to handle the pressed key.

// Create a container.
CGUICompositeObject* pkComposite = new CGUICompositeObject(...);
// Create a button with the ID OBJ_BTN_EXAMPLE.
pkComposite->AddObject(new CGUIButton(..., OBJ_BTN_EXAMPLE));
// Create a behaviour that maps a hotkey to the button.
// Map a key (e.g. the F1 key) to the button:
pkHKB->AddHotKeyMap(GK_F1, 0, false, OBJ_BTN_EXAMPLE, false);
// Alternatively, independent of the object, a command can be assigned to a hotkey.
pkHKB->AddHotKeyMap(GK_S, CGUIEvent::GKM_CONTROL, true, NO_HANDLE, false, new CGUISaveCmd());
// Attach the behaviour to the composite containing the button.
pkComposite->SetBehaviour(pkHKB);

Constructor & Destructor Documentation

◆ CGUIHotkeysBehaviour() [1/2]

CGUIHotkeysBehaviour::CGUIHotkeysBehaviour ( eC_Bool  bMarkAlwaysAsHandled = false)

Constructor.

Parameters
bMarkAlwaysAsHandledIf true the behaviour will always return false after an event has been handled.

◆ CGUIHotkeysBehaviour() [2/2]

CGUIHotkeysBehaviour::CGUIHotkeysBehaviour ( const CGUIHotkeysBehaviour kSource)

Copy-constructor of the CGUIHotkeysBehaviour class.

Parameters
kSourceSource object to be copied.

Member Function Documentation

◆ AddHotKeyMap()

void CGUIHotkeysBehaviour::AddHotKeyMap ( GUIKeyIdentifier_t  eKeyIdentifier,
eC_UInt  uiModifiers,
eC_Bool  bCheckForModifiers,
ObjectHandle_t  eMappedObjID,
eC_Bool  bAbstractObj,
CGUICommandPtr  pCommand = NULL,
eC_Bool  bActivated = true 
)

Adds a key mapping to the list of hot keys.

Parameters
eKeyIdentifierHotkey identifier to be mapped.
uiModifiersWhich modifier is to consider (CTRL, ALT, etc.)
bCheckForModifiersShould the modifier be considered while evaluating the hotkey event?
eMappedObjIDObject ID of the object whose DoClick method may be called when the key code uiKeyContent is received in an ET_KEYDOWN event.
bAbstractObjIndicate whether the object is abstract or not. A button which is visible in the GUI is not abstract object. If the object is an abstract object, the DoClick method will be executed at once if the hot key was pressed. Otherwise the object will first be checked whether it is clickable (CGUIObject::IsClickable).
pCommand(optional) This command will be executed additionally if the hotkey event occurres. This command is not written to streaming files by WriteToStream().
bActivated(optional) Is the hotkey activated, i.e. should events associated with the hotkey be handled.

◆ Clone()

CGUIBehaviourDecorator * CGUIHotkeysBehaviour::Clone ( ) const
virtual

Creates an exact copy of this behaviour. Should be re-implemented by each derived class to return the correct type of behaviour.

Returns
the created copy.

Reimplemented from CGUIBehaviourDecorator.

◆ DoKeyDown()

eC_Bool CGUIHotkeysBehaviour::DoKeyDown ( const GUIKeyIdentifier_t eKeyIdentifier,
const eC_UInt &  uiModifiers 
)
protectedvirtual

If an ET_KEYDOWN with one of the added key codes is received, the mapped object's DoClick method is called.

Parameters
eKeyIdentifierThe key identifier of the pressed key.
uiModifiersWhether a modifier key is pressed (Ctrl, ALT, etc.).
Returns
Has the event been handled.

Reimplemented from CGUIBehaviour.

◆ DoKeyUp()

eC_Bool CGUIHotkeysBehaviour::DoKeyUp ( const GUIKeyIdentifier_t eKeyIdentifier,
const eC_UInt &  uiModifiers 
)
protectedvirtual

If an ET_KEYUP with one of the added key codes is received, the mapped object's DoKeyUp method is called.

Parameters
eKeyIdentifierThe key identifier of the released key.
uiModifiersWhether a modifier key is pressed (Ctrl, ALT, etc.).
Returns
Has the event been handled.

Reimplemented from CGUIBehaviour.

◆ GetHotKey()

eC_Bool CGUIHotkeysBehaviour::GetHotKey ( GUIKeyIdentifier_t reKeyIdentifier,
eC_UInt &  ruiModifiers,
ObjectHandle_t  eMappedObjID 
) const

Find first occurrence of a hotkey mapping to an object.

Parameters
reKeyIdentifier[out] If a hot assigned to eMappedObjID is found, the key value is returned here.
ruiModifiers[out] If a hot assigned to eMappedObjID is found, the modifier is returned here.
eMappedObjIDFind the hotkey assigned to this object.
Returns
True, if the hotkey map has been found, False otherwise.

◆ MapKeyToString()

eC_String CGUIHotkeysBehaviour::MapKeyToString ( GUIKeyIdentifier_t  eKeyIdentifier)
static

Maps a GK_ key identifier to a string representation.

Parameters
eKeyIdentifierInput key.
Returns
Printable string representation of the key.

◆ operator=()

CGUIHotkeysBehaviour & CGUIHotkeysBehaviour::operator= ( const CGUIHotkeysBehaviour kSource)

Operator= method of the CGUIHotkeysBehaviour class.

Parameters
kSourceSource object to be copied.
Returns
Copied object.

◆ ReadFromStream()

void CGUIHotkeysBehaviour::ReadFromStream ( )
virtual

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

See also
CGUIObject::ReadFromStream()

Reimplemented from CGUIStreamableObject.

◆ SetActivated()

void CGUIHotkeysBehaviour::SetActivated ( GUIKeyIdentifier_t  eKeyContent,
eC_UInt  uiModifiers,
eC_Bool  bActivated 
)

Whether the hotkey is activated or not. A deactivated hotkey does not handle the specific hotkey events.

Parameters
eKeyContentThe hotkey that is to activate or deactivate.
uiModifiersThe modifier corresponding to the hotkey.
bActivatedSet true to activate the hotkey or false to deactivate it.

◆ SetMarkAlwaysAsHandled()

void CGUIHotkeysBehaviour::SetMarkAlwaysAsHandled ( eC_Bool  bMarkAlwaysAsHandled)

Sets the flag deciding if the slots should always return true or not.

Parameters
bMarkAlwaysAsHandledIf true, the behaviour will always return true when an hotkey event is handled. If false, the behaviour will return the value that is returned by the called object or its attached behaviour.

◆ SetModifiers()

void CGUIHotkeysBehaviour::SetModifiers ( GUIKeyIdentifier_t  eKey,
eC_UInt  uiModifiers,
eC_Bool  bCheckForModifiers 
)

Sets the given modifier and the flag whether the modifiers should be checked or not for given key event.

Parameters
eKeyThe key identifier.
uiModifiersThe modifier to set this hotkey should handle.
bCheckForModifiersShould modifiers be considered while evaluating a hotkey event?

◆ WriteToStream()

void CGUIHotkeysBehaviour::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.


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