The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page

VCF::Object Class Reference

Base class for the entire Visual Component Framework. More...

#include <vcf/FoundationKit/Object.h>

Inheritance diagram for VCF::Object:

List of all members.

Public Member Functions
	Object ()
virtual	~Object ()
void	init ()
	This is going to be removed from the bext release.
void	free ()
	Call this method to free up the memory of the class for heap based objects.
virtual uint32	addRef (Object *owner=NULL)
	increments the reference count of the object
virtual uint32	release (Object *owner=NULL)
	decrements the reference count of the object
uint32	getRefCount ()
	returns the number of outstanding references for this object
virtual String	toString ()
	returns a string representation of the object
String	getClassName ()
	returns the class name of the object.
virtual bool	isEqual (Object *object) const
	This determines if object is equal to this the equivalent of operator ==().
virtual void	copy (Object *source)
	Copies the data from source to this object.
virtual Object *	clone (bool deep=false)
	Makes a complete clone of this object.
Class *	getClass ()
	returns the RTTI Class instance associated object of this type
virtual uintptr	hash ()
	returns a hash value that represents the object instance
Static Public Member Functions
static void	trackDebugMemory (const bool &trackMemory)
	indicates whether or not debug memory should be tracked.
static bool	isDebugMemoryTracked ()
	returns whether or not debug memory tracking is on
static uint32	objectAllocationCount ()
	returns the total number of objects currently allocated.
Protected Member Functions
virtual void	destroy ()
	called by the free() method.
Protected Attributes
uint32	refCount_

---

Detailed Description

Base class for the entire Visual Component Framework.

New as of July 5,2001, Object will also support refcounting for those who need this kind of support. There are several places in the ApplicationKit that will need to make use of this fairly soon.

Also Object supports a new technique for destroying Object derived instances. In general, in C++, when creating a destroying an object instance on the heap (free-store) you would use the operator delete() function. This is being phased out in the VCF for a variety of reasons, in favor of a different scheme. Destroying the memory now happens in two ways: The first is the equivalent of the operator delete() call. This involves calling the objects free() method, which will call the virtual destroy() method before calling operator delete() on itself; The second way an object can be destroyed is if it's refcount drops to 0, at which point the object's free() method will be invoked. Calling the object's release() method decrements the reference count on the object. By default if an object is created on the heap via new, and no one addref()'s it, then a single call to the release() method will free up it's memory.

Object::destroy() is a virtual method, where common shared cleanup may take place. Because this is called before the delete() method, it is still safe to call virtual methods and have them execute correctly (in C++ virtual calls inside of a constructor or destructor are not allowed and if made then the behaviour is undefined).

Classes which are heap based (such as all of the UI classes that derive from Component) should define their destructor as having protected access. In addition the majority of the cleanup code should be placed in the overridden Object::destroy() method as opposed to the class destructor. Anything that requires method calls to other object or the class itself (particularly if the method is a virtual one) should be moved to the

Semantics of the addRef/release usage are as follows: An object's refcount indicates "ownership " of the object. In other words, the "owner" of the object is responsible for releasing it's hold on the object, thus decrementing the objects refcount, which, when reduced to 0, causes the object to be deleted. This is also known as a strong reference to an object, as opposed to a weak reference where the "owner" doesn't claim any responsibility over the object.

Note that this whole scheme is aimed at heap based objects. Many objects that are created on the stack do not need this. For example, common utility objects like Rect or Point do not need this - they can be created on the stack.

---

Constructor & Destructor Documentation

VCF::Object::Object (   )

virtual VCF::Object::~Object (   )  [virtual]

---

Member Function Documentation

virtual uint32 VCF::Object::addRef (  Object *  owner = NULL  )  [virtual]

increments the reference count of the object Parameters: Object*  the optional owner of the new referenced object for use in future, more sophisticated refcounting schemes Returns: uint32 the current reference count of the object

virtual Object* VCF::Object::clone (  bool  deep = false  )  [inline, virtual]

Makes a complete clone of this object. A typical implementation might be: virtual Object* clone( bool deep ) { return new MyObject( this ); } In which the implementer simply creates a new instance on the heap and calls the copy constructor. Objects which support cloning should also have a copy constructor defined as well. Parameters: bool  deep if deep is true then any object instances that this object owns should probably be cloned as well, with full new copies made. Otherwise it would be acceptable to simply copy the pointer values. The default value is for deep cloning to be false. Returns: Object a new instance that should be an copy of this. If the object doesn't support cloning the return will value will be NULL. Reimplemented in VCF::AcceleratorKey, VCF::ActionEvent, VCF::ButtonEvent, VCF::ClipboardEvent, VCF::ColumnItemEvent, VCF::ColumnModelEvent, VCF::ComponentEvent, VCF::ControlEvent, VCF::DefaultMenuItem, VCF::DialogEvent, VCF::DragSourceEvent, VCF::DropTargetEvent, VCF::FocusEvent, VCF::FrameEvent, VCF::HelpEvent, VCF::ImageListEvent, VCF::ItemEditorEvent, VCF::ItemEvent, VCF::KeyboardEvent, VCF::ListModelEvent, VCF::MenuItemEvent, VCF::ModelEvent, VCF::MouseEvent, VCF::ScrollEvent, VCF::TableModelEvent, VCF::TabModelEvent, VCF::TextEvent, VCF::TimerEvent, VCF::ToolTipEvent, VCF::TreeModelEvent, VCF::UndoRedoEvent, VCF::ValidationEvent, VCF::WhatsThisHelpEvent, VCF::WindowEvent, VCF::Dictionary, VCF::Event, VCF::NotifyEvent, VCF::OutputReadyEvent, VCF::PropertyChangeEvent, VCF::ThreadEvent, VCF::Color, VCF::Font, VCF::ImageEvent, VCF::PrintEvent, VCF::HTMLAuthenticationEvent, VCF::HTMLEvent, VCF::HTMLElementEvent, VCF::URLAuthenticationEvent, and VCF::URLEvent.

