State Control

Typedefs
typedef void(*	StateFunc_DataPoint )(DPoint3dCP point, int view)
	If the current command state defines a data point user function, the function is called when the user enters a data point. More...
typedef void(*	StateFunc_Reset )(WCharCP unused)
	If the current command state defines a Reset user function, MicroStation calls the function when the user enters a Reset. More...
typedef void(*	StateFunc_Keyin )(WCharCP cmdstring, int cmdsource, WCharCP inputTaskId)
	If the current command state defines a key-in user function, the function is called when the user enters a key-in. More...
typedef void(*	StateFunc_ComplexDynamics )(DPoint3dCP point, int view, DgnPlatform::DgnDrawMode drawMode)
	If the current command state defines an update function for complex dynamics, MicroStation calls the function when the cursor is moved. More...
typedef void(*	StateFunc_SimpleDynamics )(DPoint3dCP point, int view)
	UserFunction called when NEEDSWORK_VANCOUVER_DOC. More...
typedef void(*	StateFunc_SimpleDescrDynamics )(MSElementDescrH edPP, DPoint3dCP point, int view)
	UserFunction called when NEEDSWORK_VANCOUVER_DOC. More...
typedef void(*	StateFunc_CommandCleanup )(WCharCP unused)
	MicroStation's start primitive logic calls the current StateFunc_CommandCleanup function and then clears the userState_commandCleanUp function pointer. More...
typedef void(*	StateFunc_Oops )(int numActions)
	UserFunction called when NEEDSWORK_VANCOUVER_DOC. More...
typedef void(*	StateFunc_DragInit )(DPoint3dCP point, int view)
	UserFunction called when NEEDSWORK_VANCOUVER_DOC. More...
typedef void(*	StateFunc_Redo )(int unused)
	UserFunction called when NEEDSWORK_VANCOUVER_DOC. More...
typedef int(*	StateFunc_FenceContentOp )(CallbackArgP userArgP, bool copyInClipMode)
	The StateFunc_FenceContentOp function is called when the mdlFence_process function accepts an element. More...
typedef void(*	StateFunc_FenceOp )(DPoint3dCP point, int view)
	UserFunction called when NEEDSWORK_VANCOUVER_DOC. More...
typedef void(*	MdlFunc_Accept )(DPoint3dCP point, int view)
	UserFunction called when the user accepts the highlighted element. More...
typedef void(*	MdlFunc_Show )(DPoint3dCP point, int view)
	UserFunction called to show the result of a selection. More...
typedef void(*	MdlFunc_Clean )(WCharCP unused)
	UserFunction called to clean up any custom locate or selection information. More...
typedef void(*	MdlFunc_NotFound )(WCharCP unused)
	UserFunction called when no acceptable elements were found. More...

Functions
bool	mdlState_checkSingleShot ()
	Determines whether the user wants the command to operate in single-shot mode. More...
void	mdlState_clear ()
	Reset MicroStation's state to "no command active." After this function is called, all input that does not start a command is ignored. More...
void	mdlState_exitViewCommand (bool showMessage)
	Exit the current view command started by mdlState_startViewCommand. More...
void	mdlState_registerStringIds (long cmdStringID, long promptStringID)
	Specify the resource IDs that MicroStation uses when loading prompt and command strings for the application. More...
void	mdlState_restartCurrentCommand ()
	Restart the current primitive command. More...
void	mdlState_restartCurrentCommandNoHome ()
	This function simply calls mdlState_restartCurrentCommand but does not set focus to the Home position even if Position Mapping is turned on. More...
static StateFunc_DataPoint	SetDataPointFunction (StateFunc_DataPoint newFunc)
	An MDL application can use this to set a function to be called when the user enters a data point. More...
static StateFunc_Reset	SetResetFunction (StateFunc_Reset newFunc)
	An MDL application can use this to set a function to be called when the user enters a Reset. More...
static StateFunc_Keyin	SetKeyinFunction (StateFunc_Keyin newFunc)
	An MDL application can use this to set a function to be called when the user enters a key-in. More...
static StateFunc_ComplexDynamics	SetComplexDynamicsFunction (StateFunc_ComplexDynamics newFunc)
	An MDL application can use this to set a function to be called when the cursor is moved. More...
