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

# General

## Name

General -- library initialization and miscellaneous functions.

## Synopsis

    #include <gdk/gdk.h>

    void        gdk_init                        (gint *argc,
                                                 gchar ***argv);
    gboolean    gdk_init_check                  (gint *argc,
                                                 gchar ***argv);
    void        gdk_exit                        (gint error_code);
    gchar*      gdk_set_locale                  (void);
    void        gdk_set_sm_client_id            (const gchar *sm_client_id);

    gchar*      gdk_get_display                 (void);

    void        gdk_flush                       (void);

    gint        gdk_screen_width                (void);
    gint        gdk_screen_height               (void);
    gint        gdk_screen_width_mm             (void);
    gint        gdk_screen_height_mm            (void);

    gint        gdk_pointer_grab                (GdkWindow *window,
                                                 gint owner_events,
                                                 GdkEventMask event_mask,
                                                 GdkWindow *confine_to,
                                                 GdkCursor *cursor,
                                                 guint32 time);
    void        gdk_pointer_ungrab              (guint32 time);
    gint        gdk_pointer_is_grabbed          (void);

    gint        gdk_keyboard_grab               (GdkWindow *window,
                                                 gint owner_events,
                                                 guint32 time);
    void        gdk_keyboard_ungrab             (guint32 time);

    void        gdk_key_repeat_disable          (void);
    void        gdk_key_repeat_restore          (void);

    void        gdk_beep                        (void);

    gint        gdk_get_use_xshm                (void);
    void        gdk_set_use_xshm                (gint use_xshm);

    void        gdk_error_trap_push             (void);
    gint        gdk_error_trap_pop              (void);

## Description

This section describes the GDK initialization functions and miscellaneous utility functions.

## Details

### gdk_init ()

    void        gdk_init                        (gint *argc,
                                                 gchar ***argv);

Initializes the GDK library and connects to the X server. If initialization fails, a warning message is output and the application terminates with a call to exit(1).

Any arguments used by GDK are removed from the array and `argc` and `argv` are updated accordingly.

GTK+ initializes GDK in gtk_init() and so this function is not usually needed by GTK+ applications.

`argc` : | the number of command line arguments.
`argv` : | the array of command line arguments.

### gdk_init_check ()

    gboolean    gdk_init_check                  (gint *argc,
                                                 gchar ***argv);

Initializes the GDK library and connects to the X server, returning TRUE on success.

Any arguments used by GDK are removed from the array and `argc` and `argv` are updated accordingly.

GTK+ initializes GDK in gtk_init() and so this function is not usually needed by GTK+ applications.

`argc` : | the number of command line arguments.
`argv` : | the array of command line arguments.
Returns : | TRUE if initialization succeeded.

### gdk_exit ()

    void        gdk_exit                        (gint error_code);

Exits the application using the exit() system call.

This routine is provided mainly for backwards compatability, since it used to perform tasks necessary to exit the application cleanly. Those tasks are now performed in a function which is automatically called on exit (via the use of g_atexit()).

`error_code` : | the error code to pass to the exit() call.

### gdk_set_locale ()

    gchar*      gdk_set_locale                  (void);

Initializes the support for internationalization by calling the setlocale() system call. This function is called by gtk_set_locale() and so GTK+ applications should use that instead.

The locale to use is determined by the LANG environment variable, so to run an application in a certain locale you can do something like this:

      export LANG="fr"
      ... run application ...

If the locale is not supported by X then it is reset to the standard "C" locale.

Returns : | the resulting locale.

### gdk_set_sm_client_id ()

    void        gdk_set_sm_client_id            (const gchar *sm_client_id);

Sets the SM_CLIENT_ID property on the application's leader window so that the window manager can save the application's state using the X11R6 ICCCM session management protocol.

The leader window is automatically created by GDK and never shown. It's only use is for session management. The WM_CLIENT_LEADER property is automatically set on all X windows created by the application to point to the leader window.

See the X Session Management Library documentation for more information on session management and the Inter-Client Communication Conventions Manual (ICCCM) for information on the WM_CLIENT_LEADER property. (Both documents are part of the X Windows distribution.)

`sm_client_id` : | the client id assigned by the session manager when the connection was opened, or NULL to remove the property.

### gdk_get_display ()

    gchar*      gdk_get_display                 (void);

Gets the name of the display, which usually comes from the DISPLAY environment variable or the --display command line option.

Returns : | the name of the display.

### gdk_flush ()

    void        gdk_flush                       (void);

Flushes the X output buffer and waits until all requests have been processed by the server. This is rarely needed by applications. It's main use is for trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop().

### gdk_screen_width ()

    gint        gdk_screen_width                (void);

Returns the width of the screen in pixels.

Returns : | the width of the screen in pixels.

### gdk_screen_height ()

    gint        gdk_screen_height               (void);

Returns the height of the screen in pixels.

Returns : | the height of the screen in pixels.

### gdk_screen_width_mm ()

    gint        gdk_screen_width_mm             (void);

Returns the width of the screen in millimeters. Note that on many X servers this value will not be correct.

Returns : | the width of the screen in millimeters, though it is not always correct.

### gdk_screen_height_mm ()

    gint        gdk_screen_height_mm            (void);

Returns the height of the screen in millimeters. Note that on many X servers this value will not be correct.

Returns : | the height of the screen in millimeters, though it is not always correct.

