Attribute Notification Methods

From DocR23

An important feature of an attribute is the ability to control its behavior when its owning entity is modified during a modeling operation. Attributes are notified of their owner being modified using an attribute notification method.

Notification methods are most typically called from within ACIS geometric algorithms that are in the process of tearing down and rebuilding the model. As a result, take care in your implementation of each notification method not to assume too much about the validity of the model. You may safely assume that the attribute’s owner exists and that any input entity into the notification method exists, but you may not assume anything about the state of the model above or below the owner or the input entity(s).

Furthermore, a complex attribute that has pointers to topological and/or geometric entities in the model may not assume that those entities still exist. The ATTRIB class provides methods for the following notifications:

Contents 1 Copy Owner 1.1 Predefined Actions 1.2 Custom Behavior 1.3 Notification Method vs. Derivation Macro 2 Split Owner 2.1 Predefined Actions 2.2 Custom Behavior 3 Merge Owner 3.1 Predefined Actions 3.2 Custom Behavior 4 Transform Owner 4.1 Predefined Actions 4.2 Custom Behavior 5 Make Owner Tolerant or Non-Tolerant 5.1 Predefined Actions 5.2 Custom Behavior 6 Replace Owner 6.1 Predefined Actions 6.2 Custom Behavior 7 Change Owner by LOPS Operation 7.1 Predefined Actions 7.2 Custom Behavior 8 Replace Owner Geometry 8.1 Predefined Actions 8.2 Custom Behavior 9 Reverse Owner 9.1 Predefined Actions 9.2 Custom Behavior 10 Warp Owner 10.1 Predefined Actions 10.2 Custom Behavior 11 See Also

Copy Owner

virtual void copy_owner( ENTITY *copy_ent );

The copy_owner method notifies "this" attribute that its owner has been copied. The copy of its owner, copy_ent, is given as input.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the copy_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_copy_owner_action method to set a copy_owner action. The types of copy_owner actions available are:

• CopyLose

Loses the attribute if its owner is copied.

• CopyKeep

Does nothing if the owner is copied. Default.

• CopyCopy

Creates a new instance of the attribute on the new owner (using ATTRIB::duplicate()).

In the event a complex attribute has its copy_owner action set to CopyCopy, ACIS creates a new instance of that complex attribute on copy_ent; the caveat, however, is that all entity pointers (other than the owner_ptr) will be set to NULL.

Custom Behavior

If the copy_owner actions are not sufficient to meet your attribute’s specific needs, then the copy_owner method may be implemented directly.

Notification Method vs. Derivation Macro

A commonly asked question is "What is the difference between copy_owner and COPY_DEF?" The functions api_copy_entity and api_copy_body copy all "copyable" attributes using the standard COPY_DEF mechanism. The function api_down_copy_entity, in contrast, notifies each attribute using its copy_owner method. Why the distinction? Note that api_copy_entity creates a full-body copy. An attribute’s COPY_DEF implementation may trust that the full body is being copied. The API api_down_copy_entity, on the other hand, produces a partial-body copy. As such, complex attributes cannot make any assumptions about the state of the entities to which they point. Therefore, api_down_copy_entity uses copy_owner.

Split Owner

virtual void split_owner( ENTITY *new_entity );

The split_owner method notifies "this" attribute that its owner has been split. The new portion of the split, new_entity, is given as input.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the split_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_split_owner_action method to set a split_owner action. The types of split_owner actions available are:

• SplitLose

Loses the attribute if its owner is split.

• SplitKeep

Does nothing if the owner is split. Default.

• SplitCopy

Creates a new instance of the attribute on the new entity (using ATTRIB::duplicate()).

In the event a complex attribute has its split_owner action set to SplitCopy, ACIS creates a new instance of that complex attribute on new_entity; the caveat, however, is that all entity pointers (other than the owner_ptr) will be set to NULL.

Custom Behavior

If the split_owner actions are not sufficient to meet your attribute’s specific needs, then the split_owner method may be implemented directly.

Merge Owner

virtual void merge_owner( ENTITY * entity, logical del_owner );

The merge_owner method notifies "this" attribute that its owner has been merged. The process of merging implies that one of the two entities involved in the merge is lost during the merge process. Of these two entities, the go-ent is defined as the entity that is going away, and the keep-ent as the entity that is being kept.

Note: merge_owner is called twice for a merge: once for all attributes on the go-ent, and once for all attributes on the keep-ent:

• Once with del_owner set to TRUE, which means that "this" attribute’s owner is the go-ent and that the input "entity" is the keep-ent.
• Once with del_owner set to FALSE, which means that "this" attribute’s owner is the keep-ent and that the input "entity" is the go-ent.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the merge_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_merge_owner_action method to set a merge_owner action. The types of merge_owner actions available are:

• MergeLose

Loses the attribute if its owner is merged.

• MergeKeepKept

Does nothing if the owner is merged. Default.

• MergeKeepLost

Transfers the attribute from the entity being lost to the entity being kept, but removes the old attributes of the kept entity.

• MergeKeepAll

Moves the attribute from the entity being lost to the entity being kept.

Custom Behavior

If the merge_owner actions are not sufficient to meet your attribute’s specific needs, then the merge_owner method may be implemented directly.

Transform Owner

virtual void trans_owner( const SPAtransf &transf );

The trans_owner method notifies "this" attribute that its owner has been transformed. The transform is given as input.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the trans_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_trans_owner_action method to set a trans_owner action. The types of trans_owner actions available are:

• TransLose

Loses the attribute if its owner is transformed.

• TransIgnore

Does nothing if the owner is transformed. Default.

Custom Behavior

If the trans_owner actions are not sufficient to meet your attribute’s specific needs, then the trans_owner method may be implemented directly.

Make Owner Tolerant or Non-Tolerant

virtual void to_tolerant_owner( ENTITY *tol_ent );
virtual void from_tolerant_owner( ENTITY *non_tol_ent );

The to_tolerant_owner and from_tolerant_owner methods notify "this" attribute that its owner is being lost and is being replaced by a new, tolerant owner (to_tolerant_owner); or new, non-tolerant owner (from_tolerant_owner). The new owner is given as input.

Applications can specify how they want their attribute to behave in these methods by either:

• Setting the to_tolerant_owner/from_tolerant_owner actions in their attribute’s constructor.
• Implementing these methods directly.

Predefined Actions

Use the ATTRIB::set_to_tolerant_owner_action / ATTRIB::set_from_tolerant_owner_action method to set a tolerant_owner action. The types of tolerant_owner actions available are:

• TolerantLose

Loses the attribute if its owner is made tolerant / non-tolerant.

• TolerantMove

Moves the attribute to the new owner (only possible if "this" attribute returns moveable() == TRUE). Default.

Custom Behavior

If the tolerant_owner actions are not sufficient to meet your attribute’s specific needs, then the to_tolerant_owner / from_tolerant_owner methods may be implemented directly.

Replace Owner

virtual void replace_owner( ENTITY *other_entity, logical replace_owner );

The replace_owner method notifies "this" attribute that its owner is being replaced by a new owner. The process of replacing implies that one of the two entities involved will be lost during the replacement process. Of these two entities, we define the go-ent as the entity that is going away, and the keep-ent as the entity that is being kept.

Note: replace_owner will be called twice for a replacement: once for all attributes on the go-ent, and once for all attributes on the keep-ent:

• Once with replace_owner set to TRUE, which means that "this" attribute’s owner is the go-ent and that the input "entity" is the keep-ent.
• Once with replace_owner set to FALSE, which means that "this" attribute’s owner is the keep-ent and that the input "entity" is the go-ent.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the replace_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_replace_owner_action method to set a replace_owner action. The types of replace_owner actions available are:

• ReplaceLose

Loses the attribute if its owner is replaced.

• ReplaceKeepKept

Keeps the attribute on the entity being kept. Default.

• ReplaceKeepLost

Moves the attribute from the entity going away to the entity being kept; loses any on the one kept.

• ReplaceKeepAll

Moves the attribute from the entity going away to the entity being kept; keeps any on the one kept.

Custom Behavior

If the replace_owner actions are not sufficient to meet your attribute’s specific needs, then the replace_owner method may be implemented directly.

Change Owner by LOPS Operation

virtual void lop_change_owner();

The lop_change_owner method notifies "this" attribute that its owner has been geometrically (or possibly topologically) changed by a local operation. The specific nature of the change is not known to the attribute.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the lop_change_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_lop_change_owner_action method to set a lop_change_owner action. The types of lop_change_owner actions available are:

• GeomChangedLose

Loses the attribute if its owner is geometrically changed.

• GeomChangedKeep

Does nothing if the owner is geometrically changed. Default.

Custom Behavior

If the lop_change_owner actions are not sufficient to meet your attribute’s specific needs, then the lop_change_owner method may be implemented directly.

Replace Owner Geometry

virtual void replace_owner_geometry(ENTITY *new_geom);

The replace_owner_geometry method notifies "this" attribute that its owner is to receive new geometry. The new geometry is given as input.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the replace_owner_geometry action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_rep_owner_geom_action method to set a replace_owner_geometry action. The types of replace_owner_geometry actions available are:

• GeomChangedLose

Loses the attribute if its owner is geometrically changed.

• GeomChangedKeep

Does nothing if the owner is geometrically changed. Default.

Custom Behavior

If the replace_owner_geometry actions are not sufficient to meet your attribute’s specific needs, then the replace_owner_geometry method may be implemented directly.

Reverse Owner

virtual void reverse_owner();

The reverse_owner method notifies "this" attribute that its owner’s sense bit is about to be reversed.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the reverse_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_reverse_owner_action method to set a reverse_owner action. The types of reverse_owner actions available are:

• GeomChangedLose

Loses the attribute if its owner is geometrically changed.

• GeomChangedKeep

Does nothing if the owner is geometrically changed. Default.

Custom Behavior

If the reverse_owner actions are not sufficient to meet your attribute’s specific needs, then the reverse_owner method may be implemented directly.

Warp Owner

virtual void warp_owner( law *warp );

The warp_owner method notifies "this" attribute that its owner will be modified by warping. The warp being applied is given as input.

Applications can specify how they want their attribute to behave in this method by either:

• Setting the warp_owner action in their attribute’s constructor.
• Implementing this method directly.

Predefined Actions

Use the ATTRIB::set_warp_owner_action method to set a warp_owner action. The types of warp_owner actions available are:

• GeomChangedLose

Loses the attribute if its owner is geometrically changed.

• GeomChangedKeep

Does nothing if the owner is geometrically changed. Default.

Custom Behavior

If the warp_owner actions are not sufficient to meet your attribute’s specific needs, then the warp_owner method may be implemented directly.

See Also

• Attributes
• Types of Attributes
• How ACIS Uses Attributes