static StateFunc_CommandCleanup	SetCommandCleanupFunction (StateFunc_CommandCleanup newFunc)
	An MDL application can use this to set a function to be called when a command is terminated. More...
static StateFunc_Oops	SetOopsFunction (StateFunc_Oops newFunc)
	An MDL application can use this to set a function to be called when NEEDSWORK_VANCOUVER_DOC. More...
static StateFunc_DragInit	SetDragInitFunction (StateFunc_DragInit newFunc)
	An MDL application can use this to set a function to be called when NEEDSWORK_VANCOUVER_DOC. More...
static StateFunc_Redo	SetRedoFunction (StateFunc_Redo newFunc)
	An MDL application can use this to set a function to be called when NEEDSWORK_VANCOUVER_DOC. More...
StateFunc_SimpleDynamics	mdlState_dynamicUpdate (StateFunc_SimpleDynamics dynamicfunc, int validData)
	Specify an MDL function to be used with simple dynamics. More...
StateFunc_SimpleDescrDynamics	mdlState_simpleDynamicDescr (StateFunc_SimpleDescrDynamics dynamicfunc, int validData)
	Specify an MDL function to be used with simple dynamics. More...
void	mdlState_setKeyinPrompt (WCharCP pPrompt)
	Specify a string to be used as the prompt in the key-in area in MicroStation's command window. More...
void	mdlState_startDefaultCommand ()
	Start the default command. More...
void	mdlState_startFenceCommand (StateFunc_FenceContentOp contentOp, StateFunc_FenceOp fenceOp, StateFunc_DataPoint dataFunc, StateFunc_Reset resetFunc, int funcname, int promptNum, int inputClipMode)
	Start a command that will operate on the contents of a fence. More...
void	mdlState_startModifyCommand (StateFunc_Reset resetFunc, MdlFunc_Accept acceptFunc, StateFunc_SimpleDynamics dynamicFunc, MdlFunc_Show showFunc, MdlFunc_Clean cleanFunc, int cmdMsgNum, int acceptPrompt, bool useSelection, int needPoints)
	Start a command that will locate and modify elements. More...
void	mdlState_startPrimitive (StateFunc_DataPoint datafunc, StateFunc_Reset resetfunc, int funcname, int prompt)
	Start a MicroStation Primitive command. More...
DItem_PulldownMenu *	mdlState_startPrimitiveAndSetPopupMenu (StateFunc_DataPoint datafunc, StateFunc_Reset resetfunc, int funcname, int prompt, UInt32 menuType, long menuId, MdlDesc *ownerMD)
	Start a Primitive command and set the pop-up menu simultaneously. More...
void	mdlState_startViewCommand (StateFunc_DataPoint datafunc, int funcname, int prompt)
	Start a MicroStation Viewing command. More...
void	mdlState_setCurrentCommandName (WChar const *newName)
	Set the name of the current command using a WChar string. More...
WChar const *	mdlState_getCurrentCommandName ()
	Get the name of the current command as a WChar string. More...
int	mdlState_setAccudrawContext (long flags, DPoint3dCP origin, DPoint3dCP delta, double const *distance, double const *angle, void *orientation)
	Provide "hints" to AccuDraw, so that it behaves properly in the context of the current tool. More...
void	mdlAccuDraw_setEnabledState (bool enable)
	Set the current state of the AccuDraw compass. More...
void	mdlState_setCoordinateLockOverrides (DgnPlatform::CoordinateLockOverrides overrides)
	Commands can indicate that they do NOT want coordinate-modifying locks applied to datapoints, even when they are enabled by the user. More...
DgnPlatform::CoordinateLockOverrides	mdlState_getCoordinateLockOverrides ()
	Get the current state of the Coordinate Lock Overrides. More...

Detailed Description

Typedef Documentation

typedef void(* MdlFunc_Accept)(DPoint3dCP point, int view)

UserFunction called when the user accepts the highlighted element.

Parameters

[in]	point	Location where the user clicked.
[in]	view	The view in which the user clicked.

typedef void(* MdlFunc_Clean)(WCharCP unused)

UserFunction called to clean up any custom locate or selection information.

