1 <!-- ##### SECTION ./tmpl/color_contexts.sgml:Long_Description ##### -->
3 The #GdkColorContext type is used for allocating groups of colors.
6 It is now deprecated in favor of the gdk_colormap_*() functions described in
7 the <link linkend="gdk-Colormaps-and-Colors">Colormaps and Colors</link>
12 <!-- ##### SECTION ./tmpl/color_contexts.sgml:See_Also ##### -->
18 <!-- ##### SECTION ./tmpl/color_contexts.sgml:Short_Description ##### -->
19 routines for allocating colors (deprecated).
22 <!-- ##### SECTION ./tmpl/color_contexts.sgml:Title ##### -->
26 <!-- ##### SECTION ./tmpl/input_contexts.sgml:Long_Description ##### -->
28 A #GdkIC input context is used for each user interface element which supports
29 internationalized text input. See the
30 <link linkend="gdk-Input-Methods">Input Methods</link> section for an overview
31 of how internationalized text input works in GTK+.
35 <!-- ##### SECTION ./tmpl/input_contexts.sgml:See_Also ##### -->
41 <!-- ##### SECTION ./tmpl/input_contexts.sgml:Short_Description ##### -->
42 internationalized text input properties.
45 <!-- ##### SECTION ./tmpl/input_contexts.sgml:Title ##### -->
49 <!-- ##### SECTION ./tmpl/input_methods.sgml:Long_Description ##### -->
51 Input Methods provide a way for complex character sets to be used in GTK+.
52 Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK)
53 use a large number of ideographs, making it impossible to support all
54 characters with a simple keyboard. Instead, text is usually
55 <emphasis>pre-edited</emphasis> using a phonetic alphabet and then
56 <emphasis>composed</emphasis> to form the ideographs.
59 GTK+ makes use of the input method mechanism provided by the X Windows
60 platform. When a GTK+ application is started, it opens a connection to the
61 input method appropriate for the current locale (if any).
64 Widgets which handle textual input, such as #GtkEntry, need to do a number of
65 things to support internationalized text input:
68 <term>When the widget is realized:</term>
69 <listitem><para>Check if an input method is being used with gdk_im_ready().
70 If it is, create a new <link linkend="gdk-Input-Contexts">Input Context</link>
71 using gdk_ic_new(). Find out which events the
72 <link linkend="gdk-Input-Contexts">Input Context</link> needs to receive
73 with gdk_ic_get_events(), and make sure that the widget's window receives
74 these events using gdk_window_set_events().
79 <term>When the widget's size, state or cursor position changes:</term>
81 Update the appropriate
82 <link linkend="gdk-Input-Contexts">Input Context</link> attributes
83 using gdk_ic_set_attr().
88 <term>When the keyboard focus enters or leaves the widget:</term>
90 Call gdk_im_begin() or gdk_im_end() to start or finish editing the text.
95 <term>When the widget receives a key_press event:</term>
97 The <structfield>string</structfield> and <structfield>length</structfield>
98 fields of the #GdkEventKey struct should be used to insert the composed text
104 <term>When the widget is unrealized:</term>
106 Destroy the <link linkend="gdk-Input-Contexts">Input Context</link>.
113 See the XLib reference manual for more detailed information on input methods,
114 and the #GtkEntry and #GtkText widgets for some example code.
118 <!-- ##### SECTION ./tmpl/input_methods.sgml:See_Also ##### -->
122 <term><link linkend="gdk-Input-Contexts">Input Contexts</link></term>
124 Used for each widget that handles internationalized text input using the
133 <!-- ##### SECTION ./tmpl/input_methods.sgml:Short_Description ##### -->
134 support for internationalized text input.
137 <!-- ##### SECTION ./tmpl/input_methods.sgml:Title ##### -->
141 <!-- ##### MACRO GDK_CORE_POINTER ##### -->
143 This macro contains an integer value representing
144 the device ID for the core pointer device.
148 <!-- ##### MACRO GDK_GC_X11 ##### -->
155 <!-- ##### MACRO GDK_GC_X11_GET_CLASS ##### -->
162 <!-- ##### MACRO GDK_WINDOWING_FB ##### -->
164 This macro is defined if GDK is configured to use the Linux framebuffer backend.
168 <!-- ##### MACRO GDK_WINDOWING_NANOX ##### -->
174 <!-- ##### STRUCT GdkColorContext ##### -->
185 @need_to_free_colormap:
194 <!-- ##### STRUCT GdkColorContextDither ##### -->
204 <!-- ##### ENUM GdkColorContextMode ##### -->
209 @GDK_CC_MODE_UNDEFINED:
211 @GDK_CC_MODE_STD_CMAP:
213 @GDK_CC_MODE_MY_GRAY:
214 @GDK_CC_MODE_PALETTE:
216 <!-- ##### STRUCT GdkDeviceClass ##### -->
222 <!-- ##### STRUCT GdkDeviceInfo ##### -->
224 The #GdkDeviceInfo structure contains information about a
225 device. It has the following fields:
228 @deviceid: a unique integer ID for this device.
229 @name: the human-readable name for the device.
230 @source: the type of device.
231 @mode: a value indicating whether the device is enabled and
232 how the device coordinates map to the screen.
233 @has_cursor: if %TRUE, a cursor will be displayed indicating
234 the current on-screen location to the user. Otherwise,
235 the application is responsible for drawing a cursor
237 @num_axes: the number of axes for this device.
238 @axes: a pointer to an array of GdkAxisUse values which
239 give the mapping of axes onto the possible valuators
241 @num_keys: the number of macro buttons.
242 @keys: a pointer to an array of #GdkDeviceKey structures
243 which describe what key press events are generated
244 for each macro button.
246 <!-- ##### STRUCT GdkDrawableClass ##### -->
252 <!-- ##### STRUCT GdkGCClass ##### -->
258 <!-- ##### STRUCT GdkIC ##### -->
260 The #GdkIC struct is an opaque structure representing an input context
261 for use with the global <link linkend="gdk-Input-Methods">Input Method</link>.
265 <!-- ##### STRUCT GdkICAttr ##### -->
267 The #GdkICAttr struct is used when getting and setting attributes of the
268 input context. It is used together with a #GdkICAttributesType mask which
269 specifies which of the fields are being set or returned.
272 @style: the pre-edit and status style. This attribute is required when
273 creating the #GdkIC, and cannot be changed.
274 @client_window: the #GdkWindow in which the input method will display its
275 pre-edit and status areas or create subwindows.
276 The preedit_area and status_area attributes are specified relative to this
277 window. This attribute is required when creating the #GdkIC, and cannot be
279 @focus_window: the #GdkWindow which is to be used when editing text.
280 gdk_im_begin() sets this attribute before starting the text input process,
281 so it is normally not necessary to set it elsewhere.
282 @filter_events: the mask of events that the input method requires.
283 See the gdk_ic_get_events() function. This attribute is read-only and is
285 @spot_location: the position of the insertion cursor, for use with the
286 %GDK_IM_PREEDIT_POSITION style. The y coordinate specifies the baseline of
288 @line_spacing: the line spacing to be used in the pre-edit and status areas
289 when displaying multi-line text.
290 @cursor: the cursor to use in the input method's windows.
291 If this attribute isn't set it is determined by the input method.
292 @preedit_fontset: the font to use for the pre-edit area.
293 If this attribute isn't set it is determined by the input method.
294 @preedit_area: the area in which the input method will display pre-editing
295 data, used for the %GDK_IM_PREEDIT_POSITION and %GDK_IM_PREEDIT_AREA styles.
296 @preedit_area_needed: the area that the input method requests for displaying
297 pre-editing data, used for the %GDK_IM_PREEDIT_POSITION and
298 %GDK_IM_PREEDIT_AREA styles.
299 @preedit_foreground: the foreground color to use for the pre-edit area.
300 This color must already be allocated in the preedit_colormap.
301 If this attribute isn't set it is determined by the input method.
302 @preedit_background: the background color to use for the pre-edit area.
303 This color must already be allocated in the preedit_colormap.
304 If this attribute isn't set it is determined by the input method.
305 @preedit_pixmap: the background pixmap to use for the pre-edit area.
306 If this attribute isn't set it is determined by the input method.
307 @preedit_colormap: the colormap the input method should use to allocate colors.
308 The default value is the colormap of client_window.
309 @status_fontset: the font to use for the status area.
310 If this attribute isn't set it is determined by the input method.
311 @status_area: the are that the input method will display status information in.
312 This is used for the %GDK_IM_STATUS_AREA style.
313 @status_area_needed: the size that the input method requests for displaying
314 status information, for the %GDK_IM_STATUS_AREA style.
315 @status_foreground: the foreground color to use for the status area.
316 This color must already be allocated in the status_colormap.
317 If this attribute isn't set it is determined by the input method.
318 @status_background: the background color to use for the status area.
319 This color must already be allocated in the status_colormap.
320 If this attribute isn't set it is determined by the input method.
321 @status_pixmap: the background pixmap to use for the status area.
322 If this attribute isn't set it is determined by the input method.
323 @status_colormap: the colormap the input method should use to allocate colors.
324 The default value is the colormap of client_window.
326 <!-- ##### ENUM GdkICAttributesType ##### -->
328 The #GdkICAttributesType contains a set of bit-flags which are used to
329 specify which of the attributes in a #GdkICAttr are being set or returned.
332 It also contains several combinations of the flags which specify required
333 attributes for the various styles:
336 <term>%GDK_IC_ALL_REQ:</term>
338 the set of attributes required for all styles.
343 <term>%GDK_IC_PREEDIT_AREA_REQ:</term>
345 the set of additional attributes required for the
346 %GDK_IM_PREEDIT_AREA pre-edit style.
351 <term>%GDK_IC_PREEDIT_POSITION_REQ:</term>
353 the set of additional attributes required for the
354 %GDK_IM_PREEDIT_POSITION pre-edit style.
359 <term>%GDK_IC_STATUS_AREA_REQ:</term>
361 the set of additional attributes required for the
362 %GDK_IM_STATUS_AREA status style.
369 @GDK_IC_CLIENT_WINDOW:
370 @GDK_IC_FOCUS_WINDOW:
371 @GDK_IC_FILTER_EVENTS:
372 @GDK_IC_SPOT_LOCATION:
373 @GDK_IC_LINE_SPACING:
375 @GDK_IC_PREEDIT_FONTSET:
376 @GDK_IC_PREEDIT_AREA:
377 @GDK_IC_PREEDIT_AREA_NEEDED:
378 @GDK_IC_PREEDIT_FOREGROUND:
379 @GDK_IC_PREEDIT_BACKGROUND:
380 @GDK_IC_PREEDIT_PIXMAP:
381 @GDK_IC_PREEDIT_COLORMAP:
382 @GDK_IC_STATUS_FONTSET:
384 @GDK_IC_STATUS_AREA_NEEDED:
385 @GDK_IC_STATUS_FOREGROUND:
386 @GDK_IC_STATUS_BACKGROUND:
387 @GDK_IC_STATUS_PIXMAP:
388 @GDK_IC_STATUS_COLORMAP:
390 @GDK_IC_PREEDIT_AREA_REQ:
391 @GDK_IC_PREEDIT_POSITION_REQ:
392 @GDK_IC_STATUS_AREA_REQ:
394 <!-- ##### ENUM GdkIMStyle ##### -->
396 A set of bit-flags used to specify the input method styles which are supported
397 or which are currently in use. The flags can be divided into 2 groups, the
398 pre-edit flags and the status flags.
401 The pre-edit flags specify how pre-editing data is displayed.
402 For example, this could display the text being typed in the phonetic
403 alphabet before it is composed and inserted as an ideograph.
406 The status flags specify how status information is displayed.
407 The status information can be thought of as an extension of the
408 standard keyboard mode indicators, such as the Caps Lock indicator.
412 The %GDK_IM_PREEDIT_CALLBACKS and %GDK_IM_STATUS_CALLBACKS styles are not
413 currently supported in GTK+.
417 @GDK_IM_PREEDIT_AREA: The application provides the input method with an area
418 in which to perform <emphasis>off-the-spot</emphasis> pre-editing.
419 @GDK_IM_PREEDIT_CALLBACKS: The application registers a number of callback
420 functions which are used to display pre-editing data.
421 @GDK_IM_PREEDIT_POSITION: The application provides the input method with the
422 position of the insertion cursor, for <emphasis>over-the-spot</emphasis>
423 pre-editing. The input method creates its own window over the widget to
424 display the pre-editing data.
425 @GDK_IM_PREEDIT_NOTHING: The input method uses the root X window to perform
426 pre-editing, so the application does not need to do anything.
427 @GDK_IM_PREEDIT_NONE: No pre-editing is done by the input method, or no
428 pre-editing data needs to be displayed.
429 @GDK_IM_PREEDIT_MASK: A bit-mask containing all the pre-edit flags.
430 @GDK_IM_STATUS_AREA: The application provides the input method with an area
431 in which to display status information.
432 @GDK_IM_STATUS_CALLBACKS: The applications registers a number of callback
433 functions which are used to display status information.
434 @GDK_IM_STATUS_NOTHING: The input method uses the root X window to display
435 status information, so the application does not need to do anything.
436 @GDK_IM_STATUS_NONE: The input method does not display status information.
437 @GDK_IM_STATUS_MASK: A bit-mask containing all the status flags.
439 <!-- ##### STRUCT GdkKeyInfo ##### -->
448 <!-- ##### STRUCT GdkKeymapClass ##### -->
454 <!-- ##### ENUM GdkPixbufAlphaMode ##### -->
459 @GDK_PIXBUF_ALPHA_BILEVEL:
460 @GDK_PIXBUF_ALPHA_FULL:
462 <!-- ##### STRUCT GdkWindowRedirect ##### -->
468 <!-- ##### FUNCTION gdk_color_context_add_palette ##### -->
478 <!-- ##### FUNCTION gdk_color_context_free ##### -->
485 <!-- ##### FUNCTION gdk_color_context_free_dither ##### -->
492 <!-- ##### FUNCTION gdk_color_context_get_index_from_palette ##### -->
504 <!-- ##### FUNCTION gdk_color_context_get_pixel ##### -->
516 <!-- ##### FUNCTION gdk_color_context_get_pixel_from_palette ##### -->
528 <!-- ##### FUNCTION gdk_color_context_get_pixels ##### -->
541 <!-- ##### FUNCTION gdk_color_context_get_pixels_incremental ##### -->
555 <!-- ##### FUNCTION gdk_color_context_init_dither ##### -->
562 <!-- ##### FUNCTION gdk_color_context_new ##### -->
571 <!-- ##### FUNCTION gdk_color_context_new_mono ##### -->
580 <!-- ##### FUNCTION gdk_color_context_query_color ##### -->
589 <!-- ##### FUNCTION gdk_color_context_query_colors ##### -->
599 <!-- ##### VARIABLE gdk_core_pointer ##### -->
605 <!-- ##### VARIABLE gdk_display_name ##### -->
611 <!-- ##### FUNCTION gdk_display_set_sm_client_id ##### -->
619 <!-- ##### FUNCTION gdk_font_full_name_free ##### -->
621 Frees a full font name obtained from gdk_font_full_name_get().
624 @name: a full font name.
626 <!-- ##### FUNCTION gdk_font_full_name_get ##### -->
628 Returns a comma-separated list of XLFDs for the
629 fonts making up a given #GdkFont.
633 @Returns: a newly-allocated string containing a list of XLFDs,
634 should be freed with gdk_font_full_name_free() when no longer needed.
636 <!-- ##### FUNCTION gdk_get_client_window ##### -->
645 <!-- ##### FUNCTION gdk_get_default_display ##### -->
652 <!-- ##### FUNCTION gdk_get_default_screen ##### -->
659 <!-- ##### FUNCTION gdk_ic_attr_destroy ##### -->
661 Destroys the given #GdkICAttr struct, freeing the allocated memory.
664 @attr: a #GdkICAttr struct.
666 <!-- ##### FUNCTION gdk_ic_attr_new ##### -->
668 Creates a new #GdkICAttr struct, with all fields set to 0.
669 The #GdkICAttr struct should be freed with gdk_ic_attr_destroy() when no
673 @Returns: a new #GdkICAttr struct.
675 <!-- ##### FUNCTION gdk_ic_destroy ##### -->
677 Destroys the input context.
682 <!-- ##### FUNCTION gdk_ic_get_attr ##### -->
684 Gets attributes of a #GdkIC.
688 @attr: a #GdkICAttr struct to contain the returned attributes.
689 @mask: a #GdkICAttributesType mask specifying which attributes to get.
690 @Returns: a #GdkICAttributesType mask specifying which of the attributes
691 were not retrieved succesfully.
693 <!-- ##### FUNCTION gdk_ic_get_events ##### -->
695 Returns the mask of events that the input method needs to function properly.
696 This is typically called in a widget's realize method after creating the
697 #GdkIC. The returned event mask is then combined with the widget's
698 own event mask and applied using gdk_window_set_events().
702 @Returns: the mask of events that the input method needs to function
705 <!-- ##### FUNCTION gdk_ic_get_style ##### -->
707 Returns the pre-edit and status style of the #GdkIC.
711 @Returns: the pre-edit and status style of the #GdkIC.
713 <!-- ##### FUNCTION gdk_ic_new ##### -->
715 Creates a new #GdkIC using the given attributes.
718 @attr: a #GdkICAttr struct containing attributes to use for the input context.
719 @mask: a #GdkICAttributesType mask specifying which of the attributes in @attr
721 @Returns: a new #GdkIC.
723 <!-- ##### FUNCTION gdk_ic_set_attr ##### -->
725 Sets attributes of the #GdkIC.
728 Note that the GDK_IC_STYLE and GDK_IC_CLIENT_WINDOW attributes can only be set
729 when creating the #GdkIC, and the GDK_IC_FILTER_EVENTS attribute is read-only.
733 @attr: a #GdkICAttr struct containing attributes to use for the input context.
734 @mask: a #GdkICAttributesType mask specifying which of the attributes in @attr
736 @Returns: a #GdkICAttributesType mask indicating which of the attributes
737 were not set successfully.
739 <!-- ##### FUNCTION gdk_im_begin ##### -->
741 Starts editing, using the given input context and #GdkWindow.
742 This should be called when the widget receives the input focus, typically in
743 the widget's focus_in_event method.
747 @window: the #GdkWindow which will be receiving the key press events.
749 <!-- ##### FUNCTION gdk_im_decide_style ##### -->
751 Decides which input method style should be used, by comparing the styles given
752 in @supported_style with those of the available input method.
755 @supported_style: styles which are supported by the widget.
756 @Returns: the best style in @supported_style that is also supported by the
757 available input method.
759 <!-- ##### FUNCTION gdk_im_end ##### -->
761 Stops editing using the input method.
762 This should be called when the widget loses the input focus, typically in
763 the widget's focus_out_event method.
767 <!-- ##### FUNCTION gdk_im_ready ##### -->
769 Checks if an input method is to be used for the current locale.
770 If GTK+ has been compiled without support for input methods, or the current
771 locale doesn't need an input method, then this will return FALSE.
774 @Returns: TRUE if an input method is available and should be used.
776 <!-- ##### FUNCTION gdk_im_set_best_style ##### -->
778 Sets the best pre-edit and/or status style which should be used.
779 This will affect the style chosen in gdk_im_decide_style().
782 The order of the pre-edit styles is (from worst to best):
783 %GDK_IM_PREEDIT_NONE, %GDK_IM_PREEDIT_NOTHING, %GDK_IM_PREEDIT_AREA,
784 %GDK_IM_PREEDIT_POSITION, %GDK_IM_PREEDIT_CALLBACKS.
785 The order of the status styles is:
786 %GDK_IM_STATUS_NONE, %GDK_IM_STATUS_NOTHING, %GDK_IM_STATUS_AREA,
787 %GDK_IM_STATUS_CALLBACKS.
790 So, for example, to set the best allowed pre-edit style to %GDK_IM_PREEDIT_AREA
795 gdk_im_set_best_style (GDK_IM_PREEDIT_AREA);
799 Or to set the best allowed pre-edit style to %GDK_IM_PREEDIT_POSITION and the
800 best allowed status style to %GDK_IM_STATUS_NOTHING you can do this:
804 gdk_im_set_best_style (GDK_IM_PREEDIT_POSITION | GDK_IM_STATUS_NOTHING);
809 @best_allowed_style: a bit-mask with the best pre-edit style and/or the best
810 status style to use. If 0 is used, then the current bit-mask of all allowed
812 @Returns: a bit-mask of all the styles allowed.
814 <!-- ##### FUNCTION gdk_input_list_devices ##### -->
816 Lists all available input devices, along with their
817 configuration information.
820 @Returns: A #GList of #GdkDeviceInfo structures. This list
821 is internal data of GTK+ and should not be modified
824 <!-- ##### FUNCTION gdk_input_motion_events ##### -->
826 Retrieves the motion history for a given device/window pair.
829 @window: a #GdkWindow.
830 @deviceid: the device for which to retrieve motion history.
831 @start: the start time.
832 @stop: the stop time.
833 @nevents_return: location to store the number of events returned.
834 @Returns: a newly allocated array containing all the events
835 from @start to @stop. This array should be freed
836 with g_free() when you are finished using it.
838 <!-- ##### FUNCTION gdk_input_set_axes ##### -->
840 Sets the mapping of the axes (valuators) of a device
841 onto the predefined valuator types that GTK+ understands.
844 @deviceid: the device to configure.
845 @axes: an array of GdkAxisUse. This length of this array
846 must match the number of axes for the device.
848 <!-- ##### FUNCTION gdk_input_set_key ##### -->
850 Sets the key event generated when a macro button is pressed.
853 @deviceid: the device to configure.
854 @index_: the index of the macro button.
855 @keyval: the key value for the #GdkKeypressEvent to generate.
856 (a value of 0 means no event will be generated.)
857 @modifiers: the modifier field for the generated
860 <!-- ##### FUNCTION gdk_input_set_mode ##### -->
862 Enables or disables a device, and determines how the
863 device maps onto the screen.
866 @deviceid: the device to configure.
868 @Returns: %TRUE if the device supports the given mode, otherwise
869 %FALSE and the device's mode is unchanged.
871 <!-- ##### FUNCTION gdk_input_set_source ##### -->
873 Sets the source type for a device.
876 @deviceid: the device to configure
877 @source: the new source type.
879 <!-- ##### FUNCTION gdk_input_window_get_pointer ##### -->
881 Returns information about the current position of the pointer
882 within a window, including extended device information.
883 Any of the return parameters may be %NULL, in which case,
884 they will be ignored.
887 @window: a #GdkWindow.
888 @deviceid: a device ID.
889 @x: location to store current x postion.
890 @y: location to store current y postion.
891 @pressure: location to store current pressure.
892 @xtilt: location to store current tilt in the x direction.
893 @ytilt: location to store current tilt in the y direction.
894 @mask: location to store the current modifier state.
896 <!-- ##### VARIABLE gdk_leader_window ##### -->
902 <!-- ##### FUNCTION gdk_open_display ##### -->
910 <!-- ##### FUNCTION gdk_pixbuf_set_as_cairo_source ##### -->
920 <!-- ##### VARIABLE gdk_progclass ##### -->
926 <!-- ##### MACRO gdk_rgb_get_cmap ##### -->
928 Gets the colormap set by GdkRGB. This colormap and the corresponding
929 visual should be used when creating windows that will be drawn in by GdkRGB.
932 @Returns: The #GdkColormap set by GdkRGB.
934 <!-- ##### VARIABLE gdk_screen ##### -->
940 <!-- ##### FUNCTION gdk_screen_close ##### -->
947 <!-- ##### FUNCTION gdk_screen_get_window_at_pointer ##### -->
957 <!-- ##### FUNCTION gdk_screen_use_virtual_screen ##### -->
965 <!-- ##### VARIABLE gdk_selection_property ##### -->
971 <!-- ##### FUNCTION gdk_set_default_display ##### -->
978 <!-- ##### FUNCTION gdkx_visual_get_for_screen ##### -->