mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-10-01 19:48:11 +00:00
b837ef5a6d
* add per-display gdk_x11_display_error_trap_push() (X11-specific because gdk_error_trap_push() probably should have been) * make gdk_error_trap_push() handle only GDK displays not displays opened without a GDK wrapper * make gdk_error_trap_pop() and gdk_x11_display_error_trap_pop() automatically sync only if needed, so manual gdk_flush() is not required * add gdk_error_trap_pop_ignored() which just asynchronously ignores errors, so never needs to sync * add G_GNUC_WARN_UNUSED_RESULT to plain pop(), because if you use plain pop() and don't need the return value, the async gdk_error_trap_pop_ignored() should be used instead. This results in lots of warnings to clean up in a later patch. The main objective here was to avoid the need to sync just to ignore an error. Now, syncing is automatic, and only happens when we need to know the error code. https://bugzilla.gnome.org/show_bug.cgi?id=629608
343 lines
8.8 KiB
Plaintext
343 lines
8.8 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
General
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Library initialization and miscellaneous functions
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
This section describes the GDK initialization functions and miscellaneous
|
|
utility functions.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### SECTION Image ##### -->
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_init ##### -->
|
|
<para>
|
|
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 <literal>exit(1)</literal>.
|
|
</para>
|
|
<para>
|
|
Any arguments used by GDK are removed from the array and @argc and @argv are
|
|
updated accordingly.
|
|
</para>
|
|
<para>
|
|
GTK+ initializes GDK in gtk_init() and so this function is not usually needed
|
|
by GTK+ applications.
|
|
</para>
|
|
|
|
@argc: the number of command line arguments.
|
|
@argv: the array of command line arguments.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_init_check ##### -->
|
|
<para>
|
|
Initializes the GDK library and connects to the X server, returning %TRUE on
|
|
success.
|
|
</para>
|
|
<para>
|
|
Any arguments used by GDK are removed from the array and @argc and @argv are
|
|
updated accordingly.
|
|
</para>
|
|
<para>
|
|
GTK+ initializes GDK in gtk_init() and so this function is not usually needed
|
|
by GTK+ applications.
|
|
</para>
|
|
|
|
@argc: the number of command line arguments.
|
|
@argv: the array of command line arguments.
|
|
@Returns: %TRUE if initialization succeeded.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_parse_args ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@argc:
|
|
@argv:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_get_display_arg_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@void:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_set_locale ##### -->
|
|
<para>
|
|
Initializes the support for internationalization by calling the <function>setlocale()</function>
|
|
system call. This function is called by gtk_set_locale() and so GTK+
|
|
applications should use that instead.
|
|
</para>
|
|
<para>
|
|
The locale to use is determined by the <envar>LANG</envar> environment variable,
|
|
so to run an application in a certain locale you can do something like this:
|
|
<informalexample>
|
|
<programlisting>
|
|
export LANG="fr"
|
|
... run application ...
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
If the locale is not supported by X then it is reset to the standard "C"
|
|
locale.
|
|
</para>
|
|
|
|
@void:
|
|
@Returns: the resulting locale.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_set_sm_client_id ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@sm_client_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_notify_startup_complete ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@void:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_notify_startup_complete_with_id ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@startup_id:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_get_program_class ##### -->
|
|
<para>
|
|
Gets the program class. Unless the program class has explicitly
|
|
been set with gdk_set_program_class() or with the <option>--class</option>
|
|
commandline option, the default value is the program name (determined
|
|
with g_get_prgname()) with the first character converted to uppercase.
|
|
</para>
|
|
|
|
@void:
|
|
@Returns: the program class.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_set_program_class ##### -->
|
|
<para>
|
|
Sets the program class. The X11 backend uses the program class to set
|
|
the class name part of the <literal>WM_CLASS</literal> property on
|
|
toplevel windows; see the ICCCM.
|
|
</para>
|
|
|
|
@program_class: a string.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_get_display ##### -->
|
|
<para>
|
|
Gets the name of the display, which usually comes from the <envar>DISPLAY</envar>
|
|
environment variable or the <option>--display</option> command line option.
|
|
</para>
|
|
|
|
@void:
|
|
@Returns: the name of the display.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_flush ##### -->
|
|
<para>
|
|
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().
|
|
</para>
|
|
|
|
@void:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_screen_width ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@void:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_screen_height ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@void:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_screen_width_mm ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@void:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_screen_height_mm ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@void:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_pointer_grab ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
If you set up anything at the time you take the grab that needs to be cleaned
|
|
up when the grab ends, you should handle the #GdkEventGrabBroken events that
|
|
are emitted when the grab ends unvoluntarily.
|
|
</para>
|
|
|
|
@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. Note that only pointer events (i.e. button and motion events)
|
|
may be selected.
|
|
@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: %GDK_GRAB_SUCCESS if the grab was successful.
|
|
|
|
|
|
<!-- ##### ENUM GdkGrabStatus ##### -->
|
|
<para>
|
|
Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate
|
|
success or the reason for the failure of the grab attempt.
|
|
</para>
|
|
|
|
@GDK_GRAB_SUCCESS: the resource was successfully grabbed.
|
|
@GDK_GRAB_ALREADY_GRABBED: the resource is actively grabbed by another client.
|
|
@GDK_GRAB_INVALID_TIME: the resource was grabbed more recently than the
|
|
specified time.
|
|
@GDK_GRAB_NOT_VIEWABLE: the grab window or the @confine_to window are not
|
|
viewable.
|
|
@GDK_GRAB_FROZEN: the resource is frozen by an active grab of another client.
|
|
|
|
<!-- ##### FUNCTION gdk_pointer_ungrab ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@time_:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
|
|
<para>
|
|
</para>
|
|
<para>
|
|
</para>
|
|
|
|
@void:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_set_double_click_time ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@msec:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_keyboard_grab ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
If you set up anything at the time you take the grab that needs to be cleaned
|
|
up when the grab ends, you should handle the #GdkEventGrabBroken events that
|
|
are emitted when the grab ends unvoluntarily.
|
|
</para>
|
|
|
|
@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: %GDK_GRAB_SUCCESS if the grab was successful.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@time_:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_beep ##### -->
|
|
<para>
|
|
</para>
|
|
|
|
@void:
|
|
|
|
<!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
|
|
<para>
|
|
This macro is defined if GDK is configured to use the X11 backend.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
|
|
<para>
|
|
This macro is defined if GDK is configured to use the win32 backend.
|
|
</para>
|
|
|
|
|
|
|