SAMPLE: How to Use Paths to Create Text Effects

• Microsoft Win32 Application Programming Interface (API) included with: - Microsoft Windows NT versions 3.1, 3.5, 3.51 - Microsoft Windows 95 version 4.0

SUMMARY

This article defines the term "path" for the purposes of this article, and it explains how you can get sample code (provided in TEXTFX.EXE, a self- extracting file) that shows by example how to use paths to draw text at varying angles, orientations, and sizes. In addition, the sample code gives useful routines for displaying path data.

The following file is available for download from the Microsoft Software Library:

 ~ Textfx.exe (size: 35097 bytes) 

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online Services

MORE INFORMATION

A path is one or more figures (or shapes) that are filled, outlined, or both filled and outlined. Computer-aided design (CAD) applications use paths to create unique clipping regions, to draw outlines of irregular shapes, and to fill the interiors of irregular shapes.

A path is associated with a Device Context (DC) but unlike other objects associated with a DC, such as pens and brushes, a path has no default object.

To create a path, you first call BeginPath(). Then use the drawing functions in the table below to add to the path. Any drawing done using these functions is recorded as part of the path. When you finish building the path, call EndPath(). The new path can then be converted to a region by using PathToRegion(), selected as a clipping region for a device context by using SelectClipPath(), and rendered by using StrokePath() or FillPath(). In addition, as this sample illustrates, the path can be retrieved by using GetPath() and manipulated programmatically.

NOTE: When you use TextOut or ExtTextOut in paths, the font selected into the path's device context must be a true type font.

Functions supported in paths:

AngleArc      LineTo         Polyline
Arc           MoveToEx       PolylineTo
ArcTo         Pie            PolyPolygon
Chord         PolyBezier     PolyPolyline
CloseFigure   PolyBezierTo   Rectangle
Ellipse       PolyDraw       RoundRect
ExtTextOut    Polygon        TextOut

AngleArc ArcTo PolyDraw

Functions not supported in a path under Windows 95:

Arc Chord Ellipse Pie Rectangle RoundRect

MORE INFORMATION

The following path functions are used in the TextFX sample:

BeginPath EndPath GetPath FillPath StrokePath

To use TextFX, run it, and then draw two lines into the client area (they don't have to be straight). The first line appears as blue and the second appears as red. These lines serve as guides for how the text will be rendered. After completing the second line, the text "This is a test" will be drawn so that it appears between the two guide lines.

To remap the text so that it appears between the two lines, TextFX first breaks down the guide lines (which are composed of line segments) into distinct adjacent points. The result is that the x,y position of each point in the lines is adjacent to its neighboring points x,y position.

Next, the text "This is a test" is drawn into a device context as a path. The points that make up the lines and curves in this path are then retrieved from the device context by using the GetPath() function.

To reposition the points in the path data, the code must establish a relationship between the relative position of the points in the original text and the position defined by the guide lines. To establish this relationship, the code calculates the x and y positions of each point in the path data relative to the overall extent of the text string. The relative x position is used to calculate a corresponding point on each of the two the guide lines, while the relative y value is used as a weight to determine how far along on a line between the two guide-line points the remapped position should be.

For example, if the point in the upper left corner of the "T" in the string "This is a test" is 2% of the total x extent of the string and 10% of the total y extent, then TextFX would find the point in each guide line that corresponds to 2% of the total number of points in that guide line. Then TextFX would reposition the point in the path data representing the upper left corner of the "T" so that it would be 10% of the way along an imaginary line extending from the point on the top guide line to the point on the bottom guide line.

Two different methods can be selected for drawing the remapped data, one draws just the outline of the characters, while the other fills in the characters.

To draw the outline of the characters, TextFX converts the remapped data back into a path and uses StrokePath() to display the outlines. To do the conversion, TextFX begins a new path, and then loops through the remapped data and uses the vertex types returned from GetPath() to determine how to draw the points. After drawing all the data, TextFX ends the path and calls StrokePath().

To draw the solid characters, instead of using StrokePath(), TextFX uses FillPath(). However, in order to get the interior areas of characters like "O", "A", "D", and so on, TextFX sets the ROP2 code to R2_MERGEPENNOT before calling FillPath(). This is done so that characters like "O" that consist of two separate polygons (one representing the outer perimeter and one representing the inner perimeter) will not be drawn as a solid blob. By drawing the polygons with the R2_MERGEPENNOT code, the code ensures that the second polygon will cancel the effects of the first in the area of the inner polygon.

REFERENCES

For additional information on paths, please see the PATHS sample included with the Win32 SDK.