IlvStIAccessor Class Reference

Inspector class. More...

#include <ivstudio/inspectors/genacces.h>

Inheritance diagram for IlvStIAccessor:

List of all members.

Public Types
enum	BuildMode { , Create, Copy }
	This enumeration type defines the build mode of the inspected properties. More...
enum	DependencyMode {   InitializeAfter, InitializeBefore, ApplyBefore, ApplyAfter,   NoApply, Default, InitializeAndApplyBefore }
	This enumeration type specifies when the dependent accessor is initialized and applied. properties. More...
enum	UpdateMode { NoUpdate, OnApply, Immediate, Inherited }
	This enumeration type specifies when the accessor must update the inspected property. The provided modes are mutually exclusive. More...
Public Member Functions
void	addDependentAccessor (IlvStIAccessor *acc, DependencyMode mode=Default)
	Adds a dependent accessor with the specified dependency mode.
void	addEditor (IlvStIEditor *edt)
	Adds the specified editor to the editors stored by the accessor.
virtual IlBoolean	apply ()
	Called to apply all the changes made to the accessor.
virtual IlvStIError *	check () const
	Validates the accessor value.
virtual IlvStIError *	checkAll (const IlvStIAccessor **accessor, IlBoolean modifiedOnly=IlTrue) const
	Checks the accessor and its hierarchical tree of dependencies.
IlvStIAccessor *	findDependentAccessor (const char *name) const
	Searches an dependent accessor.
IlvStIEditor *	findEditor (const char *name) const
	Searches the specified editor inside all dependent accessors.
virtual IlvStIEditor *	findFirstEditor () const
	Returns the first editor owned by the accessor.
BuildMode	getBuildMode () const
	Returns the building mode for the accessor.
IlvStIAccessor *	getDependentAccessor (const char *name) const
	Returns the dependent accessor whose name is specified.
IlvStIAccessor **	getDependentAccessors (IlUInt &count) const
	Returns all direct dependent accessors.
IlvStIEditor *	getEditor (IlUInt index) const
	Returns the editor stored at the wished position.
IlUInt	getNumberOfEditors () const
	Returns the number of editors stored by the accessor.
virtual UpdateMode	getUpdateMode () const
	Returns the update mode for the accessor.
virtual IlBoolean	initialize ()
	Called to initialize the accessor according to the inspected data.
IlBoolean	isModified () const
	Returns IlTrue if the accessor has been modified.
void	lock ()
	Locks the accessor once.
IlBoolean	removeDependentAccessor (IlvStIAccessor *acc)
	Removes the specified dependent accessor.
IlBoolean	removeEditor (IlvStIEditor *edt)
	Removes the specified editor from the accessor.
void	setBuildMode (BuildMode mode)
	Sets the building mode for the accessor.
void	setUpdateMode (UpdateMode updateMode)
	Sets the update mode for the accessor.
void	unLock ()
	Unlocks the accessor once.
Protected Member Functions
	IlvStIAccessor (const char *name=0, UpdateMode mode=NoUpdate, BuildMode build=None)
	Initializes a new instance of the IlvStIAccessor class.

---

Detailed Description

Inspector class.

Library: ivstudio

An accessor can be considered as an interface to an object to be inspected. Usually,an accessor that inherits from the class IlvStIPropertyAccessor lets you access a property of a given object, such as the label of a text field.
From a functional point of view, an accessor has two behaviors:

• It initializes itself (via the initialize method).

• It applies modifications that have been made to inspected objects (via the apply method).

In other words, when an inspector is initialized to inspect a new object and when the Apply button is clicked, it calls the initialize and the apply methods of all its accessors.
Certain inspected values directly depend on other inspected values. Thus, if the float mode is not set for a number field, the scientific mode for this field cannot be inspected and its editors must be grayed. To achieve this, accessors are stored in a hierarchical tree of dependencies. Accessors are initialized from root to branches. When an accessor is modified, all its dependencies are reinitialized. Thus, in our previous example, the scientific mode accessor is stored as a child of the float mode accessor (via the member function IlvStIAccessor::addDependentAccessor). When the float mode is modified, the scientific mode is reinitialized automatically and its state is indicated by a precondition. For more information, see IlvStIPrecondition.
Because accessors can be shared by many other accessors (through dependencies, for example), deleting an accessor is not a safe operation. Therefore, an accessor must always be stored using a reference count mechanism (via a call to the lock and unLock methods).
Accessors manage the gadgets of an inspector panel via editors. These editors, which inherit from the class IlvStIEditor, provide a common interface for most of the gadget classes. Editors can be added to or removed from an accessor via the addEditor or removeEditor member functions so that, for example, more than one editor can edit the same property. Accessors initialize the editors when they are initialized (typically with the values of the inspected properties) and store the user's modifications notified by editors.
Two modes are provided for inspecting a property, an update mode and a building mode:

• The update mode specifies whether the accessor should apply modifications entered by the user immediately or wait for an explicit request, that is, when the user clicks Apply.

• When the building mode is set to BuildMode::Create, the accessor creates a property if the inspected object does not contain one. If BuildMode::Copy is set, it makes a copy of this property, which will be inspected in place of the original property. This is particularly useful if the accessor inspects a data pointer with UpdateMode set to OnApply.

See also:

IlvStIEditor, IlvStInspectorPanel, IlvStIProperty, IlvStIPropertyAccessor.

---

Member Enumeration Documentation

enum IlvStIAccessor::BuildMode

This enumeration type defines the build mode of the inspected properties.

Enumerator:

Create	The accessor builds the inspected property if this property cannot be found in the inspected object.
Copy	The accessor copies the inspected property before modifying it. This mode is especially useful when used in conjunction with the UpdateMode::OnApply mode.

enum IlvStIAccessor::DependencyMode

This enumeration type specifies when the dependent accessor is initialized and applied. properties.

Enumerator:

InitializeAfter	The dependent accessor is initialized after the accessor.
InitializeBefore	The dependent accessor is initialized before the accessor.
ApplyBefore	The dependent accessor applies modifications before the accessor does.
ApplyAfter	The dependent accessor applies modifications after the accessor does.
NoApply	The dependent accessor does not apply modifications.
Default	Combines the InitializeAfter and the ApplyBefore modes.
InitializeAndApplyBefore	Combines the InitializeBefore and the ApplyBefore modes.

enum IlvStIAccessor::UpdateMode

This enumeration type specifies when the accessor must update the inspected property. The provided modes are mutually exclusive.

Enumerator:

NoUpdate	No update is performed.
OnApply	The update is performed only when the apply method is explicitly called.
Immediate	The update is carried out as soon as the accessor is notified of the changes.
Inherited	The current mode is that of the accessor on which this accessor depends, if any.

---

Constructor & Destructor Documentation

IlvStIAccessor::IlvStIAccessor	(	const char *	name = 0,
		UpdateMode	mode = NoUpdate,
		BuildMode	build = None
	)			[protected]

Initializes a new instance of the IlvStIAccessor class.

Parameters:

	name	The name of the accessor used to reference this accessor from the inspector by calling the getAccessor method.
	mode	The update mode.
	build	The build mode.

---

Member Function Documentation

void IlvStIAccessor::addDependentAccessor	(	IlvStIAccessor *	acc,
		DependencyMode	mode = Default
	)

Adds a dependent accessor with the specified dependency mode.

Parameters:

	acc	The dependent accessor.
	mode	The dependency mode.

void IlvStIAccessor::addEditor

(

IlvStIEditor *

edt

)

Adds the specified editor to the editors stored by the accessor.

Parameters:

edt

The editor.

virtual IlBoolean IlvStIAccessor::apply

(

)

[virtual]

Called to apply all the changes made to the accessor.

Called to apply all the changes made to the accessor to the inspected object. By default, this method only requests that modifications be applied by its dependent accessors.

Returns:

IlTrue if successfull, otherwise return IlFalse.

virtual IlvStIError* IlvStIAccessor::check

(

)

const [virtual]

Validates the accessor value.

Returns:

An error if the current inspected value of the accessor is not available. Otherwise, it returns 0.

Reimplemented in IlvStIPropertyAccessor.

virtual IlvStIError* IlvStIAccessor::checkAll	(	const IlvStIAccessor **	accessor,
		IlBoolean	modifiedOnly = IlTrue
	)			const [virtual]

Checks the accessor and its hierarchical tree of dependencies.