It will be called when an item is highlighted and the user resets or cycles the tentative selection.

Parameters

[in]

unused

This argument is unused and will always be NULL.

typedef void(* MdlFunc_NotFound)(WCharCP unused)

UserFunction called when no acceptable elements were found.

Parameters

[in]

unused

This argument is unused and will always be NULL.

typedef void(* MdlFunc_Show)(DPoint3dCP point, int view)

UserFunction called to show the result of a selection.

Parameters

[in]	point	Location where the user clicked.
[in]	view	The view in which the user clicked.

typedef void(* StateFunc_CommandCleanup)(WCharCP unused)

MicroStation's start primitive logic calls the current StateFunc_CommandCleanup function and then clears the userState_commandCleanUp function pointer.

Therefore, if an MDL command needs to be notified when it is terminated, it designates the user function after calling the appropriate mdlState_start... functions.

Generally, MicroStation and MDL commands terminate only when another command starts. The old command is not notified that another command is starting. The new command modifies only the state function pointers and the functions for the old command are not called again.

Parameters

[in]

unused

This argument is unused and will always be NULL

See also

StateCallback::SetCommandCleanupFunction

typedef void(* StateFunc_ComplexDynamics)(DPoint3dCP point, int view, DgnPlatform::DgnDrawMode drawMode)

If the current command state defines an update function for complex dynamics, MicroStation calls the function when the cursor is moved.

Parameters

[in]	point	the location of the pointer on the screen
[in]	view	the index of the view the pointer is currently positioned over
[in]	drawMode	either TEMPDRAW or TEMPERASE. These values are often passed to MicroStation functions and used to draw elements.

See also

StateCallback::SetComplexDynamicsFunction

typedef void(* StateFunc_DataPoint)(DPoint3dCP point, int view)

If the current command state defines a data point user function, the function is called when the user enters a data point.

The current point is passed to userState_datapoint in point and the view is passed in view. Before calling the data point user function, MicroStation adjusts the point that the user enters for the current locks (such as snap, grid and unit) and tentative point information. It then transforms the point to the current coordinate system.

Parameters

[in]	point	data point entered by user
[in]	view	the number of the view the data point was in

See also

StateCallback::SetDataPointFunction

typedef void(* StateFunc_DragInit)(DPoint3dCP point, int view)

UserFunction called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]	point	NEEDSWORK_VANCOUVER_DOC
[in]	view	NEEDSWORK_VANCOUVER_DOC

See also

StateCallback::SetDragInitFunction

typedef int(* StateFunc_FenceContentOp)(CallbackArgP userArgP, bool copyInClipMode)

The StateFunc_FenceContentOp function is called when the mdlFence_process function accepts an element.

mdlFence_process can either be called directly by MDL applications or by MicroStation if dataP is NULL for mdlState_startFenceCommand.

Parameters

[in]	userArgP	The userArg that was passed to mdlFence_process. MicroStation does not use it and applications use it for arguments and/or return status to/from StateFunc_FenceContentOp.
[in]	copyInClipMode	NEEDSWORK_VANCOUVER_DOC

Returns

If SUCCESS, the fence command continues. Otherwise, it stops.

See also

mdlState_startFenceCommand

typedef void(* StateFunc_FenceOp)(DPoint3dCP point, int view)

UserFunction called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]	point	NEEDSWORK_VANCOUVER_DOC
[in]	view	NEEDSWORK_VANCOUVER_DOC

See also

mdlState_startFenceCommand

typedef void(* StateFunc_Keyin)(WCharCP cmdstring, int cmdsource, WCharCP inputTaskId)

If the current command state defines a key-in user function, the function is called when the user enters a key-in.

Parameters

[in]	cmdstring	points to the key-in string. cmdStringP is never NULL.
[in]	cmdsource	NEEDSWORK_VANCOUVER_DOC
[in]	inputTaskId	NEEDSWORK_VANCOUVER_DOC

See also

StateCallback::SetKeyinFunction

typedef void(* StateFunc_Oops)(int numActions)

UserFunction called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]

numActions

NEEDSWORK_VANCOUVER_DOC

See also

StateCallback::SetOopsFunction

typedef void(* StateFunc_Redo)(int unused)