### gdk_pointer_grab ()

    gint        gdk_pointer_grab                (GdkWindow *window,
                                                 gint owner_events,
                                                 GdkEventMask event_mask,
                                                 GdkWindow *confine_to,
                                                 GdkCursor *cursor,
                                                 guint32 time);

Grabs the pointer (usually a mouse) so that all events are passed to this application until the pointer is ungrabbed with gdk_pointer_ungrab(), or the grab window becomes unviewable. This overrides any previous pointer grab by this client.

Pointer grabs are used for operations which need complete control over mouse events, even if the mouse leaves the application. For example in GTK+ it is used for Drag and Drop, for dragging the handle in the GtkHPaned and GtkVPaned widgets, and for resizing columns in GtkCList widgets.

Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with `owner_events` set to TRUE.

`window` : | the GdkWindow which will own the grab (the grab window).
`owner_events` : | if FALSE then all pointer events are reported with respect to `window` and are only reported if selected by `event_mask`. If TRUE then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to `window` and only if selected by `event_mask`. In either mode, unreported events are discarded.
`event_mask` : | specifies the event mask, which is used in accordance with `owner_events`.
`confine_to` : | If non-`NULL`, the pointer will be confined to this window during the grab. If the pointer is outside `confine_to`, it will automatically be moved to the closest edge of `confine_to` and enter and leave events will be generated as necessary.
`cursor` : | the cursor to display while the grab is active. If this is NULL then the normal cursors are used for `window` and its descendants, and the cursor for `window` is used for all other windows.
`time` : | the timestamp of the event which led to this pointer grab. This usually comes from a GdkEventButton struct, though GDK_CURRENT_TIME can be used if the time isn't known.
Returns : | 0 if the grab was successful.

### gdk_pointer_ungrab ()

    void        gdk_pointer_ungrab              (guint32 time);

Ungrabs the pointer, if it is grabbed by this application.

`time` : | a timestamp from a GdkEvent, or GDK_CURRENT_TIME if no timestamp is available.

### gdk_pointer_is_grabbed ()

    gint        gdk_pointer_is_grabbed          (void);

Returns TRUE if the pointer is currently grabbed by this application.

Note that the return value is not completely reliable since the X server may automatically ungrab the pointer, without informing the application, if the grab window becomes unviewable. It also does not take passive pointer grabs into account.

Returns : | TRUE if the pointer is currently grabbed by this application. Though this value is not always correct.

### gdk_keyboard_grab ()

    gint        gdk_keyboard_grab               (GdkWindow *window,
                                                 gint owner_events,
                                                 guint32 time);

Grabs the keyboard so that all events are passed to this application until the keyboard is ungrabbed with gdk_keyboard_ungrab(). This overrides any previous keyboard grab by this client.

`window` : | the GdkWindow which will own the grab (the grab window).
`owner_events` : | if FALSE then all keyboard events are reported with respect to `window`. If TRUE then keyboard events for this application are reported as normal, but keyboard events outside this application are reported with respect to `window`. Both key press and key release events are always reported, independant of the event mask set by the application.
`time` : | a timestamp from a GdkEvent, or GDK_CURRENT_TIME if no timestamp is available.
Returns : | 0 if the grab was successful.

### gdk_keyboard_ungrab ()

    void        gdk_keyboard_ungrab             (guint32 time);

Ungrabs the keyboard, if it is grabbed by this application.

`time` : | a timestamp from a GdkEvent, or GDK_CURRENT_TIME if no timestamp is available.

### gdk_key_repeat_disable ()

    void        gdk_key_repeat_disable          (void);

Disables the keyboard auto-repeat mode. This should be used with care as it may affect other applications.

### gdk_key_repeat_restore ()

    void        gdk_key_repeat_restore          (void);

Restores the keyboard auto-repeat mode to its state when the application was started.

### gdk_beep ()

    void        gdk_beep                        (void);

Emits a short beep.

### gdk_get_use_xshm ()

    gint        gdk_get_use_xshm                (void);

Returns TRUE if GDK will attempt to use the MIT-SHM shared memory extension.

The shared memory extension is used for GdkImage, and consequently for GdkRGB. It enables much faster drawing by communicating with the X server through SYSV shared memory calls. However, it can only be used if the X client and server are on the same machine and the server supports it.

Returns : | TRUE if use of the MIT shared memory extension will be attempted.

### gdk_set_use_xshm ()

    void        gdk_set_use_xshm                (gint use_xshm);

Sets whether the use of the MIT shared memory extension should be attempted. This function is mainly for internal use. It is only safe for an application to set this to FALSE, since if it is set to TRUE and the server does not support the extension it may cause warning messages to be output.

`use_xshm` : | TRUE if use of the MIT shared memory extension should be attempted.

### gdk_error_trap_push ()

    void        gdk_error_trap_push             (void);

This function allows X errors to be trapped instead of the normal behavior of exiting the application. It should only be used if it is not possible to avoid the X error in any other way.

Example 1. Trapping an X error.

      gdk_error_trap_push();

      /* ... Call the X function which may cause an error here ... */

      /* Flush the X queue to catch errors now. */
      gdk_flush();

      if (gdk_error_trap_pop())
        {
          /* ... Handle the error here ... */
        }

### gdk_error_trap_pop ()

    gint        gdk_error_trap_pop              (void);

Removes the X error trap installed with gdk_error_trap_push().

Returns : | the X error code, or 0 if no error occurred.

<<< Previous Page | Home | Up | Next Page >>>
GDK | Points, Rectangles and Regions