callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Give the GDK docs some love

Browse Source 
Reorganize some sections, drop the largely redundant multihead
section, add some more information about multiple backends.
This commit is contained in:
Matthias Clasen
2011-02-09 01:32:24 -05:00
parent 7e7eaf315b
commit 1f4bb70bac
8 changed files with 87 additions and 183 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/reference/gdk/Makefile.am
View File

@ -51,8 +51,7 @@ MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=gdk
# Extra SGML files that are included by DOC_MAIN_SGML_FILE # Extra SGML files that are included by DOC_MAIN_SGML_FILE
content_files = \ content_files = \
version.xml \ version.xml
multihead.sgml
# Images to copy into HTML directory # Images to copy into HTML directory
HTML_IMAGES = \ HTML_IMAGES = \

15
docs/reference/gdk/gdk-docs.sgml
View File

@ -8,21 +8,24 @@
<bookinfo> <bookinfo>
<title>GDK Reference Manual</title> <title>GDK Reference Manual</title>
<releaseinfo> <releaseinfo>
for GDK &version; This document is for the GDK 3 library, version &version;
The latest version of this documentation can be found on-line at The latest version can be found online at
<ulink role="online-location" url="http://library.gnome.org/devel/gdk/unstable/">http://library.gnome.org/devel/gdk/unstable/</ulink>. <ulink role="online-location" url="http://library.gnome.org/devel/gdk/unstable/">http://library.gnome.org/devel/gdk/unstable/</ulink>.
If you are looking for the older GDK 2 series of libraries,
they can be found under their version numbers; for example,
2.22 is available at
<ulink role="online-location" url="http://library.gnome.org/devel/gdk/2.22/">http://library.gnome.org/devel/gdk/2.22/</ulink>.
</releaseinfo> </releaseinfo>
</bookinfo> </bookinfo>
<reference id="reference"> <reference id="reference">
<title>API Reference</title> <title>API Reference</title>
<xi:include href="xml/general.xml" /> <xi:include href="xml/general.xml" />
<xi:include href="multihead.sgml" />
<xi:include href="xml/gdkdisplay.xml" />
<xi:include href="xml/gdkdisplaymanager.xml" /> <xi:include href="xml/gdkdisplaymanager.xml" />
<xi:include href="xml/gdkdevice.xml" /> <xi:include href="xml/gdkdisplay.xml" />
<xi:include href="xml/gdkdevicemanager.xml" />
<xi:include href="xml/gdkscreen.xml" /> <xi:include href="xml/gdkscreen.xml" />
<xi:include href="xml/gdkdevicemanager.xml" />
<xi:include href="xml/gdkdevice.xml" />
<xi:include href="xml/regions.xml" /> <xi:include href="xml/regions.xml" />
<xi:include href="xml/pixbufs.xml" /> <xi:include href="xml/pixbufs.xml" />
<xi:include href="xml/colors.xml" /> <xi:include href="xml/colors.xml" />

128
docs/reference/gdk/multihead.sgml
View File

@ -1,128 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<refentry id="multihead" revision="1 May 2002">
<refmeta>
<refentrytitle>Multi-head Support Overview</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Multi-head Support Overview</refname>
<refpurpose>Overview of GdkDisplay and GdkScreen</refpurpose>
</refnamediv>
<refsect1>
<title>Overview</title>
<para>
Multihead support is based around two main object types:
<itemizedlist>
<listitem><para>GdkDisplay</para></listitem>
<listitem><para>GdkScreen</para></listitem>
</itemizedlist>
</para>
<para>
<link linkend="gdk-GdkDisplay">GdkDisplay</link> objects are the GDK
representation of the X Display which can be described as <emphasis>a
workstation consisting of a keyboard a pointing device (such as a
mouse) and one or more screens</emphasis>.
It is used to open and keep track of various <link
linkend="gdk-GdkScreen">GdkScreen</link> objects currently
instanciated by the application. It is also used to grab and release
the keyboard and the mouse pointer.
</para>
<para>
<link linkend="gdk-GdkScreen">GdkScreen</link> objects are the GDK
representation of a physical screen. It is used throughout GDK and GTK+
to specify which screen the top level windows are to be displayed on.
It is also used to query the screen specification and default settings such as
the default colormap (<link linkend="gdk-screen-get-default-colormap">gdk_screen_get_default_colormap</link>()),
the screen width (<link linkend="gdk-screen-get-width">gdk_screen_get_width</link>()), etc.
</para>
<para>
The following code samples demonstrate common usage of the objects described above.
</para>
<example>
<title>Testing the number of screen on the current display</title>
<programlisting><!--
-->gint num_screen = 0;
gchar *displayname = NULL;
GdkScreen **screen_list;
GdkDisplay *display;
gtk_init (&amp;argc, &amp;argv);
display = gdk_display_get_default ();
num_screen = gdk_display_get_n_screens (display);
displayname = gdk_display_get_name (display);
if (num_screen &lt;= 1)
{
printf ("This Xserver (%s) manages only one screen. exiting...\n",
displayname);
exit (1);
}
else
{
printf ("This Xserver (%s) manages %d screens.\n", displayname,
num_screen);
}<!--
--> </programlisting>
</example>
<example>
<title>Opening a second display</title>
<programlisting><!--
-->gchar *second_screen_name;
GdkDisplay *second_display;
GdkScreen *second_screen;
GtkWidget *window;
gtk_init (&amp;argc, &amp;argv);
/* screen2_name needs to be initialized before calling
/* gdk_display_new() */
second_display = gdk_display_new (&amp;argc, &amp;argv, second_screen_name);
if (second_display)
second_screen = gdk_display_get_default_screen (second_display);
else
{
g_print ("Can't open display :\n\t%s\n\n",
second_screen_name);
exit (1);
}
/* now GdkScreen can be assigned to GtkWindows */
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_window_set_screen (window, second_screen);<!--
--></programlisting>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<variablelist>
<varlistentry>
<term><link linkend="GdkDisplay">GdkDisplay</link></term>
<listitem><para>the GDK Object used to represent and manipulate display
related data</para></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="GdkScreen">GdkScreen</link></term>
<listitem><para>the GDK Object used to represent and query screen related
data</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>
<!--
Local variables:
mode: sgml
sgml-parent-document: ("gdk-docs.sgml" "book" "refentry" "")
End:
-->