UserFunction called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]

unused

NEEDSWORK_VANCOUVER_DOC

typedef void(* StateFunc_Reset)(WCharCP unused)

If the current command state defines a Reset user function, MicroStation calls the function when the user enters a Reset.

Parameters

[in]

unused

This argument is unused and will always be NULL

Remarks

The unused argument is included because it is often convenient for tools to designate a CmdHandler to be called on a reset event.

See also

StateCallback::SetResetFunction

typedef void(* StateFunc_SimpleDescrDynamics)(MSElementDescrH edPP, DPoint3dCP point, int view)

UserFunction called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]	edPP	NEEDSWORK_VANCOUVER_DOC
[in]	point	NEEDSWORK_VANCOUVER_DOC
[in]	view	NEEDSWORK_VANCOUVER_DOC

See also

mdlState_simpleDynamicDescr

typedef void(* StateFunc_SimpleDynamics)(DPoint3dCP point, int view)

UserFunction called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]	point	NEEDSWORK_VANCOUVER_DOC
[in]	view	NEEDSWORK_VANCOUVER_DOC

See also

mdlState_dynamicUpdate

Function Documentation

void mdlAccuDraw_setEnabledState

(

bool

enable

)

Set the current state of the AccuDraw compass.

Parameters

[in]

enable

true to enable the compass; false to disable it.

Remarks

This function can be used by tools to enable/disable the AccuDraw compass at any point in their command logic, ex. compass only enabled after second data point and disabled again on the third, etc.

Required Library: mdlbltin.lib

bool mdlState_checkSingleShot

(

)

Determines whether the user wants the command to operate in single-shot mode.

When MicroStation runs in single-shot mode, the command returns to the default command when the current command completes. Otherwise, the current command remains active.

If single shot mode is active, this function calls mdlState_startDefaultCommand to restart the default command.

Returns

true if single-shot mode is active.

See also

mdlState_restartCurrentCommand

void mdlState_clear

(

)

Reset MicroStation's state to "no command active." After this function is called, all input that does not start a command is ignored.

The cursor is reset to the initial state and call prompts and messages are cleared.

Remarks

Applications usually call mdlState_startDefaultCommand rather than this function to return MicroStation to the default state. The default command is selected in the User Preferences dialog box.

See also

mdlState_startDefaultCommand mdlState_checkSingleShot

StateFunc_SimpleDynamics mdlState_dynamicUpdate	(	StateFunc_SimpleDynamics	dynamicfunc,
		int	validData
	)

Specify an MDL function to be used with simple dynamics.

The function determines the screen display as the cursor is moved. Dynamics are used only while a primitive command is active. Starting a view command suspends the dynamics associated with the active primitive command.

When an MDL application uses simple dynamics, the function is called to create or update an element in the dgnBuf. MicroStation draws the element in a temporary mode.

Dynamic functions are valid only when MicroStation is executing a primitive command. The function pointer for dynamic functions is reset every time a primitive is started. Elements are drawn by dynamics in a temporary mode. Elements drawn in a temporary mode are erased when state functions are cleared or when a new primitive is started.

MDL also supports complex dynamic updates. With complex dynamic updates, the MDL program must also erase and draw the elements. Complex dynamics are started by a call to the mdlState_setFunction function.

Parameters

[in]	dynamicfunc	function to become new dynamic update function.
[in]	validData	designates whether dgnBuf contains a valid element. If so, MicroStation draws that element as part of the dynamics initialization. Typically, validData is true when a modify command uses mdlState_dynamicUpdate. Otherwise, it is false.

Returns

the previous simple dynamic function.

See also

mdlState_setFunction mdlState_startPrimitive mdlState_startModifyCommand mdlState_startFenceCommand userState_dynamicUpdate userState_complexDynamicUpdate

mdlState_simpleDynamicDescr

void mdlState_exitViewCommand

(

bool

showMessage

)

Exit the current view command started by mdlState_startViewCommand.

Parameters

[in]

showMessage

if true, MicroStation displays "View command exited" in the prompt field.

See also

mdlState_startViewCommand

DgnPlatform::CoordinateLockOverrides mdlState_getCoordinateLockOverrides

