Any topic

Liberty BASIC Help Online

Graphics Commands

See also: Understanding Syntax - how to use literals and variables in commands.

New for Liberty BASIC 4: scrollbars may be turned on and off, and the scroll range may be set. See HORIZSCROLLBAR and VERTSCROLLBAR commands below. The slider on the scrollbar now opens at the top for vertical scrollbars and at the left for horizontal scrollbars, rather than in the middle as they did in previous versions of Liberty BASIC. Also new: drawing segments can be given names. In previous versions of Liberty BASIC, segment ID's were numbers assigned by Liberty BASIC. For more on using named drawing segments, see the FLUSH command, below.

Most of these commands work only with windows of type graphics and with the graphicbox control.

It should be noted that graphics windows and graphicboxes are intended for drawing graphics. It is not advisable to place controls within them, since some controls do not work properly when placed in graphicboxes or graphics windows. If there is a need for text display within a graphicbox or graphics window, use the graphics text capabilities rather than a statictext control.

IMPORTANT NOTE: In order to draw, you must make sure that the drawing pen in down, and not up. See below for more information.

Here is an example using a graphics window:

open "Drawing" for graphics as #handle

print #handle, "home" 'center the pen

print #handle, "down" 'ready to draw

print #handle, "fill red" 'fill the window with red

print #handle, "circle 50" 'draw a circle

print #handle, "flush" 'make the graphics stick

wait

And here is an example using a graphicbox:

graphicbox #handle.gbox, 10, 10, 150, 150

open "Drawing" for window as #handle

print #handle.gbox, "home" 'center the pen

print #handle.gbox, "down" 'ready to draw

print #handle.gbox, "fill red" 'fill the graphics area red

print #handle.gbox, "circle 50" 'draw a circle

print #handle.gbox, "flush" 'make the graphics stick

wait

Because graphics can involve many detailed drawing operations, Liberty BASIC allows mutliple commands to be listed in a single command statement if they are separated by semicolons. The following example shows several graphics commands, each on its own line:

print #handle, "up"

print #handle, "home"

print #handle, "down"

print #handle, "north"

print #handle, "go 50"

The same commands can be issued on a single line, and will execute slightly faster:

print #handle, "up ; home ; down ; north ; go 50"

If text is displayed using graphics commands, a semicolon may not be used after the command to display the text. When graphictext is designated by the use of the ( \ ) or ( | ) character, any semicolons that follow in the same line are considered to be part of the text string to display.

Important: When drawing to a graphics window or graphic box, the operations that are performed are stored in memory by Liberty BASIC so that lightning fast redraws can be performed. This storage function uses memory. If an application continually draws raphics, the system will eventually run out of memory and even potentially crash the computer. To prevent this, the application should only store those drawing operations which are needed to display its current state. The cls, delsegment, discard and flush commands help to manage graphics memory. See also: Graphics

Liberty BASIC supports sprites in graphic windows and in graphicbox controls. Only one graphicbox or graphics window in a program may use sprites. To learn more about using sprites, see Sprites.

Using variables in commands:

To use literal values, place them inside the quotation marks:

print #handle, "box 12 57"

To use variables, place them outside the quotation marks, preserving spaces:

x=12 : y = 57

print #handle, "box ";x;" ";y

For more, see Understanding Syntax.

GRAPHICBOX COMMANDS

The following commands are sent to a graphicbox. When a graphicbox is disabled, it can no longer capture keyboard and mouse events.

print #handle.ext, "setfocus"

This causes the control to receive the input focus. This means that any keypresses will be directed to the control.

print #handle.ext, "enable"

This causes the control to be enabled.

print #handle.ext, "disable"

This causes the control to be inactive. It can no longer capture mouse and keyboard events.

print #handle.ext, "show"

This causes the control to be visible.

print #handle.ext, "hide"

This causes the control to be hidden or invisible.

print #handle, "autoresize"

This causes the edges of the control to maintain their distance from the edges of the overall window. If the user resizes the window, the graphicbox control also resizes.

Graphics commands (in alphabetical order):

print #handle, "backcolor COLOR"

This command sets the color used when drawn figures are filled with a color. The same colors are available as with the COLOR command below.

print #handle, "backcolor red(0-255) green(0-255) blue(0-255)"

