From 29fb9ae2d67683f9373629aa0b815192d7621797 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 24 May 2020 10:55:02 -0400 Subject: [PATCH] docs: Convert platform sections to markdown --- docs/reference/gtk/broadway.md | 36 +++++++++ docs/reference/gtk/broadway.xml | 71 ----------------- docs/reference/gtk/meson.build | 10 +-- docs/reference/gtk/osx.md | 10 +++ docs/reference/gtk/osx.xml | 39 ---------- docs/reference/gtk/wayland.md | 10 +++ docs/reference/gtk/wayland.xml | 39 ---------- docs/reference/gtk/windows.md | 46 +++++++++++ docs/reference/gtk/windows.xml | 93 ---------------------- docs/reference/gtk/x11.md | 66 ++++++++++++++++ docs/reference/gtk/x11.xml | 132 -------------------------------- 11 files changed, 173 insertions(+), 379 deletions(-) create mode 100644 docs/reference/gtk/broadway.md delete mode 100644 docs/reference/gtk/broadway.xml create mode 100644 docs/reference/gtk/osx.md delete mode 100644 docs/reference/gtk/osx.xml create mode 100644 docs/reference/gtk/wayland.md delete mode 100644 docs/reference/gtk/wayland.xml create mode 100644 docs/reference/gtk/windows.md delete mode 100644 docs/reference/gtk/windows.xml create mode 100644 docs/reference/gtk/x11.md delete mode 100644 docs/reference/gtk/x11.xml diff --git a/docs/reference/gtk/broadway.md b/docs/reference/gtk/broadway.md new file mode 100644 index 0000000000..53d6d3d334 --- /dev/null +++ b/docs/reference/gtk/broadway.md @@ -0,0 +1,36 @@ +# Using GTK with Broadway {#gtk-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`. 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 gtk4-demo +``` + +## Broadway-specific environment variables {#broadway-envar} + +### 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/docs/reference/gtk/broadway.xml b/docs/reference/gtk/broadway.xml deleted file mode 100644 index 4195e0e4ec..0000000000 --- a/docs/reference/gtk/broadway.xml +++ /dev/null @@ -1,71 +0,0 @@ - - - - -Using GTK with Broadway -3 -GTK Library - - - -Using GTK with Broadway - -HTML-specific aspects of using GTK - - - - -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. 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 gtk4-demo - - - - -Broadway-specific environment variables - - - - <envar>BROADWAY_DISPLAY</envar> - - - 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/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build index c3535b1e21..536d5a90f6 100644 --- a/docs/reference/gtk/meson.build +++ b/docs/reference/gtk/meson.build @@ -340,7 +340,6 @@ images = [ ] content_files = [ - 'broadway.xml', 'glossary.xml', 'gtk4-broadwayd.xml', 'gtk4-builder-tool.xml', @@ -352,7 +351,6 @@ content_files = [ 'gtk4-query-settings.xml', 'gtk4-update-icon-cache.xml', 'gtk4-widget-factory.xml', - 'osx.xml', 'other_software.xml', 'overview.xml', 'question_index.xml', @@ -360,9 +358,6 @@ content_files = [ 'text_widget.xml', 'tree_widget.xml', 'visual_index.xml', - 'wayland.xml', - 'windows.xml', - 'x11.xml', ] expand_content_files = [ @@ -373,6 +368,11 @@ expand_content_files = [ ] expand_content_md_files = [ + 'broadway.md', + 'osx.md', + 'wayland.md', + 'windows.md', + 'x11.md', 'getting_started.md', 'building.md', 'compiling.md', diff --git a/docs/reference/gtk/osx.md b/docs/reference/gtk/osx.md new file mode 100644 index 0000000000..2ee5c02bb1 --- /dev/null +++ b/docs/reference/gtk/osx.md @@ -0,0 +1,10 @@ +# Using GTK on Apple macOS {#gtk-osx} + +The Apple macOS port of GTK is an implementation of GDK (and therefore GTK) +on top of the Quartz 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/docs/reference/gtk/osx.xml b/docs/reference/gtk/osx.xml deleted file mode 100644 index 306f5fe6f3..0000000000 --- a/docs/reference/gtk/osx.xml +++ /dev/null @@ -1,39 +0,0 @@ - - - - -Using GTK on Apple macOS -3 -GTK Library - - - -Using GTK on Apple macOS - -MacOS-specific aspects of using GTK - - - - -Using GTK on Apple macOS - - -The Apple macOS port of GTK is an implementation of GDK (and therefore GTK) -on top of the Quartz 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. - - - - - diff --git a/docs/reference/gtk/wayland.md b/docs/reference/gtk/wayland.md new file mode 100644 index 0000000000..7c3f708cfe --- /dev/null +++ b/docs/reference/gtk/wayland.md @@ -0,0 +1,10 @@ +# Using GTK with Wayland {#gtk-wayland} + +The GDK Wayland backend provides support for running GTK applications +under a Wayland compositor. To run your application in this way, select +the Wayland backend by setting `GDK_BACKEND=wayland`. + +On UNIX, the Wayland backend is enabled by default, so you don't need to +do anything special when compiling it, and everything should "just work." + +Currently, the Wayland backend does not use any additional environment variables. diff --git a/docs/reference/gtk/wayland.xml b/docs/reference/gtk/wayland.xml deleted file mode 100644 index 7d38342ebd..0000000000 --- a/docs/reference/gtk/wayland.xml +++ /dev/null @@ -1,39 +0,0 @@ - - - - -Using GTK with Wayland -3 -GTK Library - - - -Using GTK with Wayland - -Wayland-specific aspects of using GTK - - - - -Using GTK with Wayland - - -The GDK Wayland backend provides support for running GTK applications -under a Wayland compositor. To run your application in this way, select -the Wayland backend by setting GDK_BACKEND=wayland. - - - -On UNIX, the Wayland backend is enabled by default, so you don't need to -do anything special when compiling it, and everything should "just work." - - - -Currently, the Wayland backend does not use any additional environment variables. - - - - - diff --git a/docs/reference/gtk/windows.md b/docs/reference/gtk/windows.md new file mode 100644 index 0000000000..b432175094 --- /dev/null +++ b/docs/reference/gtk/windows.md @@ -0,0 +1,46 @@ +# Using GTK on Windows {#gtk-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. + +More information about GTK on Windows, including detailed build +instructions, binary downloads, etc, can be found +[online](https://wiki.gnome.org/Projects/GTK/Win32). + +## Windows-specific environment variables {#win32-envar} + +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. + +## Windows-specific handling of cursors {#win32-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 `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`> setting is ignored, GTK will use +the cursor size that Windows tells it to use. + diff --git a/docs/reference/gtk/windows.xml b/docs/reference/gtk/windows.xml deleted file mode 100644 index ca25b9c892..0000000000 --- a/docs/reference/gtk/windows.xml +++ /dev/null @@ -1,93 +0,0 @@ - - - - -Using GTK on Windows -3 -GTK Library - - - -Using GTK on Windows - -Windows-specific aspects of using GTK - - - - -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 environment variables - - -The Win32 GDK backend can be influenced with some additional environment -variables. - - - -<envar>GDK_IGNORE_WINTAB</envar> - - -If this variable is set, GTK doesn't use the Wintab API for tablet support. - - - - -<envar>GDK_USE_WINTAB</envar> - - -If this variable is set, GTK uses the Wintab API for tablet support. -This is the default. - - - - - - -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 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 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. - - - - - diff --git a/docs/reference/gtk/x11.md b/docs/reference/gtk/x11.md new file mode 100644 index 0000000000..be2b74dc8e --- /dev/null +++ b/docs/reference/gtk/x11.md @@ -0,0 +1,66 @@ +# GTK for the X Window System {#gtk-x11} + +On UNIX, the X backend is enabled by default, 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](#gdk-X-Window-System-Interaction) +in the GDK manual. + +## X11-specific environment variables {#x11-envar} +: +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_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 +high-dpi displays. Normally, GDK will pick up a suitable scale factor +for each monitor from the display system. This environment variable +allows to override that. + +## Understanding the X11 architecture {#gtk-X11-arch} + +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 and the Extended Window Manager +Hints specifications. [freedesktop.org](http://www.freedesktop.org/standards/) +has links to many relevant specifications. + +The GDK manual covers [using Xlib in a GTK program](#gdk-X-Window-System-Interaction). + +### 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](http://www.freedesktop.org/standards/). + +GTK has functions for asking the window manager to do various things; +see for example gtk_window_minimize() or gtk_window_maximize(). +Keep in mind that most window managers *will* ignore certain requests +from time to time, in the interests of good user interface. diff --git a/docs/reference/gtk/x11.xml b/docs/reference/gtk/x11.xml deleted file mode 100644 index c2f73e444f..0000000000 --- a/docs/reference/gtk/x11.xml +++ /dev/null @@ -1,132 +0,0 @@ - - - - -Using GTK on the X Window System -3 -GTK Library - - - -Using GTK on the X Window System - -X11-specific aspects of using GTK - - - - -GTK for the X Window System - - -On UNIX, the X backend is enabled by default, 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. - - - -X11-specific environment variables - - -The X11 GDK backend can be influenced with some additional environment variables. - - - - <envar>GDK_SYNCHRONIZE</envar> - - - If set, GDK makes all X requests synchronously. This is a useful - option for debugging, but it will slow down the performance considerably. - - - - - <envar>GDK_SCALE</envar> - - - 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 - high-dpi displays. Normally, GDK will pick up a suitable scale factor - for each monitor from the display system. This environment variable - allows to override that. - - - - - - - - -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 and the Extended Window Manager -Hints specifications. freedesktop.org -has links to many relevant specifications. - - -The GDK manual 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_minimize() or gtk_window_maximize(). -Keep in mind that most window managers will ignore -certain requests from time to time, in the interests of good user interface. - - - - - - -