'================================================================
' ALERTS.TXT -- Visual Cadd 4.0.0 Documentation for PB/DLL6.0
' Samples for VCSetAlertAppDll and VCSetAlertAppDllEx callbacks
' To be used as a template for user-defined callbacks.
' Last Update: November 18, 2000
'================================================================
'
' These callbacks are user-defined and exported from the user's
' DLL.  Each code set in VCSetAlertAppDll(Ex) results in calls
' to one of these callbacks.  Refer to each callback sample
' below for details about parameters and when it is called.
'
' Syntax for VCSetAlertAppDll:
'   CALL VCSetAlertAppDll (iError, "YourAlert.dll", _
'                         "YourAlertName", iCode0)
'
' Syntax FOR VCSetAlertAppDllEx:
'   CALL VCSetAlertAppDllEx (iError, "YourAlert.dll", _
'                           "YourAlertName", iCode0, iCode1)
'
' "YourAlert.dll" is the name of the DLL containing the callbacks.
' Substitute the name of your custom DLL.
'
' "YourAlertName" is the name which prefixes the function names
' in the callbacks.  Substitute your custom name both in 
' VCSetAlertAppDll(Ex) and in the samples below.
'
' iCode0, iCode1 are the codes for the alerts which you desire.
'
' Refer to VCType.inc or the API Help file for their values.
' Codes which begin ALERT_APP_... are used in the iCode0
' parameter of either VCSetAlertAppDll or VCSetAlertAppDllEx.
' Codes which begin ALERT_APP_EX_... are used in the iCode1
' parameter of VCSetAlertAppDllEx.  Refer to the API Help file
' for further information.
'
' Parameters, in general:
'   All of the callbacks are defined with a parameter list.
'   Many of the callbacks do not pass actual parameters, so the
'   parameter list is merely a place holder.  It is important to
'   retain these placeholders, because VCADD expects this syntax.
'   Where parameters are actually passed, the declaration uses a
'   parameter name and gives a description of the parameter.
'
'=================================================================
' user-tool initiating - ALERT_APP_UTOOL_INIT
' parameter: LOWRD(lCmdID) is Tool ID
' note: called when a user-tool, started by VCSetUserTool,
'       is starting.
SUB Your_Init ALIAS "YourAlertName_Init" _
    (BYVAL wParam AS LONG, BYVAL lCmdID AS LONG) EXPORT
'=================================================================
' user-tool terminating - ALERT_APP_UTOOL_TERMINATE
' note: called when a user-tool, started by VCSetUserTool,
'       is terminating.
SUB Your_Terminate ALIAS "YourAlertName_Terminate" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' user-tool aborting - ALERT_APP_UTOOL_ABORT
' note: called when a user-tool, started by VCSetUserTool,
'       is aborting.
SUB Your_Abort ALIAS "YourAlertName_Abort" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' user-tool mousedown - ALERT_APP_UTOOL_MOUSEDOWN
' note: called when a user-tool, started by VCSetUserTool,
'       receives mouse-click input from the user.
'       Points entered by the user from the keyboard are
'       translated into the equivalent mouse-click and sent
'       as a mouse-down.  Refer to API Help file for
'       VCGetUserToolLBDown for mousedown location.
SUB Your_MouseDown ALIAS "YourAlertName_MouseDown" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' user-tool mousemove - ALERT_APP_UTOOL_MOUSEMOVE
' note: called when a user-tool, started by VCSetUserTool,
'       receives mousemove input from the user.  Refer to API Help
'       file for VCGetUserToolMouseMove for mousemove location.
SUB Your_MouseMove ALIAS "YourAlertName_MouseMove" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' user-tool mouseup - ALERT_APP_UTOOL_MOUSEUP
' note: called when a user-tool, started by VCSetUserTool,
'       receives mouseup input from the user.  Refer to API Help
'       file for VCGetUserToolLBUp for mouseup location.
SUB Your_MouseUp ALIAS "YourAlertName_MouseUp" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' user-tool penup - ALERT_APP_UTOOL_PENUP
' note: called when a user-tool, started by VCSetUserTool,
'       receives PenUp from the user.
SUB Your_PenUp ALIAS "YourAlertName_PenUp _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' user-tool erase rubberband - ALERT_APP_UTOOL_ERASERUBBER
' note: called when a user-tool, started by VCSetUserTool,
'       needs to erase any possible rubberband from the screen,
'       due to VCADD needing to change or redraw the drawing view.
SUB Your_EraseRubber ALIAS "YourAlertName_EraseRubber" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' tool start - ALERT_APP_TOOL_START
' parameters: LOWRD(lParam) is Tool ID, HIWRD(lParam) is Tool Type
' Tool Type: 0, tool will abort other running tools
'            1, tool is nestable in other running tools
'            2, tool is nestable and generates tool start
'               and complete messages
' note: called when a tool is starting.
'       When the user completes a tool normally, 
'       the typical sequence is:
'         1. Tool_Complete on tool completing.
'         2. Tool_Start on the default tool as it restarts.
'       When the user aborts a tool with Escape key,
'       the typical sequence is:
'         1. Tool_Abort on tool aborting.
'         2. Tool_Complete on tool aborting.
'         3. Tool_Start on the default tool as it restarts.
'       When the user aborts a tool by starting another tool,
'       the typical sequence is:
'         1. Tool_Start on the tool the user started.
'         2. Tool_Abort on tool aborting.
'         3. Tool_Complete on tool aborting.
SUB Your_ToolStart ALIAS "YourAlertName_ToolStart" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' tool complete - ALERT_APP_TOOL_COMPLETE
' parameters: LOWRD(lParam) is Tool ID, HIWRD(lParam) is Tool Type
' Tool Type: 0, tool will abort other running tools
'            1, tool is nestable in other running tools
'            2, tool is nestable and generates tool start
'               and complete messages
' note: called when a tool is completing.  See ToolStart for
'       discussion of when this alert is generated.
SUB Your_ToolComplete ALIAS "YourAlertName_ToolComplete" _
                      (wParam AS LONG, lParam AS LONG) EXPORT
