class Draw

The class encapsulates system-dependent internals of graphical output. Whenever you need to paint something in a window, you need a Draw object for it. The standard Paint method of the Ctrl class takes a Draw& parameter as well. In that case the underlying mechanism passes a Draw which is already initialized for output into the respective control, knows about the current clipping, resolution etc. In a similar manner you can create your own Draw objects to draw onto Images, Drawings (vector metafiles used for serialization of graphical operations) or to perform printer output. You can also use a Draw to query graphics-related properties of various output devices, like pixel size, resolution, supported color model, available fonts etc.

Although the internals of graphical output are very system-dependent, the Draw class is designed so as to hide most of the OS-specific details and present a unified portable interface regardless of the actual target device or object. The downside of this approach is that Draw capabilities are somewhat limited to cover most frequently used graphical objects and attributes. It is quite possible (and in certain situations rather common) that its interface lacks some advanced capabilities, although they are supported in the target operating system. For these situations the Draw object supports also methods which allow you to extend its capabilities by utilizing low-level, system specific code, and accessing the output device at the native system level. Of course, heavy use of such capabilities makes writing portable code very difficult.

The operations supported by the Draw class can be divided into several categories:

initialization and configuration of the output device

querying output device properties

managing colors

managing text styles

controlling current clipping region and drawing offset

drawing basic vector primitives (lines, polygons)

drawing raster primitives

drawing text

accessing Drawing-specific functions

accessing unified virtual output interface

accessing the underlying physical output device interface

accessing device-secific functions

Initialization and configuration of the output device

Win32-specific: initializes the Draw object to output on a Window device context (HDC). This is the usual Windows method to paint into windows, on memory-mapped bitmaps and on the printer.

Note: it is seldom necessary to construct the Draw object in this way. System-independent U++ layer hides such system-specific internals within upper-level abstract objects (PrintDraw, ImageDraw, ViewDraw). Remember that, by directly handling device contexts, you are depraved of a multitude of U++ internal housekeeping chores and checks which ensure that the device context and potentially its attributes are properly allocated and destroyed as necessary. For a complete set of rules for working with device contexts, see Microsoft Windows documentation.

X11-specific: initializes the draw object to output on a X-Windows drawable using a given graphics context (GC). This is the usual X-Windows method to paint into windows and on memory-mapped bitmaps.

Note: it is seldom necessary to construct the Draw object in this way. System-independent U++ layer hides such system-specific internals within upper-level abstract objects (ImageDraw, ViewDraw). Remember that, by directly handling device contexts, you are depraved of a multitude of U++ internal housekeeping chores and checks which ensure that the device context and potentially its attributes are properly allocated and destroyed as necessary. For a complete set of rules for working with device contexts, see X Windows documentation.

X11-specific: initializes the draw object to output on a X-Windows drawable using a given graphics context (GC). This is the usual X-Windows method to paint into windows and on memory-mapped bitmaps.

Note: it is seldom necessary to construct the Draw object in this way. System-independent U++ layer hides such system-specific internals within upper-level abstract objects (ImageDraw, ViewDraw). Remember that, by directly handling device contexts, you are depraved of a multitude of U++ internal housekeeping chores and checks which ensure that the device context and potentially its attributes are properly allocated and destroyed as necessary. For a complete set of rules for working with device contexts, see X Windows documentation.

Initializes internal variables for output on a previously set output device.

Note: this is normally not necessary. This function is called only from derived classes which need to set the output device handle (HDC under Win32, GC under X Windows) manually.

X Windows-specific: initializes Draw internals for output on a previously set output device. The parameters give clipping region and output offset to initialize the clipping stack with.

Querying output device properties

bool PaletteMode() const

Checks whether the current output device is palette-based or RGB-based. Monochrome devices are treated as RGB-based.

bool IsMono() const

Check whether the current output device is monochrome.

Size GetPagePixels() const

Returns pixel page size. For virtual output devices (like Drawings), this is the same as dot page size.

Size GetPageMMs() const

Returns physical output page size in millimeters.

