.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA)
.\" Copyright (C) 2001-2003
.\"   National Institute of Advanced Industrial Science and Technology (AIST)
.\" This file si aprt of the m17n library documentation.
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Section, Front-Cover Texts "The m17n library documentation",
.\" and no Back-Cover Texts.  A copy of the license is included in the
.\" appendix entitled "GNU Free Documentation License".
.TH "Drawing" 3m17n "14 Jul 2007" "" "Version 1.4.0" "" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Drawing \- Drawing M-texts on a window.  

.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBMDrawControl\fP"
.br
.RI "\fIType of a text drawing control. \fP"
.ti -1c
.RI "struct \fBMDrawMetric\fP"
.br
.RI "\fIType of metric for glyphs and texts. \fP"
.ti -1c
.RI "struct \fBMDrawGlyphInfo\fP"
.br
.RI "\fIType of information about a glyph. \fP"
.ti -1c
.RI "struct \fBMDrawGlyph\fP"
.br
.RI "\fIType of information about a glyph metric and font. \fP"
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef void * \fBMDrawWindow\fP"
.br
.RI "\fIWindow system dependent type for a window. \fP"
.ti -1c
.RI "typedef void * \fBMDrawRegion\fP"
.br
.RI "\fIWindow system dependent type for a region. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBmdraw_text\fP (\fBMFrame\fP *frame, \fBMDrawWindow\fP win, int x, int y, \fBMText\fP *mt, int from, int to)"
.br
.RI "\fIDraw an M-text on a window. \fP"
.ti -1c
.RI "int \fBmdraw_image_text\fP (\fBMFrame\fP *frame, \fBMDrawWindow\fP win, int x, int y, \fBMText\fP *mt, int from, int to)"
.br
.RI "\fIDraw an M-text on a window as an image. \fP"
.ti -1c
.RI "int \fBmdraw_text_with_control\fP (\fBMFrame\fP *frame, \fBMDrawWindow\fP win, int x, int y, \fBMText\fP *mt, int from, int to, \fBMDrawControl\fP *control)"
.br
.RI "\fIDraw an M-text on a window with fine control. \fP"
.ti -1c
.RI "int \fBmdraw_text_extents\fP (\fBMFrame\fP *frame, \fBMText\fP *mt, int from, int to, \fBMDrawControl\fP *control, \fBMDrawMetric\fP *overall_ink_return, \fBMDrawMetric\fP *overall_logical_return, \fBMDrawMetric\fP *overall_line_return)"
.br
.RI "\fICompute text pixel width. \fP"
.ti -1c
.RI "int \fBmdraw_text_per_char_extents\fP (\fBMFrame\fP *frame, \fBMText\fP *mt, int from, int to, \fBMDrawControl\fP *control, \fBMDrawMetric\fP *ink_array_return, \fBMDrawMetric\fP *logical_array_return, int array_size, int *num_chars_return, \fBMDrawMetric\fP *overall_ink_return, \fBMDrawMetric\fP *overall_logical_return)"
.br
.RI "\fICompute the text dimensions of each character of M-text. \fP"
.ti -1c
.RI "int \fBmdraw_coordinates_position\fP (\fBMFrame\fP *frame, \fBMText\fP *mt, int from, int to, int x_offset, int y_offset, \fBMDrawControl\fP *control)"
.br
.RI "\fIReturn the character position nearest to the coordinates. \fP"
.ti -1c
.RI "int \fBmdraw_glyph_info\fP (\fBMFrame\fP *frame, \fBMText\fP *mt, int from, int pos, \fBMDrawControl\fP *control, \fBMDrawGlyphInfo\fP *info)"
.br
.RI "\fICompute information about a glyph. \fP"
.ti -1c
.RI "int \fBmdraw_glyph_list\fP (\fBMFrame\fP *frame, \fBMText\fP *mt, int from, int to, \fBMDrawControl\fP *control, \fBMDrawGlyph\fP *glyphs, int array_size, int *num_glyphs_return)"
.br
.RI "\fICompute information about glyph sequence. \fP"
.ti -1c
.RI "void \fBmdraw_text_items\fP (\fBMFrame\fP *frame, \fBMDrawWindow\fP win, int x, int y, \fBMDrawTextItem\fP *items, int nitems)"
.br
.RI "\fIDraw one or more textitems. \fP"
.ti -1c
.RI "int \fBmdraw_default_line_break\fP (\fBMText\fP *mt, int pos, int from, int to, int line, int y)"
.br
.RI "\fICalculate a line breaking position. \fP"
.ti -1c
.RI "void \fBmdraw_per_char_extents\fP (\fBMFrame\fP *frame, \fBMText\fP *mt, \fBMDrawMetric\fP *array_return, \fBMDrawMetric\fP *overall_return)"
.br
.RI "\fIObtain per character dimension information. \fP"
.ti -1c
.RI "void \fBmdraw_clear_cache\fP (\fBMText\fP *mt)"
.br
.RI "\fIclear cached information. \fP"
.in -1c
.SS "Variables"

