mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-11-10 02:40:11 +00:00
docs: Move documentation to inline comments: general
This commit is contained in:
Javier Jardón
parent
2cd0302e64
commit
1268c17983
1
docs/reference/gdk/tmpl/.gitignore
vendored
1
docs/reference/gdk/tmpl/.gitignore
vendored
@ -6,6 +6,7 @@ gdkdisplay.sgml
|
||||
gdkdisplaymanager.sgml
|
||||
gdkscreen.sgml
|
||||
gdktesting.sgml
|
||||
general.sgml
|
||||
keys.sgml
|
||||
pixbufs.sgml
|
||||
regions.sgml
|
||||
|
||||
@ -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
68
gdk/gdk.c
@ -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.
|
||||
* Any arguments used by GDK are removed from the array and @argc and @argv are
|
||||
* updated accordingly.
|
||||
*
|
||||
* 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.
|
||||
* GTK+ initializes GDK in gtk_init() and so this function is not usually needed
|
||||
* by GTK+ applications.
|
||||
*
|
||||
* Side effects:
|
||||
* The library is initialized.
|
||||
*
|
||||
*--------------------------------------------------------------
|
||||
* 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)
|
||||
{
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
{
|
||||
|
||||
@ -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().
|
||||
|
||||
Loading…
Reference in New Issue
Block a user