Typedefs | Functions
Change Tracking

Typedefs

typedef void ChangeTrackFunc_XAttributeChanged (XAttributeHandleCP xAttr, DgnPlatform::ChangeTrackInfo *info, bool *cantBeUndoneFlag)
 UserFunction called whenever an XAttribute is directly changed in MicroStation. More...
 
typedef void ChangeTrackFunc_Changed (MSElementDescrP newDescr, MSElementDescrP oldDescr, DgnPlatform::ChangeTrackInfo *info, bool *cantBeUndoneFlag)
 UserFunction called whenever an element is directly changed in MicroStation. More...
 
typedef void ChangeTrackFunc_UndoRedo (MSElementDescrP afterUndoRedo, MSElementDescrP beforeUndoRedo, DgnPlatform::ChangeTrackAction action, bool isUndo, DgnPlatform::ChangeTrackInfo const *info, DgnPlatform::ChangeTrackSource source)
 UserFunction called whenever an element is changed by either the Undo or Redo command in MicroStation. More...
 
typedef void ChangeTrackFunc_UndoRedoXAttribute (XAttributeHandleCP xAttr, DgnPlatform::ChangeTrackAction action, bool isUndo, DgnPlatform::ChangeTrackInfo const *info, DgnPlatform::ChangeTrackSource source)
 UserFunction called whenever an XAttribute is changed by either the Undo or Redo command in MicroStation. More...
 
typedef void ChangeTrackFunc_UndoRedoFinished (bool isUndo)
 UserFunction called after undo or redo command has completed. More...
 
typedef void ChangeTrackFunc_Mark ()
 UserFunction called to notify listeners that a change track "mark" just happened. More...
 

Functions

static void AddChangedFunction (ChangeTrackFunc_Changed newFunc)
 An MDL application can use this to set a function to be called whenever an element is directly changed in MicroStation. More...
 
static bool RemoveChangedFunction (ChangeTrackFunc_Changed oldFunc)
 Removes a callback function previously installed using ChangeTrackCallback::AddChangedFunction. More...
 
static void AddUndoRedoFunction (ChangeTrackFunc_UndoRedo newFunc)
 An MDL application can use this to set a function to be called whenever an element is changed by either the Undo or Redo command in MicroStation. More...
 
static bool RemoveUndoRedoFunction (ChangeTrackFunc_UndoRedo oldFunc)
 Removes a callback function previously installed using ChangeTrackCallback::AddUndoRedoFunction. More...
 
static void AddXAttributeChangedFunction (ChangeTrackFunc_XAttributeChanged newFunc)
 An MDL application can use this to set a function to be called whenever an XAttribute is directly changed in MicroStation. More...
 
static bool RemoveXAttributeChangedFunction (ChangeTrackFunc_XAttributeChanged oldFunc)
 Removes a callback function previously installed using ChangeTrackCallback::AddXAttributeChangedFunction. More...
 
static void AddUndoRedoXAttributeFunction (ChangeTrackFunc_UndoRedoXAttribute newFunc)
 An MDL application can use this to set a function to be called whenever an XAttribute is changed by either the Undo or Redo command in MicroStation. More...
 
static bool RemoveUndoRedoXAttributeFunction (ChangeTrackFunc_UndoRedoXAttribute oldFunc)
 Removes a callback function previously installed using ChangeTrackCallback::AddXAttributeUndoRedoFunction. More...
 
static void AddUndoRedoFinishedFunction (ChangeTrackFunc_UndoRedoFinished newFunc)
 An MDL application can use this to set a function to be called after undo or redo command has completed. More...
 
static bool RemoveUndoRedoFinishedFunction (ChangeTrackFunc_UndoRedoFinished oldFunc)
 Removes a callback function previously installed using ChangeTrackCallback::AddUndoRedoFinishedFunction. More...
 
static void AddMarkFunction (ChangeTrackFunc_Mark newFunc)
 An MDL application can use this to set a function to be called when a change track "mark" happens. More...
 
static bool RemoveMarkFunction (ChangeTrackFunc_Mark oldFunc)
 Removes a callback function previously installed using ChangeTrackCallback::AddMarkFunction. More...
 
static void AddTransientChangedFunction (ChangeTrackFunc_Changed newFunc)
 An MDL application can use this to set a function to be called when a transient element is directly changed in MicroStation. More...
 
static bool RemoveTransientChangedFunction (ChangeTrackFunc_Changed oldFunc)
 Removes a callback function previously installed using ChangeTrackCallback::AddTransientChangedFunction. More...
 

