Static Public Member Functions | Protected Types | Protected Member Functions | List of all members
ITransactionHandler Struct Reference

Interface adopted by an Element Handler that wants to participate in MicroStation transactions. More...

#include <ITransactionHandler.h>

Inheritance diagram for ITransactionHandler:
DimensionHandler ParametricCellDefHandler PointCloudHandler RasterFrameHandler SectionClipElementHandler SharedCellDefHandler TextNodeHandler Type2Handler

Static Public Member Functions

static void CallOnAdded (ElementHandleR)
 
static void CallOnAddedComplete (ElementHandleR)
 

Protected Types

enum  PreActionStatus { PRE_ACTION_Ok = 0, PRE_ACTION_Block = 1 }
 

Protected Member Functions

virtual void _OnUndoRedo (ElementHandleP afterUndoRedo, ElementHandleP beforeUndoRedo, ChangeTrackAction action, bool isUndo, ChangeTrackSource source)
 Called when an element is changed by either the Undo or Redo command in MicroStation. More...
 
virtual void _OnHistoryRestore (ElementHandleP after, ElementHandleP before, ChangeTrackAction actionStep, BentleyDgnHistoryElementChangeType effectiveChange)
 Called when an element is changed by design history to restore a historical version. More...
 
virtual void _OnUndoRedoFinished (ElementRefP element, bool isUndo)
 Called after undo/redo has restored all elements involved in the transaction and after all undo/redo callbacks have been invoked. More...
 
virtual void _OnDeleted (ElementHandleP element)
 Called after an element is deleted from a model. More...
 
virtual void _OnAdded (ElementHandleP element)
 Called after an element is added to a model. More...
 
virtual void _OnAddedComplete (ElementHandleP element)
 Called after an element is added to a model. More...
 
virtual void _OnModified (ElementHandleP newElement, ElementHandleP oldElement, ChangeTrackAction action, bool *cantBeUndoneFlag)
 Called after an element is directly changed in MicroStation and the DgnModel holds the new state of the element. More...
 
virtual void _OnUndoRedoXAttributeChange (XAttributeHandleCR xAttr, ChangeTrackAction action, bool isUndo, ChangeTrackSource source)
 Called whenever an XAttribute is changed by either the Undo or Redo command in MicroStation. More...
 
virtual void _OnXAttributeChanged (XAttributeHandleCR xAttr, ChangeTrackAction action, bool *cantBeUndoneFlag)
 Called when an XAttribute has been added, removed, or modified on the element. More...
 
virtual PreActionStatus _OnAdd (EditElementHandleR)
 
virtual PreActionStatus _OnReplace (EditElementHandleR, ElementHandleCR)
 
virtual PreActionStatus _OnDelete (ElementHandleCR)
 
virtual PreActionStatus _OnRemoveHandler (ElementHandleCR)
 

Detailed Description

Interface adopted by an Element Handler that wants to participate in MicroStation transactions.

Remarks
It can be confusing to mix the use of dependency callbacks and ITransactionHandler callbacks. That's due to element ID remapping during element cloning and because of the timing of the callbacks. ITransactionHandler callbacks are invoked immediately before and after a change is made. Dependency callbacks are invoked at the close of the current transaction.

If an element contains DependencyLinkages or XAttributes containing PersistentElementRefs, these data structures are handled specially by the system during element cloning, in order to support ElementId remapping. In particular, the DependencyLinkage.u.f.invalid flag is set when remapping is in progress. When this flag is set, an ITransactionHandler callback should leave the dependency linkage alone. It's in an intermediate state. Likewise, during ElementId remapping, a PersistentElemetnRef is in an invalid state and should not be modified.

Member Enumeration Documentation

enum PreActionStatus
protected
Enumerator
PRE_ACTION_Ok 
PRE_ACTION_Block 

Member Function Documentation

virtual PreActionStatus _OnAdd ( EditElementHandleR  )
protectedvirtual
virtual void _OnAdded ( ElementHandleP  element)
protectedvirtual

Called after an element is added to a model.

Parameters
[in]elementThe element.
See also
_OnUndoRedo

Reimplemented in CalloutBaseHandler.

virtual void _OnAddedComplete ( ElementHandleP  element)
protectedvirtual

Called after an element is added to a model.

This gets called after the element and its xattributes are added.

Parameters
[in]elementThe element.
See also
_OnUndoRedo
virtual PreActionStatus _OnDelete ( ElementHandleCR  )
protectedvirtual
virtual void _OnDeleted ( ElementHandleP  element)
protectedvirtual

Called after an element is deleted from a model.

virtual void _OnHistoryRestore ( ElementHandleP  after,
ElementHandleP  before,
ChangeTrackAction  actionStep,
BentleyDgnHistoryElementChangeType  effectiveChange 
)
protectedvirtual

Called when an element is changed by design history to restore a historical version.

Parameters
[in]afterThe state of the changed element after the element was restored to its historical state. If action is ChangeTrackAction::Delete then after will be invalid.
[in]beforeThe state of the changed element before the restore happened. If action is ChangeTrackAction::Add then before will be invalid.
[in]actionStepThe current step in restoring the historical state. This action may be just one step in accomplishing the overallAction.
[in]effectiveChangeElementChangeType::Replaced if the DesignHistoryRestore is trying to update an existing element.
Remarks
When an element is to be rewritten, the default DesignHistoryRestore algorithm is to do this in two steps.
  • Delete the element currently in the file.
  • Call CopyContext::DoCopy to copy the historical version from a historical state of the file and add it to the target file. In each step, actionStep describes what actual change is being made (Add, Delete), while effectiveChange is set to ElementChangeType::Replaced, indicating that the final goal is to modify an existing element.