(

)

Get the current state of the Coordinate Lock Overrides.

Commands can indicate that they do NOT want coordinate-modifying locks applied to datapoints, even when they are enabled by the user.

Returns

The current state of the coordinate locks overriddes.

Remarks

By default, all overrides are turned off when commands are started (e.g. via mdlState_startPrimitive).

WChar const* mdlState_getCurrentCommandName

(

)

Get the name of the current command as a WChar string.

Returns

a const pointer to the string holding the current command name.

See also

mdlState_setCurrentCommandName

void mdlState_registerStringIds	(	long	cmdStringID,
		long	promptStringID
	)

Specify the resource IDs that MicroStation uses when loading prompt and command strings for the application.

Parameters

[in]	cmdStringID	ID for command MessageList
[in]	promptStringID	ID for prompt MessageList

See also

mdlState_startPrimitive mdlState_startModifyCommand mdlState_startViewCommand

void mdlState_restartCurrentCommand

(

)

Restart the current primitive command.

This function first calls mdlState_checkSingleShot. If single-shot mode is not active, it clears the point stack, clears dgnBuf, and calls the current command's restart function.

If single-shot mode is active, it starts the default command.

MDL applications should call this function only from primitive commands.

Remarks

A command indirectly specifies the address of the restart function when it calls an mdlState_start... function. These functions call mdlState_startPrimitive. mdlState_startPrimitive sets the value of the restart function to the value specified as the reset function. mdlState_setFunction never changes this value.

See also

mdlState_checkSingleShot

void mdlState_restartCurrentCommandNoHome

(

)

This function simply calls mdlState_restartCurrentCommand but does not set focus to the Home position even if Position Mapping is turned on.

See also

mdlState_restartCurrentCommand

int mdlState_setAccudrawContext	(	long	flags,
		DPoint3dCP	origin,
		DPoint3dCP	delta,
		double const *	distance,
		double const *	angle,
		void *	orientation
	)

Provide "hints" to AccuDraw, so that it behaves properly in the context of the current tool.

MDL programmers writing placement or modification tools will find that they can greatly enhance the usability and power of their tools by optimizing them for AccuDraw with this function.

This function is typically called when starting a command, after receiving a data point, or in dialog item hook functions after a setting has been changed. It is not recommended to call it from a dynamics function. The effects of the hints are temporary – they will last only until a new primitive command is started. If AccuDraw is not active or the "Context Sensitivity" setting is turned off, the function will have no effect. Furthermore, the hints can be overridden by the user through AccuDraw's settings and shortcut commands.

Parameters

[in]	flags	hints from accudraw
[in]	origin	AccuDraw's origin point. This is only used if flags has ACCUDRAW_SetOrigin set.
[in]	delta	points to be used for AccuDraw's x, y and/or z offset value(s). This is only used if flags has ACCUDRAW_Lock_X, ACCUDRAW_Lock_Y, and/or ACCUDRAW_Lock_Z set.
[in]	distance	AccuDraw's distance. This is only used if flags has ACCUDRAW_SetDistance and/or ACCUDRAW_LockDistance set.
[in]	angle	AccuDraw's angle, expressed in radians. This is only used if flags has ACCUDRAW_LockAngle set.
[in]	orientation	a RotMatrix, an array of 3 unit vectors of type Dpoint3d, or a single unit vector of type Dpoint3d, to be used to define AccuDraw's drawing plane orientation. This is used if flags has ACCUDRAW_SetRMatrix, ACCUDRAW_Set3dMatrix, ACCUDRAW_SetXAxis or ACCUDRAW_SetNormal set.

Returns

SUCCESS if AccuDraw is active.

Remarks

It is recommended that you refer to the adrwdemo MDL example application for example commands which are optimized using this function.

The flags parameter is a bit mask indicating which hints are being sent. It is set by combining any number of hints defined in accudraw.h.

The function can be used to tell AccuDraw to use an origin point other than the default (last data point placed), to define the orientation (rotation) of AccuDraw's drawing plane, to lock the x, y or z coordinate value or the distance or angle, to force AccuDraw into either polar or rectangular coordinates, or to disable AccuDraw altogether for commands where it is not appropriate.

