mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-12-25 05:01:09 +00:00
Give the GDK docs some love
Reorganize some sections, drop the largely redundant multihead section, add some more information about multiple backends.
This commit is contained in:
Matthias Clasen
parent
7e7eaf315b
commit
1f4bb70bac
@ -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
|
||||
content_files = \
|
||||
version.xml \
|
||||
multihead.sgml
|
||||
version.xml
|
||||
|
||||
# Images to copy into HTML directory
|
||||
HTML_IMAGES = \
|
||||
|
||||
@ -8,21 +8,24 @@
|
||||
<bookinfo>
|
||||
<title>GDK Reference Manual</title>
|
||||
<releaseinfo>
|
||||
for GDK &version;
|
||||
The latest version of this documentation can be found on-line at
|
||||
This document is for the GDK 3 library, version &version;
|
||||
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>.
|
||||
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>
|
||||
</bookinfo>
|
||||
|
||||
<reference id="reference">
|
||||
<title>API Reference</title>
|
||||
<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/gdkdevice.xml" />
|
||||
<xi:include href="xml/gdkdevicemanager.xml" />
|
||||
<xi:include href="xml/gdkdisplay.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/pixbufs.xml" />
|
||||
<xi:include href="xml/colors.xml" />
|
||||
|
||||
@ -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 (&argc, &argv);
|
||||
|
||||
display = gdk_display_get_default ();
|
||||
num_screen = gdk_display_get_n_screens (display);
|
||||
displayname = gdk_display_get_name (display);
|
||||
if (num_screen <= 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 (&argc, &argv);
|
||||
|
||||
/* screen2_name needs to be initialized before calling
|
||||
/* gdk_display_new() */
|
||||
second_display = gdk_display_new (&argc, &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
26
gdk/gdk.c
@ -54,27 +54,7 @@
|
||||
* The #GDK_WINDOWING_X11 macro is defined if the X11 backend
|
||||
* is supported.
|
||||
*
|
||||
* 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))
|
||||
* {
|
||||
* /* make X11-specific calls here */
|
||||
* }
|
||||
* else
|
||||
* #endif
|
||||
* #ifdef GDK_WINDOWING_QUARTZ
|
||||
* if (GDK_IS_QUARTZ_DISPLAY (display))
|
||||
* {
|
||||
* /* make Quartz-specific calls here &ast/
|
||||
* }
|
||||
* else
|
||||
* #endif
|
||||
* g_error ("Unsupported GDK backend");
|
||||
* ]|
|
||||
* Use this macro to guard code that is specific to the X11 backend.
|
||||
*/
|
||||
|
||||
/**
|
||||
@ -82,6 +62,8 @@
|
||||
*
|
||||
* The #GDK_WINDOWING_WIN32 macro is defined if the Win32 backend
|
||||
* 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
|
||||
* is supported.
|
||||
*
|
||||
* Use this macro to guard code that is specific to the Quartz backend.
|
||||
*/
|
||||
|
||||
typedef struct _GdkPredicate GdkPredicate;
|
||||
|
||||
@ -32,7 +32,8 @@
|
||||
* @Title: GdkDevice
|
||||
* @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
|
||||
* about the various kinds of master and slave devices, and their
|
||||
@ -48,7 +49,6 @@ struct _GdkAxisInfo
|
||||
|
||||
gdouble min_axis;
|
||||
gdouble max_axis;
|
||||
|
||||
gdouble min_value;
|
||||
gdouble max_value;
|
||||
gdouble resolution;
|
||||
|
||||
@ -38,26 +38,32 @@
|
||||
|
||||
/**
|
||||
* 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
|
||||
*
|
||||
* #GdkDisplay objects purpose are two fold:
|
||||
* <itemizedlist>
|
||||
* <listitem><para>
|
||||
* To grab/ungrab keyboard focus and mouse pointer
|
||||
* </para></listitem>
|
||||
* <listitem><para>
|
||||
* To manage and provide information about the #GdkScreen(s)
|
||||
* available for this #GdkDisplay
|
||||
* </para></listitem>
|
||||
* <listitem>
|
||||
* To manage and provide information about input devices (pointers
|
||||
* and keyboards)
|
||||
* </listitem>
|
||||
* <listitem>
|
||||
* To manage and provide information about the available #GdkScreens
|
||||
* </listitem>
|
||||
* </itemizedlist>
|
||||
*
|
||||
* #GdkDisplay 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 #GdkScreen objects currently
|
||||
* instanciated by the application. It is also used to grab and release the keyboard
|
||||
* and the mouse pointer.
|
||||
* GdkDisplay objects are the GDK representation of an 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 GdkScreen objects
|
||||
* 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().
|
||||
*/
|
||||
|
||||
|
||||
|
||||
@ -56,6 +56,43 @@
|
||||
* The purpose of the #GdkDisplayManager singleton object is to offer
|
||||
* notification when displays appear or disappear or the default display
|
||||
* 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))
|
||||
* {
|
||||
* /* make X11-specific calls here */
|
||||
* }
|
||||
* else
|
||||
* #endif
|
||||
* #ifdef GDK_WINDOWING_QUARTZ
|
||||
* if (GDK_IS_QUARTZ_DISPLAY (display))
|
||||
* {
|
||||
* /* make Quartz-specific calls here */
|
||||
* }
|
||||
* 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.
|
||||
*
|
||||
* When called for the first time, this function consults the
|
||||
* <envar>GDK_BACKEND</envar> to find out which of the supported
|
||||
* GDK backends to use (in case GDK has been compiled with multiple
|
||||
* backends).
|
||||
* <envar>GDK_BACKEND</envar> environment variable to find out which
|
||||
* of the supported GDK backends to use (in case GDK has been compiled
|
||||
* with multiple backends).
|
||||
*
|
||||
* Returns: (transfer none): The global #GdkDisplayManager singleton;
|
||||
* gdk_parse_args(), gdk_init(), or gdk_init_check() must have
|
||||
|
||||
@ -34,14 +34,17 @@
|
||||
* @Short_description: Object representing a physical screen
|
||||
* @Title: GdkScreen
|
||||
*
|
||||
* #GdkScreen 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 screen width (gdk_screen_get_width()), etc.
|
||||
* #GdkScreen objects are the GDK representation of the screen on
|
||||
* which windows can be displayed and on which the pointer moves.
|
||||
* X originally identified screens with physical screens, but
|
||||
* nowadays it is more common to have a single #GdkScreen which
|
||||
* combines several physical monitors (see gdk_screen_get_n_monitors()).
|
||||
*
|
||||
* Note that a screen may consist of multiple monitors which are merged to
|
||||
* form a large screen area.
|
||||
* GdkScreen 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 visual (gdk_screen_get_system_visual()), the dimensions
|
||||
* of the physical monitors (gdk_screen_get_monitor_geometry()), etc.
|
||||
*/
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user