The #GdkColorContext type is used for allocating groups of colors.

It is now deprecated in favor of the gdk_colormap_*() functions described in the Colormaps and Colors section.

routines for allocating colors (deprecated). Color Contexts

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

internationalized text input properties. Input Contexts

Input Methods provide a way for complex character sets to be used in GTK+. Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK) use a large number of ideographs, making it impossible to support all characters with a simple keyboard. Instead, text is usually pre-edited using a phonetic alphabet and then composed to form the ideographs.

GTK+ makes use of the input method mechanism provided by the X Windows platform. When a GTK+ application is started, it opens a connection to the input method appropriate for the current locale (if any).

Widgets which handle textual input, such as #GtkEntry, need to do a number of things to support internationalized text input:

When the widget is realized:

- Check if an input method is being used with gdk_im_ready(). If it is, create a new Input Context using gdk_ic_new(). Find out which events the Input Context needs to receive with gdk_ic_get_events(), and make sure that the widget's window receives these events using gdk_window_set_events().

When the widget's size, state or cursor position changes:

- Update the appropriate Input Context attributes using gdk_ic_set_attr().

When the keyboard focus enters or leaves the widget:

- Call gdk_im_begin() or gdk_im_end() to start or finish editing the text.

When the widget receives a key_press event:

- The string and length fields of the #GdkEventKey struct should be used to insert the composed text into the widget.

When the widget is unrealized:

- Destroy the Input Context.

See the XLib reference manual for more detailed information on input methods, and the #GtkEntry and #GtkText widgets for some example code.

Input Contexts

- Used for each widget that handles internationalized text input using the global input method.

support for internationalized text input. Input Methods

This macro contains an integer value representing the device ID for the core pointer device.

@object:

@obj:

This macro is defined if GDK is configured to use the Linux framebuffer backend.

@visual: @colormap: @num_colors: @max_colors: @num_allocated: @mode: @need_to_free_colormap: @std_cmap_atom: @clut: @cmap: @color_hash: @palette: @num_palette: @fast_dither:

@fast_rgb: @fast_err: @fast_erg: @fast_erb:

@GDK_CC_MODE_UNDEFINED: @GDK_CC_MODE_BW: @GDK_CC_MODE_STD_CMAP: @GDK_CC_MODE_TRUE: @GDK_CC_MODE_MY_GRAY: @GDK_CC_MODE_PALETTE:

The #GdkDeviceInfo structure contains information about a device. It has the following fields:

@deviceid: a unique integer ID for this device. @name: the human-readable name for the device. @source: the type of device. @mode: a value indicating whether the device is enabled and how the device coordinates map to the screen. @has_cursor: if %TRUE, a cursor will be displayed indicating the current on-screen location to the user. Otherwise, the application is responsible for drawing a cursor itself. @num_axes: the number of axes for this device. @axes: a pointer to an array of GdkAxisUse values which give the mapping of axes onto the possible valuators for a GDK device. @num_keys: the number of macro buttons. @keys: a pointer to an array of #GdkDeviceKey structures which describe what key press events are generated for each macro button.

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

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.