Size GetPixelsPerInch() const

Returns the resolution of the output device.

Size GetSheetPixels() const

Returns pixel size of the output page including physical margins. This is meaningful only for printers for which the printable area is sometimes smaller than the actual paper size. For such devices GetSheetPixels returns pixel size of the original (full) paper including the margins unsuitable for printing, whereas GetPagePixels returns the printable area size (paper size minus physically enforced margins).

Point GetPageOffset() const

Returns pixel offset of the topleft corner of the printable output area from the topleft corner of the physical output medium (printer paper). This is meaningful only for printers where the printable area is sometimes smaller than the actual paper size (see also GetSheetPixels). By subtracting GetPageOffset() from a pair of coordinates it is possible to position objects absolutely with respect to the paper edges.

bool Pixels() const

Checks whether the output device coordinates are pixel-based or dot-based. This is the negation of the Dots() function. Window and image draws are pixel-based, whereas printer and Drawing draws are normally dot-based.

bool Dots() const

Checks whether the output device coordinates are pixel-based or dot-based. This is the negation of the Pixels() function. Window and image draws are pixel-based, whereas printer and Drawing draws are normally dot-based.

bool IsPrinter() const

Checks whether the output device is a printer.

bool IsAborted() const

Checks whether the output job has been aborted. This is meaningful mainly for printers.

bool IsBack() const

Checks whether output device supports double-buffering. For devices with double-buffering it is not necessary (and is usually counterproductive) to take measures to prevent flickering as the whole output is composed offscreen. Output devices without direct video output (like Drawings or Images) are return true (as there is no direct video output, it is not necessary to prevent flickering).

bool IsDrawing() const

Checks whether the output device is a Drawing.

bool IsMetaFile() const

Win32-specific: Checks whether the output device is a Windows Metafile.

Managing colors

Different output devices and their technologies pose natural limitations on producing color output. The basic classes of devices with respect to their color management are:

Monochrome devices (like monochrome laser printers or certains specialized displays) support no color at all. Every pixel of the output device can be black or white.

Palette-based devices (like old 16- or 256-color displays) support a fixed set of distinct color slots, called a palette. Colors of the individual slots can be either user-settable or fixed (system-set). Every pixel of the output device is an index into the palette.

RGB-based devices (HiColor or TrueColor displays), in which every pixel of the output device can be set to any of the colors displayable by the device. Typically each pixel has at least 16 bits comprising of 5- or 8-bit subfields for the red, green, and blue color component.

Logical color model used by the Draw class communicates colors using device-independent color values (as represented by the Color class). Graphical output functions convert these colors on-the-fly to physical colors supported by the system. Pixel- and line-oriented output objects (lines, polylines, ellipses) paint the requested objects with the nearest available physical color to the requested logical color, whereas area- and raster-oriented output objects (rectangles, polygons, and images) use dithering to approximate logical colors not directly produceable by the device.

Draw supports two ways of using palette-based output devices:

Automatic palette: upon initialization Draw sets up the system palette to contain a matrix of 6x6x6 RGB triplets for all combinations of 6 equidistant intensities of the color components, a 16-level gray scale plus 16 basic system colors. This fixed color palette enables the system to closely mimic the behaviour of RGB-based color systems.

User palette: Draw works with the current palette as set by the system / user. Nearest match is used for logical color mapping.

static bool AutoPalette()

Checks palette mode of the active output device.

static void SetAutoPalette(bool ap)

Turns automatic palette mode on or off.

Updates logical palette of basic system-dependent colors (SLtGray, SWhite, SBlack etc.).

Managing text styles

static int CALLBACK AddFace(const LOGFONT *logfont, const TEXTMETRIC *, dword type, LPARAM param)

static void SetStdFont(Font font)

Sets the font to be used as the standard font (StdFont, Font::STDFONT).

static Font GetStdFont()

Returns the current standard font.

static Size GetStdFontSize()

Returns the letter box width and height of the current standard font.

static int GetStdFontCy()

Returns letter box width and height of the current standard font

