Text

From 7b52cc13af4e85f1ca2deb6b6c77de9c95ea0dcf Mon Sep 17 00:00:00 2001 From: scuri Date: Fri, 17 Oct 2008 06:10:33 +0000 Subject: First commit - moving from LuaForge to SourceForge --- html/en/func/text.html | 192 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 html/en/func/text.html (limited to 'html/en/func/text.html') diff --git a/html/en/func/text.html b/html/en/func/text.html new file mode 100644 index 0000000..6243325 --- /dev/null +++ b/html/en/func/text.html @@ -0,0 +1,192 @@ + + + + + + +Text + + + + + +

Text

+ +

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

The library has at least 4 standard typefaces: "System" (which depends on the driver and platform), + "Courier" (mono spaced + with serif), "Times" (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 other typefaces or native driver typefaces with the function + NativeFont, but they may work in a reduced set of drivers. +

You may retrieve the dimensions of the selected font with function + GetFontDim. Also you + may retrieve the bounding box of a specific text before drawing by using the + GetTextSize + and GetTextBox functions.

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

+ +

void cdCanvasText(cdCanvas* canvas, int x, int y, const char* text); [in C]
+void cdfCanvasText(cdCanvas* canvas, double x, double y, const char* text); [in C]
+void wdCanvasText(cdCanvas* canvas, double x, double y, const char* text); (WC) [in C]
+
+canvas:Text(x, y: number, text: string) [in Lua]
+canvas:fText(x, y: number, text: string) [in Lua]
+canvas: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.

+ +

Attributes

void cdCanvasFont(cdCanvas* canvas, const char* typeface, int style, int size); [in C]
+void wdCanvasFont(cdCanvas* canvas, const char* typeface, int style, double size); (WD) [in C]
+
+canvas:Font(typeface, style, size: number) [in Lua]
+canvas:wFont(typeface, style, size: number) (WD) [in Lua]

+ +

Selects a text font. The font type can be one of the standard type faces or + other driver dependent type face. Since font face names are not a standard + between drivers, a few names are specially handled to improve application + portability. If you want to use names that work for all systems we recommend + using: "Courier", "Times" and "Helvetica".

The style can be a combination of: CD_PLAIN, + CD_BOLD, CD_ITALIC, CD_UNDERLINE + or CD_STRIKEOUT. Only the Windows and PDF drivers support underline and + strikeout. The size is provided in points (1/72 inch) or in pixels (using + negative values).

Default values: "System", CD_PLAIN, 12.

You can specify partial parameters using NULL, -1 and 0 for typeface, style + and size. When these parameters are specified the current font parameter is + used. For example: CanvasFont(NULL, -1, 10) will only change the font + size.

To convert between pixels and points use the function + cdPixel2MM + to convert from pixels to millimeters and use the formula "(value in points) = CD_MM2PT * + (value in millimeters)".

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

Fonts can heavily benefit from the ANTIALIAS attribute where available in the +driver.

+ + + + + + +

Type Faces
+

Font Styles
+

+ +

void cdCanvasGetFont(cdCanvas* canvas, char* typeface, int *style, int *size); [in C]
+void wdCanvasGetFont(cdCanvas* canvas, char* typeface, int *style, double *size); (WC) [in C]
+
+canvas:GetFont() -> (typeface: string, style, size: number) [in Lua]
+canvas:wGetFont() -> (typeface: string, style, size: number) (WC) [in Lua]

+ +

Returns the values of the current font. It is not necessary to provide all + return pointers; you can provide only the desired values.

In WC, the size is returned in millimeters.

+ +

char* cdCanvasNativeFont(cdCanvas* canvas, const char* nativefont); [in C]
+
+canvas:NativeFont(font: string) -> (old_font: string) [in Lua]

+ +

Selects a font based on a string description. The description can depend on the driver + and the platform, but a common definition is available for all drivers. It + does not need to be stored by the application, as it is internally replicated + by the library. The string is case sensitive. It returns the previous string.

The string is parsed and the font typeface, style and size are set according +to the parsed values, as if cdCanvasFont was called. The native font string is +cleared when a font is set +using cdCanvasFont.

The common format definition is similar to the the +Pango library Font Description, used by GTK+2. It is defined as having 3 parts: <font +family>, <font styles> <font size>. For ex: "Times, Bold 18", or +"Arial,Helvetica, Italic Underline -24". The supported styles include: +Bold, Italic, Underline and Strikeout. Underline, Strikeout, and negative +pixel values are not supported by the standard Pango Font Description. The Pango +format include many other definitions not supported by the CD format, they are +just ignored.

The IUP "FONT" attribute internal formats are also accepted in all drivers +and platforms.

Using "NULL" as a parameter, it only returns 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.

+ +

Using "(char*)CD_QUERY" as a parameter, it returns the current selected + font in the common format definition.

+ +

int cdCanvasTextAlignment(cdCanvas* canvas, int alignment); [in C]
+
+canvas: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 cdCanvasTextOrientation(cdCanvas* canvas, double angle); [in C]
+
+canvas: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 cdCanvasGetFontDim(cdCanvas* canvas, int *max_width, int *height, int *ascent, int *descent); [in C]
+void wdCanvasGetFontDim(cdCanvas* canvas, double *max_width, double *height, double *ascent, double *descent); (WC) [in C]
+
+canvas:GetFontDim() -> (max_width, height, ascent, descent: number) [in Lua]
+canvas:wGetFontDim() -> (max_width, height, ascent, descent: number) (WC) [in Lua]

+ +

Returns the maximum width of a character, the line's height, the ascent and descent of the + characters of the currently selected font. The line's height is the sum of the + ascent and descent of a + given additional space (if this is the case). All values are given in pixels + and are positive. 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 cdCanvasGetTextSize(cdCanvas* canvas, const char* text, int *width, int *height); [in C]
+void wdCanvasGetTextSize(cdCanvas* canvas, const char* text, double *width, double *height); (WC) [in C]
+
+canvas:GetTextSize(text: string) -> (width, heigth: number) [in Lua]
+canvas:wGetTextSize(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 cdCanvasGetTextBox(cdCanvas* canvas, int x, int y, const char* text, int *xmin, int *xmax, int *ymin, int *ymax); [in C]
+void wdCanvasGetTextBox(cdCanvas* canvas, double x, double y, const char* text, double *xmin, double *xmax, double *ymin, double *ymax); (WC) [in C]
+
+canvas:GetTextBox(x, y: number, text: string) -> (xmin, xmax, ymin, ymax: number) [in Lua]
+canvas:wGetTextBox(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 cdCanvasGetTextBounds(cdCanvas* canvas, int x, int y, const char *text, int *rect); [in C]
+void wdCanvasGetTextBounds(cdCanvas* canvas, double x, double y, const char* text, double *rect); (WC) [in C]
+
+canvas:GetTextBounds(x, y: number, text: string) -> (rect0, rect1, rect2, rect3, rect4, rect5, rect6, rect7: number) [in Lua]
+canvas:wGetTextBounds(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).

+ + + + + \ No newline at end of file -- cgit v1.2.3