.in +1c
.ti -1c
.RI "int \fBmdraw_line_break_option\fP"
.br
.RI "\fIOption of line breaking for drawing text. \fP"
.in -1c
.SH "Detailed Description"
.PP 
The m17n GUI API provides functions to draw M-texts.
.PP
The fonts used for drawing are selected automatically based on the fontset and the properties of a face. A face also specifies the appearance of M-texts, i.e. font size, color, underline, etc.
.PP
The drawing format of M-texts can be controlled in a variety of ways, which provides powerful 2-dimensional layout facility. 
.SH "Data Structure Documentation"
.SS MDrawControl
.PP
Type of a text drawing control.  

.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBunsigned \fBMDrawControl::as_image\fP\fP
.PP
If nonzero, draw an M-text as image, i.e. with background filled with background colors of faces put on the M-text. Otherwise, the background is not changed. 
.PP
\fBunsigned \fBMDrawControl::align_head\fP\fP
.PP
If nonzero and the first glyph of each line has negative lbearing, shift glyphs horizontally to right so that no pixel is drawn to the left of the specified position. 
.PP
\fBunsigned \fBMDrawControl::two_dimensional\fP\fP
.PP
If nonzero, draw an M-text two-dimensionally, i.e., newlines in M-text breaks lines and the following characters are drawn in the next line. If <format> is non-NULL, and the function returns nonzero line width, a line longer than that width is also broken. 
.PP
\fBunsigned \fBMDrawControl::orientation_reversed\fP\fP
.PP
If nonzero, draw an M-text to the right of a specified position. 
.PP
\fBunsigned \fBMDrawControl::enable_bidi\fP\fP
.PP
If nonzero, reorder glyphs correctly for bidi text. 
.PP
\fBunsigned \fBMDrawControl::ignore_formatting_char\fP\fP
.PP
If nonzero, don't draw characters whose general category (in Unicode) is Cf (Other, format). 
.PP
\fBunsigned \fBMDrawControl::fixed_width\fP\fP
.PP
If nonzero, draw glyphs suitable for a terminal. Not yet implemented. 
.PP
\fBunsigned \fBMDrawControl::anti_alias\fP\fP
.PP
If nonzero, draw glyphs with anti-aliasing if a backend font driver supports it. 
.PP
\fBunsigned \fBMDrawControl::disable_overlapping_adjustment\fP\fP
.PP
If nonzero, disable the adjustment of glyph positions to avoid horizontal overlapping at font boundary. 
.PP
\fBunsigned int \fBMDrawControl::min_line_ascent\fP\fP
.PP
If nonzero, the values are minimum line ascent and descent pixels. 
.PP
\fBunsigned int \fBMDrawControl::min_line_descent\fP\fP
.PP
.PP
\fBunsigned int \fBMDrawControl::max_line_ascent\fP\fP
.PP
If nonzero, the values are maximum line ascent and descent pixels. 
.PP
\fBunsigned int \fBMDrawControl::max_line_descent\fP\fP
.PP
.PP
\fBunsigned int \fBMDrawControl::max_line_width\fP\fP
.PP
If nonzero, the value specifies how many pixels each line can occupy on the display. The value zero means that there is no limit. It is ignored if <format> is non-NULL. 
.PP
\fBunsigned int \fBMDrawControl::tab_width\fP\fP
.PP
If nonzero, the value specifies the distance between tab stops in columns (the width of one column is the width of a space in the default font of the frame). The value zero means 8. 
.PP
\fBvoid(* \fBMDrawControl::format\fP)(int line, int y, int *indent, int *width)\fP
.PP
If non-NULL, the value is a function that calculates the indentation and width limit of each line based on the line number LINE and the coordinate Y. The function store the indentation and width limit at the place pointed by INDENT and WIDTH respectively.
.PP
The indentation specifies how many pixels the first glyph of each line is shifted to the right (if the member <orientation_reversed> is zero) or to the left (otherwise). If the value is negative, each line is shifted to the reverse direction.
.PP
The width limit specifies how many pixels each line can occupy on the display. The value 0 means that there is no limit.
.PP
LINE and Y are reset to 0 when a line is broken by a newline character, and incremented each time when a long line is broken because of the width limit.
.PP
This has an effect only when <two_dimensional> is nonzero. 
.PP
\fBint(* \fBMDrawControl::line_break\fP)(\fBMText\fP *mt, int pos, int from, int to, int line, int y)\fP
.PP
If non-NULL, the value is a function that calculates a line breaking position when a line is too long to fit within the width limit. POS is the position of the character next to the last one that fits within the limit. FROM is the position of the first character of the line, and TO is the position of the last character displayed on the line if there were not width limit. LINE and Y are the same as the arguments to <format>.
.PP
The function must return a character position to break the line.
.PP
The function should not modify MT.
.PP
The \fBmdraw_default_line_break()\fP function is useful for such a script that uses SPACE as a word separator. 
.PP
\fBint \fBMDrawControl::with_cursor\fP\fP
.PP
.PP
\fBint \fBMDrawControl::cursor_pos\fP\fP
.PP
Specifies the character position to display a cursor. If it is greater than the maximum character position, the cursor is displayed next to the last character of an M-text. If the value is negative, even if <cursor_width> is nonzero, cursor is not displayed. 
.PP
\fBint \fBMDrawControl::cursor_width\fP\fP
.PP
If nonzero, display a cursor at the character position <cursor_pos>. If the value is positive, it is the pixel width of the cursor. If the value is negative, the cursor width is the same as the underlining glyph(s). 
.PP
\fBint \fBMDrawControl::cursor_bidi\fP\fP
.PP
If nonzero and <cursor_width> is also nonzero, display double bar cursors; at the character position <cursor_pos> and at the logically previous character. Both cursors have one pixel width with horizontal fringes at upper or lower positions. 
.PP
\fBint \fBMDrawControl::partial_update\fP\fP
.PP
If nonzero, on drawing partial text, pixels of surrounding texts that intrude into the drawing area are also drawn. For instance, some CVC sequence of Thai text (C is consonant, V is upper vowel) is drawn so that V is placed over the middle of two Cs. If this CVC sequence is already drawn and only the last C is drawn again (for instance by updating cursor position), the right half of V is erased if this member is zero. By setting this member to nonzero, even with such a drawing, we can keep this CVC sequence correctly displayed. 
.PP
\fBint \fBMDrawControl::disable_caching\fP\fP
.PP
If nonzero, don't cache the result of any drawing information of an M-text. 
.PP
\fB\fBMDrawRegion\fP \fBMDrawControl::clip_region\fP\fP
.PP


