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

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/FoundationKit/Component.h>

Inheritance diagram for VCF::Component:

VCF::ObjectWithCallbacks VCF::Object VCF::AbstractApplication VCF::AcceleratorKey VCF::Action VCF::Border VCF::CommonDialog VCF::Container VCF::Document VCF::DropTarget VCF::ImageList VCF::Model VCF::ScrollbarManager VCF::SystemTray VCF::TimerComponent VCF::UIComponent 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

void free ()
 Call this method to free up the memory of the class for heap based objects.
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 () const
 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.
virtual void preLoading ()
 Called when loading the component.
virtual void postLoaded (const bool &visible)
 Called after the component is done loading.
uint32 getComponentState () const
 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 addNewComponent (Component *component)
 Adds a brand new child component instance 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 () const
 returns the number of components owned by this component
virtual ComponentfindComponent (const String &componentName, const bool &recursive=false)
 finds a particular component as specified by the componentName parameter within the list of owned components.
virtual bool generatePropertyValue (const String &fullPropertyName, Property *property, VariantData *value, String &strValue)
virtual 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 () const
 returns the Component's tag value.
void setTag (const int32 &tag)
 Sets the tag value.
ComponentgetOwner () const
 Returns the owner of the component.
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 () const
 Returns a value indicating whether or not the component will attempt to translate any text using the current thread's locale.
DictionarygetSettings () const
 Returns the dictionary that holds this component's settings.
uint32 getSettingNames (std::vector< String > &names)
ComponentSettinggetSetting (const String &name) const
 Returns a specific setting specified by the name argument.
ComponentSettingassignSetting (const String &settingName, const String &valueName, const VariantData &v)
 Assigns a setting to the component's settings dictionary.
ComponentSettingassignSetting (const String &settingName, const String &valueName)
 Assigns a setting to the component's settings dictionary.
void setSetting (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 ComponentcreateComponentFromResources (Class *clazz, Class *rootClazz, ResourceBundle *resBundle=NULL)

Public Attributes

VCF::Delegate ComponentDelegate
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.
virtual void getAppNameAndKey (String &appName, String &key)

Protected Attributes

Componentowner_
uint32 componentState_
String name_
int32 tag_
std::vector< Component * > components_
EnumeratorContainer< std::vector<
Component * >, Component * > 
componentContainer_
Dictionarysettings_

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:

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.

virtual void VCF::Component::addNewComponent Component component  )  [virtual]
 

Adds a brand new child component instance to this component.

By default this simply calls addComponent(). Re-implemented in the Control class to also handle adding to the control's container as well. Used by the VFFInputStream class when loading component's up.

Reimplemented in VCF::Control.

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.

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.

virtual bool VCF::Component::bindVariable Component **  variablePtr,
const String variableName
[virtual]
 

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

Reimplemented in VCF::Control.

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 in VCF::ComboBoxControl, VCF::Control, VCF::Frame, VCF::ListBoxControl, VCF::Menu, VCF::MenuBar, VCF::PopupMenu, VCF::SystemTray, VCF::UIComponent, and VCF::Window.

virtual Component* VCF::Component::findComponent const String componentName,
const bool &  recursive = false
[virtual]
 

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.

Reimplemented in VCF::Control.

void VCF::Component::free  ) 
 

Call this method to free up the memory of the class for heap based objects.

Use this instead of calling the operator delete. For example:

    Component*  m = //get some component
    m->free();
This will ensure that the destroy() method is called before calling operator delete which allows a deriving class to override the destroy methods and safely call virtual methods from within it.

virtual bool VCF::Component::generatePropertyValue const String fullPropertyName,
Property property,
VariantData value,
String strValue
[virtual]
 

Reimplemented in VCF::CheckBoxControl, VCF::ComboBoxControl, VCF::CommandButton, VCF::StandardContainer, VCF::Control, VCF::HeaderControl, VCF::HorizontalLayoutContainer, VCF::ProgressControl, VCF::PushButton, VCF::RadioButtonControl, VCF::SliderControl, and VCF::TextControl.

virtual void VCF::Component::getAppNameAndKey String appName,
String key
[protected, virtual]
 

Reimplemented in VCF::Control.

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  )  const [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  )  const
 

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  )  const [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.

Component* VCF::Component::getOwner  )  const [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()

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  )  const
 

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

uint32 VCF::Component::getSettingNames std::vector< String > &  names  ) 
 

Dictionary* VCF::Component::getSettings  )  const
 

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  )  const [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  )  const
 

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::ImageList, VCF::ListBoxControl, VCF::ListControl, VCF::ListItem, VCF::ListViewControl, VCF::Menu, VCF::MenuBar, VCF::TabbedPages, VCF::TableControl, VCF::TextControl, VCF::ToolbarItem, VCF::Toolbar, VCF::TreeControl, VCF::TreeItem, VCF::TreeListControl, VCF::UIComponent, 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.

virtual void VCF::Component::postLoaded const bool &  visible  )  [inline, virtual]
 

Called after the component is done loading.

Control's will re-implement this and set their visible state to whatever the value of the visible parameter is.

Reimplemented in VCF::Control.

virtual void VCF::Component::preLoading  )  [inline, virtual]
 

Called when loading the component.

Control's will re-implement this and set their visible state to false.

Reimplemented in VCF::Control.

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::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::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::Label, VCF::LibraryApplication, VCF::ProgressControl, VCF::PushButton, and VCF::ToggledButton.

void VCF::Component::setNormal  ) 
 

void VCF::Component::setSetting const String settingName,
ComponentSetting setting
 

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]
 


Member Data Documentation

VCF::Delegate VCF::Component::ComponentAdded
 

EnumeratorContainer<std::vector<Component*>, Component*> VCF::Component::componentContainer_ [protected]
 

VCF::Delegate VCF::Component::ComponentCreated
 

VCF::Delegate VCF::Component::ComponentDelegate
 

Event Delegate:
ComponentCreated this is called when the component is created. This may be after the call to operator new to create the component instance.
event class: ComponentEvent
event type: Component::COMPONENT_CREATED

VCF::Delegate VCF::Component::ComponentDestroyed
 

VCF::Delegate VCF::Component::ComponentLoaded
 

VCF::Delegate VCF::Component::ComponentRemoved
 

std::vector<Component*> VCF::Component::components_ [protected]
 

VCF::Delegate VCF::Component::ComponentSaved
 

uint32 VCF::Component::componentState_ [protected]
 

String VCF::Component::name_ [protected]
 

Component* VCF::Component::owner_ [protected]
 

Reimplemented in VCF::Dialog.

std::vector<String>* VCF::Component::registeredCategory [static, protected]
 

EnumeratorContainer<std::vector<String>,String>* VCF::Component::registeredCategoryContainer [static, protected]
 

EnumeratorContainer<std::vector<Class*>,Class*>* VCF::Component::registeredCompContainer [static, protected]
 

std::map<String,std::vector<Class*>*>* VCF::Component::registeredComponentMap [static, protected]
 

a map of component classes to categories

Dictionary* VCF::Component::settings_ [mutable, protected]
 

int32 VCF::Component::tag_ [protected]
 


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