The m17n Library: Face

# Face
[GUI API]

A face is an object to control appearance of M-text. More...

## Data Structures
struct | MFaceHLineProp
| Type of horizontal line spec of face. More...
struct | MFaceBoxProp
| Type of box spec of face. More...
## Variables: Keys of face property
MSymbol | Mforeground
| Key of a face property specifying foreground color.
MSymbol | Mbackground
| Key of a face property specifying background color.
MSymbol | Mvideomode
| Key of a face property specifying video mode.
MSymbol | Mratio
| Key of a face property specifying font size ratio.
MSymbol | Mhline
| Key of a face property specifying horizontal line.
MSymbol | Mbox
| Key of a face property specifying box.
MSymbol | Mfontset
| Key of a face property specifying fontset.
MSymbol | Mhook_func
| Key of a face property specifying hook.
MSymbol | Mhook_arg
| Key of a face property specifying argument of hook.
## Variables: Possible values of #Mvideomode property of face
See the documentation of the variable Mvideomode.
MSymbol | Mnormal
MSymbol | Mreverse
## Variables: Predefined faces
MFace * | mface_normal_video
| Normal video face.
MFace * | mface_reverse_video
| Reverse video face.
MFace * | mface_underline
| Underline face.
MFace * | mface_medium
| Medium face.
MFace * | mface_bold
| Bold face.
MFace * | mface_italic
| Italic face.
MFace * | mface_bold_italic
| Bold italic face.
MFace * | mface_xx_small
| Smallest face.
MFace * | mface_x_small
| Smaller face.
MFace * | mface_small
| Small face.
MFace * | mface_normalsize
| Normalsize face.
MFace * | mface_large
| Large face.
MFace * | mface_x_large
| Larger face.
MFace * | mface_xx_large
| Largest face.
MFace * | mface_black
| Black face.
MFace * | mface_white
| White face.
MFace * | mface_red
| Red face.
MFace * | mface_green
| Green face.
MFace * | mface_blue
| Blue face.
MFace * | mface_cyan
| Cyan face.
MFace * | mface_yellow
| yellow face.
MFace * | mface_magenta
| Magenta face.
## Variables: The other symbols for face handling.
MSymbol | Mface
| Key of a text property specifying a face.
## Typedefs
typedef struct MFace | MFace
| Type of faces.
typedef void(* | MFaceHookFunc )(MFace *face, void *arg, void *info)
| Type of hook function of face.
## Functions
MFace * | mface ()
| Create a new face.
MFace * | mface_copy (MFace *face)
| Make a copy of a face.
int | mface_equal (MFace *face1, MFace *face2)
| Compare faces.
MFace * | mface_merge (MFace *dst, MFace *src)
| Merge faces.
MFace * | mface_from_font (MFont *font)
| Make a face from a font.
void * | mface_get_prop (MFace *face, MSymbol key)
| Get the value of a face property.
MFaceHookFunc | mface_get_hook (MFace *face)
| Get the hook function of a face.
int | mface_put_prop (MFace *face, MSymbol key, void *val)
| Set a value of a face property.
int | mface_put_hook (MFace *face, MFaceHookFunc func)
| Set a hook function to a face.
void | mface_update (MFrame *frame, MFace *face)
| Update a face.

## Detailed Description

A face is an object to control appearance of M-text.

A face is an object of the type MFace and controls how to draw M-texts. A face has a fixed number of face properties. Like other types of properties, a face property consists of a key and a value. A key is one of the following symbols:

Mforeground, Mbackground, Mvideomode, Mhline, Mbox, Mfoundry, Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Msize, Mfontset, Mratio, Mhook_func, Mhook_arg

The notation "xxx property of F" means the face property that belongs to face F and whose key is `Mxxx`.

The M-text drawing functions first search an M-text for the text property whose key is the symbol Mface, then draw the M-text using the value of that text property. This value must be a pointer to a face object.

If there are multiple text properties whose key is `Mface`, and they are not conflicting one another, properties of those faces are merged and used.

If no faces specify a certain property, the value of the default face is used.

