The PowerBASIC graphics capabilities supporting these features can be categorized as follows. With a few exceptions, all of these statements begin with the word GRAPHIC, such as "GRAPHIC WINDOW". Exceptions include RGB, BRG, and all of the ImageList statements.
Here is a categorized list of the Graphic statements.
Window, Bitmap New, Bitmap Load
Window End, Bitmap End
Get/Set POS, Line, Paint, Get/Set Pixel, Arc, Ellipse, Pie, Box, Polygon, Polyline
Chr Size, Print, Set Font, Text Size, Get Lines
Get Bits, Set Bits, Copy, Save, ImageList, Render, Stretch
New Bitmap, New Icon, Add Bitmap, Add Icon, Add Masked, Get Count, Kill, Set Overlay
Input, Inkey$, Waitkey$, Input Flush, InStat, Line Input
Get DC, Get PPI, Get Client, Color, Clear, Redraw, Get Scale, Scale, Window Click, Set Focus, Get/Set Loc, Get/Set Mix
Graphics Statements - Overview Diagram
The following picture shows how the various PowerBASIC statements interact to support the overall graphics capabilities.
This page covers the details of working with graphics, but this graphic gives a look ahead at what will be covered. Click on the image for a larger version.
The three possible graphic targets are in dark blue. The top arrow gives the commands that control selection of a graphic target. The yellow circles represent the commands which can load graphics into the targets - from files, resources, imagelists, or other targets. The light blue circlels are the two ways to extract bitmap information. The light green boxes represent various commands that can be used on various graphic targets.
Once you've read through this page, the graphic will serve as a mental reference on how all the various statement play together.
Graphics (drawing primitives, images, and printed text) require a canvas - a place to put the displayed content. PowerBASIC allows three locations where graphics may be placed - graphics windows, memory bitmaps, and the graphic control.
There are API techniques for putting graphics directly on a PowerBASIC DIALOG, but this tutorial covers only the built-in features of PowerBASIC dialogs.
Here are the GRAPHIC statements to create graphic windows.
GRAPHIC WINDOW 'create new, blank graphic window GRAPHIC WINDOW END 'destroy graphic window
The GRAPHIC statements to create graphic windows and memory bitmaps are shown next.
GRAPHIC BITMAP NEW 'create new canvas (empty) GRAPHIC BITMAP LOAD 'create new canvas (image from file) GRAPHIC BITMAP END 'destroy memory bitmap
Special arrays of bitmaps, called imagelists, are also supported by PowerBASIC. Imagelists are discussed further down this page.
The Graphic Control can be used with GRAPHIC statements and supports the display of images from files, memory bitmaps, imagelists, other graphic controls and resource files. Drawing commands can also be used to create graphics on a Graphic Control.
The image, imagex, imgbutton, and imgbuttons controls support the display of images, but do not support the use of GRAPHIC statements. Images must come from a resource file.
IMAGE - image display (non-resizing) IMAGEX - image display (auto resized) IMGBUTTON - image display (non-resizing) IMGBUTTONX - image display (auto resized)
Selecting a Canvas
The various GRAPHIC statements work on a "graphic target". Although an application can have many canvases, only one at a time can be designated as the graphic target. All GRAPHICS statements will then apply to the target canvas until another canvas is selected.
There are two PowerBASIC statements which handle graphic target designation:
GRAPHIC ATTACH - designates the graphic target GRAPHIC DETACH - removes current target from use with GRAPHIC statements
Once a GRAPHIC DETACH is completed, further GRAPHIC commands are ignored until another target is selected.
Drawing - Shapes
PowerBASIC provides several statements which allow easy creation of drawing primitives - basic shapes that can be used to make more complex graphics. This includes the ability to set individual points (pixels) on graphic targets.
GRAPHIC Arc GRAPHIC Pie GRAPHIC Box GRAPHIC Point (pixel) GRAPHIC Ellipse GRAPHIC Polygon GRAPHIC Line GRAPHIC Polyline
Examples of using these drawing statements is provided in the reference table at the bottom of this page.
The Ellipse can be used to draw an ellipse or a circle. The box can be drawn with square or rounded corners.
Drawing Operation Coordinates
All of the shape drawing commands require definition of where the graphical operation will take place. GRAPHIC operations use either a starting point (x,y coordinates called the POS) or a pair of (x,y) coordinates to bound the drawing operation.
POS is used by the following GRAPHIC commands.
GRAPHIC LINE GRAPHIC PAINT GRAPHIC PRINT GRAPHIC SET PIXEL
POS can be retrieved or set using the following GRAPHICS commands.
GRAPHIC GET POS ' retrieve GRAPHIC SET POS ' change
Other graphic functions neither use nor update POS.
GRAPHIC ARC GRAPHIC ELLIPSE GRAPHIC PIE
PowerBASIC provides built-in support for only two types of image formats - bitmaps (*.bmp) and icons (*.ico). As was discussed earlier, images can be placed in three basic places - controls, graphic window, and memory bitmaps. Once an image is placed in any of these locations, the images can easily be manipulated or transferred between graphic targets, imagelists, and other controls which support images.
An application could also programmatically create a bitmap, such as by creating a bitmap structure and manipulating the individual bits of the bitmap. In particular, PowerBASIC supports two very useful functions which give the programmer direct access to individual pixels within an image.
GRAPHIC GET BITS - gets image from graphic target and - places into a dynamic string GRAPHIC SET BITS - returns image string to graphic target
The dynamic string structure is simply a series of 4-bytes for each bit within the bitmap, plus a leading eight bits to give the width and height of the bitmap. This structure can easily be created or manipulated programmatically. The PowerBASIC CVL function converts 4-byte strings to long integers (color values), and the MKL$ function converts long integers to 4-byte strings.
ImageList Data Structure
As was noted above, PowerBASIC supports the creation of an array of bitmaps called an imagelist. Normal array functions do not apply to an imagelist. Instead, access to the images contained in the imagelist use special IMAGELIST statements. Imagelists can contain bitmaps or icons, but not both.
The advantage of using an imagelist is in the ease and speed of accessing images. Imagelists can be used as the source of an image for any graphic target.
To create an empty ImageList, use one of the following commands.
IMAGELIST NEW BITMAP 'creates new IMAGELIST structure (bitmaps only) IMAGELIST NEW ICON 'creates new IMAGELIST structure (icons only)
The two statements above create an empty imagelist structure, to which images must be added using one of the following:
IMAGELIST ADD BITMAP 'add bitmap to the IMAGELIST IMAGELIST ADD ICON 'adds icon to the IMAGELIST IMAGELIST ADD MASKED 'bitmap is added to the icon IMAGELIST
With the IMAGELIST ADD MASKED command, PowerBASIC provides a way to use a bitmap as an icon, with the additional feature of selecting a transparency color.
Finally, IMAGELISTs can be managed using one of the following commands.
IMAGELIST GET COUNT 'number of images in the IMAGELIST IMAGELIST KILL 'destroys the specified IMAGELIST IMAGELIST SET OVERLAY 'declares an image as an overlay
Assigning Images to Graphic Targets
Once a graphic target has been selected, the commands to place an image in the target can be characterized by the source of the image.
Here are the four basic GRAPHIC commands which place an image into a graphic target. A fifth command is also listed, showing how to clear the image.
GRAPHIC Render - from a file (*.bmp or *.pbr) GRAPHIC ImageList - from an imagelist structure (see next section) GRAPHIC Copy - from a graphic target (control, bitmap, window) GRAPHIC Stretch - from a graphic target (control, bitmap, window) GRAPHIC Clear - applies to graphic targets (control, bitmap, window)
PowerBASIC supports a 24-bit (3 byte), hexadecimal color numbering scheme. A color number is created by simply concatenating the hexadecimal values of the separate red, green, and blue values as shown in the following example.
red& = &HFF green& = &H08 blue& = &HD4 BGRcolor& = &HD408FF 'PowerBASIC standard B+G+R nomenclature RGBcolor& = &HFF08D4 'note 1st and 3rd bytes are reversed
The PowerBASIC choice of BGR was made in support of Windows API which deal with Device Independent Bitmaps (DIB), which require a BGR color number.
To support other API which require an RGB color number, PowerBASIC provides the BGR and RGB functions, each of which return the appropriate color number - either from the r, g, and b values, or from the opposite color number format.
Here are examples for each.
RGBcolor& = RGB(red&, green&, blue&) RGBcolor& = RGB(BGRColor&) BGRcolor& = BGR(red&, green&, blue&) BGRcolor$ = BGR(RGBColor&)
The PowerBASIC GRAPHIC statement also supports the following keyboard capabilities. These
GRAPHIC INKEY$ - read keyboard character GRAPHIC INPUT - read data from keyboard GRAPHIC INSTAT - tests whether keyboard character is ready GRAPHIC INPUT FLUSH - write all buffered keyboard data GRAPHIC LINE INPUT - read entire line from keyboard GRAPHIC WAITKEY$ - wait for keyboard character
These are discussed more fully in the keyboard tutorial section.
Graphic Command Summary
Here's a summary of the PowerBASIC statements available to display graphics. Most, if not all, were discussed earlier on this page.
Graphic Function Reference
Here's a quick reference of the available graphic functions, in alphabetical order.
Graphic Get Bits TO bmpVariable$ 'dynamic string variable
bmpVariable contains H-W-bits in 4-byte series. Use CVL to convert string to numeric values. Content is in BGR format. Use RGB is needed to convert. After values are changed as needed, use MKL$ to convert back to string values.
Graphic Get Client
Graphic Get DC
Graphic Get Lines
Graphic Get Loc
Graphic Get Mix
Graphic Get Pixel
Graphic Get POS
Graphic Get PPI
Graphic Get Scale
Graphic Input Flush
Graphic Line Input
Graphic Set BITS
Graphic Set Focus
Graphic Set Font
Graphic Set Loc
Graphic Set Mix
Graphic Set Pixel
Graphic Set POS
Graphic Text Size
Graphic Window Click
Graphic Window End
Imagelist Add Bitmap
Imagelist Add Icon
Imagelist Add Masked
Imagelist Get Count
Imagelist New Bitmap
Imagelist New Icon
Imagelist Set Overlay
If you have any suggestions or corrections, please let me know.