GDK Reference Manual
<<< Previous Page | Home | Up |

# Input Contexts

## Name

Input Contexts -- internationalized text input properties.

## Synopsis

    #include <gdk/gdk.h>

    struct      GdkIC;
    GdkIC*      gdk_ic_new                      (GdkICAttr *attr,
                                                 GdkICAttributesType mask);
    void        gdk_ic_destroy                  (GdkIC *ic);
    GdkEventMask gdk_ic_get_events              (GdkIC *ic);
    GdkIMStyle  gdk_ic_get_style                (GdkIC *ic);
    GdkICAttributesType gdk_ic_get_attr         (GdkIC *ic,
                                                 GdkICAttr *attr,
                                                 GdkICAttributesType mask);
    GdkICAttributesType gdk_ic_set_attr         (GdkIC *ic,
                                                 GdkICAttr *attr,
                                                 GdkICAttributesType mask);

    struct      GdkICAttr;
    enum        GdkICAttributesType;
    GdkICAttr*  gdk_ic_attr_new                 (void);
    void        gdk_ic_attr_destroy             (GdkICAttr *attr);

## Description

A GdkIC input context is used for each user interface element which supports internationalized text input. See the Input Methods section for an overview of how internationalized text input works in GTK+.

## Details

### struct GdkIC

    struct GdkIC;

The GdkIC struct is an opaque structure representing an input context for use with the global Input Method.

### gdk_ic_new ()

    GdkIC*      gdk_ic_new                      (GdkICAttr *attr,
                                                 GdkICAttributesType mask);

Creates a new GdkIC using the given attributes.

`attr` : | a GdkICAttr struct containing attributes to use for the input context.
`mask` : | a GdkICAttributesType mask specifying which of the attributes in `attr` are set.
Returns : | a new GdkIC.

### gdk_ic_destroy ()

    void        gdk_ic_destroy                  (GdkIC *ic);

Destroys the input context.

`ic` : | a GdkIC.

### gdk_ic_get_events ()

    GdkEventMask gdk_ic_get_events              (GdkIC *ic);

Returns the mask of events that the input method needs to function properly. This is typically called in a widget's realize method after creating the GdkIC. The returned event mask is then combined with the widget's own event mask and applied using gdk_window_set_events().

`ic` : | a GdkIC.
Returns : | the mask of events that the input method needs to function properly.

### gdk_ic_get_style ()

    GdkIMStyle  gdk_ic_get_style                (GdkIC *ic);

Returns the pre-edit and status style of the GdkIC.

`ic` : | a GdkIC.
Returns : | the pre-edit and status style of the GdkIC.

### gdk_ic_get_attr ()

    GdkICAttributesType gdk_ic_get_attr         (GdkIC *ic,
                                                 GdkICAttr *attr,
                                                 GdkICAttributesType mask);

Gets attributes of a GdkIC.

`ic` : | a GdkIC.
`attr` : | a GdkICAttr struct to contain the returned attributes.
`mask` : | a GdkICAttributesType mask specifying which attributes to get.
Returns : | a GdkICAttributesType mask specifying which of the attributes were not retrieved succesfully.

### gdk_ic_set_attr ()

    GdkICAttributesType gdk_ic_set_attr         (GdkIC *ic,
                                                 GdkICAttr *attr,
                                                 GdkICAttributesType mask);

Sets attributes of the GdkIC.

Note that the GDK_IC_STYLE and GDK_IC_CLIENT_WINDOW attributes can only be set when creating the GdkIC, and the GDK_IC_FILTER_EVENTS attribute is read-only.

`ic` : | a GdkIC.
`attr` : | a GdkICAttr struct containing attributes to use for the input context.
`mask` : | a GdkICAttributesType mask specifying which of the attributes in `attr` are set.
Returns : | a GdkICAttributesType mask indicating which of the attributes were not set successfully.

### struct GdkICAttr

    struct GdkICAttr
    {
      GdkIMStyle style;
      GdkWindow *client_window;
      GdkWindow *focus_window;
      GdkEventMask filter_events;
      GdkPoint spot_location;
      gint line_spacing;
      GdkCursor *cursor;

      GdkFont *preedit_fontset;
      GdkRectangle preedit_area;
      GdkRectangle preedit_area_needed;
      GdkColor preedit_foreground;
      GdkColor preedit_background;
      GdkPixmap *preedit_pixmap;
      GdkColormap *preedit_colormap;

      GdkFont *status_fontset;
      GdkRectangle status_area;
      GdkRectangle status_area_needed;
      GdkColor status_foreground;
      GdkColor status_background;
      GdkPixmap *status_pixmap;
      GdkColormap *status_colormap;
    };

The GdkICAttr struct is used when getting and setting attributes of the input context. It is used together with a GdkICAttributesType mask which specifies which of the fields are being set or returned.

