VCF::Component Class Reference

The base class for all objects within the Visual Component Framework that wish to manipulated dynamically within the an IDE. More...

#include <vcf/ApplicationKit/Component.h>

Inheritance diagram for VCF::Component:

List of all members.


Public Types
enum	ComponentEvents { COMPONENT_CREATED = 0, COMPONENT_DESTROYED, COMPONENT_NEEDS_UPDATING, COMPONENT_ADDED, COMPONENT_REMOVED, COMPONENT_LOADED, COMPONENT_SAVED, COMPONENT_EVENTS_LAST }
enum	ComponentState { csUnknown = 0, csLoading = 0x1000, csSaving = 0x2000, csCreated = 1, csDesigning = 0x100, csNormal = 3, csDestroying = 4, csUsesLocaleStrings = 0x10000 }
	The ComponentState enum represents the current state of the component. More...
Public Member Functions
virtual void	handleEvent (Event *event)
	generic handler method for events.
void	loading ()
	This is called to make sure the csLoading bit is set in the component state.
void	saving ()
	This is called to make sure the csSaving bit is set in the component state.
void	loaded ()
	Fires an event to the ComponentLoaded delegate.
void	saved ()
	Fires an event to the ComponentSaved delegate.
virtual String	getName ()
	The name of the component.
virtual void	setName (const String &name)
	sets the name of the component.
virtual void	beforeDestroy (ComponentEvent *event)
	called just prior to completely destroying the component and it's associated memory.
virtual void	afterCreate (ComponentEvent *event)
	after the component has been created/instantiated the afterCreate() method is called.
uint32	getComponentState ()
	returns the current state of the component.
bool	isNormal () const
	queries the component state to check if it's set to csNormal or not.
bool	isDestroying () const
	queries the component state to check if it's set to csDestroying or not.
bool	isLoading () const
	queries the component state to check if it's csLoading bit is set or not.
bool	isSaving () const
	queries the component state to check if it's csSaving bit is set or not.
bool	isDesigning () const
	queries the component state to check if it's csDesigning bit is set or not.
bool	isCreated () const
	queries the component state to check if it's set to csCreated or not.
void	setComponentState (const uint32 &componentState)
	Sets the component's state.
void	setCreated ()
	convenience fundtions for setting the component state
void	setNormal ()
void	setDestroying ()
void	setDesigning (const bool &designing)
virtual void	addComponent (Component *component)
	adds a component to this component.
virtual void	removeComponent (Component *component)
	removes the component.
void	removeFromOwner (const bool &freeInstance=true)
virtual Enumerator< Component * > *	getComponents ()
	returns an enumeration of all the component's that this component currently owns.
virtual uint32	getComponentCount ()
	returns the number of components owned by this component
Component *	findComponent (const String &componentName, const bool &recursive=false)
	finds a particular component as specified by the componentName parameter within the list of owned components.
bool	bindVariable (Component **variablePtr, const String &variableName)
	Used to bind a variable to a component by attempting to bind the variable passed in to the component in the variablePtr parameter to the component instance with the same name as the variableName parameter.
int32	getTag ()
	returns the Component's tag value.
void	setTag (const int32 &tag)
	Sets the tag value.
Component *	getOwner ()
	`Returns` the owner of the component.
Action *	getAction ()
	Returns the Action associated with this component.
void	setAction (Action *action)
	Set's the action for the component.
virtual bool	updateAction ()
	Calling this triggers an update event to be fired.
void	addToUpdateList ()
	Adds the component to the framework's update list.
void	removeFromUpdateList ()
	Removes the component from the framework's update list.
void	setUseLocaleStrings (const bool &val)
	Allows the user to control whether or not the component should attempt to translate the text of a specific component.
bool	getUseLocaleStrings ()
	Returns a value indicating whether or not the component will attempt to translate any text using the current thread's locale.
Dictionary *	getSettings ()
	Returns the dictionary that holds this component's settings.
ComponentSetting *	getSetting (const String &name)
	Returns a specific setting specified by the name argument.
ComponentSetting *	assignSetting (const String &settingName, const String &valueName, const VariantData &v)
	Assigns a setting to the component's settings dictionary.
