OpenCMISS-Zinc C++ API Documentation
Public Member Functions | Protected Attributes | List of all members
OpenCMISS::Zinc::Region Class Reference

A hierarchical block/namespace owning domains and fields. More...

#include <region.hpp>

Public Member Functions

 Region (cmzn_region_id in_region_id)
 
 Region (const Region &region)
 
Regionoperator= (const Region &region)
 
bool isValid () const
 
cmzn_region_id getId () const
 
int beginChange ()
 
int endChange ()
 
int beginHierarchicalChange ()
 
int endHierarchicalChange ()
 
Region createChild (const char *name)
 
Region createSubregion (const char *path)
 
Region createRegion ()
 
Fieldmodule getFieldmodule () const
 
int readFile (const char *fileName)
 
char * getName ()
 
int setName (const char *name)
 
Region getParent ()
 
Region getFirstChild ()
 
Region getNextSibling ()
 
Region getPreviousSibling ()
 
int appendChild (Region newChild)
 
int insertChildBefore (const Region &newChild, const Region &refChild)
 
int removeChild (const Region &oldChild)
 
Region findChildByName (const char *name)
 
Region findSubregionAtPath (const char *path)
 
bool containsSubregion (const Region &subregion)
 
int writeFile (const char *fileName)
 
Scene getScene ()
 
StreaminformationRegion createStreaminformationRegion ()
 
int read (const StreaminformationRegion &streaminformationRegion)
 
int write (const StreaminformationRegion &streaminformationRegion)
 

Protected Attributes

cmzn_region_id id
 

Detailed Description

A hierarchical block/namespace owning domains and fields.

A region represents a block of a hierarchical model. It owns a local set of domains and fields describing the model (each accessed from its fieldmodule), and a scene for building graphics to visualise the model. Each region has any number of uniquely named child regions, allowing tree-like models to be constructed.

Member Function Documentation

int OpenCMISS::Zinc::Region::appendChild ( Region  newChild)
inline

Adds new_child to the end of the list of child regions of this region. If the new_child is already in the region tree, it is first removed. Fails if new_child contains this region. Fails if new_child is unnamed or the name is already used by another child of this region.

Parameters
newChildThe child to add.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Region::beginChange ( )
inline

Begin caching or increment cache level for this region only. Call this function before making multiple changes to the region or its fields and objects via its field_module to minimise number of change messages sent to clients. Must call region end change method after making changes. Important: Do not pair with region end hierarchical change method! Note: region change caching encompasses field_module change caching so there is no need to call fieldmodule begin/end change methods as well. Can be nested.

See also
Region::endChange
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Region::beginHierarchicalChange ( )
inline

Begin caching or increment cache level for all regions in a tree, used to efficiently and safely make hierarchical field changes or modify the tree. Must call region end hierarchical_change method after modifications made. Can be nested. Important: Do not pair with non-hierarchical region end change method!

See also
Region::endHierarchicalChange
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
bool OpenCMISS::Zinc::Region::containsSubregion ( const Region subregion)
inline

Returns true if region is or contains the subregion.

Parameters
subregionThe region being tested for containment.
Returns
Boolean true if this region is or contains subregion, otherwise false.
Region OpenCMISS::Zinc::Region::createChild ( const char *  name)
inline

Create a child region with provided name in parent region. Fails if a child of that name exists already.

See also
Region::setName
Parameters
nameThe name for the new region.
Returns
Handle to new child region, or NULL/invalid handle on failure.
Region OpenCMISS::Zinc::Region::createRegion ( )
inline

Creates and returns a reference to a region compatible with base_region, i.e. able to exist in the same region tree.

See also
Context::createRegion
Returns
Handle to new region, or NULL/invalid handle on failure.
StreaminformationRegion OpenCMISS::Zinc::Region::createStreaminformationRegion ( )
inline

Creates a stream information object for specifying files/resources and options for reading and writing field data to/from this region and child regions.

Returns
Handle to new stream information, or NULL/invalid handle on failure.
Region OpenCMISS::Zinc::Region::createSubregion ( const char *  path)
inline

Create a region at the specified relative path, creating any intermediary regions if required. Fails if a subregion exists at that path already.

Parameters
pathRegion path, a series of valid region names separated by a forward slash "/". Leading and trailing separator slashes are optional.
Returns
Handle to new subregion, or NULL/invalid handle on failure.
int OpenCMISS::Zinc::Region::endChange ( )
inline

Decrement cache level or end caching of changes for this region only. Call region begin change method before making multiple field or region changes and call this afterwards. When change level is restored to zero in region, cached change messages are sent out to clients. Important: Do not pair with region begin hierarchical change method!

See also
Region::beginChange
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
int OpenCMISS::Zinc::Region::endHierarchicalChange ( )
inline

Decrement cache level or end caching of changes for all regions in a tree. Call region begin hierarchical change method before making hierarchical field changes or modifying the region tree, and call this afterwards. When change level is restored to zero in any region, cached change messages are sent out. Important: Do not pair with non-hierarchical region begin change method!