.SS MDrawMetric
.PP
Type of metric for glyphs and texts.  

.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBint \fBMDrawMetric::x\fP\fP
.PP
.PP
\fBint \fBMDrawMetric::y\fP\fP
.PP
.PP
\fBunsigned int \fBMDrawMetric::width\fP\fP
.PP
.PP
\fBunsigned int \fBMDrawMetric::height\fP\fP
.PP


.SS MDrawGlyphInfo
.PP
Type of information about a glyph.  

.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBint \fBMDrawGlyphInfo::from\fP\fP
.PP
Character range corresponding to the glyph. 
.PP
\fBint \fBMDrawGlyphInfo::to\fP\fP
.PP
.PP
\fBint \fBMDrawGlyphInfo::line_from\fP\fP
.PP
Character ranges corresponding to the line of the glyph. 
.PP
\fBint \fBMDrawGlyphInfo::line_to\fP\fP
.PP
.PP
\fBint \fBMDrawGlyphInfo::x\fP\fP
.PP
X/Y coordinates of the glyph. 
.PP
\fBint \fBMDrawGlyphInfo::y\fP\fP
.PP
.PP
\fB\fBMDrawMetric\fP \fBMDrawGlyphInfo::metrics\fP\fP
.PP
Metric of the glyph. 
.PP
\fB\fBMFont\fP* \fBMDrawGlyphInfo::font\fP\fP
.PP
Font used for the glyph. Set to NULL if no font is found for the glyph. 
.PP
\fBint \fBMDrawGlyphInfo::prev_from\fP\fP
.PP
Character ranges corresponding to logically previous and next glyphs. Note that we do not need the members prev_to and next_from because they must be the same as the members from and to respectively. 
.PP
\fBint \fBMDrawGlyphInfo::next_to\fP\fP
.PP
.PP
\fBint \fBMDrawGlyphInfo::left_from\fP\fP
.PP
Character ranges corresponding to visually left and right glyphs. 
.PP
\fBint \fBMDrawGlyphInfo::left_to\fP\fP
.PP
.PP
\fBint \fBMDrawGlyphInfo::right_from\fP\fP
.PP
.PP
\fBint \fBMDrawGlyphInfo::right_to\fP\fP
.PP
.PP
\fBint \fBMDrawGlyphInfo::logical_width\fP\fP
.PP
Logical width of the glyph. Nominal distance to the next glyph. 