Returns font information object describing given font and charset.

Returns font information object describing given font.

Returns Unicode font information for a given font.

Controlling current clipping region and drawing offset

Sometimes it is necessary or at least handy to move the logical coordinate origin and limit output clipping for a part of the drawing process. For this reason, coordinate origin displacement together with current clipping region is kept as a stack in the Draw object. Certain function push a new offset / clipping entry to the stack, other functions manipulate the current top of stack. Actual coordinate origin and clipping in effect while drawing corresponds to the entry on top of the stack. At the beginning the coordinate origin is usually set to topleft corner of the output medium and the clipping box encapsulates all available output area (or, like in case of Ctrl::Paint, the current "dirty" area that needs to be repainted in a window).

void Begin()

Duplicates the current entry on the top of the coordinate / clipping stack. This effectively doesn't change the current coordinate / clipping setting but creates a new entry which can be further manipulated by other methods like IntersectClip or ExcludeClip.

void End()

Discards one coordinate / clipping entry from top of the stack.

void Offset(Point p)

Creates a new coordinate / clipping entry on top of the stack equal to the previous entry with coordinate origin shifted by p pixels.

void Offset(int x, int y)

Creates a new coordinate / clipping entry on top of the stack equal to the previous entry with coordinate origin shifted by (x, y) pixels.

bool Clip(const Rect& r)

Creates a new coordinate / clipping entry on top of the stack with coordinate origin equal to the previous value and clipping equal to the intersection of the previous clipping region with the rectangle r.

bool Clip(int x, int y, int cx, int cy)

Creates a new coordinate / clipping entry on top of the stack with coordinate origin equal to the previous value and clipping equal to the intersection of the previous clipping region with the rectangle given by its topleft origin (relative to the current coordinate origin) (x, y), width cx and height cy.

bool Clipoff(const Rect& r)

Creates a new coordinate / clipping entry on top of the stack with clipping equal to the intersection of the previous clipping region with the rectangle r and with the coordinate origin shifted by r.TopLeft() pixels. For further drawing operations the current pixel r.TopLeft() will correspond to (0, 0) and r.BottomRight() to (r.Width(), r.Height()).

bool Clipoff(int x, int y, int cx, int cy)

Creates a new coordinate / clipping entry on top of the stack with clipping equal to the intersection of the previous clipping region with the rectangle r and with the coordinate origin shifted by (x, y) pixels. For further drawing operations the current pixel (x, y) will correspond to (0, 0).

bool ExcludeClip(const Rect& r)

Updates the current clipping region on top of the coordinate / clipping stack by subtracting the rectangle r from the current clipping region.

bool ExcludeClip(int x, int y, int cx, int cy)

Updates the current clipping region on top of the coordinate / clipping stack by subtracting the rectangle RectC(x, y, cx, cy) from the current clipping region.

bool IntersectClip(const Rect& r)

Updates the current clipping region on top of the coordinate / clipping stack by intersecting the rectangle r with the current clipping region.

bool IntersectClip(int x, int y, int cx, int cy)

Updates the current clipping region on top of the coordinate / clipping stack by intersecting the rectangle RectC(x, y, cx, cy) with the current clipping region.

Rect GetClip() const

Returns the smallest rectangle fully covering the current clipping region. The value can be used to limit output to the visible area. Take care not to mix the current clipping region with the output rectangle as the clipping region can be just a subset of this output rectangle (like in case of Ctrl::Paint when a part of the window is obscured).

Point GetOffset() const

Returns the current coordinate origin. This is naturally in absolute coordinates relative to the topleft corner of the output medium.

int GetCloffLevel() const

Returns the number of entries on the coordinate / clipping stack. This is normally used for self-consistency check where the drawing routine ASSERTs that after drawing something the stack depth is the same as it was before (to check whether there is not a stack 'leak' when the drawing routine forgets to End some coordinate / clipping entries it has previously pushed on the stack).

Point LPtoDP(Point p) const