virtual void VCF::Object::copy (  Object *  source  )  [inline, virtual]

Copies the data from source to this object. This is the equivalent of operator=() Reimplemented in VCF::Color, VCF::Font, and VCF::Matrix2D.

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

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

void VCF::Object::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: Mutex* m = new Mutex(); 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.

Class* VCF::Object::getClass (   )

returns the RTTI Class instance associated object of this type

String VCF::Object::getClassName (   )

returns the class name of the object.

uint32 VCF::Object::getRefCount (   )  [inline]

returns the number of outstanding references for this object

virtual uintptr VCF::Object::hash (   )  [virtual]

returns a hash value that represents the object instance

void VCF::Object::init (   )

This is going to be removed from the bext release. Deprecated: Reimplemented in VCF::AbstractContainer, VCF::AbstractWin32Component, VCF::Application, VCF::ComboBoxControl, VCF::ControlContainer, VCF::ControlGraphicsContext, VCF::CustomControl, VCF::DataObject, VCF::DefaultColumnModel, VCF::DefaultListItem, VCF::DefaultMenuItem, VCF::DefaultTreeItem, VCF::DefaultTreeModel, VCF::GTKFileOpenDialog, VCF::ImageList, VCF::ListBoxControl, VCF::ListViewControl, VCF::MenuBar, VCF::OSXDialog, VCF::Panel, VCF::PopupMenu, VCF::Splitter, VCF::TabbedPages, VCF::TableControl, VCF::TextControl, VCF::TreeControl, VCF::TreeListControl, VCF::UIShell, VCF::UIToolkit, VCF::Win32FileOpenDialog, VCF::Win32FileSaveDialog, VCF::Win32Object, VCF::Win32Tree, VCF::X11Context, VCF::X11Font, VCF::X11Image, VCF::Event, VCF::FileStreamBase, VCF::Library, VCF::MemoryStream, VCF::GraphicsContext, VCF::GTKContext, VCF::GTKFont, VCF::GTKGraphicsToolkit, VCF::GTKImage, VCF::ImageEvent, VCF::OSXContext, VCF::OSXFont, VCF::OSXImage, VCF::Point, VCF::Size, VCF::Win32Context, VCF::Win32FontManager, VCF::Win32Image, VCF::Win32GrayScaleImage, VCFNet::Socket, and VCF::OpenGLControlContext.

static bool VCF::Object::isDebugMemoryTracked (   )  [static]

returns whether or not debug memory tracking is on Returns: bool true if debug memory tracking is turned on, otherwise false

virtual bool VCF::Object::isEqual (  Object *  object  )  const [inline, virtual]

This determines if object is equal to this the equivalent of operator ==(). Reimplemented in VCF::Matrix2D.

static uint32 VCF::Object::objectAllocationCount (   )  [static]

returns the total number of objects currently allocated. Only meaningful for _DEBUG builds with memory tracking turned on. Returns: uint32 if debug memory tracking is turned on, and the _DEBUG symbol is defined, then this value will be the total count of object instances that are currently allocated. For any other conditions it will return 0.

virtual uint32 VCF::Object::release (  Object *  owner = NULL  )  [virtual]

decrements the reference count of the object Parameters: Object*  the optional owner of the new referenced object for use in future, more sophisticated refcounting schemes when the refCount_ drops to 0 the object is destroyed

virtual String VCF::Object::toString (   )  [virtual]

returns a string representation of the object Reimplemented in VCF::AbstractWin32Component, VCFCOM::DataRendering, VCF::DateTime, VCF::XMLAttr, VCF::XMLNode, VCF::Color, VCF::Size, VCFNet::Socket, VCFRemote::ClassRegistryEntry, and VCFRemote::InstanceID.

static void VCF::Object::trackDebugMemory (  const bool &  trackMemory  )  [static]

indicates whether or not debug memory should be tracked. Note that debug memory is tracked only in debug builds (meaning the VCF has been compiled with the _DEBUG symbol defined). Memory tracking is turned off for release builds. Parameters: bool  if this is true, then memory will be tracked, and when the FoundationKit::terminate() is called, the system will check how many outstanding objects (i.e. any class instance that derives from VCF::Object directly or indirectly) there are. It will then perform a diagnostic dump, displaying the memory address and the class name of the object instance

---

Member Data Documentation

uint32 VCF::Object::refCount_ [protected]

---

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

• vcf/FoundationKit/Object.h

Comments or Suggestions?    License Information