Face
GUI API

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

Collaboration diagram for Face:

## Data Structures

struct | MFaceHLineProp
| Type of horizontal line spec of face. More...
struct | MFaceBoxProp
| Type of box spec of face. More...

## Typedefs

typedef void(* | MFaceHookFunc) (MFace *face, void *arg, void *info)
| Type of hook function of face. More...

## Functions

MFace * | mface ()
| Create a new face. More...
MFace * | mface_copy (MFace *face)
| Make a copy of a face. More...
int | mface_equal (MFace *face1, MFace *face2)
| Compare faces. More...
MFace * | mface_merge (MFace *dst, MFace *src)
| Merge faces. More...
MFace * | mface_from_font (MFont *font)
| Make a face from a font. More...
void * | mface_get_prop (MFace *face, MSymbol key)
| Get the value of a face property. More...
MFaceHookFunc | mface_get_hook (MFace *face)
| Get the hook function of a face. More...
int | mface_put_prop (MFace *face, MSymbol key, void *val)
| Set a value of a face property. More...
int | mface_put_hook (MFace *face, MFaceHookFunc func)
| Set a hook function to a face. More...
void | mface_update (MFrame *frame, MFace *face)
| Update a face. More...

## Variables: Keys of face property

MSymbol | Mforeground
| Key of a face property specifying foreground color. More...
MSymbol | Mbackground
| Key of a face property specifying background color. More...
MSymbol | Mvideomode
| Key of a face property specifying video mode. More...
MSymbol | Mratio
| Key of a face property specifying font size ratio. More...
MSymbol | Mhline
| Key of a face property specifying horizontal line. More...
MSymbol | Mbox
| Key of a face property specifying box. More...
MSymbol | Mfontset
| Key of a face property specifying fontset. More...
MSymbol | Mhook_func
| Key of a face property specifying hook. More...
MSymbol | Mhook_arg
| Key of a face property specifying argument of hook. More...

## 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. More...
MFace * | mface_reverse_video
| Reverse video face. More...
MFace * | mface_underline
MFace * | mface_medium
| Medium face. More...
MFace * | mface_bold
| Bold face. More...
MFace * | mface_italic
| Italic face. More...
MFace * | mface_bold_italic
| Bold italic face. More...
MFace * | mface_xx_small
| Smallest face. More...
MFace * | mface_x_small
| Smaller face. More...
MFace * | mface_small
| Small face. More...
MFace * | mface_normalsize
| Normalsize face. More...
MFace * | mface_large
| Large face. More...
MFace * | mface_x_large
| Larger face. More...
MFace * | mface_xx_large
| Largest face. More...
MFace * | mface_black
| Black face. More...
MFace * | mface_white
| White face. More...
MFace * | mface_red
| Red face. More...
MFace * | mface_green
| Green face. More...
MFace * | mface_blue
| Blue face. More...
MFace * | mface_cyan
| Cyan face. More...
MFace * | mface_yellow
| yellow face. More...
MFace * | mface_magenta
| Magenta face. More...

## Variables: The other symbols for face handling.

MSymbol | Mface
| Key of a text property specifying a face. More...

## 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

## MFaceHookFunc

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* 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_copy()

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.

## mface_equal()

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_merge()

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_from_font()

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.

## mface_get_prop()

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`

## mface_get_hook()

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.

## mface_put_prop()

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`

## mface_put_hook()

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.

## mface_update()

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

## Mforeground

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.

## Mbackground

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.

## Mvideomode

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.

## Mratio

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.

## Mhline

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.

## Mbox

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.

## Mfontset

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.

## Mhook_func

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.

## Mhook_arg

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.

## Mnormal

MSymbol Mnormal

## Mreverse

MSymbol Mreverse

## mface_normal_video

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_reverse_video

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_underline

MFace* mface_underline

    @brief 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_medium

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_bold

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_italic

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_bold_italic

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_xx_small

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_x_small

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_small

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_normalsize

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_large

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_x_large

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_xx_large

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_black

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_white

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_red

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_green

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_blue

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_cyan

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_yellow

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_magenta

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.

## Mface

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.