'=================================================================
' tool abort - ALERT_APP_TOOL_ABORT
' parameters: LOWRD(lParam) is Tool ID, HIWRD(lParam) is Tool Type
' Tool Type: 0, tool will abort other running tools
'            1, tool is nestable in other running tools
'            2, tool is nestable and generates tool start
'               and complete messages
' note: called when a tool is aborting.  See ToolStart for
'       discussion of when this alert is generated.
SUB Your_ToolAbort ALIAS "YourAlertName_ToolAbort" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' world mousedown - ALERT_APP_WORLD_MOUSEDOWN
' note: called when the user mouse-clicks in the drawing.
'       This callback will receive all mousedowns, compared to the
'       callback for user-tools which receives only mousedowns for
'       that user-tool.  Refer to API Help file for VCGetLastPoint
'       for mousedown location.
SUB Your_WorldMouseDown ALIAS "YourAlertName_WorldMouseDown" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' world mouseup - ALERT_APP_WORLD_MOUSEUP
' note: called when the user mouseups in the drawing.
SUB Your_WorldMouseUp ALIAS "YourAlertName_WorldMouseUp" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' world mousemove - ALERT_APP_WORLD_MOUSEMOVE
' note: called when the user mousemoves in the drawing.  Refer to
' API Help file for VCGetCurrentPoint for mousemove location.
SUB Your_WorldMouseMove ALIAS "YourAlertName_WorldMouseMove" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' command line character - ALERT_APP_CMDLINE_CHAR
' parameter: LOWRD(wChar) is character code
' note: called when the user enters command line input from the
'       keyboard.  Command line input may also be captured through
'       PreTranslateGetMessage and the WM_CHAR message.
'       That method may have advantages in certain cases,
'       as it allows the message TO be 'eaten' and
'       not passed on to VCADD.
SUB Your_Char ALIAS "YourAlertName_Char" _
    (BYVAL wChar AS LONG, BYVAL lParam AS LONG) EXPORT
' ================================================================
' entity erased - ALERT_APP_ENTITY_ERASED
' note: called when an entity is erased.
SUB Your_EntityErased ALIAS "YourAlertName_EntityErased" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' entity selected - ALERT_APP_ENTITY_SELECT_CHANGE
' note: called when an entity selection changes.
SUB Your_EntitySelectChange ALIAS "YourAlertName_EntitySelectChange" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' beginning to redraw - ALERT_APP_WORLD_BEGIN_REDRAW
' note: called when a drawing begins to redraw.
SUB Your_WorldBeginRedraw ALIAS "YourAlertName_WorldBeginRedraw" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' done redrawing - ALERT_APP_WORLD_END_REDRAW
' note: called when a drawing completes redrawing.
SUB Your_WorldEndRedraw ALIAS "YourAlertName_WorldEndRedraw" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' beginning to print - ALERT_APP_WORLD_BEGIN_PRINT
' note: called when a drawing begins to print.
SUB Your_WorldBeginPrint ALIAS "YourAlertName_WorldBeginPrint" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' done printing - ALERT_APP_WORLD_END_PRINT
' note: called when a drawing completes printing.
SUB Your_WorldEndPrint ALIAS "YourAlertName_WorldEndPrint" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' dialog opening - ALERT_APP_EX_DIALOG_OPEN_MESSAGE
' parameter: LOWRD(lDlgID) is Dialog ID
' note: called when a dialog has opened.
SUB Your_DialogOpen ALIAS "YourAlertName_DialogOpen" _
    (BYVAL wParam AS LONG, BYVAL lDlgID AS LONG) EXPORT