The second form of backcolor specifies a pure RGB color. This only works with display modes greater than 256 colors. To create a green blue color for example, mix green and blue:

print #handle, "backcolor 0 127 200"

print #handle, "box x y"

This command draws a box using the pen position as one corner, and x, y as the other corner.

print #handle, "boxfilled x y"

This command draws a box using the pen position as one corner, and x, y as the other corner. The box is filled with the color specified using the other BACKCOLOR command.

print #handle, "circle r"

This command draws a circle with radius r at the current pen position.

print #handle, "circlefilled r"

This command draws a circle with radius r, and filled with the color specified using the BACKCOLOR command.

print #handle, "cls"

This command clears the graphics window, erasing all drawn elements and flushed segments (and releasing all the memory they used).

print #handle, "color COLOR"

This command sets the pen's color to be COLOR

Here is a list of valid colors (in alphabetical order):

black, blue, brown, buttonface, cyan, darkblue, darkcyan, darkgray, darkgreen, darkpink, darkred, green, lightgray, palegray, pink, red, white, yellow

Palegray and Lightgray are different names for the same color. Buttonface is the default background color currently set on a user's system, so it will vary according to the desktop color scheme. Here is a graphical representation of the named colors:

print #handle, "color red(0-255) green(0-255) blue(0-255)"

The second form of color specifies a pure RGB color. This only works with display modes greater than 256 colors. To create a violet color for example, mix red and blue:

print #handle, "color 127 0 127"

print #handle, "delsegment n"

This causes the drawn segment with segment ID number "n" to be removed from the window's list of drawn items. The memory that was used by the drawn segment is reclaimed by the operating system. When the window is redrawn the deleted segment will not be included in the redraw. See the SEGMENT command for instructions on retrieving a segment ID number.

print #handle, "delsegment segmentName"

This causes the drawn segment that has been assigned "segmentName" to be removed from the window's list of drawn items. The memory that was used by the drawn segment is reclaimed by the operating system. When the window is redrawn the deleted segment will not be included in the redraw. See the FLUSH command for instructions on assigning segment names.

print #handle, "discard"

This causes all drawn items since the last flush to be discarded (this also reclaims memory used by the discarded drawn items). Discard does not force an immediate redraw, so the items that have been discarded will still be displayed until a redraw (see redraw).

print #handle, "down"

This command is the opposite of UP. This command reactivates the drawing process. The pen must be DOWN to cause graphics to be displayed.

print #handle, "drawbmp bmpname x y"

This command draws a bitmap named bmpname (loaded beforehand with the LOADBMP statement, see command reference) at the location x y.

print #handle, "ellipse w h"

This command draws an ellipse centered at the pen position of width w and height h.

print #handle, "ellipsefilled w h"

This command draws an ellipse centered at the pen position of width w and height h. The ellipse is filled with the color specified using the command backcolor (see above).

print #handle, "fill COLOR"

or...

print #handle, "fill red(0-255) green(0-255) blue(0-255)"

This command fills the window with COLOR. For a list of accepted colors see the COLOR command above. The second form specifies a pure RGB color. This only works with display modes greater than 256 colors.

print #handle, "flush"

This command ensures that drawn graphics 'stick'. Each time a flush command is issued after one or more drawing operations, a new group (called a segment) is created. Each segment of drawn items has an ID number. The segment command retrieves the ID number of the current segment. Each time a segment is flushed, a new empty segment is created, and the ID number increases by one. See also the commands cls, delsegment, discard, redraw, and segment.

print #handle, "flush segmentName"

This command ensures that drawn graphics 'stick', and assigns a name to the flushed segment. Each time a flush command is issued after one or more drawing operations, a new group (called a segment) is created. This assigned name can be used in later commands to manipulate the segment. See also the commands cls, delsegment, discard, redraw, and segment.

print #handle, "font facename pointSize"

This command sets the pen's font to the specified face and point size. If an exact match cannot be found, then Liberty BASIC will try to find a close match, with size taking precedence over face. For more on specifying fonts read How to Specify Fonts

Example:

print #handle, "font Times_New_Roman 10"

print #handle, "getbmp bmpName x y width height"

This command will make a bitmap copied from the graphics window at x, y and using width and height. It resides in memory. This bitmap can be drawn using the DRAWBMP command, just as a bitmap loaded with LOADBMP. It is also possible to get a Windows handle to this bitmap with the HBMP() function.

