1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Library initialization and miscellaneous functions
7 <!-- ##### SECTION Long_Description ##### -->
9 This section describes the GDK initialization functions and miscellaneous
13 <!-- ##### SECTION See_Also ##### -->
18 <!-- ##### SECTION Stability_Level ##### -->
21 <!-- ##### SECTION Image ##### -->
24 <!-- ##### FUNCTION gdk_init ##### -->
26 Initializes the GDK library and connects to the X server.
27 If initialization fails, a warning message is output and the application
28 terminates with a call to <literal>exit(1)</literal>.
31 Any arguments used by GDK are removed from the array and @argc and @argv are
35 GTK+ initializes GDK in gtk_init() and so this function is not usually needed
39 @argc: the number of command line arguments.
40 @argv: the array of command line arguments.
43 <!-- ##### FUNCTION gdk_init_check ##### -->
45 Initializes the GDK library and connects to the X server, returning %TRUE on
49 Any arguments used by GDK are removed from the array and @argc and @argv are
53 GTK+ initializes GDK in gtk_init() and so this function is not usually needed
57 @argc: the number of command line arguments.
58 @argv: the array of command line arguments.
59 @Returns: %TRUE if initialization succeeded.
62 <!-- ##### FUNCTION gdk_parse_args ##### -->
71 <!-- ##### FUNCTION gdk_get_display_arg_name ##### -->
80 <!-- ##### FUNCTION gdk_set_locale ##### -->
82 Initializes the support for internationalization by calling the <function>setlocale()</function>
83 system call. This function is called by gtk_set_locale() and so GTK+
84 applications should use that instead.
87 The locale to use is determined by the <envar>LANG</envar> environment variable,
88 so to run an application in a certain locale you can do something like this:
92 ... run application ...
97 If the locale is not supported by X then it is reset to the standard "C"
102 @Returns: the resulting locale.
105 <!-- ##### FUNCTION gdk_set_sm_client_id ##### -->
112 <!-- ##### FUNCTION gdk_exit ##### -->
114 Exits the application using the <function>exit()</function> system call.
117 This routine is provided mainly for backwards compatibility, since it used to
118 perform tasks necessary to exit the application cleanly. Those tasks are now
119 performed in a function which is automatically called on exit (via the use
123 @error_code: the error code to pass to the <function>exit()</function> call.
126 <!-- ##### FUNCTION gdk_notify_startup_complete ##### -->
134 <!-- ##### FUNCTION gdk_notify_startup_complete_with_id ##### -->
142 <!-- ##### FUNCTION gdk_get_program_class ##### -->
144 Gets the program class. Unless the program class has explicitly
145 been set with gdk_set_program_class() or with the <option>--class</option>
146 commandline option, the default value is the program name (determined
147 with g_get_prgname()) with the first character converted to uppercase.
151 @Returns: the program class.
154 <!-- ##### FUNCTION gdk_set_program_class ##### -->
156 Sets the program class. The X11 backend uses the program class to set
157 the class name part of the <literal>WM_CLASS</literal> property on
158 toplevel windows; see the ICCCM.
161 @program_class: a string.
164 <!-- ##### FUNCTION gdk_get_display ##### -->
166 Gets the name of the display, which usually comes from the <envar>DISPLAY</envar>
167 environment variable or the <option>--display</option> command line option.
171 @Returns: the name of the display.
174 <!-- ##### FUNCTION gdk_flush ##### -->
176 Flushes the X output buffer and waits until all requests have been processed
177 by the server. This is rarely needed by applications. It's main use is for
178 trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop().
184 <!-- ##### FUNCTION gdk_screen_width ##### -->
192 <!-- ##### FUNCTION gdk_screen_height ##### -->
200 <!-- ##### FUNCTION gdk_screen_width_mm ##### -->
208 <!-- ##### FUNCTION gdk_screen_height_mm ##### -->
216 <!-- ##### FUNCTION gdk_pointer_grab ##### -->
218 Grabs the pointer (usually a mouse) so that all events are passed to this
219 application until the pointer is ungrabbed with gdk_pointer_ungrab(), or
220 the grab window becomes unviewable.
221 This overrides any previous pointer grab by this client.
224 Pointer grabs are used for operations which need complete control over mouse
225 events, even if the mouse leaves the application.
226 For example in GTK+ it is used for Drag and Drop, for dragging the handle in
227 the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList
231 Note that if the event mask of an X window has selected both button press and
232 button release events, then a button press event will cause an automatic
233 pointer grab until the button is released.
234 X does this automatically since most applications expect to receive button
235 press and release events in pairs.
236 It is equivalent to a pointer grab on the window with @owner_events set to
240 If you set up anything at the time you take the grab that needs to be cleaned
241 up when the grab ends, you should handle the #GdkEventGrabBroken events that
242 are emitted when the grab ends unvoluntarily.
245 @window: the #GdkWindow which will own the grab (the grab window).
246 @owner_events: if %FALSE then all pointer events are reported with respect to
247 @window and are only reported if selected by @event_mask. If %TRUE then pointer
248 events for this application are reported as normal, but pointer events outside
249 this application are reported with respect to @window and only if selected by
250 @event_mask. In either mode, unreported events are discarded.
251 @event_mask: specifies the event mask, which is used in accordance with
252 @owner_events. Note that only pointer events (i.e. button and motion events)
254 @confine_to: If non-%NULL, the pointer will be confined to this
255 window during the grab. If the pointer is outside @confine_to, it will
256 automatically be moved to the closest edge of @confine_to and enter
257 and leave events will be generated as necessary.
258 @cursor: the cursor to display while the grab is active. If this is %NULL then
259 the normal cursors are used for @window and its descendants, and the cursor
260 for @window is used for all other windows.
261 @time_: the timestamp of the event which led to this pointer grab. This usually
262 comes from a #GdkEventButton struct, though %GDK_CURRENT_TIME can be used if
263 the time isn't known.
264 @Returns: %GDK_GRAB_SUCCESS if the grab was successful.
267 <!-- ##### ENUM GdkGrabStatus ##### -->
269 Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate
270 success or the reason for the failure of the grab attempt.
273 @GDK_GRAB_SUCCESS: the resource was successfully grabbed.
274 @GDK_GRAB_ALREADY_GRABBED: the resource is actively grabbed by another client.
275 @GDK_GRAB_INVALID_TIME: the resource was grabbed more recently than the
277 @GDK_GRAB_NOT_VIEWABLE: the grab window or the @confine_to window are not
279 @GDK_GRAB_FROZEN: the resource is frozen by an active grab of another client.
281 <!-- ##### FUNCTION gdk_pointer_ungrab ##### -->
289 <!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
299 <!-- ##### FUNCTION gdk_set_double_click_time ##### -->
307 <!-- ##### FUNCTION gdk_keyboard_grab ##### -->
309 Grabs the keyboard so that all events are passed to this
310 application until the keyboard is ungrabbed with gdk_keyboard_ungrab().
311 This overrides any previous keyboard grab by this client.
314 If you set up anything at the time you take the grab that needs to be cleaned
315 up when the grab ends, you should handle the #GdkEventGrabBroken events that
316 are emitted when the grab ends unvoluntarily.
319 @window: the #GdkWindow which will own the grab (the grab window).
320 @owner_events: if %FALSE then all keyboard events are reported with respect to
321 @window. If %TRUE then keyboard events for this application are reported as
322 normal, but keyboard events outside this application are reported with respect
323 to @window. Both key press and key release events are always reported,
324 independant of the event mask set by the application.
325 @time_: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
327 @Returns: %GDK_GRAB_SUCCESS if the grab was successful.
330 <!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
337 <!-- ##### FUNCTION gdk_beep ##### -->
344 <!-- ##### FUNCTION gdk_get_use_xshm ##### -->
346 Returns %TRUE if GDK will attempt to use the MIT-SHM shared memory extension.
349 The shared memory extension is used for #GdkImage, and consequently for
350 <link linkend="gdk-GdkRGB">GdkRGB</link>.
351 It enables much faster drawing by communicating with the X server through
352 SYSV shared memory calls. However, it can only be used if the X client and
353 server are on the same machine and the server supports it.
357 @Returns: %TRUE if use of the MIT shared memory extension will be attempted.
360 <!-- ##### FUNCTION gdk_set_use_xshm ##### -->
362 Sets whether the use of the MIT shared memory extension should be attempted.
363 This function is mainly for internal use. It is only safe for an application
364 to set this to %FALSE, since if it is set to %TRUE and the server does not
365 support the extension it may cause warning messages to be output.
368 @use_xshm: %TRUE if use of the MIT shared memory extension should be attempted.
371 <!-- ##### FUNCTION gdk_error_trap_push ##### -->
373 This function allows X errors to be trapped instead of the normal behavior
374 of exiting the application. It should only be used if it is not possible to
375 avoid the X error in any other way.
378 <title>Trapping an X error</title>
380 gdk_error_trap_push (<!-- -->);
382 /* ... Call the X function which may cause an error here ... */
384 /* Flush the X queue to catch errors now. */
385 gdk_flush (<!-- -->);
387 if (gdk_error_trap_pop (<!-- -->))
389 /* ... Handle the error here ... */
397 <!-- ##### FUNCTION gdk_error_trap_pop ##### -->
399 Removes the X error trap installed with gdk_error_trap_push().
403 @Returns: the X error code, or 0 if no error occurred.
406 <!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
408 This macro is defined if GDK is configured to use the X backend.
413 <!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
415 This macro is defined if GDK is configured to use the Win32 backend.