Drawing
[GUI API]

Drawing M-texts on a window. More...


Data Structures
struct	MDrawControl
	Type of a text drawing control. More...
struct	MDrawMetric
	Type of metric for glyphs and texts. More...
struct	MDrawGlyphInfo
	Type of information about a glyph. More...
struct	MDrawGlyph
	Type of information about a glyph metric and font. More...
Typedefs
typedef void *	MDrawWindow
	Window system dependent type for a window.
typedef void *	MDrawRegion
	Window system dependent type for a region.
Functions
int	mdraw_text (MFrame frame, MDrawWindow win, int x, int y, MText mt, int from, int to)
	Draw an M-text on a window.
int	mdraw_image_text (MFrame frame, MDrawWindow win, int x, int y, MText mt, int from, int to)
	Draw an M-text on a window as an image.
int	mdraw_text_with_control (MFrame frame, MDrawWindow win, int x, int y, MText mt, int from, int to, MDrawControl *control)
	Draw an M-text on a window with fine control.
int	mdraw_text_extents (MFrame frame, MText mt, int from, int to, MDrawControl control, MDrawMetric overall_ink_return, MDrawMetric overall_logical_return, MDrawMetric overall_line_return)
	Compute text pixel width.
int	mdraw_text_per_char_extents (MFrame frame, MText mt, int from, int to, MDrawControl control, MDrawMetric ink_array_return, MDrawMetric logical_array_return, int array_size, int num_chars_return, MDrawMetric overall_ink_return, MDrawMetric overall_logical_return)
	Compute the text dimensions of each character of M-text.
int	mdraw_coordinates_position (MFrame frame, MText mt, int from, int to, int x_offset, int y_offset, MDrawControl *control)
	Return the character position nearest to the coordinates.
int	mdraw_glyph_info (MFrame frame, MText mt, int from, int pos, MDrawControl control, MDrawGlyphInfo info)
	Compute information about a glyph.
int	mdraw_glyph_list (MFrame frame, MText mt, int from, int to, MDrawControl control, MDrawGlyph glyphs, int array_size, int *num_glyphs_return)
	Compute information about glyph sequence.
void	mdraw_text_items (MFrame frame, MDrawWindow win, int x, int y, MDrawTextItem items, int nitems)
	Draw one or more textitems.
int	mdraw_default_line_break (MText *mt, int pos, int from, int to, int line, int y)
	Calculate a line breaking position.
void	mdraw_per_char_extents (MFrame frame, MText mt, MDrawMetric array_return, MDrawMetric overall_return)
	Obtain per character dimension information.
void	mdraw_clear_cache (MText *mt)
	clear cached information.
Variables
int	mdraw_line_break_option
	Option of line breaking for drawing text.

Detailed Description

Drawing M-texts on a window.

The m17n GUI API provides functions to draw M-texts.

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.

The drawing format of M-texts can be controlled in a variety of ways, which provides powerful 2-dimensional layout facility.

Typedef Documentation

typedef void* MDrawRegion

Window system dependent type for a region.

The type MDrawRegion is for a region; an arbitrary set of pixels on the screen (typically a rectangular area).

What it actually points depends on a window system. A program that uses the m17n-X library must coerce the type Region to this type.

typedef void* MDrawWindow

Window system dependent type for a window.

The type MDrawWindow is for a window; a rectangular area that works in several ways like a miniature screen.

What it actually points depends on a window system. A program that uses the m17n-X library must coerce the type Drawable to this type.

Function Documentation

void mdraw_clear_cache ( MText * mt )

clear cached information.

The mdraw_clear_cache() function clear cached information on M-text mt that was attached by any of the drawing functions. When the behavior of `format' or `line_break' member functions of MDrawControl is changed, the cache must be cleared.

See Also:: MDrawControl

int mdraw_coordinates_position	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		int	x_offset,
		int	y_offset,
		MDrawControl *	control
	)

Return the character position nearest to the coordinates.

The mdraw_coordinates_position() function checks which character is to be drawn at coordinate (x, y) when the text between from and to of M-text mt is drawn at the coordinate (0, 0) using the mdraw_text_with_control() function with the drawing control object control. Here, the character position means the number of characters that precede the character in question in mt, that is, the character position of the first character is 0.

frame is used only to get the default face information.

Return value:: If the glyph image of a character covers coordinate (x, y), mdraw_coordinates_position() returns the character position of that character.

If y is less than the minimum Y-coordinate of the drawn area, it returns from.

