Handle

From Liberty BASIC Family
Jump to navigation Jump to search
Supported in Just BASIC Supported in Liberty BASIC Not supported in Liberty BASIC 5 Supported in Run BASIC

Static Handles

Description

A handle is a unique global identifier of a file, device, window or control. It can only consist of letters, numbers and one period and must start with a sharp-sign (#).
Once a file, window or other device is closed, its handle is no longer valid. That object can not be referred to until it is once again OPENed with the same, or even a different, handle identifier.
Static handles, being global in scope, can be seen and used by all parts of the program, including subs and functions.

Syntax

File, Window or Device Handle

  1. #MyHandle

Control Handle

  1. #MyWindow.MyControl

Hints

Before a handle can be reused with the OPEN command, it must be removed with the CLOSE command.

Example

' Place a simple, working example of the keyword here

Useful Procedures

' Place a useful function using this keyword here

Variable Handles

Description

A variable handle, also known as Handle Variable, is used to allow creating reusable code blocks.
The string used for the variable handle must start with a sharp-sign (#).

Syntax

  1. #Variable$

Hints

Variable handles can only be used to access the object they identify after it is created using the OPEN command.
They can not be used to create multiple GUI controls in a loop.
They can not be used by the OPEN command.
You can use variable handles two ways:
First, you can generate them programmatically so you can loop through controls doing something with all of them.
Second, you can use one sub event handler for a group of controls. In a sub, from the handle you can distinguish which control got events or just use the handle to work with a control.
(see example #Two ways of using variable handles)

Example

General Window Closing Sub

' disable the text window
    NoMainWin

' create an empty GUI window
    OPEN "My First Window" FOR window AS #m

' trap closing the window
' call procedure Quit by pushing the X at the top right hand corner
    #m "trapclose Quit"

' wait for users action
    WAIT

' define the handler for closing the window
SUB Quit Handle$
' Handle$ will contain "#m" in this example
' use the debugger and walk through the program
' step-by-step to verify this

' close the window handle received by the procedure
    CLOSE #Handle$

' terminate the program
    END
END SUB

Two ways of using variable handles

    nomainwin

    WindowWidth = 400
    WindowHeight = 170

    UpperLeftX=int((DisplayWidth-WindowWidth)/2)
    UpperLeftY=int((DisplayHeight-WindowHeight)/2)

    graphicbox #main.graphicbox1, 30, 20, 100, 100
    graphicbox #main.graphicbox2, 150, 20, 100, 100
    graphicbox #main.graphicbox3, 270, 20, 100, 100
    open "variable handles - click in boxes" for window_nf as #main
    print #main, "trapclose [quit.main]"
    'you can use variable handles two ways
    'First, you can generate them programmatically so you can loop
    ' through controls doing something with all of them:
    for i = 1 to 3
        handle$="#main.graphicbox";i
        'you can even assign event handler
        print #handle$, "when leftButtonDown showNotice"
        print #handle$,"down; fill ";word$("red green blue", i);"; flush"
    next

    wait

'Second, you can use one sub event handler for a group of controls.
sub showNotice handle$, x, y
    'In a sub, from handle you can distinguish which control got event
    whichControl = val(right$( handle$, 1))
    whichControl$=word$("red green blue", whichControl)
'or just use handle to work with control
' we 'll make clicked box darker, and after notice restore it.
    print #handle$,"fill dark";word$("red green blue", whichControl);"; flush"
    notice "You clicked on "; whichControl$; " box"
    print #handle$,"fill ";word$("red green blue", whichControl);"; flush"
end sub

[quit.main]
    Close #main
    END

Useful Procedures

' Place a useful function using this keyword here