CGpGraphics.DrawDriverStringmethod

Draws characters at the specified positions.

GraphicsmethodCGpGraphics.incdocumented

Syntax

FUNCTION DrawDriverString (BYVAL pText AS UINT16 PTR, BYVAL length AS INT_, BYVAL pFont AS CGpFont PTR, BYVAL pBrush AS CGpBrush PTR, BYVAL positions AS ANY PTR, BYVAL flags AS INT_, BYVAL pMatrix AS CGpMatrix PTR) AS GpStatus

Parameters

Name		Description
`pText`		Pointer to an array of 16-bit values. If the DriverStringOptionsCmapLookup flag is set, each value specifies a Unicode character to be displayed. Otherwise, each value specifies an index to a font glyph that defines a character to be displayed.
`length`		Integer that specifies the number of values in the text array. The length parameter can be set to –1 if the string is null terminated.
`pFont`		Pointer to a Font object that specifies the family name, size, and style of the font that is to be applied to the string.
`pBrush`		Pointer to a Brush object that is used to fill the string.
`positions`		If the DriverStringOptionsRealizedAdvance flag is set, positions is a pointer to a GpPointF structure that specifies the position of the first glyph. Otherwise, positions is an array of GpPointF structures, each of which specifies the origin of an individual glyph.
`flags`		Integer that specifies the options for the appearance of the string. This value must be an element of the DriverStringOptions enumeration or the result of a bitwise OR applied to two or more of these elements.
`pMatrix`		Pointer to a Matrix object that specifies the transformation matrix to apply to each value in the text array.

Return value

If the function succeeds, it returns StatusOk, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

Description

Draws characters at the specified positions. The method gives the client complete control over the appearance of text. The method assumes that the client has already set up the format and layout to be applied.

Remarks

A segment is defined as a curve that connects two consecutive points in the cardinal spline. The ending point of each segment is the starting point for the next. The numberOfSegments parameter must not be greater than the count parameter minus the offset parameter plus one.

Example

' ======================================================================================== ' GdipDrawDriverString is a GDI+ function that draws individual characters at precise ' positions, giving you full control over glyph placement and rendering. Unlike GdipDrawString, ' which handles layout automatically, this method lets you: ' - Specify each character as a Unicode value or glyph index. ' - Define exact coordinates for each glyph. ' - Apply custom transformations via a matrix. ' - Use flags to control layout behavior (e.g. advance spacing or cmap lookup). ' It’s ideal for advanced text rendering scenarios like custom typesetting, vertical text, ' or non-standard scripts where layout precision is critical. ' ======================================================================================== SUB Example_DrawDriverString (BYVAL hdc AS HDC)

' // Create a graphics object from the window device context DIM graphics AS CGpGraphics = hdc ' // Set the scale transform graphics.ScaleTransformForDpi

' // Create font object DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE), FontStyleRegular)

' // Create solid brush DIM brush AS CGpSolidBrush = ARGB_RED

' // Define text as array of Unicode characters DIM text(4) AS UINT16 = {ASC("H"), ASC("e"), ASC("l"), ASC("l"), ASC("o")}

' // Define glyph positions DIM positions(4) AS GpPointF FOR i AS LONG = 0 TO 4

positions(i).x = 50.0 + i * 20.0
  positions(i).y = 100.0

' // Draw driver string with precise glyph placement graphics.DrawDriverString(@text(0), 5, @font, @brush, @positions(0), DriverStringOptionsCmapLookup)

END SUB ' ========================================================================================

Reference

Include file CGpGraphics.inc
Defined in AfxNova/CGpGraphics.inc:997
Documented in Graphics/GdiPlus Classes/CGpGraphics Classes.md
Topic: CGpGraphics Class