print #handle, "go D"

This causes the drawing pen to move forward D distance from the current position, moving in the current direction.

print #handle, "goto X Y"

This command moves the pen to position X Y. A line will be drawn if the pen is down.

print #handle, "home"

This command centers the pen in the graphics window.

print #handle "horizscrollbar on/off [min max]"

This command manages the horizontal scrollbar. If the value is "on", the scrollbar is visible. If the value is "off", the scrollbar is not displayed. If the optional paramters for min and max are used, they set the minimum scrollbar range and the maximum scrollbar range in pixels. A large scrollbar range allows the graphics window to scroll a long distance, while a short range allows it to scroll a short distance.

print #handle, "line X1 Y1 X2 Y2"

This command draws a line from point X1 Y1 to point X2 Y2. If the pen is up, then no line will be drawn, but the pen will be positioned at X2 Y2.

print #handle, "locate x y width height"

This command is for a graphicbox, not a graphics window, and it repositions the control in its window. This is effective when the control is placed inside a window of type "window". The control will not update its size and location until a refresh command is sent to the window. See the included RESIZE.BAS example program.

print #handle, "north"

This command sets the current direction to 270 (north). Zero degrees points to the right (east), 90 points down (south), and 180 points left (west).

print #handle, "pie w h angle1 angle2"

This command draws a pie slice inside an ellipse of width w and height h. The pie slice will begin at angle1, and sweep clockwise angle2 degrees if angle2 is positive, or sweep counter-clockwise angle2 degrees if angle2 is negative.

print #handle, "piefilled w h angle1 angle2"

print #handle, "place X Y"

This command positions the pen at X Y. No graphics will be drawn, even if the pen is DOWN.

print #handle, "posxy xVar yVar"

This command assigns the pen's current position to xVar & yVar.

print #handle, "print"

This command sends the plotted image to the Windows Print Manager for output. Liberty BASIC 4 now scales graphics when sending them to a printer. Until version 4.0, Liberty BASIC printed the contents of graphics windows at 1:1, which resulted in tiny printed versions of what was visible on the screen. Now it will scale the graphics based on the size they appear on the display monitor, and the resolution of the printed page. Only TrueType fonts scale when printing. Bitmap fonts stay at their native resolution when printing. When printing a graphics window which has had the fill command applied, it will cause an entire printed page to be filled with that color, which may be highly undesireable. When graphics will be sent to the printer, consider using the boxfilled command rather than the fill command so that the absolute size of the filled area can be specified.

print #handle, "redraw"

print #handle, "redraw "; idNum

print #handle, "redraw "; segmentName

This command causes the window to redraw all flushed drawn segments, or a specific drawn segment. The specific segment can be identified by the ID number assigned by Liberty BASIC and retrieved with a SEGMENT command, or it can be a segment name assigned by the program when the FLUSH command is issued. Any deleted segments will not be redrawn (see DELSEGMENT). Any items drawn since the last flush will not be redrawn either, and will be lost.

print #handle, "rule rulename"

print #handle, "rule "; _R2_NOTXORPEN

This command specifies whether drawing overwrites (rulename OVER) graphics already on the screen or uses the exclusive-OR technique (rulename XOR). It is also possible to use Windows constants to select a drawing rule (as shown above). Here are the constants that Windows defines:

_R2_BLACK

_R2_WHITE

_R2_NOP

_R2_NOT

_R2_COPYPEN <- the default LB drawing rule

_R2_NOTCOPYPEN

_R2_MERGEPENNOT

_R2_MASKPENNOT

_R2_MERGENOTPEN

_R2_MASKNOTPEN

_R2_MERGEPEN

_R2_NOTMERGEPEN

_R2_MASKPEN

_R2_NOTMASKPEN

_R2_XORPEN

_R2_NOTXORPEN <- the xor LB drawing rule

print #handle, "segment variableName"

This causes the window to set variableName to the segment ID of the currently open drawing segment. To get the segment ID of the last segment flushed, subtract one. Segment ID numbers are useful for manipulating different parts of a drawing.

print #handle, "set x y"

This command draws a point at x, y using the current pen color and size.

print #handle, "setfocus"

