Text

A raster text using a font with styles. The position the text is drawn depends on the text alignment attribute.

The library has only 4 standard typefaces: System (which depends on the driver and platform), Courier (mono spaced with serif), Times Roman (proportional with serif) and Helvetica (proportional without serif). Each typeface can have some styles: Plain, Bold, Italic and a combination of Bold and Italic. As an alternative to the standard typefaces, you can use native driver typefaces with the function cdNativeFont.

You may retrieve the dimensions of the selected font with function cdFontDim. Also you may retrieve the bounding box of a specific text before drawing by using the cdTextSize and cdTextBox functions.

The text is drawn using a reference point; you can change the alignment relative to this point using the cdTextAligment function.

---

void cdText(int x, int y, char *text); [in C]
void wdText(double x, double y, char *s); (WC) [in C]
cd.Text(x, y: number, text: string) [in Lua]
cd.wText(x, y: number, text: string) (WC) [in Lua]

Inserts a text in (x,y) according to the current font and text alignment. It expects an ANSI string with no line breaks. A string with codes over 128 may display wrong characters.

---

Attributes

void cdFont(int typeface, int style, int size); [in C]
void wdFont(int typeface, int style, double size); (WD) [in C]
cd.Font(typeface, style, size: number) [in Lua]
cd.wFont(typeface, style, size: number) (WD) [in Lua]

Selects a text font. The font type can be: CD_SYSTEM, CD_COURIER, CD_TIMES_ROMAN, CD_HELVETICA, or CD_NATIVE. The style can be: CD_PLAIN, CD_BOLD, CD_ITALIC or CD_BOLD_ITALIC. The size is provided in points (1/72 inch), and, to make the selection easier, CD provides three constants: CD_SMALL=8, CD_STANDARD=12 and CD_LARGE=18. Points were used here because it is a common unit to define font sizes.

Default values: CD_SYSTEM, CD_PLAIN, CD_STANDARD.

If you wish to specify a value in pixels, simply pass the size value in pixels providing a negative value. This way, the application will know that such value is in pixels instead of points. If you wish to specify the size in pixels but want the function to keep the value in points, use function cdPixel2MM to convert pixels into millimeters, then use the formula "(value in points) = 2.84 * (value in millimeters)" to convert from millimeters into points. Instead of 2.84, you can use the definition CD_MM2PT.

The CD_NATIVE typeface is valid only if there was a previous call to cdNativeFont. The style and size parameters are ignored.

In WC, the size is specified in millimeters, but is internally passed in points.

Type Faces

Font Styles

void cdGetFont(int *typeface, int *style, int *size); [in C]
void wdGetFont(int *typeface, int *style, double *size); (WC) [in C]
cd.GetFont() -> (typeface, style, size: number) [in Lua]
cd.wGetFont() -> (typeface, style, size: number) (WC) [in Lua]

Returns the values of the font modified by function cdFont, ignoring the values modified by function cdNativeFont. It is not necessary to provide all return pointers; you can provide only the desired values. If the current typeface is CD_NATIVE, then style and size may not reflect the actual style and size.

In WC, the size is returned in millimeters.

char* cdNativeFont(char* font); [in C]
cd.NativeFont(font: string) -> (old_font: string) [in Lua]

Selects a native text font. The font description depends on the driver and the platform. It does not need to be stored by the application, as it is internally replicated by the library. It returns the previous string. Calling this function will set the current typeface to CD_NATIVE.

Passing NULL as a parameter, it returns only the previous string and does not change the font. The value returned is the last attributed value, which may not correspond exactly to the font selected by the driver.

int cdTextAlignment(int alignment); [in C]
cd.TextAlignment(alignment: number) -> (old_alignment: number) [in Lua]

Defines the vertical and horizontal alignment of a text as: CD_NORTH, CD_SOUTH, CD_EAST, CD_WEST, CD_NORTH_EAST, CD_NORTH_WEST, CD_SOUTH_EAST, CD_SOUTH_WEST, CD_CENTER, CD_BASE_LEFT, CD_BASE_CENTER, or CD_BASE_RIGHT. Returns the previous value. Default value: CD_BASE_LEFT. Value CD_QUERY simply returns the current value.

Text Alignment

double cdTextOrientation(double angle); [in C]
cd.TextOrientation(angle: number) -> (old_angle: number) [in Lua]

Defines the text orientation, which is an angle provided in degrees relative to the horizontal line according to which the text is drawn. Returns the previous value. Value CD_QUERY simply returns the current value. The default value is 0.

---

Properties

void cdFontDim(int *max_width, int *line_height, int *ascent, int *descent); [in C]
void wdFontDim(double *max_width, double *height, double *ascent, double *descent); (WC) [in C]
cd.FontDim() -> (max_width, max_height, ascent, descent: number) [in Lua]
cd.wFontDim() -> (max_width, max_height, ascent, descent: number) (WC) [in Lua]

Returns the maximum width of a character, the line's height and the ascent and descent of the characters of the currently selected font. The line's height is the sum of the ascents and descents of a given additional space (if this is the case). All values are given in pixels. If the driver does not support this kind of query, the values will be given 0 (zero). It is not necessary to provide all return pointers, you can provide only the desired values and NULL for the others.

Font Dimension Attributes

void cdTextSize(char *text, int *width, int *height); [in C]
void wdTextSize(char *s, double *width, double *height); (WC) [in C]
cd.TextSize(text: string) -> (width, heigth: number) [in Lua]
cd.wTextSize(text: string) -> (width, heigth: number) (WC) [in Lua]

Returns the width and height of a text's minimum box with the currently selected font. If the driver does not support this kind of query, the values will be given 0 (zero). It is not necessary to provide all return pointers, you can provide only the desired values and NULL for the others.

void cdTextBox(int x, int y, char *text, int *xmin, int *xmax, int *ymin, int *ymax); [in C]
void wdTextBox(double x, double y, char *s, double *xmin, double *xmax, double *ymin, double *ymax); (WC) [in C]
cd.TextBox(x, y: number, text: string) -> (xmin, xmax, ymin, ymax: number) [in Lua]
cd.wTextBox(x, y: number, text: string) -> (xmin, xmax, ymin, ymax: number) (WC) [in Lua]

Returns the horizontal bounding rectangle of a text box, even if the text has an orientation. It is not necessary to provide all return pointers, you can provide only the desired values and NULL for the others.

void cdTextBounds(int x, int y, char *text, int *rect); [in C]
void wdTextBounds(double x, double y, char *s, double *rect); (WC) [in C]
cd.TextBounds(x, y: number, text: string) -> (rect0, rect1, rect2, rect3, rect4, rect5, rect6, rect7: number) [in Lua]
cd.wTextBounds(x, y: number, text: string) -> (rect0, rect1, rect2, rect3, rect4, rect5, rect6, rect7: number) (WC) [in Lua]

Returns the oriented bounding rectangle of a text box. The rectangle corners are returned in counter-clock wise order starting with the bottom left corner, (x,y) arranged (x0,y0,x1,y1,x2,y2,x3,y3,x4,y4,x5,y5,x6,y6,x7,y7).