History Restore is similar to undo/redo, but not exactly like it. MicroStation undo/redo will restore the historical state of all elements from the present to an undo mark or vice versa. Moreover, elements will be undone in the reverse of the order in which they were changed and are redone in original change order. History restore does not make these guarantees.
  • Sometimes, all elements are restored from a historical revision and sometimes elements are restored individually.
  • Sometimes, all changes are undone from the present to a point in history, and sometimes a particular historical version is replicated.
  • Design history does not capture the original change order, and the restore operation does not guarantee any particular element order.
In the case where actionStep is ChangeTrackAction::Delete, this callback will be invoked after the element is deleted. In this case, the before handle will contain a copy of the element's data before it was deleted in the form of an element descriptor. The descriptor will not have a copy of the element's XAttributes.
History Restore is not to be confused with Change Replication. The latter is called when an element version is merged from a shared file into a workfile.
See also
_OnUndoRedo
virtual void _OnModified ( ElementHandleP  newElement,
ElementHandleP  oldElement,
ChangeTrackAction  action,
bool *  cantBeUndoneFlag 
)
protectedvirtual

Called after an element is directly changed in MicroStation and the DgnModel holds the new state of the element.

Parameters
[in]newElementThe state of the changed element after the change. In the case of ChangeTrackAction::Delete, newElement will be invalid.
[in]oldElementThe state of the changed element before the change. In the case of ChangeTrackAction::Add, oldElement will be invalid.
[in]actionThe action that caused the element to be changed.
[in]cantBeUndoneFlagBy setting the boolean value pointed to by cantBeUndoneFlag, to true, an application can indicate that a change, and all previous changes, should not be undoable. This is useful for an application that modifies its data structures in non-reversible ways (for example, a change to an external relational database).
Remarks
NOTE: Turning on the "cantBeUndone" flag also means that ALL previous changes become non-undoable as well, since it is not possible to "skip" undo states. From the user's perspective, this is a pretty drastic action and should be avoided if at all possible.
virtual PreActionStatus _OnRemoveHandler ( ElementHandleCR  )
protectedvirtual
virtual PreActionStatus _OnReplace ( EditElementHandleR  ,
ElementHandleCR   
)
protectedvirtual
virtual void _OnUndoRedo ( ElementHandleP  afterUndoRedo,
ElementHandleP  beforeUndoRedo,
ChangeTrackAction  action,
bool  isUndo,
ChangeTrackSource  source 
)
protectedvirtual

Called when an element is changed by either the Undo or Redo command in MicroStation.

Parameters
[in]afterUndoRedothe state of the changed element after the undo/redo. If action ChangeTrackAction::Delete, then afterUndoRedo will be invalid.
[in]beforeUndoRedostate of the changed element before the undo/redo happened. If action is ChangeTrackAction::Add, then beforeUndoRedo will be invalid.
[in]actionthe original action that caused the entry to be added to the undo buffer. This action was just reversed or reinstated, depending on the state of isUndo.
[in]isUndoif true, the action was just undone. If false, the action was reinstated.
[in]sourceidentifies the undo or the history manager as the source of the version restored.
See also
_OnUndoRedoFinished
_OnDeleted
_OnAdded
_OnAddedComplete
virtual void _OnUndoRedoFinished ( ElementRefP  element,
bool  isUndo 
)
protectedvirtual

Called after undo/redo has restored all elements involved in the transaction and after all undo/redo callbacks have been invoked.

Parameters
[in]elementThe element (in its post-change state).
[in]isUndoIf true, the action was just undone. If false, the action was reinstated.
See also
_OnUndoRedo
virtual void _OnUndoRedoXAttributeChange ( XAttributeHandleCR  xAttr,
ChangeTrackAction  action,
bool  isUndo,
ChangeTrackSource  source 
)
protectedvirtual

Called whenever an XAttribute is changed by either the Undo or Redo command in MicroStation.

Parameters
[in]xAttrXAttribute that was changed.
[in]actionThe original action that caused the entry to be added to the undo buffer. This action was just reversed or reinstated, depending on the state of isUndo.
[in]isUndoIf true, the the action was just undone. If false, the action was reinstated.
[in]sourceIdentifies the undo or the history manager as the source of the version restored.
Returns
The return type of the user function is ignored.
See also
_OnXAttributeChanged
_OnUndoRedoFinished
Remarks
Normally, this callback is made after the undo/redo has been done and the XAttribute has been updated. In the case of undoing an Add or redoing a Delete, this callback is made just before the XAttribute is deleted.
virtual void _OnXAttributeChanged ( XAttributeHandleCR  xAttr,
ChangeTrackAction  action,
bool *  cantBeUndoneFlag 
)
protectedvirtual

Called when an XAttribute has been added, removed, or modified on the element.

Parameters
[in]xAttrThe affected XAttribute.
[in]actionThe action that happened.
[in]cantBeUndoneFlagBy setting the boolean value pointed to by cantBeUndoneFlag to true, an application can indicate that a change should not be undoable. This is useful for an application that modifies its data structures in non-reversible ways (for example, a change to an external relational database).
static void CallOnAdded ( ElementHandleR  )
static
static void CallOnAddedComplete ( ElementHandleR  )
static

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

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.