@style: the pre-edit and status style. This attribute is required when creating the #GdkIC, and cannot be changed. @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. @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. @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. @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. @line_spacing: the line spacing to be used in the pre-edit and status areas when displaying multi-line text. @cursor: the cursor to use in the input method's windows. If this attribute isn't set it is determined by the input method. @preedit_fontset: the font to use for the pre-edit area. If this attribute isn't set it is determined by the input method. @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. @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. @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. @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. @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. @preedit_colormap: the colormap the input method should use to allocate colors. The default value is the colormap of client_window. @status_fontset: the font to use for the status area. If this attribute isn't set it is determined by the input method. @status_area: the are that the input method will display status information in. This is used for the %GDK_IM_STATUS_AREA style. @status_area_needed: the size that the input method requests for displaying status information, for the %GDK_IM_STATUS_AREA style. @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. @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. @status_pixmap: the background pixmap to use for the status area. If this attribute isn't set it is determined by the input method. @status_colormap: the colormap the input method should use to allocate colors. The default value is the colormap of client_window.

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_STYLE: @GDK_IC_CLIENT_WINDOW: @GDK_IC_FOCUS_WINDOW: @GDK_IC_FILTER_EVENTS: @GDK_IC_SPOT_LOCATION: @GDK_IC_LINE_SPACING: @GDK_IC_CURSOR: @GDK_IC_PREEDIT_FONTSET: @GDK_IC_PREEDIT_AREA: @GDK_IC_PREEDIT_AREA_NEEDED: @GDK_IC_PREEDIT_FOREGROUND: @GDK_IC_PREEDIT_BACKGROUND: @GDK_IC_PREEDIT_PIXMAP: @GDK_IC_PREEDIT_COLORMAP: @GDK_IC_STATUS_FONTSET: @GDK_IC_STATUS_AREA: @GDK_IC_STATUS_AREA_NEEDED: @GDK_IC_STATUS_FOREGROUND: @GDK_IC_STATUS_BACKGROUND: @GDK_IC_STATUS_PIXMAP: @GDK_IC_STATUS_COLORMAP: @GDK_IC_ALL_REQ: @GDK_IC_PREEDIT_AREA_REQ: @GDK_IC_PREEDIT_POSITION_REQ: @GDK_IC_STATUS_AREA_REQ:

A set of bit-flags used to specify the input method styles which are supported or which are currently in use. The flags can be divided into 2 groups, the pre-edit flags and the status flags.

The pre-edit flags specify how pre-editing data is displayed. For example, this could display the text being typed in the phonetic alphabet before it is composed and inserted as an ideograph.

The status flags specify how status information is displayed. The status information can be thought of as an extension of the standard keyboard mode indicators, such as the Caps Lock indicator.

The %GDK_IM_PREEDIT_CALLBACKS and %GDK_IM_STATUS_CALLBACKS styles are not currently supported in GTK+.

@GDK_IM_PREEDIT_AREA: The application provides the input method with an area in which to perform off-the-spot pre-editing. @GDK_IM_PREEDIT_CALLBACKS: The application registers a number of callback functions which are used to display pre-editing data. @GDK_IM_PREEDIT_POSITION: The application provides the input method with the position of the insertion cursor, for over-the-spot pre-editing. The input method creates its own window over the widget to display the pre-editing data. @GDK_IM_PREEDIT_NOTHING: The input method uses the root X window to perform pre-editing, so the application does not need to do anything. @GDK_IM_PREEDIT_NONE: No pre-editing is done by the input method, or no pre-editing data needs to be displayed. @GDK_IM_PREEDIT_MASK: A bit-mask containing all the pre-edit flags. @GDK_IM_STATUS_AREA: The application provides the input method with an area in which to display status information. @GDK_IM_STATUS_CALLBACKS: The applications registers a number of callback functions which are used to display status information. @GDK_IM_STATUS_NOTHING: The input method uses the root X window to display status information, so the application does not need to do anything. @GDK_IM_STATUS_NONE: The input method does not display status information. @GDK_IM_STATUS_MASK: A bit-mask containing all the status flags.

@keycode: @group: @level:

@GDK_PIXBUF_ALPHA_BILEVEL: @GDK_PIXBUF_ALPHA_FULL:

@cc: @palette: @num_palette: @Returns:

@cc:

@cc:

@cc: @red: @green: @blue: @failed: @Returns:

@cc: @red: @green: @blue: @failed: @Returns:

@cc: @red: @green: @blue: @failed: @Returns:

@cc: @reds: @greens: @blues: @ncolors: @colors: @nallocated:

@cc: @reds: @greens: @blues: @ncolors: @used: @colors: @nallocated:

@cc:

@visual: @colormap: @Returns:

@visual: @colormap: @Returns:

@cc: @color: @Returns:

@cc: @colors: @num_colors: @Returns:

@display: @sm_client_id:

Frees a full font name obtained from gdk_font_full_name_get().

@name: a full font name.

Returns a comma-separated list of XLFDs for the fonts making up a given #GdkFont.

@font: a #GdkFont @Returns: a newly-allocated string containing a list of XLFDs, should be freed with gdk_font_full_name_free() when no longer needed.

@dpy: @win: @Returns:

@Returns:

@Returns:

Destroys the given #GdkICAttr struct, freeing the allocated memory.