Converts a point from coordinates relative to current coordinate origin to absolute coordinates from the topleft corner of the output medium. This effectively adds the current coordinate origin to the given point p.

Point DPtoLP(Point p) const

Converts a point from the absolute coordinates (from the topleft corner of the output medium) to coordinates relative to current coordinate origin. This effectively subtracts the current coordinate origin from the point p.

Rect LPtoDP(const Rect& r) const

Converts a rectangle from coordinates relative to current coordinate origin to absolute coordinates from the topleft corner of the output medium. This effectively offsets the rectangle r by the amount given by the current coordinate origin.

Rect DPtoLP(const Rect& r) const

Converts a rectangle from the absolute coordinates (with respect to the topleft corner of the output medium) to coordinates relative to current coordinate origin. This effectively offsets the rectangle r by the negative value of the current coordinate origin.

Drawing basic vector primitives (lines, polygons)

void DrawRect(int x, int y, int cx, int cy, Color color)

Fills rectangle RectC(x, y, cx, cy) with the color color. On palette-based devices dithering is sometimes used for approximation when the given color doesn't closely correnspond to one of the available colors (see Managing colors).

void DrawRect(const Rect& rect, Color color)

Fills rectangle rect with the color color. On palette-based devices dithering is sometimes used for approximation when the given color doesn't closely correnspond to one of the available colors (see Managing colors).

void DrawLine(int x1, int y1, int x2, int y2, int width = 0, Color color = DefaultInk)

Draws a line from the point (x1, y1) to (x2, y2) with color color. When width is positive, solid line width pixels wide is drawn. When width is negative, function draws a dashed line 1 pixel wide. width is then one of the PEN_... enumeration constants defining the desired line pattern. The fact that the function doesn't support wide dashed lines is a sad limitation of the older Win32 GDI which under Windows 95, 98 and ME doesn't support this. When wide dashed lines are needed, it is necessary to generate the segments manually and split the line patterns into individual line segments or into polygonal patches (depending on the precision requirements and time issues in given context). Under Win32 GDI the point (x1, y1) is not drawn.

void DrawLine(Point p1, Point p2, int width = 0, Color color = DefaultInk)

Draws a line from the point p1 to p2 with color color. width gives line width (positive) or dash pattern (negative). Under Win32 GDI the point (x1, y1) is not drawn.

void DrawEllipse(const Rect& r, Color color = DefaultInk, int pen = Null, Color pencolor = DefaultInk)

Draws the largest ellipse with both axes parallel to coordinate axes fully within rectangle r, i.e. with center point at r.CenterPoint(), semi major axis and semi minor axis equal to r.Width() / 2 and r.Height() / 2.

void DrawEllipse(int x, int y, int cx, int cy, Color color = DefaultInk, int pen = Null, Color pencolor = DefaultInk)

Draws the largest ellipse with both axes parallel to coordinate axes fully within rectangle RectC(x, y, cx, cy), i.e. with center point at x + cx / 2 and y + cy / 2, semi major axis and semi minor axis equal to cx / 2 and cy / 2.

void DrawArc(const Rect& rc, Point start, Point end, int width = 0, Color color = DefaultInk)

Draws elliptic arc corresponding to the largest ellipse fully within the rectangle rc and running counterclockwise from the direction corresponding to the line connecting the centre of the ellipse (rc.CenterPoint()) with the point start and ending at direction of the point end from the ellipse centre. When start == end, the full ellipse is drawn.

void DrawPolyPolyline(const Point *vertices, int vertex_count, const int *counts, int count_count, int width = 0, Color color = DefaultInk, Color doxor = Null)

Draws a series of polylines. Polyline vertices are kept in the array vertices. The parameter vertext_count gives the total number of vertices of all polylines in the array. The array counts gives numbers of points defining the individual polylines and count_count gives number of entries in this array (i.e. the number of connected polylines). The first polyline comprises vertices vertices[0], vertices[1] ... vertices[counts[0] - 1], the second polyline vertices[counts[0]], vertices[counts[0] + 1] ... vertices[counts[0] + counts[1] - 1], etc.

