The m17n Library: Frame

# Frame
[GUI API]

A frame is an object corresponding to the graphic device. More...

## Variables: Keys of frame parameter
These are the symbols to use in a parameter to create a frame. See the function mframe() for details. Mdevice, Mdisplay, Mscreen, Mdrawable, Mdepth, and Mcolormap are also keys of a frame property.
MSymbol | Mdevice
MSymbol | Mdisplay
MSymbol | Mscreen
MSymbol | Mdrawable
MSymbol | Mdepth
MSymbol | Mcolormap
MSymbol | Mwidget
MSymbol | Mgd
## Variables: Keys of frame property
These are the symbols to use as an argument to the function mframe_get_prop().
MSymbol | Mfont
MSymbol | Mfont_width
MSymbol | Mfont_ascent
MSymbol | Mfont_descent
## Typedefs
typedef struct MFrame | MFrame
| Type of frames.
## Functions
MFrame * | mframe (MPlist *plist)
| Create a new frame.
void * | mframe_get_prop (MFrame *frame, MSymbol key)
| Return property value of frame.
## Variables
MFrame * | mframe_default
| The default frame.

## Detailed Description

A frame is an object corresponding to the graphic device.

A frame is an object of the type MFrame to hold various information about each display/input device. Almost all m17n GUI functions require a pointer to a frame as an argument.

## Typedef Documentation

typedef struct MFrame MFrame

Type of frames.

The type MFrame is for a frame object. Each frame holds various information about the corresponding physical display/input device.

The internal structure of the type MFrame is concealed from an application program, and its contents depend on the window system in use. In the m17n-X library, it contains the information about display and screen in the X Window System.

## Function Documentation

MFrame* mframe | ( | MPlist * | plist | ) |

Create a new frame.

The mframe() function creates a new frame with parameters listed in plist which may be `NULL`.

The recognized keys in plist are window system dependent.

The following key is always recognized.

- Mdevice, the value must be one of Mx, Mgd, and Mnil.

  If the value is Mx, the frame is for X Window System. The argument MDrawWindow specified together with the frame must be of type `Window`. The frame is both readable and writable, thus all GUI functions can be used.

  If the value is Mgd, the frame is for an image object of GD library. The argument MDrawWindow specified together with the frame must be of type `gdImagePtr`. The frame is writable only, thus functions minput_XXX can't be used for the frame.

  If the value is Mnil, the frame is for a null device. The frame is not writable nor readable, thus functions mdraw_XXX that require the argument MDrawWindow and functions minput_XXX can't be used for the frame.

- Mface, the value must be a pointer to MFace.

  The value is used as the default face of the frame.

In addition, if the value of the key Mdevice is Mx, the following keys are recognized. They are to specify the root window and the depth of drawables that can be used with the frame.

- Mdrawable, the value type must be `Drawable`.

  A parameter of key Mdisplay must also be specified. The created frame can be used for drawables whose root window and depth are the same as those of the specified drawable on the specified display.

  When this parameter is specified, the parameter of key Mscreen is ignored.

- Mwidget, the value type must be `Widget`.

  The created frame can be used for drawables whose root window and depth are the same as those of the specified widget.

  If a parameter of key Mface is not specified, the default face is created from the resources of the widget.

  When this parameter is specified, the parameters of key Mdisplay, Mscreen, Mdrawable, Mdepth are ignored.

- Mdepth, the value type must be `unsigned`.

  The created frame can be used for drawables of the specified depth.

- Mscreen, the value type must be `(Screen *)`.

  The created frame can be used for drawables whose root window is the same as the root window of the specified screen, and depth is the same at the default depth of the screen.

  When this parameter is specified, parameter of key Mdisplay is ignored.

- Mdisplay, the value type must be `(Display *)`.

  The created frame can be used for drawables whose root window is the same as the root window for the default screen of the display, and depth is the same as the default depth of the screen.

- Mcolormap, the value type must be `(Colormap)`.

  The created frame uses the specified colormap.

- Mfont, the value must be Mx, Mfreetype, or Mxft.

  The created frame uses the specified font backend. The value Mx instructs to use X core fonts, Mfreetype to use local fonts supported by FreeType fonts, and Mxft to use local fonts via Xft library. You can specify this parameter more than once with different values if you want to use multiple font backends. This is ignored if the specified font backend is not supported on the device.

  When this parameter is not specified, all font backend supported on the device are used.

Return value:
  If the operation was successful, mframe() returns a pointer to a newly created frame. Otherwise, it returns `NULL`.

void* mframe_get_prop | ( | MFrame * | frame,
|  | MSymbol | key |
| ) |  |  |

Return property value of frame.

The mframe_get_prop() function returns a value of property key of frame frame. The valid keys and the corresponding return values are as follows.

            key             type of value   meaning of value
            ---             -------------   ----------------
            Mface           MFace *         The default face.

            Mfont           MFont *         The default font.

            Mfont_width     int             Width of the default font.

            Mfont_ascent    int             Ascent of the default font.

            Mfont_descent   int             Descent of the default font.

In the m17n-X library, the followings are also accepted.

            key             type of value   meaning of value
            ---             -------------   ----------------
            Mdisplay        Display *       Display associated with the frame.

            Mscreen         int             Screen number of a screen associated
                                            with the frame.

            Mcolormap       Colormap        Colormap of the frame.

            Mdepth          unsigned        Depth of the frame.

## Variable Documentation

MSymbol Mdevice

MSymbol Mdisplay

MSymbol Mscreen

MSymbol Mdrawable

MSymbol Mdepth

MSymbol Mcolormap

MSymbol Mwidget

MSymbol Mgd

MSymbol Mfont

MSymbol Mfont_width

MSymbol Mfont_ascent

MSymbol Mfont_descent

MFrame* mframe_default

The default frame.

The external variable mframe_default contains a pointer to the default frame that is created by the first call of mframe().