C++ Syntax

void

MKI_DialogUpdateGuide(

__int32 f_nGuideMode,

const LPCWSTR f_pszGuideText );

Displays the given texts in the guide window (if visible at the moment) ans/or at the crosshairs (if active).

Parameters

GuideMode

[__int32] This value is a bit-wise OR combination of some predefined flags that define frequently used texts, plus an optional flag that allows the use of a plug-in-defined additional text. Available flags are:

MKI_GUIDE_SINGLE_OBJ

Standard texts for single object identification.

MKI_GUIDE_MULTI_OBJ

Standard texts for multiple object choosing. Should be combined with MKI_GUIDE_SINGLE_OBJ.

MKI_GUIDE_SINGLE_POINT

Standard texts for single point identification.

MKI_GUIDE_MULTI_POINT

Standard texts for multiple point choosing. Should be combined with MKI_GUIDE_SINGLE_POINT.

MKI_GUIDE_PARAMETER

Standard text for commands that allow parameter editing.

MKI_GUIDE_ARC_DIRECTION

Standard text for commands that make use of the arc direction.

MKI_GUIDE_ARC_MODE

Standard text for commands that make use of the arc mode.

MKI_GUIDE_COORDINATES

Standard text for point entries that make use of direct coordinate entry.

MKI_GUIDE_SNAP

Standard text for point entries that make use of snap functions.

MKI_GUIDE_GRID

Standard text for point entries that make use of grid functions.

MKI_GUIDE_DUPLICATE

Standard text for point entries that make use of the duplicate function. Should not be combined with MKI_GUIDE_MULTILINE.

MKI_GUIDE_MULTILINE

Standard text for point entries that make use of the multiline function. Should not be combined with MKI_GUIDE_DUPLICATE.

MKI_GUIDE_ESC

Standard text for commands that require more than one point and that allow to re-enter previously entered points.

MKI_GUIDE_RBUTTON_CANCEL Renamed in Version 2023.1

Standard text for commands that can be cancelled by pressing the right mouse button. Should not be combined with MKI_GUIDE_RBUTTON_FINISH or MKI_GUIDE_RBUTTON_OPTION.

MKI_GUIDE_RBUTTON_FINISH Renamed in Version 2023.1

Standard text for commands that require a variable number of point entries and that are finished by pressing the right mouse button. Should not be combined with MKI_GUIDE_RBUTTON_CANCEL or MKI_GUIDE_RBUTTON_OPTION.

MKI_GUIDE_RBUTTON_OPTION New in Version 2023.1

Standard text for commands that will display an options dialog when pressing the right mouse button. Should not be combined with MKI_GUIDE_RBUTTON_CANCEL or MKI_GUIDE_RBUTTON_FINISH.

MKI_GUIDE_ENTRY

Standard text displayed during coordinate entry. Should not be combined with any flag except with either MKI_GUIDE_DUPLICATE or MKI_GUIDE_MULTILINE.

MKI_GUIDE_DEFAULT

If this flag is set, all currently "useful" flags of those described above will be set.

MKI_GUIDE_EXTERNAL

If this flag is set, and GuideText points to a valid text, that text will be displayed in the guide window. If additional texts are to be display since other flags are set, this external text will be displayed at the end of the list.

GuideText

[const LPCWSTR] Address of a text to be displayed in the guide window. The text can be a multi-paragraph, multi-line text. Each line is to be ended by a '\n' character, each paragraph by a '\0' character. The complete text must be ended by a double '\0'. Each new paragraph will start with a red square. A valid guide text would be:

"Move in 45° steps: Press SHIFT\0Define steps: SHIFT+ESC\0\0"

The text whose address is passed in GuideText must remain valid until MKI_DialogUpdateGuide() is called with another value of GuideText! To avoid problems, call this procedure with a GuideMode of MKI_GUIDE_DEFAULT and GuideText set to nullptr as soon as the custom display is no longer required.

Comment

This procedure will usually be called inside the MKI_InputPointInitProc called during command processing. Each time a new point entry is started, the content of the guide window is reset, so the plug-in should call MKI_DialogUpdateGuide() at each call of the MKI_InputPointInitProc.

In most cases, its best to combine MKI_GUIDE_DEFAULT to get the default messages, MKI_GUIDE_EXTERNAL to add a plug-in-defined text and maybe some other mode to explicitly activate messages that would normally not be active.