.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA)
.\" Copyright (C) 2001-2011
.\"   National Institute of Advanced Industrial Science and Technology (AIST)
.\" This file is part 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, no Front-Cover Texts,
.\" and no Back-Cover Texts.  A copy of the license is included in the
.\" appendix entitled "GNU Free Documentation License".
.TH "Face" 3m17n "12 Jan 2011" "Version 1.6.2" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Face \- A face is an object to control appearance of M\-text.  

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBMFaceHLineProp\fP"
.br
.RI "\fIType of horizontal line spec of face. \fP"
.ti -1c
.RI "struct \fBMFaceBoxProp\fP"
.br
.RI "\fIType of box spec of face. \fP"
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct \fBMFace\fP \fBMFace\fP"
.br
.RI "\fIType of faces. \fP"
.ti -1c
.RI "typedef void(* \fBMFaceHookFunc\fP )(\fBMFace\fP *face, void *arg, void *info)"
.br
.RI "\fIType of hook function of face. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBMFace\fP * \fBmface\fP ()"
.br
.RI "\fICreate a new face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_copy\fP (\fBMFace\fP *face)"
.br
.RI "\fIMake a copy of a face. \fP"
.ti -1c
.RI "int \fBmface_equal\fP (\fBMFace\fP *face1, \fBMFace\fP *face2)"
.br
.RI "\fICompare faces. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_merge\fP (\fBMFace\fP *dst, \fBMFace\fP *src)"
.br
.RI "\fIMerge faces. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_from_font\fP (\fBMFont\fP *font)"
.br
.RI "\fIMake a face from a font. \fP"
.ti -1c
.RI "void * \fBmface_get_prop\fP (\fBMFace\fP *face, \fBMSymbol\fP key)"
.br
.RI "\fIGet the value of a face property. \fP"
.ti -1c
.RI "\fBMFaceHookFunc\fP \fBmface_get_hook\fP (\fBMFace\fP *face)"
.br
.RI "\fIGet the hook function of a face. \fP"
.ti -1c
.RI "int \fBmface_put_prop\fP (\fBMFace\fP *face, \fBMSymbol\fP key, void *val)"
.br
.RI "\fISet a value of a face property. \fP"
.ti -1c
.RI "int \fBmface_put_hook\fP (\fBMFace\fP *face, \fBMFaceHookFunc\fP func)"
.br
.RI "\fISet a hook function to a face. \fP"
.ti -1c
.RI "void \fBmface_update\fP (\fBMFrame\fP *frame, \fBMFace\fP *face)"
.br
.RI "\fIUpdate a face. \fP"
.in -1c
.SS "Variables: Keys of face property"
 
.in +1c
.ti -1c
.RI "\fBMSymbol\fP \fBMforeground\fP"
.br
.RI "\fIKey of a face property specifying foreground color. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMbackground\fP"
.br
.RI "\fIKey of a face property specifying background color. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMvideomode\fP"
.br
.RI "\fIKey of a face property specifying video mode. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMratio\fP"
.br
.RI "\fIKey of a face property specifying font size ratio. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMhline\fP"
.br
.RI "\fIKey of a face property specifying horizontal line. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMbox\fP"
.br
.RI "\fIKey of a face property specifying box. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMfontset\fP"
.br
.RI "\fIKey of a face property specifying fontset. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMhook_func\fP"
.br
.RI "\fIKey of a face property specifying hook. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMhook_arg\fP"
.br
.RI "\fIKey of a face property specifying argument of hook. \fP"
.in -1c
.SS "Variables: Possible values of #Mvideomode property of face"
 See the documentation of the variable \fBMvideomode\fP. 
.in +1c
.ti -1c
.RI "\fBMSymbol\fP \fBMnormal\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMreverse\fP"
.br
.in -1c
.SS "Variables: Predefined faces"
 