void mdlState_setCoordinateLockOverrides

(

DgnPlatform::CoordinateLockOverrides

overrides

)

Commands can indicate that they do NOT want coordinate-modifying locks applied to datapoints, even when they are enabled by the user.

Parameters

[in]

overrides

new value specifying which coordinate locks are to be overridden.

Remarks

By default, all overrides are turned off when commands are started (e.g. via mdlState_startPrimitive).

void mdlState_setCurrentCommandName

(

WChar const *

newName

)

Set the name of the current command using a WChar string.

The "name" of the command is the string that is written to the prompt field, and is used to describe the command for UNDO/REDO. Ordinarily the name is set through the "funcname" argument to mdlState_startPrimitive, mdlState_startModifyCommand, etc. However, sometimes tools do not have an appropriate string list for the command name and/or the name of the command changes during the course of the command. This function allows tools to set the command name directly.

Parameters

[in]

newName

a string that provides the current command's name.

Remarks

This function should be called AFTER the call to mdlState_startPrimitive, mdlState_startModifyCmd, etc. since they set the current command name implicitly. &

See also

mdlState_getCurrentCommandName

void mdlState_setKeyinPrompt

(

WCharCP

pPrompt

)

Specify a string to be used as the prompt in the key-in area in MicroStation's command window.

The next time a primitive command starts, the prompt is automatically restored to MicroStation's prompt.

Parameters

[in]

pPrompt

prompt string

StateFunc_SimpleDescrDynamics mdlState_simpleDynamicDescr	(	StateFunc_SimpleDescrDynamics	dynamicfunc,
		int	validData
	)

Specify an MDL function to be used with simple dynamics.

This function is called with an element descriptor.

Parameters

[in]	dynamicfunc	function in MDL program
[in]	validData	designates whether dgnBuf contains a valid element.

Returns

the previous simple dynamic function.

See also

mdlState_dynamicUpdate

void mdlState_startDefaultCommand

(

)

Start the default command.

Generally, Primitive commands do not terminate until another command is started. Primitive commands call mdlState_checkSingleShot and utility commands call mdlState_startDefaultCommand.

void mdlState_startFenceCommand	(	StateFunc_FenceContentOp	contentOp,
		StateFunc_FenceOp	fenceOp,
		StateFunc_DataPoint	dataFunc,
		StateFunc_Reset	resetFunc,
		int	funcname,
		int	promptNum,
		int	inputClipMode
	)

Start a command that will operate on the contents of a fence.

Parameters

[in]	contentOp	MDL function to be called to process the fence elements. This function is called once for every element that satisfies the fence criteria.
[in]	fenceOp	MDL function to be called to display the new fence outline. This argument is often NULL, since it is used only if the entire fence is being moved, scaled, or rotated.
[in]	dataFunc	MDL function to be called when a data point is entered. If NULL, MicroStation set mdlFence_process as the data point function.
[in]	resetFunc	MDL function to be called when a Reset is entered.
[in]	funcname	Command name.
[in]	promptNum	Prompt number
[in]	inputClipMode	Determines the way the command wants MicroStation to treat the elements that overlap the fence when fence lock is turned on. Possible values are: inputClipMode Meaning FENCE_NO_CLIP Do not allow command to continue if user has clip lock turned on. FENCE_CLIP_ORIG If fence clip lock is on, clip original elements before calling contentOp. FENCE_CLIP_COPY If fence clip lock is on, copy the element before clipping it and then call contentOp for the clipped copy.

See also

mdlState_registerStringIds userState_fenceContent userState_fenceOutline

void mdlState_startModifyCommand	(	StateFunc_Reset	resetFunc,
		MdlFunc_Accept	acceptFunc,
		StateFunc_SimpleDynamics	dynamicFunc,
		MdlFunc_Show	showFunc,
		MdlFunc_Clean	cleanFunc,
		int	cmdMsgNum,
		int	acceptPrompt,
		bool	useSelection,
		int	needPoints
	)

Start a command that will locate and modify elements.

MicroStation's element location logic performs a majority of modify command functionality. This function ensures that all modification functions operate in a similar manner.

Parameters

