GdiPlus Package

Author: Sunderland Ober Consulting. Version: 0.9.45.0. On GitHub: KubaO/GdiPlus, in the folder GdiPlus.

The GdiPlus contributed package is a twinBASIC interface to Windows GDI+: classes for drawing lines, shapes, text and images on a device context, a window or a bitmap, with pens, brushes, fonts, paths, regions and transformations.

GDI+ is the graphics library of Windows from Windows XP on. Where the older GDI draws in whole pixels with a few fixed colours, GDI+ draws with floating-point coordinates, antialiasing, colours that have an alpha (opacity) channel, gradients, and transformations of the whole drawing surface. The package wraps the flat functions of the GDI+ library in classes that follow the C++ classes Microsoft publishes with GDI+: a Graphics object draws, a Pen or a brush such as SolidBrush says how, a Bitmap holds the pixels. Each class page here links to the Microsoft page of the class it follows. This section documents version 0.9.45.0, published under the MIT licence.

Dim user As GdiPlusUser = GdiPlusUser()
Dim bmp As Bitmap = Bitmap(64!, 64!)
Dim g As Graphics = Graphics(bmp)
g.Clear(Color(255, 255, 255, 255))
g.FillRectangle SolidBrush(Color(255, 0, 128, 255)), 0, 0, 32, 32
Debug.Print Hex$(bmp.Pixel(10, 10).argb)
Debug.Print Hex$(bmp.Pixel(50, 50).argb)
' Output:
' FF0080FF
' FFFFFFFF

Getting started

A GdiPlusUser must exist while any GDI+ object is used. It starts GDI+, and without one the other classes fail with status 18, GdiplusNotInitialized. Any number of instances can exist; GDI+ stays usable while one does. Create it with the function of the same name, in a variable that lives as long as the program draws:

Dim user As GdiPlusUser = GdiPlusUser()

Every class is created in two ways that are one thing: New Pen(...) and the function Pen(...). This section documents both under Creating on the page of the class. The structures of the package, such as GpPointF and GpRect, have such functions too: GpRect(0, 0, 10, 10).

Note 0.9.45.0

A project that has the VB and OLE Automation packages, which every default project has, has a control class Image and an OLE type Font. In a declaration, write GdiPlus.Image and GdiPlus.Font; the constructor functions Image(...) and Font(...) need no prefix.

Drawing on a bitmap

The sample above draws on a Bitmap: Graphics(bmp) makes a drawing surface for it, and every drawing call of the Graphics changes its pixels, which bmp.Pixel(x, y) reads back. A bitmap is the easiest surface to start with, because it needs no window.

Drawing in a window

A program that handles the window messages itself creates its GdiPlusUser on WM_CREATE, and in WM_PAINT makes a buffered Graphics with BufferedGraphicsFromHWND, draws, and releases it, which copies the picture to the window. Painting a window or a form shows the whole window procedure.

Drawing in a form

A form creates its GdiPlusUser in Form_Load, makes a BufferedGraphicsFromHDC of the form’s hDC property in its Paint event, draws, and sets the variable to Nothing:

Dim mGdiPlus As GdiPlusUser

Sub Form_Load()
    ScaleMode = vbPixels
    Set mGdiPlus = GdiPlusUser()
End Sub

Sub Form_Paint()
    Dim area As GpRect = GpRect(0, 0, ScaleWidth, ScaleHeight)
    Dim gr As Graphics = BufferedGraphicsFromHDC(hDC, area)
    gr.Clear(Color(255, 255, 255))
    gr.DrawLine(Pen(Color(0, 0, 255), 3), 10, 10, 100, 60)
    Set gr = Nothing
End Sub

Sub Form_Resize()
    Refresh
End Sub

Failures

A call that fails raises no error by default. A method that returns no value returns the GpStatus of the call, and every object keeps the last failure in its LastResult property, which stays set until ClearResult is called. A constructor that fails returns an unusable object. The global variable GdipErrorHandlingStrategy makes the package raise an error or call a handler instead. GdiPlusBase has the details.

What is not documented

The package declares more than a program uses. These parts are left out of this section:

  • the handle types, such as GpGraphics, GpPen, GpBitmap and GpPath. Each holds the handle of one GDI+ object, and the classes of the package use them in their implementation. A member that takes or returns one says so in words, and GetNative returns the handle of an object for a program that calls the flat GDI+ functions itself;
  • the structures and enumerations with the prefix GDIP_, the Gdip… modules that hold the flat function declarations (GdipGraphics, GdipBitmap and the others), and GDIPDEF_UUID. They are the package’s own layer over the flat API;
  • the protected members that the classes use among themselves, such as Native, which returns the handle of the object, and Class_Terminate, which releases it;
  • the test code of the package, the modules ModMain and TypesTest.

Classes and interfaces

Starting GDI+, errors and helpers

  • GdiPlusUser – starts GDI+; one instance must exist while the package is used
  • GdiPlusBase – the base class of the classes: LastResult, the status text and the error handling
  • GdiPlusAbort – an object that GDI+ can ask whether to stop (GDI+ does not use it)
  • Helpers – the functions and constants that belong to no class: status text, pixel formats, effect IDs, metafile headers, property tags
  • ImageCodec – the installed encoders and decoders, and the IDs of image formats and encoder parameters

Drawing

  • Graphics – the drawing surface: lines, shapes, text and images on a bitmap, a window or a device context
  • VBGraphics – a Graphics that also draws with the Line, Circle and PSet statements of Visual Basic
  • IDeviceContext – the interface to hand out a Windows device context
  • ITransformable – the members that classes with a transformation matrix share

Paths, regions and transformations

  • GraphicsPath – a sequence of connected lines, curves and shapes
  • PathIterator – reads the figures and points of a path one part after another
  • PathData – the points of a path and their types, in memory
  • Region – an area of a drawing surface, of any shape
  • Matrix – a 3 by 3 affine transformation

Pens and brushes

Images and effects

Text

Types

The Types page lists the structures of the package, in groups:

Enumerations

The Enumerations page lists the 74 enumerations of the package, in groups by topic. Most follow the GDI+ headers, with Gp in front of the name, such as GpUnit, GpSmoothingMode, GpFontStyle, PixelFormat and GpStatus. CColor names 140 common colours.

See Also