.in +1c
.ti -1c
.RI "\fBMFace\fP * \fBmface_normal_video\fP"
.br
.RI "\fINormal video face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_reverse_video\fP"
.br
.RI "\fIReverse video face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_underline\fP"
.br
.RI "\fIUnderline face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_medium\fP"
.br
.RI "\fIMedium face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_bold\fP"
.br
.RI "\fIBold face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_italic\fP"
.br
.RI "\fIItalic face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_bold_italic\fP"
.br
.RI "\fIBold italic face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_xx_small\fP"
.br
.RI "\fISmallest face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_x_small\fP"
.br
.RI "\fISmaller face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_small\fP"
.br
.RI "\fISmall face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_normalsize\fP"
.br
.RI "\fINormalsize face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_large\fP"
.br
.RI "\fILarge face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_x_large\fP"
.br
.RI "\fILarger face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_xx_large\fP"
.br
.RI "\fILargest face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_black\fP"
.br
.RI "\fIBlack face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_white\fP"
.br
.RI "\fIWhite face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_red\fP"
.br
.RI "\fIRed face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_green\fP"
.br
.RI "\fIGreen face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_blue\fP"
.br
.RI "\fIBlue face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_cyan\fP"
.br
.RI "\fICyan face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_yellow\fP"
.br
.RI "\fIyellow face. \fP"
.ti -1c
.RI "\fBMFace\fP * \fBmface_magenta\fP"
.br
.RI "\fIMagenta face. \fP"
.in -1c
.SS "Variables: The other symbols for face handling."
 
.in +1c
.ti -1c
.RI "\fBMSymbol\fP \fBMface\fP"
.br
.RI "\fIKey of a text property specifying a face. \fP"
.in -1c
.SH "Detailed Description"
.PP 
A face is an object to control appearance of M\-text. 

A \fIface\fP is an object of the type \fBMFace\fP and controls how to draw M\-texts. A face has a fixed number of \fIface\fP \fIproperties\fP. Like other types of properties, a face property consists of a key and a value. A key is one of the following symbols:
.PP
\fBMforeground\fP, \fBMbackground\fP, \fBMvideomode\fP, \fBMhline\fP, \fBMbox\fP, \fBMfoundry\fP, \fBMfamily\fP, \fBMweight\fP, \fBMstyle\fP, \fBMstretch\fP, \fBMadstyle\fP, \fBMsize\fP, \fBMfontset\fP, \fBMratio\fP, \fBMhook_func\fP, \fBMhook_arg\fP
.PP
The notation 'xxx property of F' means the face property that belongs to face F and whose key is \fCMxxx\fP.
.PP
The M\-text drawing functions first search an M\-text for the text property whose key is the symbol \fBMface\fP, then draw the M\-text using the value of that text property. This value must be a pointer to a face object.
.PP
If there are multiple text properties whose key is \fCMface\fP, and they are not conflicting one another, properties of those faces are merged and used.
.PP
If no faces specify a certain property, the value of the default face is used. 
.SH "Data Structure Documentation"
.SS MFaceHLineProp
.PP
.ad l
.nh
\fBPublic Types:\fP

.in +1c
.ti -1c
.RI "enum \fBMFaceHLineType\fP { \fBMFACE_HLINE_BOTTOM\fP, \fBMFACE_HLINE_UNDER\fP, \fBMFACE_HLINE_STRIKE_THROUGH\fP, \fBMFACE_HLINE_OVER\fP, \fBMFACE_HLINE_TOP\fP }"
.br
.in -1c
.PP
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBenum \fBMFaceHLineProp::MFaceHLineType\fP  \fBMFaceHLineProp::type\fP\fP
.PP
\fBunsigned \fBMFaceHLineProp::width\fP\fP
.PP
\fB\fBMSymbol\fP \fBMFaceHLineProp::color\fP\fP

