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 >> Graphics

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 Operations
    There are three general kinds of graphic tasks programmers use in their programs - drawing shapes, displaying images and printing text.

    • 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.

    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.

      • Create
       Window, Bitmap New, Bitmap Load 
      • End
       Window End, Bitmap End 
      • 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 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.

    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.

    • Graphic Window
      A graphic window is different than a PowerBASIC DIALOG. Whereas a dialog does not provide the ability to use graphics, except on child controls, a graphics windows supports both images and printing directly on the window.

      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
          

    • Memory Bitmap
      A memory bitmap canvas is a location in RAM memory where an image can be saved. The memory bitmap is not visible until it is copied to one of the other two canvases (graphics window or control). However, it can be drawn upon and images placed on it, just as though it were visible.

      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.

    • Graphic Control
      Five of the controls supported by PowerBASIC support the display of images - the graphic, image, imagex, imgbutton, and imgbuttonx controls.

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

    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.

    • BGR - get BGR value r/g/b values. Convert RGB to BGR
    • CONTROL ADD GRAPHIC - add graphic control
    • CONTROL ADD IMAGE - add image non-resizing image control
    • CONTROL ADD IMAGEX - add stretched image control
    • CONTROL ADD IMGBUTTON - add image button
    • CONTROL ADD IMGBUTTONX - add stretched image button
    • GRAPHIC ARC - draw an arc
    • GRAPHIC ATTACH - select graphic target
    • GRAPHIC BITMAP END - close selected graphic bitmap
    • GRAPHIC BITMAP LOAD - create memory bitmap and load image
    • GRAPHIC BITMAP NEW - create new memory bitmap
    • GRAPHIC BOX - draw box with square/rounded corners
    • GRAPHIC CHR SIZE - get character size
    • GRAPHIC CLEAR - clear graphic window w/specified color/fill style
    • GRAPHIC COLOR - set fg/bg colors for graphic statements
    • GRAPHIC COPY - copy bitmap to graphic target
    • GRAPHIC DETACH - detach a graphic target
    • GRAPHIC ELLIPSE - draw ellipse or circle
    • GRAPHIC FONT - select a font (for use with GRAPHIC PRINT)
    • GRAPHIC GET BITS - store image as a DIB in a dynamic string
    • GRAPHIC GET CLIENT - get client size of graphic target
    • GRAPHIC GET DC - get handle of DC (device context)
    • GRAPHIC GET LINES - get max number of lines possible on graphic target
    • GRAPHIC GET LOC - get location of graphic target on the screen
    • GRAPHIC GET MIX - get color mix mode for selected graphic target
    • GRAPHIC GET PIXEL - get pixel color on graphic target
    • GRAPHIC GET POS - get POS
    • GRAPHIC GET PPI - get display device resolution
    • GRAPHIC GET SCALE - get current coordinate limits for graphic target
    • GRAPHIC IMAGELIST - display image from IMAGELIST
    • GRAPHIC INKEY$ - read keyboard character from the graphic target
    • GRAPHIC INPUT FLUSH - write all buffered keyboard data
    • GRAPHIC INPUT - read data from keyboard from graphic window
    • GRAPHIC INSTAT - determine whether a keyboard character is ready
    • GRAPHIC LINE INPUT - read an entire line from the keyboard from graphic window
    • GRAPHIC LINE - draw a line in the selected graphic target
    • GRAPHIC PAINT - fill area with solid color or a hatch pattern
    • GRAPHIC PIE - draw pie section on selected graphic target
    • GRAPHIC POLYGON - draw polygon on selected graphic target
    • GRAPHIC POLYLINE - draw polyline (series of connected line segments)
    • GRAPHIC PRINT - print text to selected graphic target
    • GRAPHIC REDRAW - draw buffered graphical statements to selected graphic target
    • GRAPHIC RENDER - put image on selected graphic target
    • GRAPHIC SAVE - save image to .BMP file
    • GRAPHIC SCALE - define custom coordinates for graphic target
    • GRAPHIC SET BITS - replace copy of DIB
    • GRAPHIC SET FOCUS - bring graphic window to foreground, give it focus
    • GRAPHIC SET FONT - select font
    • GRAPHIC SET LOC - set location of selected graphic window
    • GRAPHIC SET MIX - set color mix mode for selected graphic target
    • GRAPHIC SET PIXEL - set pixel color on selected graphic window
    • GRAPHIC SET POS - set POS
    • GRAPHIC STRETCH - copy/resize bitmap on selected graphic target
    • GRAPHIC STYLE - set line style for graphical statements
    • GRAPHIC TEXT SIZE - get size (HxW) of text to be printed
    • GRAPHIC WAITKEY$ - wait for keyboard character from graphic window
    • GRAPHIC WIDTH - set line width for various graphical statements
    • GRAPHIC WINDOW CLICK - check if mouse clicked on graphic window
    • GRAPHIC WINDOW END - close/destroy selected graphic window
    • GRAPHIC WINDOW - create new graphic window
    • IMAGELIST ADD BITMAP - add bitmap to imagelist
    • IMAGELIST ADD ICON - add icon to imagelist
    • IMAGELIST ADD MASKED - add bitmap to icon imagelist
    • IMAGELIST GET COUNT - get number of images in imagelist
    • IMAGELIST KILL - destroy imagelist
    • IMAGELIST NEW BITMAP - create new bitmap imagelist structure
    • IMAGELIST NEW ICON - create new icon imagelist structure
    • IMAGELIST SET OVERLAY - specify overlay image
    • RGB - create RGB value from r/g/b values. Convert BGR to RGB.

    Graphic Function Reference
    Here's a quick reference of the available graphic functions, in alphabetical order.

    • BRG - add image non-resizing image control
      
      

    • CONTROL ADD IMAGE - add image non-resizing image control
      
      

    • CONTROL ADD IMAGEX - add stretched image control
      
      

    • CONTROL ADD IMGBUTTON - add image button
      
      

    • CONTROL ADD IMGBUTTONX - add stretched image button
      
      

    • CONTROL ADD GRAPHIC - add graphic control
      
      

    • BGR - get BGR value r/g/b values. Convert RGB to BGR
      
      

    • GRAPHIC ARC - draw an arc
      
      

    • GRAPHIC ATTACH - select graphic target
      
      

    • GRAPHIC BITMAP END - close selected graphic bitmap
      
      

    • GRAPHIC BITMAP LOAD - create memory bitmap and load image
      
      

    • GRAPHIC BITMAP NEW - create new memory bitmap
      
      

    • GRAPHIC BOX - draw box with square/rounded corners
      
      

    • GRAPHIC CHR SIZE - get character size
      
      

    • GRAPHIC CLEAR - clear graphic window w/specified color/fill style
      
      

    • GRAPHIC COLOR - set fg/bg colors for graphic statements
      
      

    • GRAPHIC COPY - copy bitmap to graphic target
      
      

    • GRAPHIC DETACH - detach a graphic target
      
      

    • GRAPHIC ELLIPSE - draw ellipse or circle
      
      

    • GRAPHIC FONT - select a font (for use with GRAPHIC PRINT)
      
      

    • Graphic Get Bits - get bitmap in a string
          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 - get client size of graphic target
          Graphic Get Client
      

    • GRAPHIC GET DC - get handle of DC (device context)
          Graphic Get DC
      

    • GRAPHIC GET LINES - get max number of lines possible on graphic target
          Graphic Get Lines
      

    • GRAPHIC GET LOC - get location of graphic target on the screen
          Graphic Get Loc
      

    • GRAPHIC GET MIX - get color mix mode for selected graphic target
          Graphic Get Mix
      

    • GRAPHIC GET PIXEL - get pixel color on graphic target
          Graphic Get Pixel
      

    • GRAPHIC GET POS - get POS
          Graphic Get POS
      

    • GRAPHIC GET PPI - get display device resolution
          Graphic Get PPI
      

    • GRAPHIC GET SCALE - get current coordinate limits for graphic target
          Graphic Get Scale
      

    • GRAPHIC IMAGELIST - display image from IMAGELIST
          Graphic ImageList
      

    • GRAPHIC INKEY$ - read keyboard character from the graphic target
          Graphic Inkey$
      

    • GRAPHIC INPUT - read data from keyboard from graphic window
          Graphic Input
      

    • GRAPHIC INSTAT - determine whether a keyboard character is ready
          Graphic Instat
      

    • GRAPHIC INPUT FLUSH - write all buffered keyboard data
          Graphic Input Flush
      

    • GRAPHIC LINE - draw a line in the selected graphic target
          Graphic Line
      

    • GRAPHIC LINE INPUT - read an entire line from the keyboard from graphic window
          Graphic Line Input
      

    • GRAPHIC PAINT - fill area with solid color or a hatch pattern
          Graphic Paint
      

    • GRAPHIC PIE - draw pie section on selected graphic target
          Graphic Pie
      

    • GRAPHIC POLYGON - draw polygon on selected graphic target
          Graphic Polygon
      

    • GRAPHIC POLYLINE - draw polyline (series of connected line segments)
          Graphic Polyline
      

    • GRAPHIC PRINT - print text to selected graphic target
          Graphic Print
      

    • GRAPHIC REDRAW - draw buffered graphical statements to selected graphic target
          Graphic Redraw
      

    • GRAPHIC RENDER - put image on selected graphic target
          Graphic Render
      

    • GRAPHIC SAVE - save image to .BMP file
          Graphic Save
      

    • GRAPHIC SCALE - define custom coordinates for graphic target
          Graphic Scale
      

    • GRAPHIC SET BITS - replace copy of DIB
          Graphic Set BITS
      

    • GRAPHIC SET FOCUS - bring graphic window to foreground, give it focus
          Graphic Set Focus
      

    • GRAPHIC SET FONT - select font
          Graphic Set Font
      

    • GRAPHIC SET LOC - set location of selected graphic window
          Graphic Set Loc
      

    • GRAPHIC SET MIX - set color mix mode for selected graphic target
          Graphic Set Mix
      

    • GRAPHIC SET PIXEL - set pixel color on selected graphic window
          Graphic Set Pixel
      

    • GRAPHIC SET POS - set POS
          Graphic Set POS
      

    • GRAPHIC STRETCH - copy/resize bitmap on selected graphic target
          Graphic Stretch
      

    • GRAPHIC STYLE - set line style for graphical statements
          Graphic Style
      

    • GRAPHIC TEXT SIZE - get size (HxW) of text to be printed
          Graphic Text Size
      

    • GRAPHIC WAITKEY$ - wait for keyboard character from graphic window
          Graphic WaitKey$
      

    • GRAPHIC WIDTH - set line width for various graphical statements
          Graphic Width
      

    • GRAPHIC WINDOW - create new graphic window
          Graphic Window
      

    • GRAPHIC WINDOW CLICK - check if mouse clicked on graphic window
          Graphic Window Click
      

    • GRAPHIC WINDOW END - close/destroy selected graphic window
          Graphic Window End
      

    • IMAGELIST ADD BITMAP - add bitmap to imagelist
          Imagelist Add Bitmap
      

    • IMAGELIST ADD ICON - add icon to imagelist
          Imagelist Add Icon
      

    • IMAGELIST ADD MASKED - add bitmap to icon imagelist
          Imagelist Add Masked
      

    • IMAGELIST GET COUNT - get number of images in imagelist
          Imagelist Get Count
      

    • IMAGELIST KILL - destroy imagelist
          Imagelist Kill
      

    • IMAGELIST NEW BITMAP - create new bitmap imagelist structure
          Imagelist New Bitmap
      

    • IMAGELIST NEW ICON - create new icon imagelist structure
          Imagelist New Icon
      

    • IMAGELIST SET OVERLAY - specify overlay image
          Imagelist Set Overlay
      

    • RGB - create RGB value from r/g/b values. Convert BGR to RGB.
          RGB
      

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