AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Move documentation to inline comments: general

Browse Source
This commit is contained in:
Javier Jardón 2010-11-15 04:58:21 +01:00 committed by Tristan Van Berkom
parent 145fe4bdc0
commit 2909edb3e7
6 changed files with 108 additions and 396 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gdk/tmpl/.gitignore vendored
View File

@ -6,6 +6,7 @@ gdkdisplay.sgml
gdkdisplaymanager.sgml gdkdisplaymanager.sgml
gdkscreen.sgml gdkscreen.sgml
gdktesting.sgml gdktesting.sgml
general.sgml
keys.sgml keys.sgml
pixbufs.sgml pixbufs.sgml
regions.sgml regions.sgml

366
docs/reference/gdk/tmpl/general.sgml
View File

@ -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>

68
gdk/gdk.c
View File

@ -38,6 +38,17 @@
#include <string.h> #include <string.h>
#include <stdlib.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; typedef struct _GdkPredicate GdkPredicate;
struct _GdkPredicate struct _GdkPredicate
@ -338,25 +349,19 @@ gdk_display_open_default_libgtk_only (void)
/** /**
* gdk_init_check: * gdk_init_check:
* @argc: (inout): * @argc: (inout): the number of command line arguments.
* @argv: (array length=argc) (inout): * @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: * Any arguments used by GDK are removed from the array and @argc and @argv are
* "argc" is the number of arguments. * updated accordingly.
* "argv" is an array of strings.
* *
* Results: * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
* "argc" and "argv" are modified to reflect any arguments * by GTK+ applications.
* which were not handled. (Such arguments should either
* be handled by the application or dismissed). If initialization
* fails, returns FALSE, otherwise TRUE.
* *
* Side effects: * Returns: %TRUE if initialization succeeded.
* The library is initialized.
*
*--------------------------------------------------------------
*/ */
gboolean gboolean
gdk_init_check (int *argc, gdk_init_check (int *argc,
@ -370,8 +375,18 @@ gdk_init_check (int *argc,
/** /**
* gdk_init: * gdk_init:
* @argc: (inout): * @argc: (inout): the number of command line arguments.
* @argv: (array length=argc) (inout): * @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 void
gdk_init (int *argc, char ***argv) gdk_init (int *argc, char ***argv)
@ -772,13 +787,30 @@ gdk_threads_add_timeout_seconds (guint interval,
interval, function, data, NULL); 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 * G_CONST_RETURN char *
gdk_get_program_class (void) gdk_get_program_class (void)
{ {
return gdk_progclass; 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 void
gdk_set_program_class (const char *program_class) gdk_set_program_class (const char *program_class)
{ {

37
gdk/gdkmain.h
View File

@ -50,6 +50,27 @@ gboolean gdk_init_check (gint *argc,
void gdk_add_option_entries_libgtk_only (GOptionGroup *group); void gdk_add_option_entries_libgtk_only (GOptionGroup *group);
void gdk_pre_parse_libgtk_only (void); 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); gchar* gdk_set_locale (void);
void gdk_enable_multidevice (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); 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); gchar* gdk_get_display (void);
#ifndef GDK_MULTIDEVICE_SAFE #ifndef GDK_MULTIDEVICE_SAFE
@ -102,6 +132,13 @@ void gdk_beep (void);
#endif /* GDK_MULTIHEAD_SAFE */ #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); void gdk_flush (void);
G_END_DECLS G_END_DECLS

15
gdk/gdktypes.h
View File

@ -196,9 +196,18 @@ typedef enum
GDK_ERROR_MEM = -4 GDK_ERROR_MEM = -4
} GdkStatus; } GdkStatus;
/* We define specific numeric values for these constants, /**
* since old application code may depend on them matching the X values * GdkGrabStatus:
* We don't actually depend on the matchup ourselves. * @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 typedef enum
{ {

7
gdk/gdkwindow.c
View File

@ -8864,8 +8864,7 @@ _gdk_display_set_window_under_pointer (GdkDisplay *display,
* Pointer grabs are used for operations which need complete control over mouse * Pointer grabs are used for operations which need complete control over mouse
* events, even if the mouse leaves the application. * events, even if the mouse leaves the application.
* For example in GTK+ it is used for Drag and Drop, for dragging the handle in * 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 * the #GtkHPaned and #GtkVPaned widgets.
* widgets.
* *
* Note that if the event mask of an X window has selected both button press and * 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 * button release events, then a button press event will cause an automatic
@ -8987,8 +8986,8 @@ gdk_pointer_grab (GdkWindow * window,
* are reported with respect to @window. Both key press and key * are reported with respect to @window. Both key press and key
* release events are always reported, independant of the event mask * release events are always reported, independant of the event mask
* set by the application. * 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. * available.
* *
* Grabs the keyboard so that all events are passed to this * Grabs the keyboard so that all events are passed to this
* application until the keyboard is ungrabbed with gdk_keyboard_ungrab(). * application until the keyboard is ungrabbed with gdk_keyboard_ungrab().