.SS MFaceBoxProp
.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBunsigned \fBMFaceBoxProp::width\fP\fP
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_top\fP\fP
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_bottom\fP\fP
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_left\fP\fP
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_right\fP\fP
.PP
\fBunsigned \fBMFaceBoxProp::inner_hmargin\fP\fP
.PP
\fBunsigned \fBMFaceBoxProp::inner_vmargin\fP\fP
.PP
\fBunsigned \fBMFaceBoxProp::outer_hmargin\fP\fP
.PP
\fBunsigned \fBMFaceBoxProp::outer_vmargin\fP\fP

.SH "Typedef Documentation"
.PP 
.SS "typedef struct \fBMFace\fP \fBMFace\fP"
.PP
Type of faces. The type \fBMFace\fP is the structure of face objects. The internal structure is concealed from an application program. 
.SS "typedef void(* \fBMFaceHookFunc\fP)(\fBMFace\fP *face, void *arg, void *info)"
.PP
Type of hook function of face. \fBMFaceHookFunc\fP is a type of a hook function of a face. 
.SH "Variable Documentation"
.PP 
.SS "\fBMSymbol\fP \fBMforeground\fP"
.PP
Key of a face property specifying foreground color. The variable \fBMforeground\fP is used as a key of face property. The property value must be a symbol whose name is a color name, or \fBMnil\fP.
.PP
\fBMnil\fP means that the face does not specify a foreground color. Otherwise, the foreground of an M\-text is drawn by the specified color. 
.SS "\fBMSymbol\fP \fBMbackground\fP"
.PP
Key of a face property specifying background color. The variable \fBMbackground\fP is used as a key of face property. The property value must be a symbol whose name is a color name, or \fBMnil\fP.
.PP
\fBMnil\fP means that the face does not specify a background color. Otherwise, the background of an M\-text is drawn by the specified color. 
.SS "\fBMSymbol\fP \fBMvideomode\fP"
.PP
Key of a face property specifying video mode. The variable \fBMvideomode\fP is used as a key of face property. The property value must be \fBMnormal\fP, \fBMreverse\fP, or \fBMnil\fP.
.PP
\fBMnormal\fP means that an M\-text is drawn in normal video mode (i.e. the foreground is drawn by foreground color, the background is drawn by background color).
.PP
\fBMreverse\fP means that an M\-text is drawn in reverse video mode (i.e. the foreground is drawn by background color, the background is drawn by foreground color).
.PP
\fBMnil\fP means that the face does not specify a video mode. 
.SS "\fBMSymbol\fP \fBMratio\fP"
.PP
Key of a face property specifying font size ratio. The variable \fBMratio\fP is used as a key of face property. The value RATIO must be an integer.
.PP
The value 0 means that the face does not specify a font size ratio. Otherwise, an M\-text is drawn by a font of size (FONTSIZE RATIO / 100) where FONTSIZE is a font size specified by the face property \fBMsize\fP. 
.SS "\fBMSymbol\fP \fBMhline\fP"
.PP
Key of a face property specifying horizontal line. The variable \fBMhline\fP is used as a key of face property. The value must be a pointer to an object of type \fBMFaceHLineProp\fP, or \fCNULL\fP.
.PP
The value \fCNULL\fP means that the face does not specify this property. Otherwise, an M\-text is drawn with a horizontal line by a way specified by the object that the value points to. 
.SS "\fBMSymbol\fP \fBMbox\fP"
.PP
Key of a face property specifying box. The variable \fBMbox\fP is used as a key of face property. The value must be a pointer to an object of type \fBMFaceBoxProp\fP, or \fCNULL\fP.
.PP
The value \fCNULL\fP means that the face does not specify a box. Otherwise, an M\-text is drawn with a surrounding box by a way specified by the object that the value points to. 
.SS "\fBMSymbol\fP \fBMfontset\fP"
.PP
Key of a face property specifying fontset. The variable \fBMfontset\fP is used as a key of face property. The value must be a pointer to an object of type \fBMfontset\fP, or \fCNULL\fP.
.PP
The value \fCNULL\fP means that the face does not specify a fontset. Otherwise, an M\-text is drawn with a font selected from what specified in the fontset. 
.SS "\fBMSymbol\fP \fBMhook_func\fP"
.PP
Key of a face property specifying hook. The variable \fBMhook_func\fP is used as a key of face property. The value must be a function of type \fBMFaceHookFunc\fP, or \fCNULL\fP.
.PP
The value \fCNULL\fP means that the face does not specify a hook. Otherwise, the specified function is called before the face is realized. 
.SS "\fBMSymbol\fP \fBMhook_arg\fP"
.PP
Key of a face property specifying argument of hook. The variable \fBMhook_arg\fP is used as a key of face property. The value can be anything that is passed a hook function specified by the face property \fBMhook_func\fP. 
.SS "\fBMSymbol\fP \fBMnormal\fP"
.SS "\fBMSymbol\fP \fBMreverse\fP"
.SS "\fBMFace\fP* \fBmface_normal_video\fP"
.PP
Normal video face. The variable \fBmface_normal_video\fP points to a face that has the \fBMvideomode\fP property with value \fBMnormal\fP. The other properties are not specified. An M\-text drawn with this face appear normal colors (i.e. the foreground is drawn by foreground color, and background is drawn by background color). 
.SS "\fBMFace\fP* \fBmface_reverse_video\fP"
.PP
Reverse video face. The variable \fBmface_reverse_video\fP points to a face that has the \fBMvideomode\fP property with value \fBMreverse\fP. The other properties are not specified. An M\-text drawn with this face appear in reversed colors (i.e. the foreground is drawn by background color, and background is drawn by foreground color). 
.SS "\fBMFace\fP* \fBmface_underline\fP"
.PP
Underline face. The variable \fBmface_underline\fP points to a face that has the \fBMhline\fP property with value a pointer to an object of type \fBMFaceHLineProp\fP. The members of the object are as follows:
.PP
.PP
.nf

    member  value
    \-\-\-\-\-   \-\-\-\-\-
    type    MFACE_HLINE_UNDER
    width   1
    color   Mnil