void DrawPolyPolyline(const Vector<Point>& vertices, const Vector<int>& counts, int width = 0, Color color = DefaultInk, Color doxor = Null)

Draws a series of polylines. Polyline vertices are kept in the array vertices. The array counts gives numbers of points defining the individual polylines (i.e. the number of connected polylines is equal to counts.GetCount()). The first polyline comprises vertices vertices[0], vertices[1] ... vertices[counts[0] - 1], the second polyline vertices[counts[0]], vertices[counts[0] + 1] ... vertices[counts[0] + counts[1] - 1], etc.

void DrawPolyline(const Point *vertices, int count, int width = 0, Color color = DefaultInk, Color doxor = Null)

Draws a single polyline connecting all count vertices.

void DrawPolyline(const Vector<Point>& vertices, int width = 0, Color color = DefaultInk, Color doxor = Null)

Draws a single polyline connecting all vertices.

void DrawPolyPolyPolygon(const Point *vertices, int vertex_count, const int *subpolygon_counts, int subpolygon_count_count, const int *disjunct_polygon_counts, int disjunct_polygon_count_count, Color color = DefaultInk, int width = 0, Color outline = Null, Image image = Null, Color doxor = Null)

Draws a series of complex polygons (i.e. polygons which may contain holes). The vertices array holds all polygon defining vertices. The array is divided into sections corresponding to the whole complex polygons (parameters disjunct_polygon_counts and disjunct_polygon_count_count) and these sections are further divided into the individual polygons defining one complex polygon (i.e. outer boundary and holes). Numbers of vertices in the individual polygons are held in the array subpolygon_counts (total number of simple polygons = subpolygon_count_count).

Drawing raster primitives

void DrawImage(int x, int y, int cx, int cy, const Image& img, const Rect& src)

void DrawImage(int x, int y, int cx, int cy, const Image& img)

void DrawImage(int x, int y, int cx, int cy, const Image& img, const Rect& src, Color color)

void DrawImage(int x, int y, int cx, int cy, const Image& img, Color color)

void DrawImage(const Rect& r, const Image& img, const Rect& src)

void DrawImage(const Rect& r, const Image& img)

void DrawImage(const Rect& r, const Image& img, const Rect& src, Color color)

void DrawImage(const Rect& r, const Image& img, Color color)

void DrawImage(int x, int y, const Image& img, const Rect& src)

void DrawImage(int x, int y, const Image& img)

void DrawImage(int x, int y, const Image& img, const Rect& src, Color color)

void DrawImage(int x, int y, const Image& img, Color color)

Draws an Image at specified position. If the position specifies dimension (cx, cy or is defined using  Rect r, Image is rescaled. If color is provided, only Image alpha channel is used and painted with the specified color. src can be used specify only a portion of the source Image to be painted.

Measures width and height of a Unicode text (as when painted using given font).

Draws text on the output device.

Note: when working with rotated texts, always remember that [x, y] define the topleft corner of the text box. Box size is that returned by the function GetTextSize. In case of rotated texts, the text box is naturally not aligned with the coordinate axes. Also, some system fonts do not support rotation (bitmap fonts). Unfortunately there is currently no reliable way to detect if a font supports rotation. FontInfo::IsScaleable should provide a good guess as to whether a given font supports rotation.

Draws text on the output device. This is a simplified version of the above function for the most common case when angle == 0 (i.e. the text is being painted in the ordinary direction from left to right).

Measures width and height of a Unicode text (as when painted using given font).

Draws text on the output device (from left to right). This is a variation of one of the above function for the case when the input parameter is a WString. In such situation the number of letters is known (text.GetLength()) and doesn't (indeed shoudn't) be measured using wcslen.

Draws text on the output device. A variation of the above function allowing text rotation. See above notes concerning text rotation issues.

Measures text box size for text in given character set.

Draw given text in a given character set to the ouput device. This variant allows text rotation.

Draws text in given character set to the output device (from left to right).

Measures text box size for a text encoded in system-defau