GdkIMStyle `style` | the pre-edit and status style. This attribute is required when creating the GdkIC, and cannot be changed.
GdkWindow *`client_window` | the GdkWindow in which the input method will display its pre-edit and status areas or create subwindows. The preedit_area and status_area attributes are specified relative to this window. This attribute is required when creating the GdkIC, and cannot be changed.
GdkWindow *`focus_window` | the GdkWindow which is to be used when editing text. gdk_im_begin() sets this attribute before starting the text input process, so it is normally not necessary to set it elsewhere.
GdkEventMask `filter_events` | the mask of events that the input method requires. See the gdk_ic_get_events() function. This attribute is read-only and is never changed.
GdkPoint `spot_location` | the position of the insertion cursor, for use with the `GDK_IM_PREEDIT_POSITION` style. The y coordinate specifies the baseline of the text.
gint `line_spacing` | the line spacing to be used in the pre-edit and status areas when displaying multi-line text.
GdkCursor *`cursor` | the cursor to use in the input method's windows. If this attribute isn't set it is determined by the input method.
GdkFont *`preedit_fontset` | the font to use for the pre-edit area. If this attribute isn't set it is determined by the input method.
GdkRectangle `preedit_area` | the area in which the input method will display pre-editing data, used for the `GDK_IM_PREEDIT_POSITION` and `GDK_IM_PREEDIT_AREA` styles.
GdkRectangle `preedit_area_needed` | the area that the input method requests for displaying pre-editing data, used for the `GDK_IM_PREEDIT_POSITION` and `GDK_IM_PREEDIT_AREA` styles.
GdkColor `preedit_foreground` | the foreground color to use for the pre-edit area. This color must already be allocated in the preedit_colormap. If this attribute isn't set it is determined by the input method.
GdkColor `preedit_background` | the background color to use for the pre-edit area. This color must already be allocated in the preedit_colormap. If this attribute isn't set it is determined by the input method.
GdkPixmap *`preedit_pixmap` | the background pixmap to use for the pre-edit area. If this attribute isn't set it is determined by the input method.
GdkColormap *`preedit_colormap` | the colormap the input method should use to allocate colors. The default value is the colormap of client_window.
GdkFont *`status_fontset` | the font to use for the status area. If this attribute isn't set it is determined by the input method.
GdkRectangle `status_area` | the are that the input method will display status information in. This is used for the `GDK_IM_STATUS_AREA` style.
GdkRectangle `status_area_needed` | the size that the input method requests for displaying status information, for the `GDK_IM_STATUS_AREA` style.
GdkColor `status_foreground` | the foreground color to use for the status area. This color must already be allocated in the status_colormap. If this attribute isn't set it is determined by the input method.
GdkColor `status_background` | the background color to use for the status area. This color must already be allocated in the status_colormap. If this attribute isn't set it is determined by the input method.
GdkPixmap *`status_pixmap` | the background pixmap to use for the status area. If this attribute isn't set it is determined by the input method.
GdkColormap *`status_colormap` | the colormap the input method should use to allocate colors. The default value is the colormap of client_window.

### enum GdkICAttributesType

    typedef enum
    {
      GDK_IC_STYLE			= 1 << 0,
      GDK_IC_CLIENT_WINDOW		= 1 << 1,
      GDK_IC_FOCUS_WINDOW		= 1 << 2,
      GDK_IC_FILTER_EVENTS		= 1 << 3,
      GDK_IC_SPOT_LOCATION		= 1 << 4,
      GDK_IC_LINE_SPACING		= 1 << 5,
      GDK_IC_CURSOR			= 1 << 6,

      GDK_IC_PREEDIT_FONTSET	= 1 << 10,
      GDK_IC_PREEDIT_AREA		= 1 << 11,
      GDK_IC_PREEDIT_AREA_NEEDED	= 1 << 12,
      GDK_IC_PREEDIT_FOREGROUND	= 1 << 13,
      GDK_IC_PREEDIT_BACKGROUND	= 1 << 14,
      GDK_IC_PREEDIT_PIXMAP		= 1 << 15,
      GDK_IC_PREEDIT_COLORMAP	= 1 << 16,

      GDK_IC_STATUS_FONTSET		= 1 << 21,
      GDK_IC_STATUS_AREA		= 1 << 22,
      GDK_IC_STATUS_AREA_NEEDED	= 1 << 23,
      GDK_IC_STATUS_FOREGROUND	= 1 << 24,
      GDK_IC_STATUS_BACKGROUND	= 1 << 25,
      GDK_IC_STATUS_PIXMAP		= 1 << 26,
      GDK_IC_STATUS_COLORMAP	= 1 << 27,

      GDK_IC_ALL_REQ		= GDK_IC_STYLE |
        				  GDK_IC_CLIENT_WINDOW,

      GDK_IC_PREEDIT_AREA_REQ	= GDK_IC_PREEDIT_AREA |
    				  GDK_IC_PREEDIT_FONTSET,
      GDK_IC_PREEDIT_POSITION_REQ	= GDK_IC_PREEDIT_AREA | GDK_IC_SPOT_LOCATION |
    				  GDK_IC_PREEDIT_FONTSET,

      GDK_IC_STATUS_AREA_REQ	= GDK_IC_STATUS_AREA |
    				  GDK_IC_STATUS_FONTSET
    } GdkICAttributesType;

The GdkICAttributesType contains a set of bit-flags which are used to specify which of the attributes in a GdkICAttr are being set or returned.

It also contains several combinations of the flags which specify required attributes for the various styles:

`GDK_IC_ALL_REQ`:

  the set of attributes required for all styles.

`GDK_IC_PREEDIT_AREA_REQ`:

  the set of additional attributes required for the `GDK_IM_PREEDIT_AREA` pre-edit style.

`GDK_IC_PREEDIT_POSITION_REQ`:

  the set of additional attributes required for the `GDK_IM_PREEDIT_POSITION` pre-edit style.

`GDK_IC_STATUS_AREA_REQ`:

  the set of additional attributes required for the `GDK_IM_STATUS_AREA` status style.

### gdk_ic_attr_new ()

    GdkICAttr*  gdk_ic_attr_new                 (void);

Creates a new GdkICAttr struct, with all fields set to 0. The GdkICAttr struct should be freed with gdk_ic_attr_destroy() when no longer needed.

Returns : | a new GdkICAttr struct.

### gdk_ic_attr_destroy ()

    void        gdk_ic_attr_destroy             (GdkICAttr *attr);

Destroys the given GdkICAttr struct, freeing the allocated memory.

`attr` : | a GdkICAttr struct.

<<< Previous Page | Home | Up |
Input Methods |