ComponentSetting *	assignSetting (const String &settingName, const String &valueName)
	Assigns a setting to the component's settings dictionary.
void	assignSetting (const String &settingName, ComponentSetting *setting)
virtual void	initializeSettings (const bool &recursive)
virtual void	storeSettings (const bool &recursive)
Static Public Member Functions
static bool	registerComponent (const String &componentClassName, const String &category)
	registers a component in the system component map.
static Enumerator< Class * > *	getComponentClassesForCategory (const String &category)
	Used by IDE's to list the various Component classes for a given category.
static Enumerator< String > *	getRegisteredComponentCategories ()
	returns a list of all the known, registered, component categories.
static void	initComponentRegistrar ()
static void	clearRegistedComponents ()
static void	initComponent (Component instance, Class clazz, Class rootClazz, ResourceBundle resBundle=NULL)
	Takes a valid component instance and initializes it from a VFF file that is assumed to be present in the programs resource bundle.
static Component *	createComponentFromResources (Class clazz, Class rootClazz, ResourceBundle *resBundle=NULL)
Public Attributes
VCF::Delegate	ComponentCreated
VCF::Delegate	ComponentDestroyed
VCF::Delegate	ComponentAdded
VCF::Delegate	ComponentRemoved
VCF::Delegate	ComponentLoaded
VCF::Delegate	ComponentSaved
Protected Member Functions
	Component ()
	The constructor and destructor is hidden - this is an abstract class and should NEVER be instantiated directly.
	Component (Component *owner)
	Component (const String &name, Component *owner)
	Component (const String &name)
virtual	~Component ()
	This is protected - you should call free, or release to destroy the component.
virtual void	destroy ()
	called by the free() method.
Protected Attributes
Component *	owner_
uint32	componentState_
String	name_
int32	tag_
Action *	action_
std::vector< Component * >	components_
EnumeratorContainer< std::vector< Component * >, Component * >	componentContainer_
Dictionary *	settings_
Static Protected Attributes
static std::map< String, std::vector< Class * > * > *	registeredComponentMap
	a map of component classes to categories
static std::vector< String > *	registeredCategory
static EnumeratorContainer< std::vector< String >, String > *	registeredCategoryContainer
static EnumeratorContainer< std::vector< Class * >, Class * > *	registeredCompContainer

Detailed Description

The base class for all objects within the Visual Component Framework that wish to manipulated dynamically within the an IDE.

All UI controls are descended from this class.

Some of the services that are provided are as follows:

provides methods for registering components into logical groups, that can then be displayed with an IDE
provides the ability to own other components
the ability to be manipulated by the IDE UI designer
methods for uniquely identifying each instance, either by name or by a numerical tag.

The component itself is a non visual object, thus it can be used as a base class for a wide variety of things, in addition to serving as a base class for UI controls. The Component by itself is an abstract class and should never be created by itself, instead you should be created derived instances of classes derived from Component.

Event Delegates for this class:

Member Enumeration Documentation

enum VCF::Component::ComponentEvents

Enumerator:

COMPONENT_CREATED

COMPONENT_DESTROYED

COMPONENT_NEEDS_UPDATING

COMPONENT_ADDED

COMPONENT_REMOVED

COMPONENT_LOADED

COMPONENT_SAVED

COMPONENT_EVENTS_LAST

enum VCF::Component::ComponentState

The ComponentState enum represents the current state of the component.
Some states will prevent the Component from responding to events, for example, a Control with it state set to CS_DESIGNING, will not respond to certain UI events, while a Control with it's state set to CS_DESTROYING, will not respond to any pending UI events.
Enumerator:

csUnknown

csLoading csLoading and csReading are mutually exclusive - you can't be read AND writing at the same time

csSaving

csCreated

csDesigning

csNormal

csDestroying

csUsesLocaleStrings

Constructor & Destructor Documentation

VCF::Component::Component ( ) [protected]

The constructor and destructor is hidden - this is an abstract class and should NEVER be instantiated directly.

VCF::Component::Component ( Component * owner ) [protected]

VCF::Component::Component ( const String & name,

Component * owner

) [protected]