This causes Windows to give input focus to this control. This means that, if some other control in the same window was highlighted and active, this control now becomes the highlighted and active control, receiving mouse and keyboard input.

print #handle, "size S"

This command sets the size of the pen to S. The default is 1. This will affect the thickness of lines and figures plotted with most of the commands listed in this section.

print #handle, "stringwidth? varToMeasure$ widthInPixels"

This command retrieves the width in pixels of a string, based on the current font of the graphicbox or graphic window.

open "my stringwidth" for graphics as #g

name$ = "Carl Gundel"

print #g, "stringwidth? name$ width"

print width

print #g, "font courier_new 30"

print #g, "stringwidth? name$ width"

print width

close #g

end

print #handle, "\text"

This command displays the specified text at the current pen position. The text is located with its lower left corner at the pen position.

Each additional \ in the text will cause a carriage return and line feed. For example, print #handle, "\text1\text2" will cause text1 to be printed at the pen position, and then text2 will be displayed directly under text1.

also... print #handle, "|text"

This command works like print #handle, "\text" above, but uses the | character instead of the \ character, which allows display of the character a ( \ ).

print #handle, "trapclose branchLabel"

This will tell Liberty BASIC to continue execution of the program at branchLabel if the user double clicks on the system menu box or pulls down the system menu and selects close (this command does not work with graphicbox controls).

print #handle, "turn A"

This command causes the drawing pen to turn from the current direction, using angle A and adding it to the current direction. A can be positive or negative.

print #handle, "up"

This command lifts up the pen. All GO or GOTO commands will now only move the pen to its new position without drawing. Any other drawing commands will simply be ignored until the pen is put back down.

print #handle "vertscrollbar on/off [min max]"

This command manages the vertical scrollbar. If the value is "on", the scrollbar is visible. If the value is "off", the scrollbar is not displayed. If the optional paramters for min and max are used, they set the minimum scrollbar range and the maximum scrollbar range in pixels. A large scrollbar range allows the graphics window to scroll a long distance, while a short range allows it to scroll a short distance.

print #handle, "when event eventHandler"

This tells the window to process mouse and keyboard events. These events occur when a user clicks, double-clicks, drags, or just moves the mouse inside the graphics window. An event can also be the user pressing a key while the graphics window or graphicbox has the input focus (see the setfocus command, above). This provides a really simple mechanism for controlling flow of a program which uses the graphics window.

The eventHandler can be a valid branch label or the name of a subroutine. See also: Controls and Events

Sending print #handle, "when leftButtonDown [startDraw]" to a graphicbox or graphics window will tell that window to force a goto [startDraw] if the mouse is inside that window when the user presses the left mouse button. Sending "when leftButtonDown startDraw" to a graphics window or graphicbox tells the window to call the subroutine startDraw if the mouse is inside that window when the user presses the left mouse button. The graphicbox handle, MouseX and MouseY variables are passed into the designated subroutine. If keyboard input is trapped, the graphicbox handle and the value of the key pressed are passed into the designated subroutine. See Reading Mouse Events and Keystrokes.

Whenever a mouse event is trapped, Liberty BASIC places the x and y position of the mouse in the variables MouseX, and MouseY. The values represent the number of pixels in x and y the mouse was from the upper left corner of the graphic window display pane.

Whenever a keyboard event is trapped, Liberty BASIC places the value of the key(s) pressed into the special variable, Inkey$. See Using Inkey$.

If the expression print #handle, "when event" is used with no branch label designation, then trapping for that event is discontinued. It can however be reinstated at any time. Example of turning off the leftButtonDown event handler:

print #handle, "when leftButtonDown"

Events that can be trapped:

leftButtonDown- the left mouse button is now down

leftButtonUp - the left mouse button has been released

leftButtonMove- the mouse moved while the left button is down

leftButtonDouble- the left button has been double-clicked

rightButtonDown- the right mouse button is now down

rightButtonUp- the right mouse button has been released

rightButtonMove- the mouse moved while the right button is down

rightButtonDouble- the right button has been double-clicked

mouseMove- the mouse moved when no button was down

characterInput- a key was pressed while the graphics window has

input focus (see the setfocus command, above)

WARNING: using graphicboxes in dialog-type windows is fine, but they do not properly accept the input focus for keyboard input. If a program needs graphicboxes that trap keyboard events, then a window of type "window" must be used.