[in]	resetFunc	Function called when the user clicks the Reset button.
[in]	acceptFunc	Function called when the user identifies and accepts the element(s) to be modified - either via Selection Set or through the ~s"Picking Elements" procedures.
[in]	dynamicFunc	Function called for dynamic display.
[in]	showFunc	Function called when the element has been located.
[in]	cleanFunc	Function that cleans up the effects of showFunc.
[in]	cmdMsgNum	String in MessageList resources in the application's resource file.
[in]	acceptPrompt	String in MessageList resources in the application's resource file.
[in]	useSelection	How the tool works with Selection Sets.
[in]	needPoints	0, 1, or 2

Remarks

Accept functions for element modification commands generally use the ~s"Element Modification" functions to change the selected element(s). When the accept function is called, the point that the user gave to identify the element is in statedata.pointstack[0], and is passed as the first argument to the data point function.

Once the data point is entered, MicroStation uses acceptFunc as the new data point function. It also displays the prompt specified by acceptPromptNum.

Remarks

The cleanup function is called if the user enters Reset after an element is located.

NULL is commonly specified for showFunc and cleanFunc. As an example,MicroStation uses clean and show functions for the fillet command. See mdlState_show and mdlState_clean for more information on these functions.

Remarks

Users can employ two methods to identify elements for the element modification commands. The command can prompt the user to identify an element (or set of elements) and wait until the user identifies and then accepts the elements. Alternatively, Selection Sets can be used. Selection Sets are a group of elements that the user identifies before activating the element modification command. Some modification commands (such as delete, copy, or move element) understand selection sets, whereas others (such as extend line and fillet) do not. When writing element modification commands, you must decide whether you will accept selection sets to identify elements.

If needPoints is 0, MicroStation immediately calls the accept function. For example, the MicroStation DELETE ELEMENT command does not need additional data points. Commands use 0 for needPoints if they need only to know which elements are to be involved in the operation.

If needPoints is 1, MicroStation calls mdlState_startPrimitive, specifying acceptFunc as the data point function and acceptPromptNum as the prompt.

If needPoints is 2, MicroStation first calls mdlState_startPrimitive, specifying an internal MicroStation function as the data point function. This function puts a data point in statedata.pointstack [0].

Remarks

When a Selection Set is used, MicroStation's modify logic skips the element identification and acceptance steps, since the elements have already been identified. If useSel is non-zero and at least one element is selected, needPoints tells MicroStation the number of additional data points required.

The mdlState_startModifyCommand function automatically establishes the proper sequence for modification commands so the user interface is the same. It uses the following logic:

if (useSelection is true and a Selection Set is active)
    {
    if (needsPoints is 0)
        {
        // command does not need additional data points
        call the acceptFunc function;
        }
   else if (needsPoints is 1)
        {
        // command needs one additional data point
        call mdlState_startPrimitive with acceptFunc as the data
        point function and mdlState_restartCurrentCommand as
        the reset function;
        load dynamic buffer with entire Selection Set;
        }
   else if (needsPoints is 2)
        {
        // cmd needs more than one additional data pt
        save acceptFunc function, dynamicFunc function, and acceptPrompt;
        display "enter first point (selection set)" prompt;
        call mdlState_startPrimitive with an internal function
        that gets the anchor point as the data point function;
        }
    }
else
    {
    // useSelection is false, or no active selection set
    clear Selection Set if one is active;
    call mdlState_startPrimitive with mdlLocate_identifyElement as
    the data point function;
    put out "Identify element" prompt;
    save info specified as arguments (prompts & function pointers);
    set cursor to the "Locate Element" cursor;
    }

The application can control the Element Location routine operation by filtering elements in a LocateFunc_locateFilter user function.

When a modify command completes, it calls mdlLocate_restart. This function calls mdlState_checkSingleShot. Depending on the return value of mdlState_checkSingleShot, mdlLocate_restart restarts either the modify command or the default command.

void mdlState_startPrimitive	(	StateFunc_DataPoint	datafunc,
		StateFunc_Reset	resetfunc,
		int	funcname,
		int	prompt
	)

Start a MicroStation Primitive command.

Parameters

