[gtk/docs-gtk-org] gtk3: Add windowing system backend pages

[Emmanuele Bassi <ebassi src gnome org>]

commit 976510e561bdf0508b572bb5bd4034b6f951509a
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Aug 11 13:59:37 2021 +0100

    gtk3: Add windowing system backend pages

 gtk3/gtk/broadway.md  | 29 ++++++++++++++++
 gtk3/gtk/gtk3.toml.in |  6 ++++
 gtk3/gtk/macos.md     | 12 +++++++
 gtk3/gtk/meson.build  |  5 +++
 gtk3/gtk/wayland.md   | 13 ++++++++
 gtk3/gtk/windows.md   | 67 +++++++++++++++++++++++++++++++++++++
 gtk3/gtk/x11.md       | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 224 insertions(+)
---
diff --git a/gtk3/gtk/broadway.md b/gtk3/gtk/broadway.md
new file mode 100644
index 0000000000..86c220c506
--- /dev/null
+++ b/gtk3/gtk/broadway.md
@@ -0,0 +1,29 @@
+Title: Using GTK with Broadway
+
+The GDK Broadway backend provides support for displaying GTK applications in
+a web browser, using HTML5 and web sockets. To run your application in this
+way, select the Broadway backend by setting `GDK_BACKEND=broadway` in your
+environment. Then you can make your application appear in a web browser by
+pointing it at http://127.0.0.1:8080. Note that you need to enable web
+sockets in your web browser.
+
+You can choose a different port from the default 8080 by setting the
+`BROADWAY_DISPLAY` environment variable to the port that you want to use.
+
+It is also possible to use multiple GTK applications in the same web browser
+window, by using the Broadway server, `broadwayd`, that ships with GTK. To
+use `broadwayd`, start it like this:
+
+    broadwayd :5
+
+Then point your web browser at http://127.0.0.1:8085. Start your
+applications like this:
+
+    GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk3-demo
+
+## Broadway-specific environment variables
+
+`BROADWAY_DISPLAY`
+:  Specifies the Broadway display number. The default display is 0. The
+   display number determines the port to use when connecting to a Broadway
+   application via the following formula: `port = 8080 + display`
diff --git a/gtk3/gtk/gtk3.toml.in b/gtk3/gtk/gtk3.toml.in
index 6c31fcf98a..39e246c00a 100644
--- a/gtk3/gtk/gtk3.toml.in
+++ b/gtk3/gtk/gtk3.toml.in
@@ -42,6 +42,12 @@ base_url = "https://gitlab.gnome.org/GNOME/gtk/-/blob/gtk-3-24/";
 [extra]
 content_files = [
   "treeview-tutorial.md",
+
+  "x11.md",
+  "windows.md",
+  "wayland.md",
+  "macos.md",
+  "broadway.md",
 ]
 content_images = [
   "gtk-logo.svg",
diff --git a/gtk3/gtk/macos.md b/gtk3/gtk/macos.md
new file mode 100644
index 0000000000..af08fe5250
--- /dev/null
+++ b/gtk3/gtk/macos.md
@@ -0,0 +1,12 @@
+Title: Using GTK on macOS
+
+# Using GTK on macOS
+
+The macOS port of GTK is an implementation of GDK (and therefore GTK) on top
+of the Quarz API.
+
+Currently, the macOS port does not use any additional commandline options or
+environment variables.
+
+For up-to-date information about the current status of this port, see the
+[project page](https://wiki.gnome.org/Projects/GTK+/OSX).
diff --git a/gtk3/gtk/meson.build b/gtk3/gtk/meson.build
index f7ac90ecdd..4c99a982e3 100644
--- a/gtk3/gtk/meson.build
+++ b/gtk3/gtk/meson.build
@@ -1,5 +1,10 @@
 expand_content_files = [
+  'broadway.md',
+  'macos.md',
   'treeview-tutorial.md',
+  'wayland.md',
+  'windows.md',
+  'x11.md',
 ]
 
 gtk_gir = meson.current_source_dir() / 'Gtk-3.0.gir'
diff --git a/gtk3/gtk/wayland.md b/gtk3/gtk/wayland.md
new file mode 100644
index 0000000000..ab178b003d
--- /dev/null
+++ b/gtk3/gtk/wayland.md
@@ -0,0 +1,13 @@
+Title: Using GTK with Wayland
+
+# Using GTK with Wayland
+
+The GDK Wayland backend provides support for running GTK applications under
+the Wayland display server. To run your application in this way, select the
+Wayland backend by setting `GDK_BACKEND=wayland` in your environment.
+
+Currently, the Wayland backend does not use any additional commandline
+options or environment variables.
+
+For up-to-date information about the current status of this backend, see [the
+project page](https://wiki.gnome.org/Initiatives/Wayland/GTK%2B).
diff --git a/gtk3/gtk/windows.md b/gtk3/gtk/windows.md
new file mode 100644
index 0000000000..50a43c0e1b
--- /dev/null
+++ b/gtk3/gtk/windows.md
@@ -0,0 +1,67 @@
+Title: Using GTK on Windows
+
+# Using GTK on Windows
+
+The Windows port of GTK is an implementation of GDK (and therefore GTK) on
+top of the Win32 API. When compiling GTK on Windows, this backend is the
+default.
+
+## Windows-specific commandline options
+
+The Windows GDK backend can be influenced with some additional command line
+arguments.
+
+`--sync`
+: Don't batch GDI requests. This might be a marginally useful option for
+  debugging.
+
+`--no-wintab`, `--ignore-wintab`
+: Don't use the Wintab API for tablet support.
+
+`--use-wintab`
+: Use the Wintab API for tablet support. *This is the default*.
+
+`--max-colors number`
+: In 256 color mode, restrict the size of the color palette to the specified
+  number of colors. *This option is obsolete*.
+
+## Windows-specific environment variables
+
+The Win32 GDK backend can be influenced with some additional environment
+variables.
+
+`GDK_IGNORE_WINTAB`
+: If this variable is set, GTK doesn't use the Wintab API for tablet support.
+
+`GDK_USE_WINTAB`
+: If this variable is set, GTK uses the Wintab API for tablet support. *This
+  is the default*.
+
+`GDK_WIN32_MAX_COLORS`
+: Specifies the size of the color palette used in 256 color mode.
+
+## Windows-specific handling of cursors
+
+By default the "system" cursor theme is used. This makes GTK prefer cursors
+that Windows currently uses, falling back to Adwaita cursors and (as the
+last resort) built-in X cursors.
+
+When any other cursor theme is used, GTK will prefer cursors from that
+theme, falling back to Windows cursors and built-in X cursors.
+
+Theme can be changed by setting the `gtk-cursor-theme-name` GTK setting.
+Users can override GTK settings in the `settings.ini` file or at runtime in
+the GTK Inspector.
+
+Themes are loaded from normal Windows variants of the XDG locations:
+
+- `HOME/icons/THEME/cursors`
+- `APPDATA/icons/THEME/cursors`
+- `RUNTIME_PREFIX/share/icons/THEME/cursors`
+
+The `gtk-cursor-theme-size` GTK setting is ignored, GTK will use the cursor
+size that Windows tells it to use.
+
+More information about GTK on Windows, including detailed build
+instructions, binary downloads, etc, can be found
+[online](https://wiki.gnome.org/Projects/GTK+/Win32).
diff --git a/gtk3/gtk/x11.md b/gtk3/gtk/x11.md
new file mode 100644
index 0000000000..8df5a32469
--- /dev/null
+++ b/gtk3/gtk/x11.md
@@ -0,0 +1,92 @@
+Title: Using GTK on the X11 Window System
+
+# Using GTK on the X11 Windows System
+
+On UNIX, the X11 backend is the default build for GTK. So you don't need to
+do anything special when compiling it, and everything should "just work."
+
+To mix low-level Xlib routines into a GTK program, see *GDK X Window System
+interaction* in [the GDK manual](https://docs.gtk.org/gdk3/).
+
+GTK includes an cross-process embedding facility in the form of the
+`GtkSocket` and `GtkPlug` widgets. These are X11-specific, and you have to
+include the `gtk/gtkx.h` header to use them.
+
+## X11-specific commandline options
+
+The X backend understands some additional command line arguments.
+
+`--display=DISPLAY`
+: The name of the X display to open instead of the one specified in the
+  `DISPLAY` environment variable.
+
+## X11-specific environment variables
+
+The X11 GDK backend can be influenced with some additional environment
+variables.
+
+`GDK_SYNCHRONIZE`
+: If set, GDK makes all X requests synchronously. This is a useful option for
+  debugging, but it will slow down the performance considerably.
+
+`GDK_CORE_DEVICE_EVENTS`
+: If set, GDK makes does not use the XInput extension, and only reacts to core
+  X input events.
+
+`GDK_SCALE`
+: Must be set to an integer, typically 2. If set, GDK will scale all windows
+  by the specified factor. Scaled output is meant to be used on HiDPI displays.
+  Normally, GDK will pick up a suitable scale factor for each monitor from the
+  display system. This environment variable allows to override that.
+
+`GDK_DPI_SCALE`
+: This can be useful when using scale-aware GTK applications together with
+  scale-unaware applications on a HiDPI display. In that case, the font
+  resolution can be doubled to make scale-unaware applications readable, and
+  `GDK_DPI_SCALE=0.5` can be set to compensate for that in GTK applications
+  which are already scaled by setting `GDK_SCALE=2`.
+
+## Understanding the X11 architecture
+
+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 *Xlib Programming Manual* by Adrian Nye; this book is volume one in
+the O'Reilly X Window System series.
+
+Standards are another important resource if you're poking in low-level X11
+details, in particular the
+[ICCCM](https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html)
+and the [Extended Window Manager
+Hints](https://specifications.freedesktop.org/wm-spec/latest/)
+specifications. The [freedesktop.org](https://freedesktop.org) website has
+links to many relevant specifications.
+
+The [GDK manual](https://docs.gtk.org/gdk3/) covers using Xlib in a GTK
+program.
+
+## Server, client, window manager
+
+Other window systems typically put all their functionality in the
+application itself. With X, each application involves three different
+programs: the X server, the application (called a client because it's a
+client of the X server), and a special client called the window manager.
+
+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.
+
+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 convention.
+
+GTK has functions for asking the window manager to do various things; see
+for example `gtk_window_iconify()` or `gtk_window_maximize()` or
+`gtk_window_set_decorated()`. Keep in mind that `gtk_window_move()` and window
+sizing are ultimately controlled by the window manager as well and most
+window managers will ignore certain requests from time to time, in the
+interests of good user interface.