Parameters:

	accessor	Contains the accessor which failed.
	modifiedOnly	If IlTrue, the check is run only on accessors that have been modified.

Returns:

An error if the check failed for one of the accessors in the hierarchical tree of dependencies that contains this accessor. Otherwise, it returns 0.

IlvStIAccessor* IlvStIAccessor::findDependentAccessor

(

const char *

name

)

const

Searches an dependent accessor.

Parameters:

name

The accessor name which is searching in the hierarchical tree of dependencies.

Returns:

0 if no dependent accessor with the specified name is found otherwise returns the accessor.

IlvStIEditor* IlvStIAccessor::findEditor

(

const char *

name

)

const

Searches the specified editor inside all dependent accessors.

Parameters:

name

The editor name.

Returns:

The editor, however it returns 0 if no editor with the specified name is found.

virtual IlvStIEditor* IlvStIAccessor::findFirstEditor

(

)

const [virtual]

Returns the first editor owned by the accessor.

Returns:

The first editor owned by the accessor, if any. Otherwise, it returns the first editor found in the nearest dependent accessor. For example, if calling the check method generates an error, you can use this function to find the editor associated with the checked accessor and give it the focus so that the user can modify it. It returns 0 if no editors with the specified name is found.

Reimplemented in IlvStIPropertiesAccessor.

BuildMode IlvStIAccessor::getBuildMode

(

)

const

Returns the building mode for the accessor.

Returns:

The building mode for the accessor.

IlvStIAccessor* IlvStIAccessor::getDependentAccessor

(

const char *

name

)

const

Returns the dependent accessor whose name is specified.

Parameters:

name

The accessor name.

Returns:

The dependent accessor whose name is specified.

IlvStIAccessor** IlvStIAccessor::getDependentAccessors

(

IlUInt &

count

)

const

Returns all direct dependent accessors.

Parameters:

count

Contains the accessor count.

Returns:

The accessors list.

IlvStIEditor* IlvStIAccessor::getEditor

(

IlUInt

index

)

const

Returns the editor stored at the wished position.

Parameters:

index

The editor position.

Returns:

Returns the editor stored at index index if found, otherwise it returns 0.

IlUInt IlvStIAccessor::getNumberOfEditors

(

)

const

Returns the number of editors stored by the accessor.

Returns:

The number of editors stored by the accessor.

virtual UpdateMode IlvStIAccessor::getUpdateMode

(

)

const [virtual]

Returns the update mode for the accessor.

Returns:

The update mode for the accessor.

Reimplemented in IlvStICombinedAccessor.

virtual IlBoolean IlvStIAccessor::initialize

(

)

[virtual]

Called to initialize the accessor according to the inspected data.

By default, this method only initializes all dependent accessors.

Returns:

IlTrue if successfull, otherwise return IlFalse.

Reimplemented in IlvStIPropertyAccessor, IlvStICombinedAccessor, and IlvStIPropertiesAccessor.

IlBoolean IlvStIAccessor::isModified

(

)

const

Returns IlTrue if the accessor has been modified.

Returns:

IlTrue if the accessor has been modified since the last call to initialize or apply. When apply is called, the accessor does nothing if it has not been modified.

void IlvStIAccessor::lock

(

)

Locks the accessor once.

Call this method if you want this object to be shared by different objects.

IlBoolean IlvStIAccessor::removeDependentAccessor

(

IlvStIAccessor *

acc

)

Removes the specified dependent accessor.

Parameters:

acc

The dependent accessor.

Returns:

IlFalse if the specified accessor does not depend on this accessor, otherwise returns IlTrue.

IlBoolean IlvStIAccessor::removeEditor

(

IlvStIEditor *

edt

)

Removes the specified editor from the accessor.

Parameters:

edt

The editor which must be removed from the editors stored by the accessor.

Returns:

IlTrue if successfull otherwise returns IlFalse.

void IlvStIAccessor::setBuildMode

(

BuildMode

mode

)

Sets the building mode for the accessor.

Parameters:

mode

The new build mode.

void IlvStIAccessor::setUpdateMode

(

UpdateMode

updateMode

)

Sets the update mode for the accessor.

Parameters:

updateMode

The new update mode.

void IlvStIAccessor::unLock

(

)

Unlocks the accessor once.

The accessor is destroyed when it is no longer locked.