General
<!-- ##### SECTION Short_Description ##### -->
-library initialization and miscellaneous functions.
+Library initialization and miscellaneous functions
<!-- ##### SECTION Long_Description ##### -->
<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 exit(1).
+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
<!-- ##### FUNCTION gdk_init_check ##### -->
<para>
-Initializes the GDK library and connects to the X server, returning TRUE on
+Initializes the GDK library and connects to the X server, returning %TRUE on
success.
</para>
<para>
@argc: the number of command line arguments.
@argv: the array of command line arguments.
-@Returns: TRUE if initialization succeeded.
+@Returns: %TRUE if initialization succeeded.
-<!-- ##### FUNCTION gdk_exit ##### -->
+<!-- ##### FUNCTION gdk_parse_args ##### -->
<para>
-Exits the application using the exit() system call.
+
</para>
+
+@argc:
+@argv:
+
+
+<!-- ##### FUNCTION gdk_get_display_arg_name ##### -->
<para>
-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()).
+
</para>
-@error_code: the error code to pass to the exit() call.
+@void:
+@Returns:
<!-- ##### FUNCTION gdk_set_locale ##### -->
<para>
-Initializes the support for internationalization by calling the setlocale()
+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 LANG environment variable,
+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>
locale.
</para>
+@void:
@Returns: the resulting locale.
<!-- ##### FUNCTION gdk_set_sm_client_id ##### -->
<para>
-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.
</para>
+
+@sm_client_id:
+
+
+<!-- ##### FUNCTION gdk_exit ##### -->
+<para>
+Exits the application using the <function>exit()</function> system call.
+</para>
+<para>
+This routine is provided mainly for backwards compatibility, 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()).
+</para>
+
+@error_code: the error code to pass to the <function>exit()</function> call.
+
+
+<!-- ##### FUNCTION gdk_notify_startup_complete ##### -->
+<para>
+
+</para>
+
+@void:
+
+
+<!-- ##### FUNCTION gdk_notify_startup_complete_with_id ##### -->
<para>
-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.
+
</para>
+
+@startup_id:
+
+
+<!-- ##### FUNCTION gdk_get_program_class ##### -->
<para>
-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.)
+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>
-@sm_client_id: the client id assigned by the session manager when the
-connection was opened, or NULL to remove the property.
+@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 DISPLAY
-environment variable or the --display command line option.
+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.
trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop().
</para>
+@void:
<!-- ##### FUNCTION gdk_screen_width ##### -->
<para>
-Returns the width of the screen in pixels.
</para>
-@Returns: the width of the screen in pixels.
+@void:
+@Returns:
<!-- ##### FUNCTION gdk_screen_height ##### -->
<para>
-Returns the height of the screen in pixels.
</para>
-@Returns: the height of the screen in pixels.
+@void:
+@Returns:
<!-- ##### FUNCTION gdk_screen_width_mm ##### -->
<para>
-Returns the width of the screen in millimeters.
-Note that on many X servers this value will not be correct.
</para>
-@Returns: the width of the screen in millimeters, though it is not always
-correct.
+@void:
+@Returns:
<!-- ##### FUNCTION gdk_screen_height_mm ##### -->
<para>
-Returns the height of the screen in millimeters.
-Note that on many X servers this value will not be correct.
</para>
-@Returns: the height of the screen in millimeters, though it is not always
-correct.
+@void:
+@Returns:
<!-- ##### FUNCTION gdk_pointer_grab ##### -->
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.
+%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
+@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: TRUE to confine the pointer to @window. If the pointer is outside
-@window, it will automatically be moved to the closest edge of @window 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
+@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
+@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.
+@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>
-Ungrabs the pointer, if it is grabbed by this application.
+
</para>
-@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
-available.
+@time_:
<!-- ##### FUNCTION gdk_pointer_is_grabbed ##### -->
<para>
-Returns TRUE if the pointer is currently grabbed by this application.
</para>
<para>
-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.
</para>
-@Returns: TRUE if the pointer is currently grabbed by this application.
-Though this value is not always correct.
+@void:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_set_double_click_time ##### -->
+<para>
+
+</para>
+
+@msec:
<!-- ##### FUNCTION gdk_keyboard_grab ##### -->
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
+@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 alwasy reported,
+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
+@time_: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
available.
-@Returns: 0 if the grab was successful.
+@Returns: %GDK_GRAB_SUCCESS if the grab was successful.
<!-- ##### FUNCTION gdk_keyboard_ungrab ##### -->
<para>
-Ungrabs the keyboard, if it is grabbed by this application.
-</para>
-
-@time: a timestamp from a #GdkEvent, or #GDK_CURRENT_TIME if no timestamp is
-available.
-
-
-<!-- ##### FUNCTION gdk_key_repeat_disable ##### -->
-<para>
-Disables the keyboard auto-repeat mode.
-This should be used with care as it may affect other applications.
-</para>
-
-
-
-<!-- ##### FUNCTION gdk_key_repeat_restore ##### -->
-<para>
-Restores the keyboard auto-repeat mode to its state when the application was
-started.
</para>
+@time_:
<!-- ##### FUNCTION gdk_beep ##### -->
<para>
-Emits a short beep.
</para>
+@void:
<!-- ##### FUNCTION gdk_get_use_xshm ##### -->
<para>
-Returns TRUE if GDK will attempt to use the MIT-SHM shared memory extension.
+Returns %TRUE if GDK will attempt to use the MIT-SHM shared memory extension.
</para>
<para>
The shared memory extension is used for #GdkImage, and consequently for
server are on the same machine and the server supports it.
</para>
-@Returns: TRUE if use of the MIT shared memory extension will be attempted.
+@void:
+@Returns: %TRUE if use of the MIT shared memory extension will be attempted.
<!-- ##### FUNCTION gdk_set_use_xshm ##### -->
<para>
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
+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.
</para>
-@use_xshm: TRUE if use of the MIT shared memory extension should be attempted.
+@use_xshm: %TRUE if use of the MIT shared memory extension should be attempted.
<!-- ##### FUNCTION gdk_error_trap_push ##### -->
avoid the X error in any other way.
</para>
<example>
-<title>Trapping an X error.</title>
+<title>Trapping an X error</title>
<programlisting>
- gdk_error_trap_push ();
+ gdk_error_trap_push (<!-- -->);
/* ... Call the X function which may cause an error here ... */
/* Flush the X queue to catch errors now. */
- gdk_flush ();
+ gdk_flush (<!-- -->);
- if (gdk_error_trap_pop ())
+ if (gdk_error_trap_pop (<!-- -->))
{
/* ... Handle the error here ... */
}
</programlisting>
</example>
+@void:
<!-- ##### FUNCTION gdk_error_trap_pop ##### -->
Removes the X error trap installed with gdk_error_trap_push().
</para>
+@void:
@Returns: the X error code, or 0 if no error occurred.
+<!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
+<para>
+This macro is defined if GDK is configured to use the X backend.
+</para>
+
+
+
+<!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
+<para>
+This macro is defined if GDK is configured to use the Win32 backend.
+</para>
+
+
+
projects / ~andy / gtk / blobdiff