VCF::Component::Component ( const String & name ) [protected]

virtual VCF::Component::~Component ( ) [protected, virtual]

This is protected - you should call free, or release to destroy the component.

Member Function Documentation

virtual void VCF::Component::addComponent ( Component * component ) [virtual]

adds a component to this component.
Components may contain one or more child, or owned, components. When the component is destroyed, all owned components are destroyed as well. This is entirely independent from the Container interface's add() method. This provides a convenient way to clean up memory of components added on the heap. For example, a Window may have a popup menu that is created during initialization. By adding the popup menu (which is derived from Component), the popup menu will be destroyed automatically for you once the Window is destroyed. The implementation checks to prevent multiple adds of the same component instance in the internal list.

void VCF::Component::addToUpdateList ( )

Adds the component to the framework's update list.
This list will be traversed periodically, during idle time, and the framework will create a COMPONENT_NEEDS_UPDATING event and pass it to the component. The component can specialize this functionality by customizing the behaviour of the handleEvent() method.

virtual void VCF::Component::afterCreate ( ComponentEvent * event ) [virtual]

after the component has been created/instantiated the afterCreate() method is called.
Special initializations may then happen here.
Reimplemented in VCF::CommonDialog, VCF::Control, VCF::Frame, VCF::ImageList, VCF::ScrollbarManager, VCF::TimerComponent, VCF::HTMLBrowserControl, and VCF::OpenGLControl.

void VCF::Component::assignSetting ( const String & settingName,

ComponentSetting * setting

)

ComponentSetting* VCF::Component::assignSetting ( const String & settingName,

const String & valueName

)

Assigns a setting to the component's settings dictionary.
If the setting already exists it's value is modified, otherwise a new setting is created. Returns the setting that was modified or created. This version uses the component's property to get the initial value for the setting. Therefore the value name needs to be a valid component property name.
Parameters:

String the name setting's key in the dictionary

String the value name of the setting. This must be a valid, existing property name that belongs to the component's Class.

See also:
Class
Property

ComponentSetting* VCF::Component::assignSetting ( const String & settingName,

const String & valueName,

const VariantData & v

)

Assigns a setting to the component's settings dictionary.
If the setting already exists it's value is modified, otherwise a new setting is created. Returns the setting that was modified or created.
Parameters:

String the name setting's key in the dictionary

String the value name of the setting

the value of the setting

virtual void VCF::Component::beforeDestroy ( ComponentEvent * event ) [virtual]

called just prior to completely destroying the component and it's associated memory.

Reimplemented in VCF::Control, and VCF::Window.

bool VCF::Component::bindVariable ( Component ** variablePtr,

const String & variableName

)

Used to bind a variable to a component by attempting to bind the variable passed in to the component in the variablePtr parameter to the component instance with the same name as the variableName parameter.
This functions looks at all the owned components first, then checks to see if the Container interface is supported, and if so, it checks all the child controls of the container.
Parameters:

Component* a pointer to a Component pointer variable

String the name of the component to find

Returns:
bool true if the component is found, otherwise false

static void VCF::Component::clearRegistedComponents ( ) [static]

static Component* VCF::Component::createComponentFromResources ( Class * clazz,

Class * rootClazz,

ResourceBundle * resBundle = NULL

) [static]

virtual void VCF::Component::destroy ( ) [protected, virtual]

called by the free() method.
Should be overriden and any clean up code performed here
Reimplemented from VCF::Object.
Reimplemented in VCF::ComboBoxControl, VCF::Control, VCF::Frame, VCF::ListBoxControl, VCF::Menu, VCF::MenuBar, VCF::PopupMenu, VCF::SystemTray, and VCF::Window.

Component* VCF::Component::findComponent ( const String & componentName,

const bool & recursive = false

)

finds a particular component as specified by the componentName parameter within the list of owned components.

Parameters:

String the name of the component to look for

Returns:
Component a pointer to the Component with a matching name to componentName. If no match is found or the component has no owned components, the return value is NULL.

Action* VCF::Component::getAction ( ) [inline]

Returns the Action associated with this component.
Any component can have an action associated with it. This allows multiple component components (like a menu item, and a push button) to share the same action and to respond in a coordinated manner to changes in state.