Detailed Description

Typedef Documentation

typedef void ChangeTrackFunc_Changed(MSElementDescrP newDescr, MSElementDescrP oldDescr, DgnPlatform::ChangeTrackInfo *info, bool *cantBeUndoneFlag)

UserFunction called whenever an element is directly changed in MicroStation.

Remarks
This callback is established by calling ChangeTrackCallback::AddChangedFunction.
Parameters
[in]newDescra complete element descriptor holding the state of the changed element after the change. In the case of ChangeTrackAction::Delete, newDescr will be NULL.
[in]oldDescra complete element descriptor reflecting the state of the changed element before the change. In the case of ChangeTrackAction::Add, oldDescr will be NULL.
[in]infothe DgnPlatform::ChangeTrackInfo relevant to the command that caused the change.
[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).
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.
NOTE: ChangeTrackFunc_Changed functions are called AFTER the change has been completed and the DgnPlatform::DgnModel already holds the new copy of the element.
See also
DgnPlatform::ChangeTrackInfo, ChangeTrackCallback::AddChangedFunction
ChangeTrackCallback::AddChangedFunctionC ChangeTrackCallback::RemoveChangedFunctionC
typedef void ChangeTrackFunc_Mark()

UserFunction called to notify listeners that a change track "mark" just happened.

A mark signals the end of a logically related set of changes. A mark generally means that a Command just completed, but it may also occur in between commands.

Remarks
This callback is established by calling ChangeTrackCallback::AddMarkFunction.
Returns
The return value of this user function is ignored.
See also
ChangeTrackFunc_UndoRedoFinished, ChangeTrackCallback::AddMarkFunction
ChangeTrackCallback::AddMarkFunctionC ChangeTrackCallback::RemoveMarkFunctionC
typedef void ChangeTrackFunc_UndoRedo(MSElementDescrP afterUndoRedo,MSElementDescrP beforeUndoRedo,DgnPlatform::ChangeTrackAction action,bool isUndo,DgnPlatform::ChangeTrackInfo const *info,DgnPlatform::ChangeTrackSource source)

UserFunction called whenever an element is changed by either the Undo or Redo command in MicroStation.

