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]	newDescr	a complete element descriptor holding the state of the changed element after the change. In the case of ChangeTrackAction::Delete, `newDescr` will be NULL.
[in]	oldDescr	a complete element descriptor reflecting the state of the changed element before the change. In the case of ChangeTrackAction::Add, `oldDescr` will be NULL.
[in]	info	the DgnPlatform::ChangeTrackInfo relevant to the command that caused the change.
[in]	cantBeUndoneFlag	By 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]	afterUndoRedo	a 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]	beforeUndoRedo	a 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]	action	the 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]	isUndo	if true, the the action was just undone. If false, the action was reinstated.
[in]	source	identifies the undo or the history manager as the source of the version restored.
[in]	info	the 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] isUndo if 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]	xAttr	Identifies the XAttribute
[in]	action	the 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]	isUndo	if true, the the action was just undone. If false, the action was reinstated.
[in]	source	identifies the undo or the history manager as the source of the version restored.
[in]	info	the DgnPlatform::ChangeTrackInfo relevant to the command that caused the original change.
[in]	info	the 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]	xAttr	Identifies the XAttribute that was changed
[in]	info	the DgnPlatform::ChangeTrackInfo relevant to the command that caused the change.
[in]	cantBeUndoneFlag	By 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] newFunc The 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] newFunc The 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] newFunc The 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] newFunc The 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] newFunc The 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] newFunc The 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] newFunc The 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