.fi
.PP
.PP
The other properties are not specified. An M\-text that has this face is drawn with an underline. 
.SS "\fBMFace\fP* \fBmface_medium\fP"
.PP
Medium face. The variable \fBmface_medium\fP points to a face that has the \fBMweight\fP property with value a symbol of name 'medium'. The other properties are not specified. An M\-text that has this face is drawn with a font of medium weight. 
.SS "\fBMFace\fP* \fBmface_bold\fP"
.PP
Bold face. The variable \fBmface_bold\fP points to a face that has the \fBMweight\fP property with value a symbol of name 'bold'. The other properties are not specified. An M\-text that has this face is drawn with a font of bold weight. 
.SS "\fBMFace\fP* \fBmface_italic\fP"
.PP
Italic face. The variable \fBmface_italic\fP points to a face that has the \fBMstyle\fP property with value a symbol of name 'italic'. The other properties are not specified. An M\-text that has this face is drawn with a font of italic style. 
.SS "\fBMFace\fP* \fBmface_bold_italic\fP"
.PP
Bold italic face. The variable \fBmface_bold_italic\fP points to a face that has the \fBMweight\fP property with value a symbol of name 'bold', and \fBMstyle\fP property with value a symbol of name 'italic'. The other properties are not specified. An M\-text that has this face is drawn with a font of bold weight and italic style. 
.SS "\fBMFace\fP* \fBmface_xx_small\fP"
.PP
Smallest face. The variable \fBmface_xx_small\fP points to a face that has the \fBMratio\fP property with value 50. The other properties are not specified. An M\-text that has this face is drawn with a font whose size is 50% of a normal font. 
.SS "\fBMFace\fP* \fBmface_x_small\fP"
.PP
Smaller face. The variable \fBmface_x_small\fP points to a face that has the \fBMratio\fP property with value 66. The other properties are not specified. An M\-text that has this face is drawn with a font whose size is 66% of a normal font. 
.SS "\fBMFace\fP* \fBmface_small\fP"
.PP
Small face. The variable \fBmface_x_small\fP points to a face that has the \fBMratio\fP property with value 75. The other properties are not specified. An M\-text that has this face is drawn with a font whose size is 75% of a normal font. 
.SS "\fBMFace\fP* \fBmface_normalsize\fP"
.PP
Normalsize face. The variable \fBmface_normalsize\fP points to a face that has the \fBMratio\fP property with value 100. The other properties are not specified. An M\-text that has this face is drawn with a font whose size is the same as a normal font. 
.SS "\fBMFace\fP* \fBmface_large\fP"
.PP
Large face. The variable \fBmface_large\fP points to a face that has the \fBMratio\fP property with value 120. The other properties are not specified. An M\-text that has this face is drawn with a font whose size is 120% of a normal font. 
.SS "\fBMFace\fP* \fBmface_x_large\fP"
.PP
Larger face. The variable \fBmface_x_large\fP points to a face that has the \fBMratio\fP property with value 150. The other properties are not specified. An M\-text that has this face is drawn with a font whose size is 150% of a normal font. 
.SS "\fBMFace\fP* \fBmface_xx_large\fP"
.PP
Largest face. The variable \fBmface_xx_large\fP points to a face that has the \fBMratio\fP property with value 200. The other properties are not specified. An M\-text that has this face is drawn with a font whose size is 200% of a normal font. 
.SS "\fBMFace\fP* \fBmface_black\fP"
.PP
Black face. The variable \fBmface_black\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'black'. The other properties are not specified. An M\-text that has this face is drawn with black foreground. 
.SS "\fBMFace\fP* \fBmface_white\fP"
.PP
White face. The variable \fBmface_white\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'white'. The other properties are not specified. An M\-text that has this face is drawn with white foreground. 
.SS "\fBMFace\fP* \fBmface_red\fP"
.PP
Red face. The variable \fBmface_red\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'red'. The other properties are not specified. An M\-text that has this face is drawn with red foreground. 
.SS "\fBMFace\fP* \fBmface_green\fP"
.PP
Green face. The variable \fBmface_green\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'green'. The other properties are not specified. An M\-text that has this face is drawn with green foreground. 
.SS "\fBMFace\fP* \fBmface_blue\fP"
.PP
Blue face. The variable \fBmface_blue\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'blue'. The other properties are not specified. An M\-text that has this face is drawn with blue foreground. 
.SS "\fBMFace\fP* \fBmface_cyan\fP"
.PP
Cyan face. The variable \fBmface_cyan\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'cyan'. The other properties are not specified. An M\-text that has this face is drawn with cyan foreground. 
.SS "\fBMFace\fP* \fBmface_yellow\fP"
.PP
yellow face. The variable \fBmface_yellow\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'yellow'. The other properties are not specified. An M\-text that has this face is drawn with yellow foreground. 
.SS "\fBMFace\fP* \fBmface_magenta\fP"
.PP
Magenta face. The variable \fBmface_magenta\fP points to a face that has the \fBMforeground\fP property with value a symbol of name 'magenta'. The other properties are not specified. An M\-text that has this face is drawn with magenta foreground. 
.SS "\fBMSymbol\fP \fBMface\fP"
.PP
Key of a text property specifying a face. The variable \fBMface\fP is a symbol of name \fC'face'\fP. A text property whose key is this symbol must have a pointer to an object of type \fBMFace\fP. This is a managing key. 
.SH "Author"
.PP 
Generated automatically by Doxygen for The m17n Library from the source code.
.SH COPYRIGHT
Copyright (C) 2001 Information\-technology Promotion Agency (IPA)
.br
Copyright (C) 2001\-2011 National Institute of Advanced Industrial Science and Technology (AIST)
.br
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License 
<http://www.gnu.org/licenses/fdl.html>.