9.0.0

Creates a new user defined tool, its first prompt, and its user tool behavior.

extern "C" void WINAPI VCSetUserToolEx(short iStates, char* szNativeCmd, char* szFirstPrompt, DWORD dw);

procedure VCSetUserToolEx(iStates: SmallInt; szNativeCmd: PAnsiChar; szFirstPrompt: PAnsiChar; dw: LongWord); stdcall;

Sub SetUserToolEx(ByVal iStates As Integer, ByVal szNativeCmd As String, ByVal szFirstPrompt As String, ByVal dw As Long)

iStates - number of steps the user tool uses (-1 specifies a continuous tool that ends with Esc or a PenUp)
szNativeCmd - name of a custom native command as defined in CmdExt.vcdef
szFirstPrompt - string used as the first prompt for the user tool
dw - bit flags to control user tool behavior which are combined by 'or' (|)
USERTOOL_IS_NESTED (0x00000001) - user tool is nested and does not abort the current tool
USERTOOL_IS_SNAP (0x00000002) - nested user tool is a snap, requires also setting USERTOOL_IS_NESTED
USERTOOL_USES_RUNNING_SNAPS (0x00000004) - user tool accepts running snaps
USERTOOL_PASSTRHU_MOUSEMOVE (0x00000008) - nested user tool passes mouse moves to the previous tool, usually for rubberband purposes, requires also setting USERTOOL_IS_NESTED
USERTOOL_PASSTRHU_RUBBERSTATE (0x00000010) - nested user tool uses the rubberband state from the previous tool, usually for rubberband purposes, requires also setting USERTOOL_IS_NESTED

Setting the parameter dw=0 is equivalent to using VCSetUserTool to create the user tool.

Until the introduction of VCSetUserToolEx in v9.0.0, user tools were created by using VCSetUserTool, were non-nested so always aborted the current tool, and could optionally use running snaps. Previously, nested tools could only be developed using the API by not calling VCSetUserTool and instead using alert app callbacks and managing the status bar prompts to emulate nested tool behavior.

VCSetUserToolEx supports user tools using running snaps as did VCSetUserTool, plus supports nested tools which do not abort the current tool and optional features of nestable tools such as snap tools which return a snap point to the previous tool and passing mouse moves to the previous tool for rubberband purposes.

Please note that nestable user tools must set the USERTOOL_IS_NESTED flag when calling VCSetUserToolEx. The USERTOOL_IS_NESTED flag cannot later be changed by VCSetUserToolFlags. The USERTOOL_IS_NESTED flag is fixed for the duration of the user tool. All other options can be changed while the user tool is running, for example, to begin as a non-snap and at some stage of the user tool change to being a snap, although as described under the parameters, certain options require that the user tool be nestable.

VCSetUserTool, VCGetPrompt, VCSetAlertAppDll, VCClearAlertAppDll, VCGetUserToolFlags, VCGetUserToolIsSnap, VCGetUserToolSnapPoint, VCGetUserToolSnapable