BB___TRAPCLOSE

=TRAPCLOSE= toc

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:
 * 1) terminating the TIMER
 * 2) unloading all loaded images using UNLOADBMP
 * 3) closing the window using CLOSE
 * 4) terminating the process using END

>

Syntax
> //When using with a text window://
 * 1) #handle "trapclose //[branch]//"
 * 2) #handle "trapclose //subName//"
 * 1) #handle "!trapclose //[branch]...or subName//"

Hints
> If you include in your program 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 when the user selects 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. An END statement will not have been encountered, and the program will continue running in the background - you just won't know it.

> If the window is of type "text", use an exclamation point, (!), 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 (mainwin). Closing the main window terminates the program.

Example
code format="LB" ' 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 code

code format="LB" ' 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 code

code format="lb" ' 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 code

Useful Functions
code format="LB" Place a useful function using this keyword here code