AlLayer

An interface to Alias layer objects.

Synopsis

#include <AlLayer.h>
class AlLayer : public AlObject
enum AlLayerPickType {
        kLayerPickable,
        kLayerReference,
        kLayerInactive
};
    AlLayer();
virtual    ~AlLayer();
virtual AlObject*    copyWrapper() const;
virtual statusCode    deleteObject();
virtual AlObjectType    type() const;

boolean isFolder() const;
AlLayer* childLayer() const;
AlLayer* parentLayer() const;
AlLayer* nextLayer() const;
AlLayer* prevLayer() const;

statusCode    create(const char * = NULL);
statusCode    create(int&, const char * = NULL);
statusCode    create(int);

statusCode createFolder(const char * = NULL);
statusCode createFolder(int&, const char * = NULL);

statusCode assignChild(int);
statusCode assignParent(int);
statusCode assignSiblingOnRight(int);
statusCode assignSiblingOnLeft(int);

boolean    invisible() const;
statusCode    setInvisible( boolean );

int    number() const;

const char *    name() const;
statusCode    setName( const char * );

statusCode    pickability( AlLayerPickType& ) const;
statusCode    setPickability( AlLayerPickType );

boolean    playback() const;
statusCode    setPlayback( boolean );

boolean    drawInstances() const;
statusCode    setDrawInstances( boolean );

boolean    visibleInLayerBar() const;
statusCode    setVisibleInLayerBar( boolean );

int    color() const;  //obsolete
statusCode    setColor( int );  //obsolete

statusCode    setCustomColor( unsigned char, unsigned char, unsigned char, unsigned char );
statusCode    customColor( unsigned char &, unsigned char &, unsigned char &, unsigned char & ) const;

boolean    isPicked() const;
statusCode    pick();
statusCode    unpick();

static boolean    startNumber();
static statusCode    setStartNumber( boolean );

// Symmetric layer support
statusCode    setSymmetric( boolean );
boolean    isSymmetric() const;    

statusCode    setSymmetricOrigin( double, double, double );
statusCode    setSymmetricNormal( double, double, double );
statusCode    symmetricOrigin( double&, double&, double& );
statusCode    symmetricNormal( double&, double&, double& );
statusCode    pickNodesOnLayer();

Description

Layers provide a way of organizing models to improve the workflow. The layers have attributes such as visibility and pickability that apply to all the DAG nodes which refer to them. The AlDagNode has methods to get the AlLayer it is in and set to a new AlLayer.

Each AlLayer has a unique identifying number and a name. By default, the layer gets the unique name based on its number; however, the user is free to change it to any name. Layer names provided by the user do not have to be unique.

The types of layers are:

Default Layer: There is always a default layer in the AlUniverse with a number 0. Its attributes can never be changed. Any object of a class derived from the AlDagNode class can be assigned to an AlLayer.
Creation Layer: Any new AlDagNode is automatically assigned to the creation layer. Any existing layer can be made into the creation layer, including the default layer. When a layer is made a creation layer, its attributes such as invisibility temporarily become ineffective and it gets the same attributes as the default layer. These attributes become effective again, as soon as another layer is made a creation layer.

A DAG node (AlDagNode) can be transferred from one layer to another but can exist on only one layer at a time. When an AlDagNode is assigned to a non-default layer:

all of its children are assigned to the non-default layer
all the parents are assigned to the default layer
all instances of the AlDagNode are also assigned to the same layer
siblings of the AlDagNode remain unaffected.

All attributes in an AlLayer can be obtained and set with the methods in this class. By default, all the layers have a corresponding menu in the Alias interface and are visible in the layer bar in the Alias interface. However, if you want to work with a partial list of layers you can make them visible using the visibleInLayerBar() method. The change in visibility in the layer bar does not change the other attributes of the AlLayer.