See also
Region::beginHierarchicalChange
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
Region OpenCMISS::Zinc::Region::findChildByName ( const char *  name)
inline

Finds child region with supplied name, if any.

Parameters
nameThe name of the child.
Returns
Handle to child region, or NULL/invalid handle if not found or failed.
Region OpenCMISS::Zinc::Region::findSubregionAtPath ( const char *  path)
inline

Returns a handle to the subregion at the path relative to this region. The format of the path string is CHILD_NAME/CHILD_NAME/... i.e. forward slash characters '/' are used as parent/child name separators. Single leading and trailing separator characters are ignored. Hence, both name="" and name="/" find the region itself.

Parameters
pathThe directory-style path to the subregion.
Returns
Handle to subregion, or NULL/invalid handle if not found or failed.
Fieldmodule OpenCMISS::Zinc::Region::getFieldmodule ( ) const
inline

Get field module which manages this region's fields, which must be passed to field factory create methods.

Returns
Handle to field module, or NULL/invalid handle on failure.
Region OpenCMISS::Zinc::Region::getFirstChild ( )
inline

Returns a handle to the first child region of this region.

Returns
Handle to first child region, or NULL/invalid handle if none or failed.
cmzn_region_id OpenCMISS::Zinc::Region::getId ( ) const
inline

Return the C handle of the Region object.

Returns
C handle of Region if this objects is valid, 0 otherwise.
char* OpenCMISS::Zinc::Region::getName ( )
inline

Returns the name of the region.

Returns
On success: allocated string containing region name. Up to caller to free using cmzn_deallocate().
Region OpenCMISS::Zinc::Region::getNextSibling ( )
inline

Returns a reference to this region's next sibling region.

Returns
Handle to next sibling region, or NULL/invalid handle if none or failed.
Region OpenCMISS::Zinc::Region::getParent ( )
inline

Returns a handle to the parent region of this region.

Returns
Handle to parent region, or NULL/invalid handle if none or failed.
Region OpenCMISS::Zinc::Region::getPreviousSibling ( )
inline

Returns a reference to this region's previous sibling region.

Returns
Handle to previous sibling region, or NULL/invalid handle if none or failed.
Scene OpenCMISS::Zinc::Region::getScene ( )
inline

Return handle to the scene for this region, which contains graphics for visualising fields in the region.

Parameters
cmiss_regionThe region of query.
Returns
Handle to scene, or NULL/invalid handle on failure.
int OpenCMISS::Zinc::Region::insertChildBefore ( const Region newChild,
const Region refChild 
)
inline

Inserts new_child before the existing ref_child in the list of child regions of this region. If ref_child is NULL new_child is added at the end of the list. If the new_child is already in the region tree, it is first removed. Fails if new_child contains this region. Fails if new_child is unnamed or the name is already used by another child of this region.

Parameters
newChildThe child to append.
Returns
Status OpenCMISS::Zinc::OK on success, any other value on failure.
bool OpenCMISS::Zinc::Region::isValid ( ) const
inline

Check if this is a valid Region object.

Returns
Status True if object is valid, false otherwise.
int OpenCMISS::Zinc::Region::read ( const StreaminformationRegion streaminformationRegion)
inline

Reads region data using stream resource objects provided in the stream information object.

See also
Streaminformation
Parameters
streaminformationRegionHandle to the stream information region containing information about resources to read from.
Returns
Status OpenCMISS::Zinc::OK if data successfully read and merged into specified region, any other value on failure.
int OpenCMISS::Zinc::Region::readFile ( const char *  fileName)
inline

Convenient function to read a file with the provided name into a region directly.

Parameters
fileNamename of the file to read from.
Returns
Status OpenCMISS::Zinc::OK if data successfully read and merged into specified region, any other value on failure.
int OpenCMISS::Zinc::Region::removeChild ( const Region oldChild)
inline

Removes old_child from the list of child regions of this region. Fails if old_child is not a child of this region.

Parameters
oldChildThe child to remove.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Region::setName ( const char *  name)
inline

Sets the name of the region. Any name is valid as long as it is unique in the parent region, however use of forward slash characters '/' in names is discouraged since it prevent regions being found by paths.

Parameters
nameThe new name for the region.
Returns
Status OpenCMISS::Zinc::OK on success, otherwise OpenCMISS::Zinc::ERROR_ARGUMENT.
int OpenCMISS::Zinc::Region::write ( const StreaminformationRegion streaminformationRegion)
inline

Writes region data to stream resource objects described in the stream information object.

Parameters
streaminformationRegionHandle to the stream information region containing information about resources to write to.
Returns
Status OpenCMISS::Zinc::OK if data is successfully written out, any other value on failure.
int OpenCMISS::Zinc::Region::writeFile ( const char *  fileName)
inline

Convenient function to write the region into a file with the provided name.

Parameters
fileNamename of the file to write to..
Returns
Status OpenCMISS::Zinc::OK if data is successfully written out, any other value otherwise.

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