If y is greater than the maximum Y-coordinate of the drawn area, it returns to.

If y fits in with the drawn area but x is less than the minimum X-coordinate, it returns the character position of the first character drawn on the line y.

If y fits in with the drawn area but x is greater than the maximum X-coordinate, it returns the character position of the last character drawn on the line y.

int mdraw_default_line_break	(	MText *	mt,
		int	pos,
		int	from,
		int	to,
		int	line,
		int	y
	)

Calculate a line breaking position.

The function mdraw_default_line_break() calculates a line breaking position based on the line number line and the coordinate y, 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 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.

Return value:: This function returns a character position to break the line.

int mdraw_glyph_info	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	pos,
		MDrawControl *	control,
		MDrawGlyphInfo *	info
	)

Compute information about a glyph.

The mdraw_glyph_info() function computes information about a glyph that covers a character at position pos of the M-text mt assuming that the text is drawn from the character at from of mt on a window of frame frame using the mdraw_text_with_control() function with the drawing control object control.

The information is stored in the members of info.

See Also:: MDrawGlyphInfo

int mdraw_glyph_list	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control,
		MDrawGlyph *	glyphs,
		int	array_size,
		int *	num_glyphs_return
	)

Compute information about glyph sequence.

The mdraw_glyph_list() function computes information about glyphs corresponding to the text between from and to of M-text mt when it is drawn on a window of frame frame using the mdraw_text_with_control() function with the drawing control object control. glyphs is an array of objects to store the information, and array_size is the array size.

If array_size is large enough to cover all glyphs, it stores the number of actually filled elements in the place pointed by num_glyphs_return, and returns 0.

Otherwise, it stores the required array size in the place pointed by num_glyphs_return, and returns -1.

See Also:: MDrawGlyph

int mdraw_image_text	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MText *	mt,
		int	from,
		int	to
	)

Draw an M-text on a window as an image.

The mdraw_image_text() function draws the text between from and to of M-text mt as image on window win of frame frame at coordinate (x, y).

The way to draw a text is the same as in mdraw_text() except that this function also draws the background with the color specified by faces.

This function is the counterpart of XDrawImageString(), XmbDrawImageString(), and XwcDrawImageString() functions in the X Window System.

Return value:: If the operation was successful, mdraw_image_text() returns 0. If an error is detected, it returns -1 and assigns an error code to the external variable merror_code.

Errors:: MERROR_RANGE

See Also:: mdraw_text()

void mdraw_per_char_extents	(	MFrame *	frame,
		MText *	mt,
		MDrawMetric *	array_return,
		MDrawMetric *	overall_return
	)

Obtain per character dimension information.

The mdraw_per_char_extents() function computes the text dimension of each character in M-text mt. The faces given as text properties in mt and the default face of frame frame determine the fonts to draw the text. Each successive element in array_return is set to the drawn metrics of successive characters, which is relative to the origin of the drawing, and a rectangle for each character in mt. The number of elements of array_return must be equal to or greater than the number of characters in mt.

If pointer overall_return is not NULL, this function also computes the extents of the overall text and stores the results in the members of the structure pointed to by overall_return.

int mdraw_text	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MText *	mt,
		int	from,
		int	to
	)

Draw an M-text on a window.

The mdraw_text() function draws the text between from and to of M-text mt on window win of frame frame at coordinate (x, y).

The appearance of the text (size, style, color, etc) is specified by the value of the text property whose key is Mface. If the M-text or a part of the M-text does not have such a text property, the default face of frame is used.

The font used to draw a character in the M-text is selected from the value of the fontset property of a face by the following algorithm:

Search the text properties given to the character for the one whose key is Mcharset; its value should be either a symbol specifying a charset or Mnil. If the value is Mnil, proceed to the next step.
Otherwise, search the mapping table of the fontset for the charset. If no entry is found proceed to the next step.
If an entry is found, use one of the fonts in the entry that has a glyph for the character and that matches best with the face properties. If no such font exists, proceed to the next step.
Get the character property "script" of the character. If it is inherited, get the script property from the previous characters. If there is no previous character, or none of them has the script property other than inherited, proceed to the next step.
Search the text properties given to the character for the one whose key is Mlanguage; its value should be either a symbol specifying a language or Mnil.
Search the mapping table of the fontset for the combination of the script and language. If no entry is found, proceed to the next step.
If an entry is found, use one of the fonts in the entry that has a glyph for the character and that matches best with the face properties. If no such font exists, proceed to the next step.
Search the fall-back table of the fontset for a font that has a glyph of the character. If such a font is found, use that font.