.SS MDrawGlyph
.PP
Type of information about a glyph metric and font.  

.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBint \fBMDrawGlyph::from\fP\fP
.PP
Character range corresponding to the glyph. 
.PP
\fBint \fBMDrawGlyph::to\fP\fP
.PP
.PP
\fBint \fBMDrawGlyph::glyph_code\fP\fP
.PP
Font glyph code of the glyph. 
.PP
\fBint \fBMDrawGlyph::x_advance\fP\fP
.PP
Logical width of the glyph. Nominal distance to the next glyph. 
.PP
\fBint \fBMDrawGlyph::y_advance\fP\fP
.PP
.PP
\fBint \fBMDrawGlyph::x_off\fP\fP
.PP
X/Y offset relative to the glyph position. 
.PP
\fBint \fBMDrawGlyph::y_off\fP\fP
.PP
.PP
\fBint \fBMDrawGlyph::lbearing\fP\fP
.PP
Metric of the glyph. 
.PP
\fBint \fBMDrawGlyph::rbearing\fP\fP
.PP
.PP
\fBint \fBMDrawGlyph::ascent\fP\fP
.PP
.PP
\fBint \fBMDrawGlyph::descent\fP\fP
.PP
.PP
\fB\fBMFont\fP* \fBMDrawGlyph::font\fP\fP
.PP
Font used for the glyph. Set to NULL if no font is found for the glyph. 
.PP
\fB\fBMSymbol\fP \fBMDrawGlyph::font_type\fP\fP
.PP
Type of the font. One of Mx, Mfreetype, Mxft. 
.PP
\fBvoid* \fBMDrawGlyph::fontp\fP\fP
.PP
Pointer to the font structure. The actual type is (XFontStruct *) if <font_type> member is Mx, FT_Face if <font_type> member is Mfreetype, and (XftFont *) if <font_type> member is Mxft. 

.SH "Typedef Documentation"
.PP 
.SS "typedef void* \fBMDrawWindow\fP"
.PP
The type \fBMDrawWindow\fP is for a window; a rectangular area that works in several ways like a miniature screen.
.PP
What it actually points depends on a window system. A program that uses the m17n-X library must coerce the type \fCDrawable\fP to this type. 
.SS "typedef void* \fBMDrawRegion\fP"
.PP
The type \fBMDrawRegion\fP is for a region; an arbitrary set of pixels on the screen (typically a rectangular area).
.PP
What it actually points depends on a window system. A program that uses the m17n-X library must coerce the type \fCRegion\fP to this type. 
.SH "Variable Documentation"
.PP 
.SS "int \fBmdraw_line_break_option\fP"
.PP
The variable \fBmdraw_line_break_option\fP specifies line breaking options by logical-or of the members of \fBMTextLineBreakOption\fP. It controls the line breaking algorithm of the function \fBmdraw_default_line_break()\fP.