26
gdk/gdk.c
View File

@ -54,27 +54,7 @@
* The #GDK_WINDOWING_X11 macro is defined if the X11 backend * The #GDK_WINDOWING_X11 macro is defined if the X11 backend
* is supported. * is supported.
* *
* Use this macro to guard code that is specific to the X11-backend. * Use this macro to guard code that is specific to the X11 backend.
* Since GDK may be configured with multiple backends, an additional
* runtime check for the used backend is recommended:
*
* |[
* #ifdef GDK_WINDOWING_X11
* if (GDK_IS_X11_DISPLAY (display))
* {
* /&ast; make X11-specific calls here &ast;/
* }
* else
* #endif
* #ifdef GDK_WINDOWING_QUARTZ
* if (GDK_IS_QUARTZ_DISPLAY (display))
* {
* /&ast; make Quartz-specific calls here &ast/
* }
* else
* #endif
* g_error ("Unsupported GDK backend");
* ]|
*/ */
/** /**
@ -82,6 +62,8 @@
* *
* The #GDK_WINDOWING_WIN32 macro is defined if the Win32 backend * The #GDK_WINDOWING_WIN32 macro is defined if the Win32 backend
* is supported. * is supported.
*
* Use this macro to guard code that is specific to the Win32 backend.
*/ */
/** /**
@ -89,6 +71,8 @@
* *
* The #GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend * The #GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend
* is supported. * is supported.
*
* Use this macro to guard code that is specific to the Quartz backend.
*/ */
typedef struct _GdkPredicate GdkPredicate; typedef struct _GdkPredicate GdkPredicate;

4
gdk/gdkdevice.c
View File

@ -32,7 +32,8 @@
* @Title: GdkDevice * @Title: GdkDevice
* @See_also: #GdkDeviceManager * @See_also: #GdkDeviceManager
* *
* The #GdkDevice object represents a single input device. * The #GdkDevice object represents a single input device, such
* as a keyboard, a mouse, a touchpad, etc.
* *
* See the #GdkDeviceManager documentation for more information * See the #GdkDeviceManager documentation for more information
* about the various kinds of master and slave devices, and their * about the various kinds of master and slave devices, and their
@ -48,7 +49,6 @@ struct _GdkAxisInfo
gdouble min_axis; gdouble min_axis;
gdouble max_axis; gdouble max_axis;
gdouble min_value; gdouble min_value;
gdouble max_value; gdouble max_value;
gdouble resolution; gdouble resolution;

34
gdk/gdkdisplay.c
View File