[in]	datafunc	specifies a function to be called if a data point is entered.
[in]	resetfunc	specifies a function to be called if Reset is entered. MicroStation also uses the function specified by resetFunc as the restart function (see mdlState_restartCurrentCommand). The values of these arguments can be valid MDL function pointers or NULL.
[in]	funcname	and prompt are integers that specify strings in MessageList resources in the application's resource file. The strings corresponding to these numbers display as the current command name and the initial prompt. If these strings are zero, nothing displays for the command or prompt. Also, the undo logic records the funcName value and uses it to display the command name if the Undo command is used to undo the command.
[in]	prompt	same as funcname

Remarks

This function terminates active commands. It also clears highlighting remaining from the previous command. If a temporary element remains from a previous command, this function erases it. It resets snap data, clears all state data, and sets up the state data using dataFunc, resetFunc, funcname and prompt.

See also

mdlState_startPrimitiveAndSetPopupMenu mdlState_startModifyCommand mdlState_startFenceCommand mdlState_startViewCommand mdlState_setFunction mdlState_registerStringIdsC

DItem_PulldownMenu* mdlState_startPrimitiveAndSetPopupMenu	(	StateFunc_DataPoint	datafunc,
		StateFunc_Reset	resetfunc,
		int	funcname,
		int	prompt,
		UInt32	menuType,
		long	menuId,
		MdlDesc *	ownerMD
	)

Start a Primitive command and set the pop-up menu simultaneously.

See the discussion of mdlState_startPrimitive for the use of the first four parameters.

Parameters

[in]	datafunc	data point function or NULL
[in]	resetfunc	reset function or NULL
[in]	funcname	index into message list
[in]	prompt	index into message list
[in]	menuType	type of menu to insert into view popup; 0=Text
[in]	menuId	id of menu to insert into view popup
[in]	ownerMD	usually NULL

Remarks

The menu to add is identified by menuType and menuId, belonging to the MDL task specified by ownerMD. If ownerMD is NULL, as is usually the case, the current task is the owner.

Returns

The inserted menu, or NULL if there was an error.

See also

mdlView_setPopupMenu mdlState_startPrimitive mdlWindow_isPopUp

void mdlState_startViewCommand	(	StateFunc_DataPoint	datafunc,
		int	funcname,
		int	prompt
	)

Start a MicroStation Viewing command.

Parameters

[in]	datafunc	a function to be called when a data point is entered.
[in]	funcname	a command name.
[in]	prompt	a prompt number.

Remarks

Both funcname and prompt are string numbers for MessageList resources in the application's resource file. If either parameter is 0, it is ignored.

See also

mdlState_setFunction

static StateFunc_CommandCleanup SetCommandCleanupFunction ( StateFunc_CommandCleanup  newFunc )

static

An MDL application can use this to set a function to be called when a command is terminated.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_CommandCleanup

static StateFunc_ComplexDynamics SetComplexDynamicsFunction ( StateFunc_ComplexDynamics  newFunc )

static

An MDL application can use this to set a function to be called when the cursor is moved.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_ComplexDynamics

static StateFunc_DataPoint SetDataPointFunction ( StateFunc_DataPoint  newFunc )

static

An MDL application can use this to set a function to be called when the user enters a data point.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_DataPoint

static StateFunc_DragInit SetDragInitFunction ( StateFunc_DragInit  newFunc )

static

An MDL application can use this to set a function to be called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_DragInit

static StateFunc_Keyin SetKeyinFunction ( StateFunc_Keyin  newFunc )

static

An MDL application can use this to set a function to be called when the user enters a key-in.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_Keyin

static StateFunc_Oops SetOopsFunction ( StateFunc_Oops  newFunc )

static

An MDL application can use this to set a function to be called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_Oops

static StateFunc_Redo SetRedoFunction ( StateFunc_Redo  newFunc )

static

An MDL application can use this to set a function to be called when NEEDSWORK_VANCOUVER_DOC.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_Redo

static StateFunc_Reset SetResetFunction ( StateFunc_Reset  newFunc )

static

An MDL application can use this to set a function to be called when the user enters a Reset.

Parameters

[in]

newFunc

The new function to call, or NULL.

Returns

The return value is the previous function that was set for this MdlApp, NULL if no previous function was defined.

See also

StateFunc_Reset