@attr: a #GdkICAttr struct.

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.

Destroys the input context.

@ic: a #GdkIC.

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.

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.

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

@ic: a #GdkIC. @Returns: the pre-edit and status style of the #GdkIC.

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.

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.

Starts editing, using the given input context and #GdkWindow. This should be called when the widget receives the input focus, typically in the widget's focus_in_event method.

@ic: a #GdkIC. @window: the #GdkWindow which will be receiving the key press events.

Decides which input method style should be used, by comparing the styles given in @supported_style with those of the available input method.

@supported_style: styles which are supported by the widget. @Returns: the best style in @supported_style that is also supported by the available input method.

Stops editing using the input method. This should be called when the widget loses the input focus, typically in the widget's focus_out_event method.

Checks if an input method is to be used for the current locale. If GTK+ has been compiled without support for input methods, or the current locale doesn't need an input method, then this will return FALSE.

@Returns: TRUE if an input method is available and should be used.

Sets the best pre-edit and/or status style which should be used. This will affect the style chosen in gdk_im_decide_style().

The order of the pre-edit styles is (from worst to best): %GDK_IM_PREEDIT_NONE, %GDK_IM_PREEDIT_NOTHING, %GDK_IM_PREEDIT_AREA, %GDK_IM_PREEDIT_POSITION, %GDK_IM_PREEDIT_CALLBACKS. The order of the status styles is: %GDK_IM_STATUS_NONE, %GDK_IM_STATUS_NOTHING, %GDK_IM_STATUS_AREA, %GDK_IM_STATUS_CALLBACKS.

So, for example, to set the best allowed pre-edit style to %GDK_IM_PREEDIT_AREA you would do this:

      gdk_im_set_best_style (GDK_IM_PREEDIT_AREA);

Or to set the best allowed pre-edit style to %GDK_IM_PREEDIT_POSITION and the best allowed status style to %GDK_IM_STATUS_NOTHING you can do this:

      gdk_im_set_best_style (GDK_IM_PREEDIT_POSITION | GDK_IM_STATUS_NOTHING);

@best_allowed_style: a bit-mask with the best pre-edit style and/or the best status style to use. If 0 is used, then the current bit-mask of all allowed styles is returned. @Returns: a bit-mask of all the styles allowed.

Lists all available input devices, along with their configuration information.

@Returns: A #GList of #GdkDeviceInfo structures. This list is internal data of GTK+ and should not be modified or freed.

Retrieves the motion history for a given device/window pair.

@window: a #GdkWindow. @deviceid: the device for which to retrieve motion history. @start: the start time. @stop: the stop time. @nevents_return: location to store the number of events returned. @Returns: a newly allocated array containing all the events from @start to @stop. This array should be freed with g_free() when you are finished using it.

Sets the mapping of the axes (valuators) of a device onto the predefined valuator types that GTK+ understands.

@deviceid: the device to configure. @axes: an array of GdkAxisUse. This length of this array must match the number of axes for the device.

Sets the key event generated when a macro button is pressed.

@deviceid: the device to configure. @index_: the index of the macro button. @keyval: the key value for the #GdkKeypressEvent to generate. (a value of 0 means no event will be generated.) @modifiers: the modifier field for the generated #GdkKeyPressEvent.

Enables or disables a device, and determines how the device maps onto the screen.

@deviceid: the device to configure. @mode: the new mode. @Returns: %TRUE if the device supports the given mode, otherwise %FALSE and the device's mode is unchanged.

Sets the source type for a device.

@deviceid: the device to configure @source: the new source type.

Returns information about the current position of the pointer within a window, including extended device information. Any of the return parameters may be %NULL, in which case, they will be ignored.

@window: a #GdkWindow. @deviceid: a device ID. @x: location to store current x postion. @y: location to store current y postion. @pressure: location to store current pressure. @xtilt: location to store current tilt in the x direction. @ytilt: location to store current tilt in the y direction. @mask: location to store the current modifier state.

@display_name: @Returns:

@pixbuf: @cr: @pixbuf_x: @pixbuf_y:

@screen:

@screen: @win_x: @win_y: @Returns:

@screen: @Returns:

@display:

@screen: @xvisualid: @Returns: