Sourceforge.net - The VCF's Project Host
   The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page   

VCF::Action Class Reference

The Action class is used to represent an "action" that gets performed because of some event from the UI, such as clicking a menu item or button. More...

#include <vcf/ApplicationKit/Action.h>

Inheritance diagram for VCF::Action:

VCF::Component VCF::ObjectWithCallbacks VCF::Object List of all members.

Public Types

enum  { UpdateEvent = 40521, ActionPerformedEvent = 40511, AcceleratorChanged = 40541 }

Public Member Functions

 Action ()
 Action (Component *owner)
 Action (const String &name, Component *owner)
 Action (const String &name)
virtual ~Action ()
void update ()
 This is called by a target (or the framework itself) to tell the action to fire off an update event to all the actions targets.
void perform (Event *event=NULL)
 This is called to execute the action.
void addTarget (UIComponent *target)
 adds a target to the action
void removeTarget (UIComponent *target)
 removes a target from the action.
UIComponentgetTarget (const uint32 &index)
void setTarget (const uint32 &index, UIComponent *target)
uint32 getTargetIndexes (std::vector< uint32 > &indexes)
Enumerator< UIComponent * > * getTargets ()
 returns an enumerator of all the targets currently attached to this action.
uint32 getTargetCount ()
 returns a count of the number of targets attached to this action.
void setAcceleratorKeyInfo (const VirtualKeyCode &keyCode, const uint32 &modifierMask)
 This sets the accelerator key object for the action item.
void setAcceleratorKey (AcceleratorKey *accelerator)
 Sets the acclerator object for this action item.
AcceleratorKeygetAccelerator ()
 Returns the accelerator for the action item.
EventHandlergetAcceleratorEventHandler ()
 Returns the event handler used to trigger the action's perform() method when the appropriate key combination is pressed.

Public Attributes

VCF::Delegate ActionDelegate
 Update
 Performed

Protected Member Functions

void onAccelerator (Event *e)
 the default event handler for the accelerator associated to this action.

Protected Attributes

AcceleratorKeycurrentAccelerator_
std::vector< UIComponent * > targets_
EnumeratorContainer< std::vector<
UIComponent * >, UIComponent * > 
targetsContainer_

Detailed Description

The Action class is used to represent an "action" that gets performed because of some event from the UI, such as clicking a menu item or button.

An Action also allows you to consolidate multiple event handlers for menu items, buttons, etc, and their associated code to update their UI state in relation to the application's state. An Action has one or more targets that get notified for update events. Any of these targets can also cause the action to be executed or "performed".

An example of how this might be useful:

Consider an application that has three UI elements, a button, a toolbar item, and a menu item. Clicking the menu item, toolbar item, or button all cause some change of state in the application. Without using actions, you would have to write 3 individual event handlers for the "click" events of the menu item, button, and toolbar item, as well as separate ui updating code. If you use an action, you simply add all three items as targets to the action, and then write a single handler that's attached to the action's Performed delegate, and another event handler that is attached to the action's Update delegate. The framework then takes care of the rest, and clicking the button, menu item, or toolbar item will all cause event handler attached to the action's Performed delegate to get called, and each UI element will in turn be updated as specified by event handler attached to the action's Update delegate.

Event Delegates for this class:
  • Update
  • Performed


Member Enumeration Documentation

anonymous enum
 

Enumerator:
UpdateEvent  This event type is used when the update method is invoked.
ActionPerformedEvent  This is used when an action event is fired.
AcceleratorChanged  This is used when the action's accelerator is changed, specifically by the method setAcceleratorKey().


Constructor & Destructor Documentation

VCF::Action::Action  ) 
 

VCF::Action::Action Component owner  ) 
 

VCF::Action::Action const String name,
Component owner
 

VCF::Action::Action const String name  ) 
 

virtual VCF::Action::~Action  )  [virtual]
 


Member Function Documentation

void VCF::Action::addTarget UIComponent target  ) 
 

adds a target to the action

AcceleratorKey* VCF::Action::getAccelerator  ) 
 

Returns the accelerator for the action item.

EventHandler* VCF::Action::getAcceleratorEventHandler  ) 
 

Returns the event handler used to trigger the action's perform() method when the appropriate key combination is pressed.

If no event handler exists at the time of this call, a new instance will be created.

UIComponent* VCF::Action::getTarget const uint32 index  ) 
 

uint32 VCF::Action::getTargetCount  ) 
 

returns a count of the number of targets attached to this action.

uint32 VCF::Action::getTargetIndexes std::vector< uint32 > &  indexes  ) 
 

Enumerator<UIComponent*>* VCF::Action::getTargets  ) 
 

returns an enumerator of all the targets currently attached to this action.

void VCF::Action::onAccelerator Event e  )  [protected]
 

the default event handler for the accelerator associated to this action.

void VCF::Action::perform Event event = NULL  ) 
 

This is called to execute the action.

An action performed event will be fired off to all the event handlers attached to the Performed delegate.

void VCF::Action::removeTarget UIComponent target  ) 
 

removes a target from the action.

void VCF::Action::setAcceleratorKey AcceleratorKey accelerator  ) 
 

Sets the acclerator object for this action item.

If one already exists then it is removed. To ensure that any targets of this action are properly updated, the action creates a Event instance, sets it's event type to Action::AcceleratorChanged, loops through all it's targets, and then calls each target's handleEvent() method passing in the event instance. Targets should respond accordingly to this event if it makes sense.

void VCF::Action::setAcceleratorKeyInfo const VirtualKeyCode keyCode,
const uint32 modifierMask
 

This sets the accelerator key object for the action item.

If one already exists it is removed for this action item. The accelerator is assigned the key code and modifier mask passed in, and is given a default event handler which calls the action item's perform method. An action may have only one accelerator associated with it at any given time. Internally this method creates a new AcceleratorKey isntance and then calls the setAcceleratorKey( AcceleratorKey* ) method. See this method's documentation for more details.

See also:
setAcceleratorKey

void VCF::Action::setTarget const uint32 index,
UIComponent target
 

void VCF::Action::update  ) 
 

This is called by a target (or the framework itself) to tell the action to fire off an update event to all the actions targets.

First an Update event is fired in order to let the application to set, in the event(s) handler(s) of this action, the desired state for the ActionEvent ( e.g. enabled or not, checked or not. Then the update ActionEvent is fired off to all the actions targets. The enabled state of the accelerator associated to this action, if any, is also updated accordingly.

See also:
ActionEvent


Member Data Documentation

VCF::Delegate VCF::Action::ActionDelegate
 

Event Delegate:
Update this is fired when the action's update() method is called.
event class: ActionEvent
event type: Action::UpdateEvent
See also:
update()

AcceleratorKey* VCF::Action::currentAccelerator_ [protected]
 

VCF::Action::Performed
 

std::vector<UIComponent*> VCF::Action::targets_ [protected]
 

EnumeratorContainer<std::vector<UIComponent*>,UIComponent*> VCF::Action::targetsContainer_ [protected]
 

VCF::Action::Update
 


The documentation for this class was generated from the following file:
   Comments or Suggestions?    License Information