static Enumerator<Class*>* VCF::Component::getComponentClassesForCategory ( const String & category ) [static]

Used by IDE's to list the various Component classes for a given category.
Each Class pointer that is contained in the Enumerator guarantees the ability to create an instance of the component it represents.

virtual uint32 VCF::Component::getComponentCount ( ) [virtual]

returns the number of components owned by this component

virtual Enumerator<Component*>* VCF::Component::getComponents ( ) [virtual]

returns an enumeration of all the component's that this component currently owns.

uint32 VCF::Component::getComponentState ( )

returns the current state of the component.
Some states will prevent the Component from responding to events, for example, a Control with it's state set to CS_DESIGNING, will not respond to certain UI events, while a Control with it's state set to CS_DESTROYING, will not respond to any pending UI events.

virtual String VCF::Component::getName ( ) [virtual]

The name of the component.
While technically the name can be any character sequence, it is preferred if the name follow C++ variable name rules, i.e. must start with a character of [a..z] or [A..Z], followed by any sequence of characters in the set [a..z,A..Z,0..9,_]. The name of the component should be unique.
Returns:
String the name of the component.

Reimplemented in VCF::Document.

Component* VCF::Component::getOwner ( ) [inline]

Returns the owner of the component.
The owner (you could also think of this as the component's "parent") is responsible for destroying the component when the owner is destroyed.
See also:
addComponent()

Reimplemented in VCF::Dialog.

static Enumerator<String>* VCF::Component::getRegisteredComponentCategories ( ) [static]

returns a list of all the known, registered, component categories.
These in turn may be used to gather the classes for each category with a call to the getComponentClassesForCategory() static method.
See also:
Component::getComponentClassesForCategory()

ComponentSetting* VCF::Component::getSetting ( const String & name )

Returns a specific setting specified by the name argument.
The name is the key that is used to store the setting in the component's settings dictionary. This name may be completely different from the setting's value name.
See also:
ComponentSetting

Dictionary* VCF::Component::getSettings ( )

Returns the dictionary that holds this component's settings.
May return NULL. The default value for a component's settings is NULL, so if no settings have been assigned this will definitely return NULL.

int32 VCF::Component::getTag ( ) [inline]

returns the Component's tag value.
A Tag is borrowed from the NeXTStep idea of tags. A unique number is automatically associated with the component when it is created, but can be changed by the programmer. The following info is lifted directly from the NeXTSTEP docs. "Tags are integers that you use in your code to identify objects. They offer a convenient alternative to such methods of object identification as fetching an object's title. (What if the object't title changes while the application is running, or the object has no title?)"
Returns:
int32 the tag value of the Component

bool VCF::Component::getUseLocaleStrings ( )

Returns a value indicating whether or not the component will attempt to translate any text using the current thread's locale.
By default, this is true.
Returns:
bool A boolean value that indicates whether or not a lookup will be made based on the current thread's locale to translate any text that needs displaying. A value of true means the lookup will take place, a value of false means the lookup will be ignored.

virtual void VCF::Component::handleEvent ( Event * event ) [virtual]

generic handler method for events.
All UI events are sent here and then dispatched accordingly to a more specific event handler. If an Application class is present, then it is given a chance to "see" the event first before delegating it to the Component.
All events are dispatched by their type so it is important to correctly identify the event objects type if you would like it to be dispatched correctly. The method will call the appropriate component method, like afterCreate(), beforeDestroy(), etc.
Parameters:

Event based on the value returned by Event::getType(),

Reimplemented in VCF::Control, VCF::DefaultMenuItem, VCF::DropTarget, VCF::HeaderControl, VCF::ListViewControl, VCF::Menu, VCF::MenuBar, VCF::TableControl, VCF::TextControl, VCF::ToolbarItem, VCF::Toolbar, VCF::TreeControl, and VCF::Window.

static void VCF::Component::initComponent ( Component * instance,

Class * clazz,

Class * rootClazz,

ResourceBundle * resBundle = NULL

) [static]

Takes a valid component instance and initializes it from a VFF file that is assumed to be present in the programs resource bundle.

static void VCF::Component::initComponentRegistrar ( ) [static]

virtual void VCF::Component::initializeSettings ( const bool & recursive ) [virtual]

bool VCF::Component::isCreated ( ) const

queries the component state to check if it's set to csCreated or not.

Returns:
bool true if component state is csCreated, otherwise false

bool VCF::Component::isDesigning ( ) const

queries the component state to check if it's csDesigning bit is set or not.

Returns:
bool true if component state includes csDesigning otherwise false

bool VCF::Component::isDestroying ( ) const

queries the component state to check if it's set to csDestroying or not.

Returns:
bool true if component state is csDestroying, otherwise false

bool VCF::Component::isLoading ( ) const

queries the component state to check if it's csLoading bit is set or not.

Returns:
bool true if component state includes csLoading, otherwise false

bool VCF::Component::isNormal ( ) const

queries the component state to check if it's set to csNormal or not.

Returns:
bool true if component state is csNormal, otherwise false

bool VCF::Component::isSaving ( ) const

queries the component state to check if it's csSaving bit is set or not.

Returns:
bool true if component state includes csSaving otherwise false

void VCF::Component::loaded ( )

Fires an event to the ComponentLoaded delegate.
The csLoading bit is removed from the component's state.

void VCF::Component::loading ( )

This is called to make sure the csLoading bit is set in the component state.
Called by streams that read in a component object

static bool VCF::Component::registerComponent ( const String & componentClassName,

const String & category

) [static]

registers a component in the system component map.
The map is organized into a series of keys called categories, with 1 or more entries in each category. The UIToolkit registers the default ApplicationKit components, and other developers may use this to extend the list with their own components.

virtual void VCF::Component::removeComponent ( Component * component ) [virtual]

removes the component.

void VCF::Component::removeFromOwner ( const bool & freeInstance = true )

void VCF::Component::removeFromUpdateList ( )

Removes the component from the framework's update list.

void VCF::Component::saved ( )

Fires an event to the ComponentSaved delegate.
The csSaving bit is removed from the component's state.

void VCF::Component::saving ( )

This is called to make sure the csSaving bit is set in the component state.
Called by streams that write out a component object

void VCF::Component::setAction ( Action * action )

Set's the action for the component.

void VCF::Component::setComponentState ( const uint32 & componentState )

Sets the component's state.

void VCF::Component::setCreated ( )

convenience fundtions for setting the component state

void VCF::Component::setDesigning ( const bool & designing )

void VCF::Component::setDestroying ( )

virtual void VCF::Component::setName ( const String & name ) [virtual]

sets the name of the component.
For naming conventions/rules please see getName().
Reimplemented in VCF::CommandButton, VCF::Document, VCF::Label, VCF::ProgressControl, VCF::PushButton, and VCF::ToggledButton.

void VCF::Component::setNormal ( )

void VCF::Component::setTag ( const int32 & tag ) [inline]

Sets the tag value.

Parameters:

int32 - represents the new value of the component's tag will be set to.

void VCF::Component::setUseLocaleStrings ( const bool & val )

Allows the user to control whether or not the component should attempt to translate the text of a specific component.
This is typically used in derived control classes paint() methods, which would check this value before calling System::getCurrentThreadLocale()->translate() to translate the text to a specific locale sensitive value. Setting this value will also set it for any child components.
Parameters:

bool A boolean value that indicates whether or not a lookup should be made based on the current thread's locale to translate any text that needs displaying. A value of true means the lookup should take place, a value of false means the lookup should be ignored.

See also:
Locale
System::getCurrentThreadLocale

virtual void VCF::Component::storeSettings ( const bool & recursive ) [virtual]

virtual bool VCF::Component::updateAction ( ) [virtual]

Calling this triggers an update event to be fired.
The default behaviour is to see if the component has an action associated with it, and then calls the action's update() method.
Returns:
bool the method returns true if the component has an action and the action's update() method is called. Otherwise it returns false.

See also:
Action::update()

Reimplemented in VCF::ToolbarItem.

Member Data Documentation

Action* VCF::Component::action_ [protected]

VCF::Delegate VCF::Component::ComponentAdded

<

VCF::Component Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation