--- /dev/null
+<refentry id="gtk-x11" revision="17 Jan 2002">
+<refmeta>
+<refentrytitle>Using GTK+ on the X Window System</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Using GTK+ on the X Window System</refname>
+<refpurpose>
+X11 aspects of using GTK+
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>GTK+ for the X Window System</title>
+
+<para>
+On UNIX, the X backend is the default build for GTK+. So
+you don't need to do anything special when compiling it,
+and everything should "just work."
+</para>
+
+<para>
+To mix low-level Xlib routines into a GTK program,
+see <link linkend="gdk-X-Window-System-Interaction">GDK X Window
+System interaction</link> in the GDK manual.
+</para>
+
+</refsect1>
+
+<refsect1 id="gtk-X11-arch">
+<title>Understanding the X11 architecture</title>
+
+<para>
+People coming from a Windows or MacOS background often find certain
+aspects of the X Window System surprising. This section introduces
+some basic X concepts at a high level. For more details, the book most
+people use is called the <citetitle pubwork="book">Xlib Programming
+Manual</citetitle> by Adrian Nye; this book is volume one in the
+O'Reilly X Window System series.
+</para>
+<para>
+Standards are another important resource if you're poking in low-level
+X11 details, in particular the ICCCM and the Extended Window Manager
+Hints specifications. <ulink
+url="http://www.freedesktop.org/standards/">freedesktop.org</ulink>
+has links to many relevant specifications.
+</para>
+<para>
+The GDK manual covers <link
+linkend="gdk-X-Window-System-Interaction">using Xlib in a GTK
+program</link>.
+</para>
+
+<refsect2>
+<title>Server, client, window manager</title>
+
+<para>
+Other window systems typically put all their functionality in the
+application itself. With X, each application involves three different
+programs: the <firstterm>X server</firstterm>, the application (called
+a <firstterm>client</firstterm> because it's a client of the X
+server), and a special client called the <firstterm>window
+manager</firstterm>.
+</para>
+
+<para>
+The X server is in charge of managing resources, processing drawing
+requests, and dispatching events such as keyboard and mouse events to
+interested applications. So client applications can ask the X server
+to create a window, draw a circle, or move windows around.
+</para>
+
+<para>
+The window manager is in charge of rendering the frame or borders
+around windows; it also has final say on the size of each window,
+and window states such as minimized, maximized, and so forth.
+On Windows and MacOS the application handles most of this.
+On X11, if you wish to modify the window's state, or
+change its frame, you must ask the window manager to do so on your
+behalf, using an established <ulink
+url="http://www.freedesktop.org/standards/">convention</ulink>.
+</para>
+
+<para>
+GTK+ has functions for asking the window manager to do various things;
+see for example <link
+linkend="gtk-window-iconify">gtk_window_iconify()</link> or <link
+linkend="gtk-window-maximize">gtk_window_maximize()</link> or <link
+linkend="gtk-window-set-decorated">gtk_window_set_decorated()</link>.
+Keep in mind that <link
+linkend="gtk-window-move">gtk_window_move()</link> and window sizing
+are ultimately controlled by the window manager as well and most
+window managers <emphasis>will</emphasis> ignore certain requests from
+time to time, in the interests of good user interface.
+</para>
+
+</refsect2>
+
+</refsect1>
+
+</refentry>
* you might use #GTK_WINDOW_POPUP. #GTK_WINDOW_POPUP is not for
* dialogs, though in some other toolkits dialogs are called "popups".
* In GTK+, #GTK_WINDOW_POPUP means a pop-up menu or pop-up tooltip.
- * Popup windows are not controlled by the window manager.
+ * On X11, popup windows are not controlled by the <link
+ * linkend="gtk-X11-arch">window manager</link>.
*
* If you simply want an undecorated window (no window borders), use
* gtk_window_set_decorated(), don't use #GTK_WINDOW_POPUP.
* @window: a #GtkWindow
* @title: title of the window
*
- * Sets the title of the #GtkWindow. The title of a window will be displayed in
- * its title bar; on the X Window System, the title bar is rendered by the
- * window manager, so exactly how the title appears to users may vary according
- * to a user's exact configuration. The title should help a user distinguish
- * this window from other windows they may have open. A good title might
- * include the application name and current document filename, for example.
+ * Sets the title of the #GtkWindow. The title of a window will be
+ * displayed in its title bar; on the X Window System, the title bar
+ * is rendered by the <link linkend="gtk-X11-arch">window
+ * manager</link>, so exactly how the title appears to users may vary
+ * according to a user's exact configuration. The title should help a
+ * user distinguish this window from other windows they may have
+ * open. A good title might include the application name and current
+ * document filename, for example.
*
**/
void
* @window: a #GtkWindow
* @role: unique identifier for the window to be used when restoring a session
*
+ * This function is only useful on X11, not with other GTK+ targets.
+ *
* In combination with the window title, the window role allows a
- * window manager to identify "the same" window when an application is
- * restarted. So for example you might set the "toolbox" role on your
- * app's toolbox window, so that when the user restarts their session,
- * the window manager can put the toolbox back in the same place.
+ * <link linkend="gtk-X11-arch">window manager</link> to identify "the
+ * same" window when an application is restarted. So for example you
+ * might set the "toolbox" role on your app's toolbox window, so that
+ * when the user restarts their session, the window manager can put
+ * the toolbox back in the same place.
*
* If a window already has a unique title, you don't need to set the
* role, since the WM can use the title to identify the window when
* with other windows in the same application. To keep modal dialogs
* on top of main application windows, use
* gtk_window_set_transient_for() to make the dialog transient for the
- * parent; most window managers will then disallow lowering the dialog
- * below the parent.
+ * parent; most <link linkend="gtk-X11-arch">window managers</link>
+ * will then disallow lowering the dialog below the parent.
*
*
**/
* @parent: parent window
*
* Dialog windows should be set transient for the main application
- * window they were spawned from. This allows window managers to
- * e.g. keep the dialog on top of the main window, or center the
- * dialog over the main window. gtk_dialog_new_with_buttons() and
- * other convenience functions in GTK+ will sometimes call
+ * window they were spawned from. This allows <link
+ * linkend="gtk-X11-arch">window managers</link> to e.g. keep the
+ * dialog on top of the main window, or center the dialog over the
+ * main window. gtk_dialog_new_with_buttons() and other convenience
+ * functions in GTK+ will sometimes call
* gtk_window_set_transient_for() on your behalf.
+ *
+ * On Windows, this function will and put the child window
+ * on top of the parent, much as the window manager would have
+ * done on X.
*
**/
void
* @setting: %TRUE to decorate the window
*
* By default, windows are decorated with a title bar, resize
- * controls, etc. Some window managers allow GTK+ to disable these
- * decorations, creating a borderless window. If you set the decorated
- * property to %FALSE using this function, GTK+ will do its best to
- * convince the window manager not to decorate the window.
+ * controls, etc. Some <link linkend="gtk-X11-arch">window
+ * managers</link> allow GTK+ to disable these decorations, creating a
+ * borderless window. If you set the decorated property to %FALSE
+ * using this function, GTK+ will do its best to convince the window
+ * manager not to decorate the window.
+ *
+ * On Windows, this function always works, since there's no window manager
+ * policy involved.
*
**/
void
* @width: return location for width, or %NULL
* @height: return location for height, or %NULL
*
- * Obtains the current size of @window. If @window is not onscreen,
- * it returns the size GTK+ will suggest to the window manager for the
- * initial window size (but this is not reliably the same as the size
- * the window manager will actually select). The size obtained by
+ * Obtains the current size of @window. If @window is not onscreen, it
+ * returns the size GTK+ will suggest to the <link
+ * linkend="gtk-X11-arch">window manager</link> for the initial window
+ * size (but this is not reliably the same as the size the window
+ * manager will actually select). The size obtained by
* gtk_window_get_size() is the last size received in a
* #GdkEventConfigure, that is, GTK+ uses its locally-stored size,
* rather than querying the X server for the size. As a result, if you
* application cannot.
*
* In any case, if you insist on application-specified window
- * positioning, there's <emphasis>still</emphasis> a better way than doing it yourself -
- * gtk_window_set_position() will frequently handle the details
- * for you.
+ * positioning, there's <emphasis>still</emphasis> a better way than
+ * doing it yourself - gtk_window_set_position() will frequently
+ * handle the details for you.
*
**/
void
* @x: X coordinate to move window to
* @y: Y coordinate to move window to
*
- * Asks the window manager to move @window to the given position.
- * Window managers are free to ignore this; most window managers
- * ignore requests for initial window positions (instead using a
- * user-defined placement algorithm) and honor requests after the
- * window has already been shown.
+ * Asks the <link linkend="gtk-X11-arch">window manager</link> to move
+ * @window to the given position. Window managers are free to ignore
+ * this; most window managers ignore requests for initial window
+ * positions (instead using a user-defined placement algorithm) and
+ * honor requests after the window has already been shown.
*
* Note: the position is the position of the gravity-determined
* reference point for the window. The gravity determines two things:
* Thus GTK+ is using a "best guess" that works with most
* window managers.
*
- * Moreover, nearly all window managers are broken with respect to
- * their handling of window gravity. So moving a window to its current
- * position as returned by gtk_window_get_position() tends to
- * result in moving the window slightly.
+ * Moreover, nearly all window managers are historically broken with
+ * respect to their handling of window gravity. So moving a window to
+ * its current position as returned by gtk_window_get_position() tends
+ * to result in moving the window slightly. Window managers are
+ * slowly getting better over time.
*
* If a window has gravity #GDK_GRAVITY_STATIC the window manager
* frame is not relevant, and thus gtk_window_get_position() will
* gtk_window_iconify:
* @window: a #GtkWindow
*
- * Asks to iconify (i.e. minimize) the specified @window. Note that you
- * shouldn't assume the window is definitely iconified afterward,
- * because other entities (e.g. the user or window manager) could
- * deiconify it again, or there may not be a window manager in which
- * case iconification isn't possible, etc. But normally the window
- * will end up iconified. Just don't write code that crashes if not.
+ * Asks to iconify (i.e. minimize) the specified @window. Note that
+ * you shouldn't assume the window is definitely iconified afterward,
+ * because other entities (e.g. the user or <link
+ * linkend="gtk-X11-arch">window manager</link>) could deiconify it
+ * again, or there may not be a window manager in which case
+ * iconification isn't possible, etc. But normally the window will end
+ * up iconified. Just don't write code that crashes if not.
*
* It's permitted to call this function before showing a window,
* in which case the window will be iconified before it ever appears
*
* Asks to deiconify (i.e. unminimize) the specified @window. Note
* that you shouldn't assume the window is definitely deiconified
- * afterward, because other entities (e.g. the user or window manager)
- * could iconify it again before your code which assumes
- * deiconification gets to run.
+ * afterward, because other entities (e.g. the user or <link
+ * linkend="gtk-X11-arch">window manager</link>) could iconify it
+ * again before your code which assumes deiconification gets to run.
*
* You can track iconification via the "window_state_event" signal
* on #GtkWidget.
*
* Asks to stick @window, which means that it will appear on all user
* desktops. Note that you shouldn't assume the window is definitely
- * stuck afterward, because other entities (e.g. the user or window
- * manager) could unstick it again, and some window managers do not
- * support sticking windows. But normally the window will end up
- * stuck. Just don't write code that crashes if not.
+ * stuck afterward, because other entities (e.g. the user or <link
+ * linkend="gtk-X11-arch">window manager</link>) could unstick it
+ * again, and some window managers do not support sticking
+ * windows. But normally the window will end up stuck. Just don't
+ * write code that crashes if not.
*
* It's permitted to call this function before showing a window.
*
* Asks to unstick @window, which means that it will appear on only
* one of the user's desktops. Note that you shouldn't assume the
* window is definitely unstuck afterward, because other entities
- * (e.g. the user or window manager) could stick it again. But
- * normally the window will end up stuck. Just don't write code that
- * crashes if not.
+ * (e.g. the user or <link linkend="gtk-X11-arch">window
+ * manager</link>) could stick it again. But normally the window will
+ * end up stuck. Just don't write code that crashes if not.
*
* You can track stickiness via the "window_state_event" signal
* on #GtkWidget.
*
* Asks to maximize @window, so that it becomes full-screen. Note that
* you shouldn't assume the window is definitely maximized afterward,
- * because other entities (e.g. the user or window manager) could
- * unmaximize it again, and not all window managers support
- * maximization. But normally the window will end up maximized. Just
- * don't write code that crashes if not.
+ * because other entities (e.g. the user or <link
+ * linkend="gtk-X11-arch">window manager</link>) could unmaximize it
+ * again, and not all window managers support maximization. But
+ * normally the window will end up maximized. Just don't write code
+ * that crashes if not.
*
* It's permitted to call this function before showing a window,
* in which case the window will be maximized when it appears onscreen
*
* Asks to unmaximize @window. Note that you shouldn't assume the
* window is definitely unmaximized afterward, because other entities
- * (e.g. the user or window manager) could maximize it again, and not
- * all window managers honor requests to unmaximize. But normally the
- * window will end up unmaximized. Just don't write code that crashes
- * if not.
+ * (e.g. the user or <link linkend="gtk-X11-arch">window
+ * manager</link>) could maximize it again, and not all window
+ * managers honor requests to unmaximize. But normally the window will
+ * end up unmaximized. Just don't write code that crashes if not.
*
* You can track maximization via the "window_state_event" signal
* on #GtkWidget.
*
* Starts resizing a window. This function is used if an application
* has window resizing controls. When GDK can support it, the resize
- * will be done using the standard mechanism for the window manager or
- * windowing system. Otherwise, GDK will try to emulate window
- * resizing, potentially not all that well, depending on the windowing system.
+ * will be done using the standard mechanism for the <link
+ * linkend="gtk-X11-arch">window manager</link> or windowing
+ * system. Otherwise, GDK will try to emulate window resizing,
+ * potentially not all that well, depending on the windowing system.
*
**/
void
*
* (Note: this is a special-purpose function intended for the
* framebuffer port; see gtk_window_set_has_frame(). It will not
- * return the size of the window border drawn by the window manager,
- * which is the normal case when using a windowing system.
- * See gdk_window_get_frame_extents() to get the standard
- * window border extents.)
+ * return the size of the window border drawn by the <link
+ * linkend="gtk-X11-arch">window manager</link>, which is the normal
+ * case when using a windowing system. See
+ * gdk_window_get_frame_extents() to get the standard window border
+ * extents.)
*
* Retrieves the dimensions of the frame window for this toplevel.
* See gtk_window_set_has_frame(), gtk_window_set_frame_dimensions().
* @root_y: Y position where the user clicked to initiate the drag
* @timestamp: timestamp from the click event that initiated the drag
*
- * Starts moving a window. This function is used if an application
- * has window movement grips. When GDK can support it, the window movement
- * will be done using the standard mechanism for the window manager or
- * windowing system. Otherwise, GDK will try to emulate window
- * movement, potentially not all that well, depending on the windowing system.
+ * Starts moving a window. This function is used if an application has
+ * window movement grips. When GDK can support it, the window movement
+ * will be done using the standard mechanism for the <link
+ * linkend="gtk-X11-arch">window manager</link> or windowing
+ * system. Otherwise, GDK will try to emulate window movement,
+ * potentially not all that well, depending on the windowing system.
*
**/
void
projects / ~andy / gtk / commitdiff