Graphic Control
The graphic control displays an image, supports drawing operations, and supports the printing of text. More versatile than the image/imagex controls, the graphic control can display images from multiple sources - including files, memory bitmaps, imagelists, other graphic controls and resource files.

This page covers only the graphic control as well as the various GRAPHIC statements which can be used to manage the content of a graphic control.

However, the GRAPHIC statements discussed on this page can also be applied to graphic windows and memory bitmaps. See my tutorial section on graphics for more information.

Arguments
The Control Add statement is used to create all new controls. Here are the statement's arguments and any special significance to the graphic control.

Graphic Operations
There are three general kinds of graphic tasks programmers use in their programs - drawing shapes, displaying images and printing text. These are all supported by the graphic control.

GRAPHICS Statement - Summary
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. These do not begin with the word GRAPHIC.

Here is a categorized list of the GRAPHIC statements, but only those which apply to a graphic control (other GRAPHIC statements are available which apply to graphic windows and memory bitmaps).

Graphics Statements - Overview Diagram
The following picture shows how the various PowerBASIC statements interact to support the overall graphics capabilities.

This page covers only the details of working with graphic controls, but the graphic above gives an overview of all PowerBASIC graphics operations, including those covered in the tutorial on all three canvases supported by PowerBASIC - graphic controls, graphic windows and memory bitmaps. See my tutorial section on graphics for more information.

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 circles are the two ways to extract bitmap information. The light green boxes represent various commands that can be used on various graphic targets.

Canvas
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. Only the graphic control is covered on 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.

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: apply. 

    GRAPHIC ATTACH - designates the graphic target
    GRAPHIC DETACH - detaches current target from the

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.

Images
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)

Colors
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&)

KeyBoard Statements
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.

Usage Notes
As noted earlier, images must come from PowerBASIC resource files.

Note that the #INCLUDE "Win32API.inc" is required because it contains the %STN_CLICKED message named constant.

The %SS_NOTIFY style must be included to received the %stn_click and %stn_dblclk notifications.

Messages, Notifications, Styles, and ExtSstyles
There are four types of named constants in the following table. All are pulled from the MSDN web site.

The first column contains control-specific named constants and the second column contains generic window named constants (graphic controls are windows).

Also, if the PowerBASIC Help file has an entry on the value, it is highlighted in yellow. If the value was noted in PowerBASIC Help as a default value, it is also shown in bold text.

In the values for notifications, descriptions starting with -n and -c refer to events received through the %wm_notify and %wm_command messages. By default, PowerBASIC controls can receive both of these messages.

   

And here is a short description of many of the named constants corresponding to notifications, styles, and extstyle - particularly those discussed in the PowerBASIC Help topics. 

    %ss_notify             - sends %stn_clicked/%stn_dblclk messages
    %ss_ownerdraw          - app is required to draw
    %ss_sunken             - draw half-sunken border
    %stn_clicked           -c mouse click
    %stn_dblclk            -c double slick
    %stn_disable           -c when control has been disabled
    %stn_enable            -c when control has been enabled
    %wm_ctlcolorstatic     - about to be drawn
    %ws_border             - thin line border
    %ws_child              -
    %ws_dlgframe           - same border as dialog boxes
    %ws_ex_clientedge      - apply sunken edge border
    %ws_ex_staticedge      - apply 3D border
    %ws_group              - starts/ends group. use %ws_tabstop style.
    %ws_visible            - visible

Callback Function
A control can have its own callback function, or use the parent dialog callback function.

A control callback function should return TRUE to indicate it has processed the message. This prevents unnecessarily calling the dialog callback function, which will process the message if no control callback function is available, or if the control callback function returns FALSE.

By default, both %WM_COMMAND and %WM_NOTIFY messages are received. However, if the #MESSAGE COMMAND compiler directive is invoked, the %WM_NOTIFY messages will not be available.

In addition, %ss_notify must be included in style& to receive the %stn_clicked and %stn_dblclk messages.

Here's a sample graphic control callback function. 

   CallBack Function cbImage()
      Select Case CB.MSG
         Case %WM_COMMAND
            Select Case CB.CTLMSG
               Case %stn_clicked
               Case %stn_dblclk
               Case %stn_disable
               Case %stn_enable
         End Select
      End Select
   End Function

In each Case section, add the statements the application needs to respond to the event. Also, be sure to add "Function=1" as appropriate to indicate that the event was handled by the callback function.

CONTROL Statement Syntax
The following table lists the various Control statements (except the ADD statements). Most, but not all, can be used with the graphic control. A one-line description of the statement and then its syntax are presented.

If you have any suggestions or corrections, please let me know.