All existing layers in an AlUniverse can be accessed through methods in AlUniverse. The layer functionality can be temporarily disabled through the static method setLayersEnabled() in the AlUniverse class. When the layer functionality is disabled or turned off, all the layer attributes temporarily become similar to the default layer. However, the layer references of the AlDagNode are not changed.

Symmetric layers are also supported in the API. Methods available allow the developer to turn symmetric layers on, find out if a layer is symmetric, set/query the origin and normal parameters of the symmetric plane and create the symmetric geometry. Symmetric layers are specified by a normal and a point(origin).

Note: creation of symmetric geometry is done by the AlDagNode class. The complete layer interface is available in Open Model as well.

AlLayer::AlLayer(void)

Description

Constructs an AlLayer wrapper object.

AlLayer::~AlLayer()

Description

Deletes an AlLayer wrapper object.

statusCode AlLayer::deleteObject()

Description

This method deletes the layer.

Return Codes

sSuccess - the object was deleted

sInvalidObject - the locator was not valid

AlObject* AlLayer::copyWrapper() const

Description

Returns an exact copy of the AlLayer wrapper.

AlObjectType AlLayer::type() const

Description

Returns the class identifier kLayerType.

boolean AlLayer::isFolder() const

Description

Returns if the AlLayer is a folder (ture or false.

AlLayer* AlLayer::childLayer() const

Description

Returns the child layer below this layer in the graph of Alias AlLayer objects. NULL is returned if there is no child layer.

AlLayer* AlLayer::parentLayer() const

Description

Returns the parent layer above this layer in the graph of Alias AlLayer objects. NULL is returned if there is no parent layer.

AlLayer* AlLayer::nextLayer() const

Description

Returns the layer following this layer in the graph of Alias AlLayer objects. NULL is returned if there is no next layer.

AlLayer* AlLayer::prevLayer() const

Description

Returns the layer previous to this layer in the graph of Alias AlLayer objects. NULL is returned if there is no previous layer.

statusCode AlLayer::create( const char* name)

Description

Creates a new layer.

Arguments

> number - the number of the new layer

< name - the name of the new layer

Return Codes

sSuccess - the layer was created

sFailure - the layer was not created because either the maximum number of layers were already created or the layer functionality is turned off

sAlreadyCreated - the object has already been created

statusCode AlLayer::create( int& number, const char* name)

Description

Creates a new layer.

Arguments

> number - the number of the new layer

< name - the name of the new layer

Return Codes

sSuccess - the layer was created

sFailure - the layer was not created because either the maximum number of layers were already created or the layer functionality is turned off

sAlreadyCreated - the object has already been created

statusCode AlLayer::create( int number)

Description

Create a new layer with the given number

Arguments

> number - the number of the new layer

Return Codes

sSuccess - the layer was created

sFailure - the layer was not created because either the maximum number of layers had already created or the layer functionality is turned off.

sAlreadyCreated - object has already been created

statusCode AlLayer::createFolder( const char* name)

Description

Create a new layer folder

Arguments

< name - the name of the new layer folder

Return Codes

sSuccess - the layer folder was created

sFailure - the layer folder was not created because either the maximum number of layers were already created or the layer functionality is turned off.

sAlreadyCreated - object has already been created

statusCode AlLayer::createFolder( int& number, const char* name)

Description

Create a new layer folder

Arguments

> number - the number of the new layer folder

< name - the name of the new layer folder

Return Codes

sSuccess - the layer folder was created

sFailure - the layer folder was not created because either the maximum number of layers were already created or the layer functionality is turned off.

sAlreadyCreated - object has already been created

statusCode AlLayer::assignChild( int number)

Assigns layerID as a child of this layer.

Note: This layer must be a layer folder.

statusCode AlLayer::assignParent( int number)

Assigns layerID as the parent of this layer.

Note: This layerID must be a layer folder.

statusCode AlLayer::assignSiblingOnRight( int number)

Assigns layerID as a sibling on the right.

statusCode AlLayer::assignSiblingOnLeft( int number)

Assigns layerID as a sibling on the left.

boolean AlLayer::invisible() const

Description

Checks if the layer is invisible. Note that if an invisible layer is made the creation layer, it temporarily becomes visible while it is the creation layer.

Return Values

true - the layer is invisible

false - the layer is visible or the object is invalid or layer functionality is turned off

statusCode AlLayer::setInvisible(boolean invisible)

Description

Changes the visibility of the layer. If a creation layer is made invisible, the default layer becomes the creation layer.

Arguments

< invisible - a value of true makes the layer invisible and false makes it visible

Return Codes

sSuccess - the layer visibility attribute was set

sFailure - the attribute was not set (perhaps the layer functionality was turned off)

sInvalidObject - the object is not valid

statusCode AlLayer::pickability (AlLayerPickType& pickType) const

Description

Checks the pickability of the layer.

Arguments

> pickType - shows whether the layer is inactive, reference or pickable

Return Codes

sSuccess - the layer pickability attribute was found

sInvalidObject - the object is not valid.

statusCode AlLayer::setPickability (AlLayerPickType pickType)

Description

Changes the pickability of the layer. If a creation layer is made referenced or inactive, the default layer becomes the creation layer.

Arguments

< pickability - kLayerInactive makes the layer unpickable and unsnappable, kLayerReference makes the layer unpickable but snappable, and kLayerPickable makes the layer both pickable and snappable.

Return Codes

sSuccess - the layer pickability attribute was set

sFailure - the layers have been turned off

sInvalidObject - the object is not valid

int AlLayer::number() const

Description

Gets the number of the layer. This number is fixed and unique. It cannot be set to another value.

A value of 0 is returned if this is the default layer. -1 is returned if the object is not valid.

const char * AlLayer::name() const

Description

Returns the name of the object.

statusCode AlLayer::setName (const char *newName)

Description

Sets the name of a layer. By default the name of the layer is determined by its number. For example, a layer with a number 3 is named layer#3 by default

Arguments

< newName - the new name of the layer

Return Codes

sSuccess - the name was set

sFailure - the layer is a default layer or the name length exceeded 255 characters, or the layers functionality is disabled.

sInvalidArgument - newName was NULL

sInvalidObject - the object is not valid

boolean AlLayer::drawInstances() const

Description

Returns true if the instances are drawn in the modeling windows and false otherwise. False is also returned if the layer is invalid.

statusCode AlLayer::setDrawInstances (boolean draw)

Description

Sets the drawability of instance nodes in the Alias modeling windows.

Arguments

< draw - a value of true enables the drawing of instances and a value of false disables it

Return Codes

sSuccess - the drawing of instances was set

sFailure - the layer is a default layer or the layer functionality is disabled

sInvalidObject - the object is not valid

boolean AlLayer::playback() const

Description

Returns true if the layer can be played back and false otherwise. False is also returned if the layer is invalid.

statusCode AlLayer::setPlayback (boolean enablePlayback)

Description

Sets whether or not a layer can play back.

Arguments

< enablePlayback - a value of true enables the layer to play back; false prevents it from playing back

Return Codes

sSuccess - the playback setting was enabled

sFailure - the layer is a default layer or the layer functionality is disabled

sInvalidObject - the object is not valid

int AlLayer::color() const

Description

Returns the color index for inactive modeling in the Alias interface. Color indexes are defined in AlUserColors.h.

Return Values

kUserInactiveModelColor - the layer does not have a color and it uses the default Alias colors

kUserInactiveLayerUser1, kUserInactiveLayerUser2, ..., kUserInactiveLayerUser15 - the color index of the Alias inactive modeling colors

-1 - the object is invalid

statusCode AlLayer::setColor (int colorField)

Description

Sets the layer color by colorField, as defined in AlUserColors.h. The valid color indices vary from kUserInactiveLayerUser1Color to kUserInactiveLayerUser15Color, providing 15 valid colors which can be set for the layers. The definition of these colors can be changed with AlUniverse::setUserPrefColor().

Arguments

< colorField - kUserInactiveLayerUser1Color to kUserInactiveLayerUser15Color - the layer uses colors 1 through 15, depending on which value you specify, or kUserInactiveModelColor - the layer uses the default Alias model color

Return Codes

sSuccess - the color was set

sFailure - the layer functionality is disabled

sInvalidArgument - the color index was out of range

sInvalidObject - the object is not valid

boolean AlLayer::isPicked() const

Description

Returns true if the layer is picked. FALSE is returned if the layer is not picked or if the object is invalid.

statusCode AlLayer::unpick()

Description

Unpicks the layer.

Return code

sSuccess - the unpick was successfully

sFailure - the unpick operation failed because layers have been disabled

sInvalidObject - the object is not valid

statusCode AlLayer::pick()

Description

Picks the layer.

Return code

sSuccess - the pick was successful

sFailure - the pick operation failed because layers have been disabled

sInvalidObject - the object is not valid

boolean AlLayer::visibleInLayerBar() const

Description

Determines whether or not the layer is visible in the layer bar in the Alias window

statusCode AlLayer::setVisibleInLayerBar (boolean visibility)

Description

Sets whether or not the layer menu should appear in the layer bar.

Arguments

< visibility - a value of true makes the layer bar visible and false makes it invisible

Return Codes

sSuccess - the visibility in the layer bar was set

sFailure - the layers functionality is turned off

int AlLayer::startNumber()

Description

Provides the number of the layer which will be added with the create() method.

statusCode AlLayer::setStartNumber(int newStart)

Description

Sets the number which a new layer created with create() method will get. Further create() invocations will increment the number by one for each new layer. Once the layer is created its number cannot be changed. Also if the layer by that number already exists, the number is incremented until a layer by that number does not exist.

Arguments

< newStart - the new layer will get the layer of this number. newStart can range from 1 to 65,023.

Return Codes

sSuccess - the layer start number was set

sFailure - the layer could not be set

sInvalidArgument - the number was outside the range of 1 to 65,023

statusCode AlLayer::setSymmetric(boolean symm)

Description

Sets this layer to be symmetric or turns layer symmetry off.

Arguments

< symm - true if symmetry is required, false to turn symmetry off

Return code

sSuccess - the method was successful

sFailure - the method failed

sInvalidObject - the layer is invalid

boolean AlLayer::isSymmetric() const

Description

Returns TRUE if this layer is symmetric. FALSE will be returned if the layer is not symmetric of if the method failed.

statusCode AlLayer::setSymmetricOrigin(double x, double y, double z)

Description

This methods sets the location of the origin of the symmetric layer.

Arguments:

< x,y,z -coordinates of the symmetric layer’s origin

Return code

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - the layer is invalid or is not symmetric

statusCode AlLayer::setSymmetricNormal(double x, double y, double z)

Description

This method sets the normal of the symmetric plane.

Arguments:

< x,y,z - the normal of the symmetric plane.

Return code

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - the layer is invalid or is not symmetric

statusCode AlLayer::symmetricOrigin(double& x, double& y, double& z)

Description

Returns the symmetric origin of the layer.

Arguments

> x,y,z - components of the symmetric origin

Return code

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - the layer is invalid or is not symmetric

statusCode AlLayer::symmetricNormal(double& x, double& y, double& z)

Description

Returns the symmetric normal of the layer.

Arguments

> x,y,z - the components of the normal

Return code

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - the layer is invalid or is not symmetric

statusCode AlLayer::pickNodesOnLayer()

Description

First unpicks everything. Then, marks all leaf nodes contained in this Layer (which are pickable). This method behaves as Alias' "Pick By Layer" tool does.

Return code

sSuccess - the method succeeded

sFailure - the method failed