PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC -
the scope of the language as well as it's specific capabilities.
 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.
- Syntax:
Control Add Graphic, hDlg, id&, txt$, x, y, xx, yy, _
style&, extsytle& CALL callback
The Control Add Graphic simply creates an empty control. Once the GRAPHIC Attach
statement is used to select the graphic control for use in subsequent GRAPHIC
statements, there are over a dozen available GRAPHIC statements which
can add content to a graphic control. All of them are discussed below.
- Source Code Example:
This not-to-short example creates a complete application with a several graphic
controls, demonstrating several of its capabilities, including response to
a mouse click.
This tutorial page discusses most of the statements used, however the
DDT,
Controls,
Messages, and
Callback tutorials provide
background information that may be helpful in understanding the example.
#Compile Exe
#Include "Win32API.inc"
#Resource "pb-test.pbr"
Global hDlg As Dword, hLst As Dword, hTemp As Dword
Global style&, extstyle&
Function PBMain() As Long
Dialog New Pixels, 0, "Graphic Control Test",300,300,450,380, _
%WS_SysMenu, 0 To hDlg
'create imagelist w,h,depth,size
ImageList New Icon 16,16,32,3 To hLst
ImageList Add Icon hLst, "x"
ImageList Add Icon hLst, "y"
ImageList Add Icon hLst, "check"
'create graphic control - various frames
style& = %WS_Visible Or %SS_Sunken
Control Add Graphic, hDlg, 301,"", 10,10,30,30, style&
style& = %WS_Visible Or %WS_DlgFrame
Control Add Graphic, hDlg, 302,"", 50,10,30,30, style&
style& = %WS_Visible Or %WS_Border
Control Add Graphic, hDlg, 303,"", 90,10,30,30, style&
'create graphic control
style& = %WS_Visible Or %SS_Sunken Or %SS_Notify
Control Add Graphic, hDlg, 110,"", 10,50,100,100, style&
Control Add Graphic, hDlg, 120,"", 120,50,100,100, style&
Control Add Graphic, hDlg, 130,"", 230,50,100,100, style&
Control Add Graphic, hDlg, 210,"", 10,160,100,100, style&
Control Add Graphic, hDlg, 220,"", 120,160,100,100, style&
Control Add Graphic, hDlg, 230,"", 230,160,100,100, style&
Control Add Graphic, hDlg, 310,"", 10,270,100,100, style&
Control Add Graphic, hDlg, 320,"", 120,270,100,100, style&
Control Add Graphic, hDlg, 330,"", 230,270,100,100, style&
'BMP FILE bmpname$, (x,y)-(x2,y2) dest coordinates
Graphic Attach hDlg, 110
Graphic Render "cowgirl", (0,0)-(100,100) 'same size (could resize)
'PBR FILE
Graphic Attach hDlg, 120
Graphic Render "icons/cowgirl.bmp", (0,0)-(100,100) 'same size
'IMAGELIST (x,y), hList, index&, overlay&, style&
Graphic Attach hDlg, 130
Graphic ImageList (0,0), hLst, 1,0, %ILD_Normal
Graphic ImageList (50,50), hLst, 2,0, %ILD_Normal
Graphic ImageList (10,70), hLst, 3,0, %ILD_Normal
Graphic ImageList (70,30), hLst, 3,0, %ILD_Normal
'COPY hSource, id&
Graphic Attach hDlg, 210 'source
Graphic Copy hDlg, 110 'copy all to 0,0
Graphic Attach hDlg, 220 'source
Graphic Copy hDlg, 110 To (20,20) 'copy all to 40,40
Graphic Attach hDlg, 230 'source
Graphic Copy hDlg, 110, (0,0)-(40,80) To (40,10) 'copy part to 40,40
'STRETCH
Graphic Attach hDlg, 310 'copy all to 0,0
Graphic Stretch hDlg, 110, (0,0)-(100,100) To _
(0,0)-(50,50) 'copy part+shrink
Graphic Attach hDlg, 320
Graphic Stretch hDlg, 110, (0,0)-(100,100) To _
(0,0)-(200,200) 'copy part+expend
'DRAWING
Graphic Attach hDlg, 330
Graphic Print "Print";" here"
Graphic Color %Red
Graphic Print
Graphic Print "Now here!"
Graphic Color %Blue
Graphic Print
Graphic Print "and here!"
Graphic Ellipse (20,20)-(70,95), %Black
Graphic Ellipse (25,15)-(35,25), %Black, %Red
Graphic Line (80,10)-(50,100), %Black
Graphic Paint Border (60,75),%Green, %Black
Graphic Paint Border (60,75),%Green, %Black
Graphic Box (75,60)-(90,90),50, %White, %Red
Dialog Show Modal hDlg Call DlgProc
End Function
CallBack Function DlgProc() As Long
If Cb.Msg = %WM_Command And Cb.Ctl = 110 And _
Cb.CtlMsg = %STN_Clicked Then
MsgBox "Clicked!"
End If
End Function
In this example, the image "cowgirl" is stored in a resource file,
available from here. Also
note that the #INCLUDE "Win32API.inc" is required because it contains the
%STN_CLICKED named constant.
An additional example of a callback function is provided further down this page.
- Visual Examples:
And here are a few examples of what you can do with the image control in PowerBASIC.
Variations on the Control Add Graphic statement were used to create the examples.
In most cases, other GRAPHIC statements were used to modify the results.
|
|
Row 1: blank images simply showing border options.
Row 2: Load from BMP file, Load from PBR, Load from ImageList. Note
that loading an image does not automatically erase any previous content.
So in the case of the ImageList images, which are 16x16, several images
have been loaded.
Row 3: Shows 3 ways to use COPY to copy a image from another graphic control.
The first two place the image at 0,0 and then 50,50. The third copies only
a part of the source image and then resizes it at a different location on the
target graphic control.
Row 4: The first two use the STRETCH statement to copy a part of a source
image then shrink (1st image) and expand (2nd image) it. The third
shows how text and drawings can be placed on a graphic control.
|
A graphic control, along with the GRAPHIC statements, has a very wide range of
options. Images, graphics and text can be displayed. Full or partial images
can be copied, saved, and moved between graphic controls - with or without
resizing. There are border options, font options, colors, fills, and custom
scales.
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.
- hDlg
The dialog handle to which the graphic control is to be added. The value
was returned by the DIALOG NEW statement.
- id&
The id& argument is a control identifier assigned by the programmer.
It must be a value of 1-65535. Values of 100+ are suggested, as PowerBASIC
pre-assigns identifiers with special meaning. Numeric equates are
suggested over the use of literal values.
- txt$
The graphic control does not display the txt$ value, so it is usually set
to "". However, any entered txt$ value can be accessed using the GET/SET TEXT
statements. This provides the application with a control-specific property that
can used for any purpose the programmer chooses.
- x,y and xx,yy
The integer x,y and xx,yy dimensions use the same units as the parent dialog.
(x,y) is the upper/left coordinates of the control. (xx,yy) is the width/height
of the control.
- style& and extstyle&
The style& and extstyle& arguments (listed below) are optional. If not supplied,
default values are used (see the table below). If values are supplied, they
completely replace default values (i.e., the entered values are not in addition
to the default values).
- CALL
The "CALL callback" section is optional. If not supplied, the callback
function of the parent dialog is used. An example callback function for
graphic controls is provided further down this page. The #MESSAGE COMMAND compiler
directive can be used to prevent sending %WS_NOTIFY messages to the callback
function. By default, both %WS_NOTIFY and %WS_COMMAND messages are sent.
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.
- Shapes - PowerBASIC has a complete set of standard drawing tools,
covering lines, boxes, arcs, polygons, polylines, circles, pie shapes and more.
- Images - When working with images, PowerBASIC supports only Windows bitmap (BMP) formats, including icons. It has no built-in capability to support JPG, GIF, PNG, or any other image formats.
- Text - Words are often mixed with the other graphics types. Color and font
control is supported by PowerBASIC, as is pinpoint placement of the text to be printed.
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).
|
| Attach, Detach
|
|
|
Get/Set POS, Line, Paint, Get/Set Pixel,
Arc, Ellipse, Pie, Box, Polygon, Polyline
|
|
|
Chr Size, Print, Set Font, Text Size, Get Lines
|
|
| Style, Width
|
|
|
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
|
|
|
RGB, BGR
|
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.
- POS
POS is known as LPR (Last Point Referenced) or even NPR (Next Point Referenced)
When a Graphic Window or Graphic Bitmap is created, the default POS is set to (0,0),
which is the upper left corner of the image.
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.
- Bounding Rectangle
These GRAPHICS drawing operations require definition of two
(x,y) coordinate pairs which define a bounding rectangle
to contain the drawing:
GRAPHIC ARC
GRAPHIC ELLIPSE
GRAPHIC PIE
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.
- Notifications - event notifications a control receives
- Messages - controls may send these
- Styles - affect the visual look of a control
- ExtStyles - additional values that affect the visual look
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.
| CONTROL DISABLE | disable
| | hDlg, id&
| | 
| | CONTROL ENABLE | enable
| hDlg, id&
| |
| | CONTROL GET CHECK | check state
| hDlg, id& TO iResult1&
| |
| | CONTROL GET CLIENT | top/left location
| hDlg, id& TO wide&, high&
| |
| | CONTROL GET LOC | top/left location
| hDlg, id& TO x&, y&
| |
| | CONTROL GET SIZE | width/height
| hDlg, id& TO width&, height&
| |
| | CONTROL GET TEXT | text
| hDlg, id& TO txt$
| |
| | CONTROL GET USER | get user data
| hDlg, id&, index& TO retvar&
| |
| | CONTROL HANDLE | window handle for control id
| hDlg, id& TO hCtl&
| |
| | CONTROL KILL | remove control
| hDlg, id&
| |
| | CONTROL POST | put message in queue (non-blocking)
| hDlg, id&, Msg&, wParam&, lParam&
| |
| | CONTROL REDRAW | schedule redraw of control
| hDlg, id&
| |
| | CONTROL SEND | send message to control, wait for processing
| hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
| |
| | CONTROL SET CHECK | set check for 3state or checkbox
| hDlg, id&, checkstate&
| |
| | CONTROL SET CLIENT | change size to specific client area size
| hDlg, id&, wide&, high&
| |
| | CONTROL SET COLOR | set fg/bg color
| hDlg, id&, fgcolor&, bgcolor&
| |
| | CONTROL SET FOCUS | set focus
| hDlg, id&
| |
| | CONTROL SET FONT | select font for a control
| hDlg, id&, fonthandle&
| |
| | CONTROL SET LOC | relocate control within dialog
| hDlg, id&, x&, y&
| |
| | CONTROL SET OPTION | set check state of option control
| hDlg, id&, minid&, maxid&
| |
| | CONTROL SET SIZE | change control size
| hDlg, id&, width&, height&
| |
| | CONTROL SET TEXT | change control text
| hDlg, id&, text$
| |
| | CONTROL SET USER | set user data
| hDlg, id&, index&, uservalue&
| |
| | CONTROL SHOW STATE | toggle visibility
| hDlg, id&, showstate& TO iResult3&
| |
| | | | | | | | | | | | | | | | | | | | | | | |
If you have any suggestions or corrections, please let me know.
|
