TRAPCLOSE

Description

Used to properly handle terminating the program, if a user clicks the red "X" close button or uses the system menu to close the window. This command is mandatory for any program that uses a Graphical User Interface (GUI) window. If you do not act on closing the window, the process will continue to run in the background, which is bad practice.

The event handler for TRAPCLOSE usually includes the following actions:

terminating the TIMER
unloading all loaded images using UNLOADBMP
closing the window using CLOSE
terminating the process using END

FYI: The trapclose statement gives your BASIC program control of terminating it correctly, instead of closing only the window.

Syntax

#handle "trapclose [branch]"
#handle "trapclose subName"
When using with a window of type text:
- #handle "!trapclose [branch]...or subName"

Hints

If you include a drop down menu with a Close or Exit option, or if you provide a button to Close or Exit your program, you will write an event handler for that option. That same event handler can be the routine where your trapclose command branches if the user clicks the red "X" or uses Alt+F4 to close the window. In that way, you can ensure that any clean-up, file closing, or last minute instructions to the user will be handled whichever way the program or window is closed.

When using a sub event handler, the window's handle must be passed to the sub as a parameter such as handle$. If the sub is being used to terminate the program, which is probably the case since a user may have clicked on the red "X", be sure to include an END statement within the sub. Otherwise, the window will be closed but the sub will return program flow to the first WAIT statement after the OPEN window command. If an END statement is not encountered, the program will continue running in the background - you just won't know it.

If the window is of type "text", use an exclamation mark (!), before trapclose to send the statement as a command rather than ordinary text.

Window of type dialog closes on pressing ESC key. Close event is trapped in this case, too. (See example).

This command is not used if your program is text-based running in a main window (console). Closing the main window terminates the program.

Example

' Using trapclose with branch label event handler
    nomainwin

    statictext #myWindow.msg "", 40, 40, 200, 250

    open "Trapclose Test Window" for window as #myWindow
    #myWindow "trapclose [quit]"

    ' Prompt the user for the action
    #myWindow.msg "Click the red 'X' to close this window."; chr$(13); chr$(13);_
                "If the TRAPCLOSE statement is not provided, the ";_
                "operating system (WINDOWS) will close the window without your ";_
                "program having the opportunity to close any open ";_
                "files, etc. This could lead to a loss of data and Error messages!";_
                chr$(13); chr$(13);_
                "Run this program again using Alt+F4 to close the window."
    wait

' This is the branch for the event handler
[quit]
    notice "For your protection..."; chr$(13); "Always include a TRAPCLOSE statement.";_
    chr$(13); "The window will close when you click 'OK' to this notice."
    close #myWindow
    end

' Using trapclose with a sub as an event handler
    nomainwin

    statictext #myWindow.msg "", 40, 40, 200, 250

    open "Trapclose Test Window" for window as #myWindow
    #myWindow "trapclose closeMeBaby"

    ' Prompt the user for the action
    #myWindow.msg "Click the red 'X' to close this window."; chr$(13); chr$(13);_
                "If the TRAPCLOSE statement is not provided, the ";_
                "operating system (WINDOWS) will close the window without your ";_
                "program having the opportunity to close any open ";_
                "files, etc. This could lead to a loss of data and Error messages!";_
                chr$(13); chr$(13);_
                "Run this program again using Alt+F4 to close the window."
    wait

' This is the sub that handles the close event. The handle of the window
' that called the sub is passed to the sub through the parameter handle$.
' The parameter can be any string variable name you choose to use but 'handle$'
' is an appropriate descriptive name, and is often used.
sub closeMeBaby handle$
    notice "For your protection..."; chr$(13); "Always include a TRAPCLOSE statement.";_
    chr$(13); "The window will close when you click 'OK' to this notice."
    ' The sharp sign, (#), must precede the parameter name. This is because
    ' the parameter represents the window's '#handle', which is always
    ' preceded by a sharp sign.
    close #handle$
    end
end sub

' An example using the ESC key to close a DIALOG window and showing that the
'  trapclose event handler is still called. This allows you to process final 
'  instructions even if the ESC key is used to close the window.
    statictext #1.st, "Press ESC key", 40, 40, 150, 20
    open "ESC Close Test" for dialog as #1
    #1 "trapclose [quit]"

    wait

    [quit]
    print "All done"
    close #1
    end

Useful Procedures

' Place a useful function using this keyword here