Getting Started
Introduction
Sample Programs
IDEs
History
Advice
Mini-Tutorial
Tutorials
Code Snippets

Resources
Web Sites
More Tutorials
Forums
Vendors/Tools
Books
Magazines
Newsletters
NewsGroups
User Groups
Talk Shows
Blogs

Controls
Overview
Button
Check3State
Checkbox
ComboBox
Frame
Graphic
Image
ImageX
ImgButton
ImgButtonX
Label
Line
ListBox
ListView
Option
Progress Bar
Scrollbar
StatusBar
TAB
TextBox
Toolbar
TreeView

GBIC >> PowerBASIC >> Tutorials >> Controls >> Graphic Control

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.

Introduction       Projects       Language           Messages       Functions           Advanced
  • Overview
  • Examples
  • IDE
  • Compilation
  • Distribution
  • Project Files
  • DDT Windows
  • Controls
  • Menus
  • Dialogs  
  • Help Files
  • Resources  
  • Templates  
  • Project Shell  
  • Syntax
  • Operators
  • Data Types
  • Variables
  • Scope
  • Declarations  
  • Procedures
  • Flow Control
  • Windows
  • Messages
  • Callbacks
  • Mouse
  • Keyboard
  • Dialogs
  • Controls
  • Subclassing
  • Arithmetic
  • Trig  
  • Strings
  • Arrays
  • Date/Time
  • Printing
  • Files
  • Folders
  • Keyboard
  • Mouse
  • Sound
  • System
  • Error Traps
  • Debugging
  • Objects
  • Graphics
  • Databases
  • API
  • DLLs
  • ASM
  • Threads
  • 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).

      • Select
       Attach, Detach 
      • Draw
       Get/Set POS, Line, Paint, Get/Set Pixel, 
       Arc, Ellipse, Pie, Box, Polygon, Polyline
      
      • Text
       Chr Size, Print, Set Font, Text Size, Get Lines 
      • Lines
       Style, Width 
      • Images
      Get Bits, Set Bits, Copy, Save, 
      ImageList, Render, Stretch 
      
      • ImageList
      New Bitmap, New Icon, Add Bitmap, Add Icon, 
      Add Masked, Get Count, Kill, Set Overlay
      
      • Keyboard
       Input, Inkey$, Waitkey$, Input Flush,
       InStat, Line Input 
      • Manage Canvas
       Get DC, Get PPI, Get Client, Color, Clear, 
       Redraw, Get Scale, Scale, Window Click, 
       Set Focus, Get/Set Loc, Get/Set Mix 
      
      • Colors
       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 DISABLEdisable
      hDlg, id&
      CONTROL ENABLEenable hDlg, id&
      CONTROL GET CHECKcheck state hDlg, id& TO iResult1&
      CONTROL GET CLIENTtop/left location hDlg, id& TO wide&, high&
      CONTROL GET LOCtop/left location hDlg, id& TO x&, y&
      CONTROL GET SIZEwidth/height hDlg, id& TO width&, height&
      CONTROL GET TEXTtext hDlg, id& TO txt$
      CONTROL GET USERget user data hDlg, id&, index& TO retvar&
      CONTROL HANDLE window handle for control id hDlg, id& TO hCtl&
      CONTROL KILLremove control hDlg, id&
      CONTROL POSTput message in queue (non-blocking) hDlg, id&, Msg&, wParam&, lParam&
      CONTROL REDRAWschedule redraw of control hDlg, id&
      CONTROL SENDsend message to control, wait for processing hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
      CONTROL SET CHECKset check for 3state or checkbox hDlg, id&, checkstate&
      CONTROL SET CLIENTchange size to specific client area size hDlg, id&, wide&, high&
      CONTROL SET COLORset fg/bg color hDlg, id&, fgcolor&, bgcolor&
      CONTROL SET FOCUSset focus hDlg, id&
      CONTROL SET FONTselect font for a control hDlg, id&, fonthandle&
      CONTROL SET LOCrelocate control within dialog hDlg, id&, x&, y&
      CONTROL SET OPTIONset check state of option control hDlg, id&, minid&, maxid&
      CONTROL SET SIZEchange control size hDlg, id&, width&, height&
      CONTROL SET TEXTchange control text hDlg, id&, text$
      CONTROL SET USERset 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.