## Typedef Documentation

typedef struct MFace MFace

Type of faces.

The type MFace is the structure of face objects. The internal structure is concealed from an application program.

typedef void(* MFaceHookFunc)(MFace *face, void *arg, void *info)

Type of hook function of face.

MFaceHookFunc is a type of a hook function of a face.

## Function Documentation

MFace* mface | ( |  | ) |

Create a new face.

The mface() function creates a new face object that specifies no property.

Return value:
  This function returns a pointer to the created face.

MFace* mface_copy | ( | MFace * | face | ) |

Make a copy of a face.

The mface_copy() function makes a copy of face and returns a pointer to the created copy.

int mface_equal | ( | MFace * | face1,
|  | MFace * | face2 |
| ) |  |  |

Compare faces.

The mface_equal() function compares faces face1 and face2.

Return value:
  If two faces have the same property values, return 1. Otherwise return 0.

MFace* mface_merge | ( | MFace * | dst,
|  | MFace * | src |
| ) |  |  |

Merge faces.

The mface_merge() functions merges the properties of face src into dst.

Return value:
  This function returns dst.

MFace* mface_from_font | ( | MFont * | font | ) |

Make a face from a font.

The mface_from_font() function return a newly created face while reflecting the properties of font in its properties.

void* mface_get_prop | ( | MFace * | face,
|  | MSymbol | key |
| ) |  |  |

Get the value of a face property.

The mface_get_prop() function returns the value of the face property whose key is key in face face. key must be one of the followings:

Mforeground, Mbackground, Mvideomode, Mhline, Mbox, Mfoundry, Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Msize, Mfontset, Mratio, Mhook_func, Mhook_arg

Return value:
  The actual type of the returned value depends of key. See documentation of the above keys. If an error is detected, it returns `NULL` and assigns an error code to the external variable merror_code.

See Also:
  mface_put_prop(), mface_put_hook()

Errors:
  `MERROR_FACE`

MFaceHookFunc mface_get_hook | ( | MFace * | face | ) |

Get the hook function of a face.

The mface_get_hook() function returns the hook function of face face.

int mface_put_prop | ( | MFace * | face,
|  | MSymbol | key,
|  | void * | val |
| ) |  |  |

Set a value of a face property.

The mface_put_prop() function assigns val to the property whose key is key in face face. key must be one the followings:

Mforeground, Mbackground, Mvideomode, Mhline, Mbox, Mfoundry, Mfamily, Mweight, Mstyle, Mstretch, Madstyle, Msize, Mfontset, Mratio, Mhook_func, Mhook_arg

Among them, font related properties (Mfoundry through Msize) are used as the default values when a font in the fontset of face does not specify those values.

The actual type of the returned value depends of key. See documentation of the above keys.

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

See Also:
  mface_get_prop()

Errors:
  `MERROR_FACE`

int mface_put_hook | ( | MFace * | face,
|  | MFaceHookFunc | func |
| ) |  |  |

Set a hook function to a face.

The mface_set_hook() function sets the hook function of face face to func.

void mface_update | ( | MFrame * | frame,
|  | MFace * | face |
| ) |  |  |

Update a face.

The mface_update() function update face face on frame frame by calling a hook function of face (if any).

## Variable Documentation

MSymbol Mforeground

Key of a face property specifying foreground color.

The variable Mforeground is used as a key of face property. The property value must be a symbol whose name is a color name, or Mnil.

Mnil means that the face does not specify a foreground color. Otherwise, the foreground of an M-text is drawn by the specified color.

MSymbol Mbackground

Key of a face property specifying background color.

The variable Mbackground is used as a key of face property. The property value must be a symbol whose name is a color name, or Mnil.

Mnil means that the face does not specify a background color. Otherwise, the background of an M-text is drawn by the specified color.

MSymbol Mvideomode

Key of a face property specifying video mode.

The variable Mvideomode is used as a key of face property. The property value must be Mnormal, Mreverse, or Mnil.

Mnormal 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).

Mreverse 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).

Mnil means that the face does not specify a video mode.

MSymbol Mratio