'=================================================================
' dialog closing - ALERT_APP_EX_DIALOG_CLOSE_MESSAGE
' parameter: LOWRD(lDlgID) is Dialog ID
' note: called when a dialog has closed.
SUB Your_DialogClose ALIAS "YourAlertName_DialogClose" _
    (BYVAL wParam AS LONG, BYVAL lDlgID AS LONG) EXPORT
'=================================================================
' VCADD application closing - ALERT_APP_CLOSE
' note: called when the VCADD application is closing.
SUB Your_AppClose ALIAS "YourAlertName_AppClose" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' VCADD drawing closing - ALERT_APP_WORLD_CLOSE
' note: called when a VCADD drawing is closing.
SUB Your_DrawingClose ALIAS "YourAlertName_DrawingClose" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' VCADD main frame closing - ALERT_APP_FRAME_CLOSE
' note: called when the main VCADD frame window is closing.
SUB Your_FrameClose ALIAS "YourAlertName_FrameClose" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' VCADD main frame resizing - ALERT_APP_FRAME_RESIZE
' note: called when the main VCADD frame window is resizing.
SUB Your_FrameResize ALIAS "YourAlertName_FrameResize" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' VCADD activating - ALERT_APP_ACTIVATE
' note: called when the VCADD application is being activated.
SUB Your_Activate ALIAS "YourAlertName_Activate" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' VCADD deactivating - ALERT_APP_DEACTIVATE
' note: called when the VCADD application is being de-activated.
SUB Your_DeActivate ALIAS "YourAlertName_DeActivate" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' VCADD user-alert received - ALERT_APP_EX_USER_ALERT_MESSAGE
' parameter: lParam is the code sent by user
' notes: called when VCADD receives a user alert sent by the
'        user's application.  This is analogous TO WM_USER
'        messages and allows the user to send and process
'        user-defined messages.  User posts a user alert to
'        VCADD with the following:
'        lError = PostMessage (VCGethWndFrame(), %WM_COMMAND, _
'                              %VCM_USER_ALERT, lParam)
'        Note:  %VCM_USER_ALERT is defined as 2801 in VCType32.inc
SUB Your_UserAlert ALIAS "YourAlertName_UserAlert" _
    (BYVAL wParam AS LONG, BYVAL lParam AS LONG) EXPORT
'=================================================================
' VCADD GetMessage (from PostMessage) -
'       ALERT_APP_EX_PRE_TRANSLATE_GET_MESSAGE
' parameter: pMsg is pointer to Windows message structure
' return value: TRUE to eat message and not allow VCADD
'                    to process it
'               FALSE to allow VCADD TO process message
' notes: called when VCADD gets a message from the Windows
'        message queue.  Messages in this queue originate as
'        PostMessages.  VCADD can be prevented from receiving
'        and processing the message by returning TRUE from
'        this callback function.
FUNCTION Your_PreTranslateMessage _
         ALIAS "YourAlertName_PreTranslateGetMessage" _
               (pMsg AS tagMSG) EXPORT AS LONG
'=================================================================
' VCADD FrameMessage (from SendMessage) -
'       ALERT_APP_EX_PRE_TRANSLATE_FRAME_MESSAGE
' parameter: pMsg is pointer to Windows message structure
' return value: TRUE to eat message and not allow VCADD
'               to process it
'               FALSE to allow VCADD to process message
' notes: called when VCADD handles a Windows SendMessage.
'        VCADD can be prevented from receiving and processing the
'        message by returning TRUE from this callback function.
FUNCTION Your_PreTranslateFrameMessage _
         ALIAS "YourAlertName_PreTranslateFrameMessage" _
               (pMsg AS tagMSG) EXPORT AS LONG
'=================================================================
' VCADD dialog messages -
'       ALERT_APP_EX_PRE_TRANSLATE_DIALOG_MESSAGE
' parameter: pMsg is pointer TO Windows message structure
' return value: TRUE to eat message and not allow VCADD
'               to process it
'               FALSE to allow VCADD TO process message
' notes: called when VCADD processes dialog box messages.
'        VCADD can be prevented from receiving and processing the
'        message by returning TRUE from this callback function.
FUNCTION Your_PreTranslateDialogMessage _
         ALIAS "YourAlertName_PreTranslateDialogMessage" _
               (pMsg AS tagMSG) EXPORT AS LONG
'=================================================================
' VCADD MDI window messages -
'       ALERT_APP_EX_PRE_TRANSLATE_MDICHILD_MESSAGE
' paramter: pMsg is pointer to Windows message structure
' return value: TRUE to eat message and not allow VCADD
'               to process it
'               FALSE to allow VCADD to process message
' notes: called when VCADD processes MDI child messsages.
'        VCADD can be prevented from receiving and processing the
'        message by returning TRUE from this callback function.
FUNCTION Your_PreTranslateMdiChildMessage _
         ALIAS "YourAlertName_PreTranslateMdiChildMessage" _
               (pMsg as tagMSG) EXPORT AS LONG
'=================================================================