diff options
| -rw-r--r-- | docs/reference/gdk/tmpl/.gitignore | 1 | ||||
| -rw-r--r-- | docs/reference/gdk/tmpl/general.sgml | 366 | ||||
| -rw-r--r-- | gdk/gdk.c | 68 | ||||
| -rw-r--r-- | gdk/gdkmain.h | 37 | ||||
| -rw-r--r-- | gdk/gdktypes.h | 15 | ||||
| -rw-r--r-- | gdk/gdkwindow.c | 17 |
6 files changed, 108 insertions, 396 deletions
diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore index ef29778065..5b8a121d69 100644 --- a/docs/reference/gdk/tmpl/.gitignore +++ b/docs/reference/gdk/tmpl/.gitignore @@ -6,6 +6,7 @@ gdkdisplay.sgml gdkdisplaymanager.sgml gdkscreen.sgml gdktesting.sgml +general.sgml keys.sgml pixbufs.sgml regions.sgml diff --git a/docs/reference/gdk/tmpl/general.sgml b/docs/reference/gdk/tmpl/general.sgml deleted file mode 100644 index 089b44d677..0000000000 --- a/docs/reference/gdk/tmpl/general.sgml +++ /dev/null @@ -1,366 +0,0 @@ -<!-- ##### 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: - - -<!-- ##### FUNCTION gdk_error_trap_push ##### --> -<para> - -</para> - -@void: - - -<!-- ##### MACRO gdk_error_trap_pop ##### --> -<para> - -</para> - - - -<!-- ##### FUNCTION gdk_error_trap_pop_ignored ##### --> -<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> - - - @@ -38,6 +38,17 @@ #include <string.h> #include <stdlib.h> + +/** + * SECTION:general + * @Short_description: Library initialization and miscellaneous functions + * @Title: General + * + * This section describes the GDK initialization functions and miscellaneous + * utility functions. + */ + + typedef struct _GdkPredicate GdkPredicate; struct _GdkPredicate @@ -338,25 +349,19 @@ gdk_display_open_default_libgtk_only (void) /** * gdk_init_check: - * @argc: (inout): - * @argv: (array length=argc) (inout): + * @argc: (inout): the number of command line arguments. + * @argv: (array length=argc) (inout): the array of command line arguments. * - * Initialize the library for use. + * Initializes the GDK library and connects to the X server, returning %TRUE on + * success. * - * Arguments: - * "argc" is the number of arguments. - * "argv" is an array of strings. - * - * Results: - * "argc" and "argv" are modified to reflect any arguments - * which were not handled. (Such arguments should either - * be handled by the application or dismissed). If initialization - * fails, returns FALSE, otherwise TRUE. + * Any arguments used by GDK are removed from the array and @argc and @argv are + * updated accordingly. * - * Side effects: - * The library is initialized. + * GTK+ initializes GDK in gtk_init() and so this function is not usually needed + * by GTK+ applications. * - *-------------------------------------------------------------- + * Returns: %TRUE if initialization succeeded. */ gboolean gdk_init_check (int *argc, @@ -370,8 +375,18 @@ gdk_init_check (int *argc, /** * gdk_init: - * @argc: (inout): - * @argv: (array length=argc) (inout): + * @argc: (inout): the number of command line arguments. + * @argv: (array length=argc) (inout): the array of command line arguments. + * + * 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>. + * + * 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. */ void gdk_init (int *argc, char ***argv) @@ -772,13 +787,30 @@ gdk_threads_add_timeout_seconds (guint interval, interval, function, data, NULL); } - +/** + * gdk_get_program_class: + * + * 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. + * + * Returns: the program class. + */ G_CONST_RETURN char * gdk_get_program_class (void) { return gdk_progclass; } +/** + * gdk_set_program_class: + * @program_class: a string. + * + * 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. + */ void gdk_set_program_class (const char *program_class) { diff --git a/gdk/gdkmain.h b/gdk/gdkmain.h index f2ceaaa4bf..75ffb4e62a 100644 --- a/gdk/gdkmain.h +++ b/gdk/gdkmain.h @@ -50,6 +50,27 @@ gboolean gdk_init_check (gint *argc, void gdk_add_option_entries_libgtk_only (GOptionGroup *group); void gdk_pre_parse_libgtk_only (void); +/** + * gdk_set_locale: + * + * 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. + * + * 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> + * + * If the locale is not supported by X then it is reset to the standard "C" + * locale. + * + * Returns: the resulting locale. + */ gchar* gdk_set_locale (void); void gdk_enable_multidevice (void); @@ -68,6 +89,15 @@ void gdk_error_trap_pop_ignored (void); G_CONST_RETURN gchar *gdk_get_display_arg_name (void); + +/** + * gdk_get_display: + * + * Gets the name of the display, which usually comes from the <envar>DISPLAY</envar> + * environment variable or the <option>--display</option> command line option. + * + * Returns: the name of the display. + */ gchar* gdk_get_display (void); #ifndef GDK_MULTIDEVICE_SAFE @@ -102,6 +132,13 @@ void gdk_beep (void); #endif /* GDK_MULTIHEAD_SAFE */ +/** + * gdk_flush: + * + * 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(). + */ void gdk_flush (void); G_END_DECLS diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h index 53937d8ca6..44efa3fa9c 100644 --- a/gdk/gdktypes.h +++ b/gdk/gdktypes.h @@ -196,9 +196,18 @@ typedef enum GDK_ERROR_MEM = -4 } GdkStatus; -/* We define specific numeric values for these constants, - * since old application code may depend on them matching the X values - * We don't actually depend on the matchup ourselves. +/** + * GdkGrabStatus: + * @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. + * + * Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate + * success or the reason for the failure of the grab attempt. */ typedef enum { diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c index d186b4dce5..c2485980f5 100644 --- a/gdk/gdkwindow.c +++ b/gdk/gdkwindow.c @@ -8864,8 +8864,7 @@ _gdk_display_set_window_under_pointer (GdkDisplay *display, * 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. + * the #GtkHPaned and #GtkVPaned 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 @@ -8982,13 +8981,13 @@ gdk_pointer_grab (GdkWindow * window, * gdk_keyboard_grab: * @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. + * @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. * * Grabs the keyboard so that all events are passed to this * application until the keyboard is ungrabbed with gdk_keyboard_ungrab(). |