Key of a face property specifying font size ratio.

The variable Mratio is used as a key of face property. The value RATIO must be an integer.

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 Msize.

MSymbol Mhline

Key of a face property specifying horizontal line.

The variable Mhline is used as a key of face property. The value must be a pointer to an object of type MFaceHLineProp, or `NULL`.

The value `NULL` 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.

MSymbol Mbox

Key of a face property specifying box.

The variable Mbox is used as a key of face property. The value must be a pointer to an object of type MFaceBoxProp, or `NULL`.

The value `NULL` 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.

MSymbol Mfontset

Key of a face property specifying fontset.

The variable Mfontset is used as a key of face property. The value must be a pointer to an object of type Mfontset, or `NULL`.

The value `NULL` 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.

MSymbol Mhook_func

Key of a face property specifying hook.

The variable Mhook_func is used as a key of face property. The value must be a function of type MFaceHookFunc, or `NULL`.

The value `NULL` means that the face does not specify a hook. Otherwise, the specified function is called before the face is realized.

MSymbol Mhook_arg

Key of a face property specifying argument of hook.

The variable Mhook_arg is used as a key of face property. The value can be anything that is passed a hook function specified by the face property Mhook_func.

MSymbol Mnormal

MSymbol Mreverse

MFace* mface_normal_video

Normal video face.

The variable mface_normal_video points to a face that has the Mvideomode property with value Mnormal. 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).

MFace* mface_reverse_video

Reverse video face.

The variable mface_reverse_video points to a face that has the Mvideomode property with value Mreverse. 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).

MFace* mface_underline

Underline face.

The variable mface_underline points to a face that has the Mhline property with value a pointer to an object of type MFaceHLineProp. The members of the object are as follows:

        member  value
        -----   -----
        type    MFACE_HLINE_UNDER
        width   1
        color   Mnil

The other properties are not specified. An M-text that has this face is drawn with an underline.

MFace* mface_medium

Medium face.

The variable mface_medium points to a face that has the Mweight 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.

MFace* mface_bold

Bold face.

The variable mface_bold points to a face that has the Mweight 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.

MFace* mface_italic

Italic face.

The variable mface_italic points to a face that has the Mstyle 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.

MFace* mface_bold_italic

Bold italic face.

The variable mface_bold_italic points to a face that has the Mweight property with value a symbol of name "bold", and Mstyle 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.

MFace* mface_xx_small

Smallest face.

The variable mface_xx_small points to a face that has the Mratio 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.

MFace* mface_x_small

Smaller face.

The variable mface_x_small points to a face that has the Mratio 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.

MFace* mface_small

Small face.

The variable mface_x_small points to a face that has the Mratio 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.

MFace* mface_normalsize

Normalsize face.

The variable mface_normalsize points to a face that has the Mratio 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.

MFace* mface_large

Large face.

The variable mface_large points to a face that has the Mratio 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.

MFace* mface_x_large

Larger face.

The variable mface_x_large points to a face that has the Mratio 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.

MFace* mface_xx_large

Largest face.

The variable mface_xx_large points to a face that has the Mratio 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.

MFace* mface_black

Black face.

The variable mface_black points to a face that has the Mforeground 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.

MFace* mface_white

White face.

The variable mface_white points to a face that has the Mforeground 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.

MFace* mface_red

Red face.

The variable mface_red points to a face that has the Mforeground 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.

MFace* mface_green

Green face.

The variable mface_green points to a face that has the Mforeground 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.

MFace* mface_blue

Blue face.

The variable mface_blue points to a face that has the Mforeground 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.

MFace* mface_cyan

Cyan face.

The variable mface_cyan points to a face that has the Mforeground 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.

MFace* mface_yellow

yellow face.

The variable mface_yellow points to a face that has the Mforeground 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.

MFace* mface_magenta

Magenta face.

The variable mface_magenta points to a face that has the Mforeground 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.

MSymbol Mface

Key of a text property specifying a face.

The variable Mface is a symbol of name `"face"`. A text property whose key is this symbol must have a pointer to an object of type MFace. This is a managing key.