Remarks
This callback is established by calling ChangeTrackCallback::AddUndoRedoFunction.
Parameters
[in]afterUndoRedoa complete element descriptor holding the state of the changed element after the undo/redo. In the case where the undo/redo deletes the element (e.g. undo of an Add or a redo of a Delete), afterUndoRedo will be NULL.
[in]beforeUndoRedoa complete element descriptor reflecting the state of the changed element before the undo/redo happened. In the case of an undo of ChangeTrackAction::Add, oldDescr will be NULL.
[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.
[in]infothe DgnPlatform::ChangeTrackInfo relevant to the command that caused the original change. For certain types of undo/redo operations (e.g. history operations) this argument will be NULL! Implementers should always test for NULL. (New in V8.5)
Returns
The return type of the user function is ignored.
See also
ChangeTrackFunc_UndoRedoFinished, DgnPlatform::ChangeTrackAction, ChangeTrackCallback::AddUndoRedoFunction
ChangeTrackCallback::AddUndoRedoFunctionC ChangeTrackCallback:RemoveUndoRedoFunctionC
typedef void ChangeTrackFunc_UndoRedoFinished(bool isUndo)

UserFunction called after undo or redo command has completed.

This means that all of the changes between the start and end marks have been undone or redone.

Remarks
This callback is established by calling ChangeTrackCallback::AddUndoRedoFinishedFunction.
Parameters
[in]isUndoif true, the undo command is finished. If false, the redo command is finished.
Returns
The return value of this user function is ignored.
See also
ChangeTrackFunc_UndoRedo, ChangeTrackCallback::AddUndoRedoFinishedFunction
ChangeTrackCallback::AddUndoRedoFinishedFunctionC ChangeTrackCallback::RemoveUndoRedoFinishedFunctionC
typedef void ChangeTrackFunc_UndoRedoXAttribute(XAttributeHandleCP xAttr, DgnPlatform::ChangeTrackAction action,bool isUndo,DgnPlatform::ChangeTrackInfo const *info,DgnPlatform::ChangeTrackSource source)

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

Remarks
This callback is established by calling ChangeTrackCallback::AddUndoRedoXAttributeFunction.
Parameters
[in]xAttrIdentifies the XAttribute
[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.
[in]infothe DgnPlatform::ChangeTrackInfo relevant to the command that caused the original change.
[in]infothe DgnPlatform::ChangeTrackInfo relevant to the command that caused the original change. When the source of undo/redo is Design History, this argument will be NULL! Implementers should always test for NULL.
Returns
The return type of the user function is ignored.
See also
ChangeTrackFunc_UndoRedoFinished, DgnPlatform::ChangeTrackAction, ChangeTrackCallback::AddUndoRedoXAttributeFunction
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.
If you need to see the pre-change version of the XAttribute's data, you must call ***TBD
See also
ChangeTrackCallback::AddUndoRedoXAttributeFunctionC ChangeTrackCallback::RemoveUndoRedoXAttributeFunctionC
typedef void ChangeTrackFunc_XAttributeChanged(XAttributeHandleCP xAttr, DgnPlatform::ChangeTrackInfo *info, bool *cantBeUndoneFlag)

UserFunction called whenever an XAttribute is directly changed in MicroStation.

Change Tracking

The Change Track API is designed to enable applications to "monitor" all of the changes that happen to DGN files during a MicroStation session. Its purpose is to allow applications to react to those changes. This is useful, for example, where the application keeps redundant, in-memory information that is somehow correlated with the current state of the elements in a DGN file.

NOTE: The Change Track API replaces the "UNDO_" asynch subsystem of pre-V8 versions of MicroStation. The built-in mdlUndo_setFunction has been removed and is replaced by several static methods in the ChangeTrackCallback class.

Importantly, the Change Track API is NOT intended to enable applications to "influence" or modify the changes to the DGN file (that's the purpose of the SYSTEM_ELMDSCR_TO_FILE asynch call). Obviously, many applications can monitor the Change Track events simultaneously, and the order in which they are processed is indeterminate. However, since none of them can change the information being processed, the order of execution is moot.

There are two types of changes that happen to a DGN file during a MicroStation session: direct changes, and undo/redo changes. Direct changes are just that - they directly modify the state of the DGN file. Direct changes happen either as a result of input from the user, or by API calls from an application. The DGN file can be viewed as a database that is driven from one consistent state to another consistent state via a series of direct changes. The Change Tracking listeners are notified as each change is made to the DGN file.

Through the UNDO buffer, MicroStation keeps track of groups of changes that together constitute a consistent set of changes, and provides a user interface to reverse unwanted changes. A "mark" delineates the end of a logically related group of changes. The undo command reverses all changes between two marks, and the redo command restores all changes between two marks. The Change Track listeners are notified as marks are created and as files are modified by undo's and redo's.

Change Track distinguishes between direct changes and undo/redo changes to allow applications to "propagate" further changes. Change propagation can happen recursively (that is, one change can cause another change that causes still other changes) but only as a result of direct changes. Change propagation cannot happen when reversing changes via undo/redo because the file must return to a previous known-to-be-valid state. For example, the Dependency Manager is a client of, and in fact receives all of its input from, the Change Track API. It only notifies dependent listeners for direct changes, not undo/redo changes.

Remarks
This callback is established by calling ChangeTrackCallback::AddXAttributeChangedFunction.
Parameters
[in]xAttrIdentifies the XAttribute that was changed
[in]infothe DgnPlatform::ChangeTrackInfo relevant to the command that caused the change.
[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).
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.
NOTE: ChangeTrackFunc_XAttributeChanged functions are called AFTER the change has been completed and the DgnPlatform::DgnModel already holds the new copy of the element.
See also
DgnPlatform::ChangeTrackInfo, AddXAttributeChangedFunction
ChangeTrackCallback::AddXAttributeChangedFunctionC ChangeTrackCallback::RemoveXAttributeChangedFunctionC

Function Documentation

static void AddChangedFunction ( ChangeTrackFunc_Changed  newFunc)
static

An MDL application can use this to set a function to be called whenever an element is directly changed in MicroStation.

Remarks
NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use ChangeTrackCallback::RemoveChangedFunction.
Parameters
[in]newFuncThe new function to call, or NULL.
See also
ChangeTrackFunc_Changed
static void AddMarkFunction ( ChangeTrackFunc_Mark  newFunc)
static

An MDL application can use this to set a function to be called when a change track "mark" happens.

A mark signals the end of a logically related set of changes. A mark generally means that a Command just completed, but it may also occur in between commands.

Remarks
NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use ChangeTrackCallback::RemoveMarkFunction.
Parameters
[in]newFuncThe new function to call, or NULL.
See also
ChangeTrackFunc_Mark
@remark                Required Library: mdlbltin.lib
static void AddTransientChangedFunction ( ChangeTrackFunc_Changed  newFunc)
static

An MDL application can use this to set a function to be called when a transient element is directly changed in MicroStation.

Remarks
NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use ChangeTrackCallback::RemoveTransientChangedFunction.
Parameters
[in]newFuncThe new function to call, or NULL.
See also
ChangeTrackFunc_Changed
static void AddUndoRedoFinishedFunction ( ChangeTrackFunc_UndoRedoFinished  newFunc)
static

An MDL application can use this to set a function to be called after undo or redo command has completed.

This means that all of the changes between the start and end marks have been undone or redone.

Remarks
NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use ChangeTrackCallback::RemoveUndoRedoFinishedFunction.
Parameters
[in]newFuncThe new function to call, or NULL.
See also
ChangeTrackFunc_UndoRedoFinished
static void AddUndoRedoFunction ( ChangeTrackFunc_UndoRedo  newFunc)
static

An MDL application can use this to set a function to be called whenever an element is changed by either the Undo or Redo command in MicroStation.

Remarks
NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use ChangeTrackCallback::RemoveUndoRedoFunction.
Parameters
[in]newFuncThe new function to call, or NULL.
See also
ChangeTrackFunc_UndoRedo
static void AddUndoRedoXAttributeFunction ( ChangeTrackFunc_UndoRedoXAttribute  newFunc)
static

An MDL application can use this to set a function to be called whenever an XAttribute is changed by either the Undo or Redo command in MicroStation.

Remarks
NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use ChangeTrackCallback::RemoveXAttributeUndoRedoFunction.
Parameters
[in]newFuncThe new function to call, or NULL.
See also
ChangeTrackFunc_UndoRedoXAttribute
static void AddXAttributeChangedFunction ( ChangeTrackFunc_XAttributeChanged  newFunc)
static

An MDL application can use this to set a function to be called whenever an XAttribute is directly changed in MicroStation.

Remarks
NOTE: A single MDL application can have multiple callbacks for the same event. If newFunc is NULL, then all callbacks for this event for this MDL application are removed. To remove callback individually use ChangeTrackCallback::RemoveXAttributeChangedFunction.
Parameters
[in]newFuncThe new function to call, or NULL.
See also
ChangeTrackFunc_XAttributeChanged
static bool RemoveChangedFunction ( ChangeTrackFunc_Changed  oldFunc)
static

Removes a callback function previously installed using ChangeTrackCallback::AddChangedFunction.

Parameters
[in]oldFuncThe callback function to remove.
See also
ChangeTrackFunc_Changed
static bool RemoveMarkFunction ( ChangeTrackFunc_Mark  oldFunc)
static

Removes a callback function previously installed using ChangeTrackCallback::AddMarkFunction.

Parameters
[in]oldFuncThe callback function to remove.
See also
ChangeTrackFunc_Mark
static bool RemoveTransientChangedFunction ( ChangeTrackFunc_Changed  oldFunc)
static

Removes a callback function previously installed using ChangeTrackCallback::AddTransientChangedFunction.

Parameters
[in]oldFuncThe callback function to remove.
See also
ChangeTrackFunc_Changed
static bool RemoveUndoRedoFinishedFunction ( ChangeTrackFunc_UndoRedoFinished  oldFunc)
static

Removes a callback function previously installed using ChangeTrackCallback::AddUndoRedoFinishedFunction.

Parameters
[in]oldFuncThe callback function to remove.
See also
ChangeTrackFunc_UndoRedoFinished
static bool RemoveUndoRedoFunction ( ChangeTrackFunc_UndoRedo  oldFunc)
static

Removes a callback function previously installed using ChangeTrackCallback::AddUndoRedoFunction.

Parameters
[in]oldFuncThe callback function to remove.
See also
ChangeTrackFunc_UndoRedo
static bool RemoveUndoRedoXAttributeFunction ( ChangeTrackFunc_UndoRedoXAttribute  oldFunc)
static

Removes a callback function previously installed using ChangeTrackCallback::AddXAttributeUndoRedoFunction.

Parameters
[in]oldFuncThe callback function to remove.
See also
ChangeTrackFunc_UndoRedoXAttribute
static bool RemoveXAttributeChangedFunction ( ChangeTrackFunc_XAttributeChanged  oldFunc)
static

Removes a callback function previously installed using ChangeTrackCallback::AddXAttributeChangedFunction.

Parameters
[in]oldFuncThe callback function to remove.
See also
ChangeTrackFunc_XAttributeChanged

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