.\" 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 "Face" 3m17n "14 Jul 2007" "" "Version 1.4.0" "" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Face \- A face is an object to control appearance of M-text.  

.PP
.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 "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"

.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
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef \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
.SH "Detailed Description"
.PP 
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 face property that belongs to face F and whose key is @c xxx' may be shortened to 'the xxx property of F'.
.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
Type of horizontal line spec of face.  

.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
Type of the horizontal line. 
.PP
\fBunsigned \fBMFaceHLineProp::width\fP\fP
.PP
Width of the line in pixels. 
.PP
\fB\fBMSymbol\fP \fBMFaceHLineProp::color\fP\fP
.PP
Color of the line. If the value is Mnil, foreground color of a merged face is used. 

.SS MFaceBoxProp
.PP
Type of box spec of face.  

.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBunsigned \fBMFaceBoxProp::width\fP\fP
.PP
Width of the box line in pixels. 
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_top\fP\fP
.PP
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_bottom\fP\fP
.PP
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_left\fP\fP
.PP
.PP
\fB\fBMSymbol\fP \fBMFaceBoxProp::color_right\fP\fP
.PP
.PP
\fBunsigned \fBMFaceBoxProp::inner_hmargin\fP\fP
.PP
.PP
\fBunsigned \fBMFaceBoxProp::inner_vmargin\fP\fP
.PP
.PP
\fBunsigned \fBMFaceBoxProp::outer_hmargin\fP\fP
.PP
.PP
\fBunsigned \fBMFaceBoxProp::outer_vmargin\fP\fP
.PP


.SH "Typedef Documentation"
.PP 
.SS "typedef struct \fBMFace\fP \fBMFace\fP"
.PP
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
\fBMFaceHookFunc\fP is a type of a hook function of a face. 
.SH "Variable Documentation"
.PP 
.SS "\fBMSymbol\fP \fBMforeground\fP"
.PP
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
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
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
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
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
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
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
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
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"
.PP
See the documentation of the variable \fBMvideomode\fP. 
.SS "\fBMSymbol\fP \fBMreverse\fP"
.PP
See the documentation of the variable \fBMvideomode\fP. 
.SS "\fBMFace\fP* \fBmface_normal_video\fP"
.PP
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.