@ -38,26 +38,32 @@
/** /**
* SECTION:gdkdisplay * SECTION:gdkdisplay
* @Short_description: Controls the keyboard/mouse pointer grabs and a set of <type>GdkScreen</type>s * @Short_description: Controls a set of GdkScreens and their associated input devices
* @Title: GdkDisplay * @Title: GdkDisplay
* *
* #GdkDisplay objects purpose are two fold: * #GdkDisplay objects purpose are two fold:
* <itemizedlist> * <itemizedlist>
* <listitem><para> * <listitem>
* To grab/ungrab keyboard focus and mouse pointer * To manage and provide information about input devices (pointers
* </para></listitem> * and keyboards)
* <listitem><para> * </listitem>
* To manage and provide information about the #GdkScreen(s) * <listitem>
* available for this #GdkDisplay * To manage and provide information about the available #GdkScreens
* </para></listitem> * </listitem>
* </itemizedlist> * </itemizedlist>
* *
* #GdkDisplay objects are the GDK representation of the X Display which can be * GdkDisplay objects are the GDK representation of an X Display,
* described as <emphasis>a workstation consisting of a keyboard a pointing * which can be described as <emphasis>a workstation consisting of
* device (such as a mouse) and one or more screens</emphasis>. * a keyboard, a pointing device (such as a mouse) and one or more
* It is used to open and keep track of various #GdkScreen objects currently * screens</emphasis>.
* instanciated by the application. It is also used to grab and release the keyboard * It is used to open and keep track of various GdkScreen objects
* and the mouse pointer. * currently instantiated by the application. It is also used to
* access the keyboard(s) and mouse pointer(s) of the display.
*
* Most of the input device handling has been factored out into
* the separate #GdkDeviceManager object. Every display has a
* device manager, which you can obtain using
* gdk_display_get_device_manager().
*/ */

43
gdk/gdkdisplaymanager.c
View File

@ -56,6 +56,43 @@
* The purpose of the #GdkDisplayManager singleton object is to offer * The purpose of the #GdkDisplayManager singleton object is to offer
* notification when displays appear or disappear or the default display * notification when displays appear or disappear or the default display
* changes. * changes.
*
* You can use gdk_display_manager_get() to obtain the GdkDisplayManager
* singleton, but that should be rarely necessary. Typically, initializing
* GTK+ opens a display that you can work with without ever accessing the
* GdkDisplayManager.
*
* The GDK library can be built with support for multiple backends.
* The GdkDisplayManager object determines which backend is used
* at runtime.
*
* When writing backend-specific code that is supposed to work with
* multiple GDK backends, you have to consider both compile time and
* runtime. At compile time, use the #GDK_WINDOWING_X11, #GDK_WINDOWING_WIN32
* macros, etc. to find out which backends are present in the GDK library
* you are building your application against. At runtime, use type-check
* macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:
*
* <example id="backend-specific">
* <title>Backend-specific code</title>
* <programlisting>
* #ifdef GDK_WINDOWING_X11
* if (GDK_IS_X11_DISPLAY (display))
* {
* /&ast; make X11-specific calls here &ast;/
* }
* else
* #endif
* #ifdef GDK_WINDOWING_QUARTZ
* if (GDK_IS_QUARTZ_DISPLAY (display))
* {
* /&ast; make Quartz-specific calls here &ast;/
* }
* else
* #endif
* g_error ("Unsupported GDK backend");
* </programlisting>
* </example>
*/ */
@ -168,9 +205,9 @@ gdk_display_manager_get_property (GObject *object,
* Gets the singleton #GdkDisplayManager object. * Gets the singleton #GdkDisplayManager object.
* *
* When called for the first time, this function consults the * When called for the first time, this function consults the
* <envar>GDK_BACKEND</envar> to find out which of the supported * <envar>GDK_BACKEND</envar> environment variable to find out which
* GDK backends to use (in case GDK has been compiled with multiple * of the supported GDK backends to use (in case GDK has been compiled
* backends). * with multiple backends).
* *
* Returns: (transfer none): The global #GdkDisplayManager singleton; * Returns: (transfer none): The global #GdkDisplayManager singleton;
* gdk_parse_args(), gdk_init(), or gdk_init_check() must have * gdk_parse_args(), gdk_init(), or gdk_init_check() must have

17
gdk/gdkscreen.c
View File

@ -34,14 +34,17 @@
* @Short_description: Object representing a physical screen * @Short_description: Object representing a physical screen
* @Title: GdkScreen * @Title: GdkScreen
* *
* #GdkScreen objects are the GDK representation of a physical screen. It is used * #GdkScreen objects are the GDK representation of the screen on
* throughout GDK and GTK+ to specify which screen the top level windows * which windows can be displayed and on which the pointer moves.
* are to be displayed on. * X originally identified screens with physical screens, but
* It is also used to query the screen specification and default settings such as * nowadays it is more common to have a single #GdkScreen which
* the screen width (gdk_screen_get_width()), etc. * combines several physical monitors (see gdk_screen_get_n_monitors()).
* *
* Note that a screen may consist of multiple monitors which are merged to * GdkScreen is used throughout GDK and GTK+ to specify which screen
* form a large screen area. * the top level windows are to be displayed on. it is also used to
* query the screen specification and default settings such as
* the default visual (gdk_screen_get_system_visual()), the dimensions
* of the physical monitors (gdk_screen_get_monitor_geometry()), etc.
*/ */