diff --git a/docs/reference/gdk/Makefile.am b/docs/reference/gdk/Makefile.am index 6eeffdb0d7..8a70de8c1a 100644 --- a/docs/reference/gdk/Makefile.am +++ b/docs/reference/gdk/Makefile.am @@ -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 = \ diff --git a/docs/reference/gdk/gdk-docs.sgml b/docs/reference/gdk/gdk-docs.sgml index 7be666074f..765d26cc42 100644 --- a/docs/reference/gdk/gdk-docs.sgml +++ b/docs/reference/gdk/gdk-docs.sgml @@ -8,21 +8,24 @@ GDK Reference Manual - 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 http://library.gnome.org/devel/gdk/unstable/. + 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 + http://library.gnome.org/devel/gdk/2.22/. API Reference - - - - + + + diff --git a/docs/reference/gdk/multihead.sgml b/docs/reference/gdk/multihead.sgml deleted file mode 100644 index 89c52cc201..0000000000 --- a/docs/reference/gdk/multihead.sgml +++ /dev/null @@ -1,128 +0,0 @@ - - - - - Multi-head Support Overview - 3 - GDK Library - - - - Multi-head Support Overview - Overview of GdkDisplay and GdkScreen - - - - Overview - - Multihead support is based around two main object types: - - GdkDisplay - GdkScreen - - - - - GdkDisplay objects are the GDK - representation of the X Display which can be described as a - workstation consisting of a keyboard a pointing device (such as a - mouse) and one or more screens. - 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. - - - 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 default colormap (gdk_screen_get_default_colormap()), - the screen width (gdk_screen_get_width()), etc. - - - The following code samples demonstrate common usage of the objects described above. - - - - Testing the number of screen on the current display - 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); - } - - - Opening a second display - 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); - - - - See Also - - - - GdkDisplay - the GDK Object used to represent and manipulate display - related data - - - GdkScreen - the GDK Object used to represent and query screen related - data - - - - - - - diff --git a/gdk/gdk.c b/gdk/gdk.c index 5182d72e2f..e65f68b3f3 100644 --- a/gdk/gdk.c +++ b/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; diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c index 2cc3ea88c9..8106bea510 100644 --- a/gdk/gdkdevice.c +++ b/gdk/gdkdevice.c @@ -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; diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c index ad520b6554..f3c4f0e778 100644 --- a/gdk/gdkdisplay.c +++ b/gdk/gdkdisplay.c @@ -38,26 +38,32 @@ /** * SECTION:gdkdisplay - * @Short_description: Controls the keyboard/mouse pointer grabs and a set of GdkScreens + * @Short_description: Controls a set of GdkScreens and their associated input devices * @Title: GdkDisplay * * #GdkDisplay objects purpose are two fold: * - * - * To grab/ungrab keyboard focus and mouse pointer - * - * - * To manage and provide information about the #GdkScreen(s) - * available for this #GdkDisplay - * + * + * To manage and provide information about input devices (pointers + * and keyboards) + * + * + * To manage and provide information about the available #GdkScreens + * * * - * #GdkDisplay objects are the GDK representation of the X Display which can be - * described as a workstation consisting of a keyboard a pointing - * device (such as a mouse) and one or more screens. - * 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 a workstation consisting of + * a keyboard, a pointing device (such as a mouse) and one or more + * screens. + * 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(). */ diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c index 160404d75c..508d60910b 100644 --- a/gdk/gdkdisplaymanager.c +++ b/gdk/gdkdisplaymanager.c @@ -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: + * + * + * Backend-specific code + * + * #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"); + * + * */ @@ -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 - * GDK_BACKEND to find out which of the supported - * GDK backends to use (in case GDK has been compiled with multiple - * backends). + * GDK_BACKEND 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 diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c index 4dd9164a85..ebdf2c64d9 100644 --- a/gdk/gdkscreen.c +++ b/gdk/gdkscreen.c @@ -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. */