If no font is found by the algorithm above, this function draws an empty box for the character.

This function draws only the glyph foreground. To specify the background color, use mdraw_image_text() or mdraw_text_with_control().

This function is the counterpart of XDrawString(), XmbDrawString(), and XwcDrawString() functions in the X Window System.

Return value:: If the operation was successful, mdraw_text() returns 0. If an error is detected, it returns -1 and assigns an error code to the external variable merror_code.

Errors:: MERROR_RANGE

See Also:: mdraw_image_text()

int mdraw_text_extents	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control,
		MDrawMetric *	overall_ink_return,
		MDrawMetric *	overall_logical_return,
		MDrawMetric *	overall_line_return
	)

Compute text pixel width.

The mdraw_text_extents() function computes the width of text between from and to of M-text mt when it is drawn on a window of frame frame using the mdraw_text_with_control() function with the drawing control object control.

If overall_ink_return is not NULL, this function also computes the bounding box of character ink of the M-text, and stores the results in the members of the structure pointed to by overall_ink_return. If the M-text has a face specifying a surrounding box, the box is included in the bounding box.

If overall_logical_return is not NULL, this function also computes the bounding box that provides minimum spacing to other graphical features (such as surrounding box) for the M-text, and stores the results in the members of the structure pointed to by overall_logical_return.

If overall_line_return is not NULL, this function also computes the bounding box that provides minimum spacing to the other M-text drawn, and stores the results in the members of the structure pointed to by overall_line_return. This is a union of overall_ink_return and overall_logical_return if the members min_line_ascent, min_line_descent, max_line_ascent, and max_line_descent of control are all zero.

Return value:: This function returns the width of the text to be drawn in the unit of pixels. If control->two_dimensional is nonzero and the text is drawn in multiple physical lines, it returns the width of the widest line. If an error occurs, it returns -1 and assigns an error code to the external variable merror_code.

Errors:: MERROR_RANGE

void mdraw_text_items	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MDrawTextItem *	items,
		int	nitems
	)

Draw one or more textitems.

The mdraw_text_items() function draws one or more M-texts on window win of frame frame at coordinate (x, y). items is an array of the textitems to be drawn and nitems is the number of textitems in the array.

See Also:: MTextItem, mdraw_text().

int mdraw_text_per_char_extents	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control,
		MDrawMetric *	ink_array_return,
		MDrawMetric *	logical_array_return,
		int	array_size,
		int *	num_chars_return,
		MDrawMetric *	overall_ink_return,
		MDrawMetric *	overall_logical_return
	)

Compute the text dimensions of each character of M-text.

The mdraw_text_per_char_extents() function computes the drawn metric of each character between from and to of M-text mt assuming that they are drawn on a window of frame frame using the mdraw_text_with_control() function with the drawing control object control.

array_size specifies the size of ink_array_return and logical_array_return. Each successive element of ink_array_return and logical_array_return are set to the drawn ink and logical metrics of successive characters respectively, relative to the drawing origin of the M-text. The number of elements of ink_array_return and logical_array_return that have been set is returned to num_chars_return.

If array_size is too small to return all metrics, the function returns -1 and store the requested size in num_chars_return. Otherwise, it returns zero.

If pointer overall_ink_return and overall_logical_return are not NULL, this function also computes the metrics of the overall text and stores the results in the members of the structure pointed to by overall_ink_return and overall_logical_return.

If control->two_dimensional is nonzero, this function computes only the metrics of characters in the first line.

int mdraw_text_with_control	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control
	)

Draw an M-text on a window with fine control.

The mdraw_text_with_control() function draws the text between from and to of M-text mt on windows win of frame frame at coordinate (x, y).

The way to draw a text is the same as in mdraw_text() except that this function also follows what specified in the drawing control object control.

For instance, if <two_dimensional> of control is nonzero, this function draw an M-text 2-dimensionally, i.e., newlines in M-text breaks lines and the following characters are drawn in the next line. See the documentation of the structure @ MDrawControl for more detail.

Variable Documentation

int mdraw_line_break_option

Option of line breaking for drawing text.

The variable mdraw_line_break_option specifies line breaking options by logical-or of the members of MTextLineBreakOption. It controls the line breaking algorithm of the function mdraw_default_line_break().

Drawing [GUI API]

Data Structures

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation

Variable Documentation

Drawing
[GUI API]