Appendix N
Graphics
This appendix provides information about graphics classes used by Windows Forms applications.
GRAPHICS NAMESPACES
This section describes the most important graphics namespaces and their most useful classes, structures, and enumerated values.
System.Drawing
This namespace defines the most important graphics objects such as Graphics, Pen, Brush, Font, FontFamily, Bitmap, Icon, and Image. The following table describes the namespace’s most useful classes and structures.
| CLASSES AND STRUCTURES | PURPOSE |
| Bitmap | Represents a bitmap image defined by pixel data. |
| Brush | Represents area fill characteristics. |
| Color | Defines a color’s red, green, blue, and alpha components as values between 0 and 255. Alpha = 0 means the object is transparent, and alpha = 255 means it is opaque. |
| Font | Represents a particular font (name, size, and style, such as italic or bold). |
| FontFamily | Represents a group of typefaces with similar characteristics. |
| Graphics | Represents a drawing surface. Provides methods to draw on the surface. |
| Icon | Represents a Windows icon. |
| Image | Abstract base class from which Bitmap, Icon, and Metafile inherit. |
| Metafile | Represents a graphic metafile that contains drawing commands (in contrast to rasterized bitmap data). |
| Pen | Represents line drawing characteristics such as color, thickness, and dash style. |
| Pens | Provides a large number of predefined pens with different colors and thickness 1. |
| Point | Defines a point’s X and Y coordinates. |
| PointF | Defines a point’s X and Y coordinates with floating-point values. |
| Rectangle | Defines a rectangle using a Point and a Size. |
| RectangleF | Defines a rectangle using a PointF and a SizeF (with floating-point values). |
| Region | Defines a shape created from rectangles and paths for use in filling, hit testing, or clipping. |
| Size | Defines a width and height. |
| SizeF | Defines a width and height with floating-point values. |
| SolidBrush | Represents a solid brush. |
System.Drawing.Drawing2D
This namespace contains classes for more advanced two-dimensional drawing. Some of these classes refine more basic drawing classes. For example, the HatchBrush class represents a specialized type of Brush that fills with a hatch pattern. Other classes define values for use by other graphics classes. For example, the Blend class defines color-blending parameters for a LinearGradientBrush.
The following table describes this namespace’s most useful classes and enumerations.
| CLASSES AND ENUMERATIONS | PURPOSE |
| Blend | Defines blend characteristics for a LinearGradientBrush. |
| ColorBlend | Defines blend characteristics for a PathGradientBrush. |
| DashCap | Enumeration that determines how the ends of each dash in a dashed line are drawn. |
| DashStyle | Enumeration that determines how a dashed line is drawn. |
| GraphicsPath | Represents a series of connected lines and curves for drawing, filling, or clipping. |
| HatchBrush | Defines a Brush that fills an area with a hatch pattern. |
| HatchStyle | Enumeration that determines the hatch style used by a HatchBrush object. |
| LinearGradientBrush | Defines a Brush that fills an area with a linear color gradient. |
| LineCap | Enumeration that determines how the ends of a line are drawn. |
| LineJoin | Enumeration that determines how lines are joined by a method that draws connected lines such as Graphics.DrawLines or Graphics.DrawPolygon. |
| Matrix | Represents a transformation matrix. |
| PathGradientBrush | Defines a Brush that fills an area with a color gradient that follows a path. |
System.Drawing.Imaging
This namespace contains objects that deal with more advanced bitmap graphics. It includes classes that define image file formats such as GIF and JPG, classes that manage color palettes, and classes that define metafiles. The following table describes this namespace’s most useful classes.
| CLASS | PURPOSE |
| ColorMap | Defines a mapping from old color values to new ones. |
| ColorPalette | Represents a palette of color values. |
| ImageFormat | Specifies an image’s format (.bmp, .emf, .gif, .jpg, and so on). |
| Metafile | Represents a graphic metafile that contains drawing instructions. |
| MetafileHeader | Defines the attributes of a Metafile object. |
| MetaHeader | Contains information about a Windows metafile (WMF). |
| WmfPlaceableFileHeader | Specifies how a metafile should be mapped to an output device. |
System.Drawing.Printing
This namespace contains objects for printing and managing the printer’s characteristics. The following table describes the most useful of these classes.
| CLASS | PURPOSE |
| Margins | Defines the margins for the printed page. |
| PageSettings | Defines the page settings either for an entire PrintDocument or for a particular page. This object has properties that are Margins, PaperSize, PaperSource, PrinterResolution, and PrinterSettings objects. |
| PaperSize | Defines the paper’s size. |
| PaperSource | Defines the printer’s paper source. |
| PrinterResolution | Defines the printer’s resolution. |
| PrinterSettings | Defines the printer’s settings. |
System.Drawing.Text
This namespace contains only three classes, all of which are for working with installed fonts. The following table describes these classes.
| CLASS | PURPOSE |
| FontCollection | Base class for the derived InstalledFontCollection and PrivateFontCollection classes. |
| InstalledFontCollection | Provides a list of the system’s installed fonts. |
| PrivateFontCollection | Provides a list of the application’s privately installed fonts. |
DRAWING CLASSES
The basic steps for drawing in Visual Basic are to obtain a Graphics object and use its methods to draw shapes. Brush classes determine how shapes are filled, and Pen classes determine how lines are drawn.
The following sections describe the most useful properties and methods provided by key drawing classes, including the Graphics, Pen, and Brush classes.
Graphics
The Graphics object represents a drawing surface. It provides many methods for drawing shapes, filling areas, and determining the appearance of drawing results.
All of the drawing methods (as opposed to the filling methods) except DrawString take a Pen object as a parameter to determine the lines’ color, thickness, dash style, and other properties. DrawString takes a Brush object instead of a Pen object as a parameter.
The following table lists the Graphics object’s drawing methods.
| DRAWING METHOD | PURPOSE |
| DrawArc | Draws an arc of an ellipse. |
| DrawBezier | Draws a Bézier curve. |
| DrawBeziers | Draws a series of connected Bézier curves. |
| DrawClosedCurve | Draws a smooth closed curve that connects a series of points, joining the final point to the first point. |
| DrawCurve | Draws a smooth curve that connects a series of points. |
| DrawEllipse | Draws an ellipse. |
| DrawIcon | Draws an Icon onto the Graphics object’s drawing surface. |
| DrawIconUnstretched | Draws an Icon object onto the Graphics object’s drawing surface without scaling. |
| DrawImage | Draws an Image object onto the Graphics object’s drawing surface. |
| DrawImageUnscaled | Draws an Image object onto the drawing surface without scaling. |
| DrawLine | Draws a line. |
| DrawLines | Draws a series of connected lines. |
| DrawPath | Draws a GraphicsPath object. |
| DrawPie | Draws a pie slice taken from an ellipse. |
| DrawPolygon | Draws a polygon. |
| DrawRectangle | Draws a rectangle. |
| DrawRectangles | Draws a series of rectangles. |
| DrawString | Draws text. |
The following table lists the Graphics object’s area filling methods. These methods take Brush objects as parameters to determine the filled shape’s color, hatch pattern, gradient colors, and other fill characteristics.
| FILLING METHOD | PURPOSE |
| FillClosedCurve | Fills a smooth curve that connects a series of points. |
| FillEllipse | Fills an ellipse. |
| FillPath | Fills a GraphicsPath object. |
| FillPie | Fills a pie slice taken from an ellipse. |
| FillPolygon | Fills a polygon. |
| FillRectangle | Fills a rectangle. |
| FillRectangles | Fills a series of rectangles. |
| FillRegion | Fills a Region object. |
The following table lists other useful Graphics object properties and methods.
| PROPERTIES AND METHODS | PURPOSE |
| AddMetafileComment | Adds a comment to a metafile. |
| Clear | Clears the Graphics object and fills it with a specific color. |
| Clip | Determines the Region object used to clip any drawing the program does on the Graphics surface. |
| Dispose | Releases the resources held by the Graphics object. |
| DpiX | Returns the horizontal number of dots per inch (DPI) for this object’s surface. |
| DpiY | Returns the vertical number of dots per inch (DPI) for this object’s surface. |
| EnumerateMetafile | Invokes a callback method for each record defined in a metafile. |
| ExcludeClip | Updates the Graphics object’s clipping region to exclude the area defined by a Region or Rectangle. |
| FromHdc | Creates a new Graphics object from a device context handle (hDC). |
| FromHwnd | Creates a new Graphics object from a window handle (hWnd). |
| FromImage | Creates a new Graphics object to draw on an Image object. |
| InterpolationMode | Controls anti-aliasing when drawing scaled images to determine how smooth the result is. |
| IntersectClip | Updates the Graphics object’s clipping region to be the intersection of the current clipping region and the area defined by a Region or Rectangle. |
| IsVisible | Returns True if a specified point is within the Graphics object’s visible clipping region. |
| MeasureCharacterRanges | Returns an array of Region objects that show where each character in a string will be drawn. |
| MeasureString | Returns a SizeF structure that gives the size of a string drawn on the Graphics object with a particular font. |
| MultiplyTransform | Multiplies the Graphics object’s current transformation matrix by another transformation matrix. |
| PageScale | Determines the amount by which drawing commands are scaled. |
| PageUnit | Determines the units of measurement: Display (depends on the device, typically pixel for monitors and 1/100 inch for printers), Document (1/300 inch), Inch, Millimeter, Pixel, or Point (1/72 inch). |
| RenderingOrigin | Determines the point used as a reference when hatching. |
| ResetClip | Resets the object’s clipping region so that the drawing is not clipped. |
| ResetTransformation | Resets the object’s transformation matrix to the identity matrix. |
| Restore | Restores the Graphics object to a state saved by the Save method. |
| RotateTransform | Adds a rotation to the object’s current transformation. |
| Save | Saves the object’s current state. |
| ScaleTransform | Adds a scaling transformation to the Graphics object’s current transformation. |
| SetClip | Sets or merges the Graphics object’s clipping area to another Graphics object, a GraphicsPath object, or a Rectangle. |
| SmoothingMode | Controls anti-aliasing when drawing lines, curves, or filled areas. |
| TextRenderingHint | Controls anti-aliasing and hinting when drawing text. |
| Transform | Gets or sets the Graphics object’s transformation matrix. |
| TransformPoints | Applies the object’s current transformation to an array of points. |
| TranslateTransform | Adds a translation transformation to the Graphics object’s current transformation. |
Pen
The Pen object determines the appearance of drawn lines. It determines such properties as a line’s width, color, and dash style. The following table lists the Pen object’s most useful properties and methods.
| PROPERTIES AND METHODS | PURPOSE |
| Alignment | Determines whether the line is drawn inside or centered on the theoretical perfectly thin line specified by the drawing routine. |
| Brush | Determines the Brush used to fill the line. |
| Color | Determines the line’s color. |
| CompoundArray | Lets you draw a line that is striped lengthwise. |
| CustomEndCap | Determines the line’s end cap. |
| CustomStartCap | Determines the line’s start cap. |
| DashCap | Determines the cap drawn at the ends of dashes. |
| DashOffset | Determines the distance from the start of the line to the start of the first dash. |
| DashPattern | An array of Singles that specifies a custom dash pattern. |
| DashStyle | Determines the line’s dash style. |
| EndCap | Determines the cap used at the end of the line. |
| LineJoin | Determines how lines are joined by a method that draws connected lines such as DrawPolygon. |
| MultiplyTransform | Multiplies the Pen object’s current transformation by another transformation matrix. |
| ResetTransform | Resets the Pen object’s transformation to the identity transformation. |
| RotateTransform | Adds a rotation transformation to the Pen object’s current transformation. |
| ScaleTransform | Adds a scaling transformation to the Pen object’s current transformation. |
| SetLineCap | This method takes parameters that let you specify the Pen object’s StartCap, EndCap, and LineJoin properties at the same time. |
| StartCap | Determines the cap used at the start of the line. |
| Transform | Determines the transformation applied to the initially circular “pen tip” used to draw lines. |
| Width | The width of the pen. |
Brushes
The Brush class is an abstract class, so you cannot make instances of it. Instead, you must make instances of one of its derived classes: SolidBrush, TextureBrush, HatchBrush, LinearGradientBrush, or PathGradientBrush. The following table briefly describes these classes.
| CLASS | PURPOSE |
| SolidBrush | Fills areas with a single solid color. |
| TextureBrush | Fills areas with a repeating image. |
| HatchBrush | Fills areas with a repeating hatch pattern. |
| LinearGradientBrush | Fills areas with a linear gradient of two or more colors. |
| PathGradientBrush | Fills areas with a color gradient that follows a path. |
GraphicsPath
The GraphicsPath object represents a path defined by lines, curves, text, and other drawing commands. You can use Graphics object methods to fill and draw a GraphicsPath, and you can use a GraphicsPath to define a clipping region. The following table lists the GraphicsPath object’s most useful properties and methods.
| PROPERTIES AND METHODS | PURPOSE |
| CloseAllFigures | Closes all open figures by connecting their last points with their first points and then starts a new figure. |
| CloseFigure | Closes the current figure by connecting its last point with its first point and then starts a new figure. |
| FillMode | Determines how the path handles overlaps when you fill it. This property can take the values Alternate and Winding. |
| Flatten | Converts any curves in the path into a sequence of lines. |
| GetBounds | Returns a RectangleF structure representing the path’s bounding box. |
| GetLastPoint | Returns the last PointF structure in the PathPoints array. |
| IsOutlineVisible | Returns True if the indicated point lies beneath the path’s outline. |
| IsVisible | Returns True if the indicated point lies in the path’s interior. |
| PathData | Returns a PathData object that encapsulates the path’s graphical data. |
| PathPoints | Returns an array of PointF structures giving the points in the path. |
| PathTypes | Returns an array of Bytes representing the types of the points in the path. |
| PointCount | Returns the number of points in the path. |
| Reset | Clears the path data and resets FillMode to Alternate. |
| Reverse | Reverses the order of the path’s data. |
| StartFigure | Starts a new figure, so future data is added to the new figure. |
| Transform | Applies a transformation matrix to the path. |
| Warp | Applies a warping transformation defined by mapping a parallelogram onto a rectangle to the path. |
| Widen | Enlarges the curves in the path to enclose a line drawn by a specific pen. |
StringFormat
The StringFormat object determines how text is formatted. It enables you to draw text that is centered vertically or horizontally, aligned on the left or right, and wrapped or truncated. The following table lists the StringFormat object’s most useful properties and methods.
| PROPERTIES AND METHODS | PURPOSE |
| Alignment | Determines the text’s horizontal alignment. This can be Near (left), Center (middle), or Far (right). |
| FormatFlags | Gets or sets flags that modify the StringFormat object’s behavior. |
| GetTabStops | Returns an array of Singles giving the positions of tab stops. |
| HotkeyPrefix | Determines how the hotkey prefix character is displayed. This can be Show, Hide, or None. |
| LineAlignment | Determines the text’s vertical alignment. This can be Near (top), Center (middle), or Far (bottom). |
| SetMeasureableCharacter Ranges | Sets an array of CharacterRange structures representing ranges of characters that will later be measured by the Graphics object’s MeasureCharacterRanges method. |
| SetTabStops | Sets an array of Singles giving the positions of tab stops. |
| Trimming | Determines how the text is trimmed if it cannot fit within a layout rectangle. |
Image
The Image class represents the underlying physical drawing surface hidden below the logical layer created by the Graphics class. Image is an abstract class, so you cannot directly create instances of it. Instead, you must create instances of its child classes Bitmap and Metafile.
The following table describes the Image class’s most useful properties and methods, which are inherited by the Bitmap and Metafile classes.
| PROPERTIES AND METHODS | PURPOSE |
| Dispose | Frees the resources associated with this image. |
| Flags | Returns attribute flags for the image. |
| FromFile | Loads an image from a file. |
| FromHbitmap | Loads a Bitmap image from a Windows bitmap handle. |
| FromStream | Loads an image from a data stream. |
| GetBounds | Returns a RectangleF structure representing the rectangle’s bounds. |
| GetPixelFormatSize | Returns the color resolution (bits per pixel) for a specified PixelFormat. |
| GetThumbnailImage | Returns a thumbnail representation of the image. |
| Height | Returns the image’s height. |
| HorizontalResolution | Returns the horizontal resolution of the image in pixels per inch. |
| IsAlphaPixelFormat | Returns True if the specified PixelFormat contains alpha information. |
| Palette | Determines the ColorPalette object used by the image. |
| PhysicalDimension | Returns a SizeF structure giving the image’s dimensions in pixels for Bitmaps and 0.01 millimeters for Metafiles. |
| PixelFormat | Returns the image’s pixel format. |
| RawFormat | Returns an ImageFormat object representing the image’s raw format. |
| RotateFlip | Rotates, flips, or rotates and flips the image. |
| Save | Saves the image in a file or stream with a given data format. |
| Size | Returns a Size structure containing the image’s width and height in pixels. |
| VerticalResolution | Returns the vertical resolution of the image in pixels per inch. |
| Width | Returns the image’s width. |
Bitmap
The Bitmap class represents an image defined by pixel data. It inherits the Image class’s properties and methods described in the previous section. The following table describes some of the most useful new methods added by the Bitmap class.
| METHOD | PURPOSE |
| FromHicon | Loads a Bitmap image from a Windows icon handle. |
| FromResource | Loads a Bitmap image from a Windows resource. |
| GetPixel | Returns a Color representing a specified pixel. |
| LockBits | Locks the Bitmap image’s data in memory, so it cannot move until the program calls UnlockBits. |
| MakeTransparent | Makes all pixels with a specified color transparent by setting the alpha component of those pixels to 0. |
| SetPixel | Sets a specified pixel’s Color value. |
| SetResolution | Sets the Bitmap image’s horizontal and vertical resolution in dots per inch (DPI). |
| UnlockBits | Unlocks the Bitmap image’s data in memory so that the system can relocate it, if necessary. |
Metafile
The Metafile class represents an image defined by metafile records. Those records define drawing commands so the image can be smoothly scaled. In contrast, a Bitmap contains pixel data that cannot be resized without some jagged or fuzzy appearance.
The Metafile class inherits the Image class’s properties and methods described in the section “Image” earlier in this appendix. The following table describes some of the most useful new methods added by the Metafile class.
| METHOD | PURPOSE |
| GetMetafileHeader | Returns the MetafileHeader object associated with this Metafile. |
| PlayRecord | Plays a metafile record. Use the Graphics class’s EnumerateMetafile method to get the data needed to play metafile records. |