Commit 29fb9ae2 authored by Matthias Clasen's avatar Matthias Clasen

docs: Convert platform sections to markdown

parent 2595cd5a
# 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`
<?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="gtk-broadway">
<refmeta>
<refentrytitle>Using GTK with Broadway</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Using GTK with Broadway</refname>
<refpurpose>
HTML-specific aspects of using GTK
</refpurpose>
</refnamediv>
<refsect1>
<title>Using GTK with Broadway</title>
<para>
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
<literal>GDK_BACKEND=broadway</literal>. Then you can make
your application appear in a web browser by pointing it at
<literal>http://127.0.0.1:8080</literal>. Note that you need
to enable web sockets in your web browser.
</para>
<para>
You can choose a different port from the default 8080 by setting
the <envar>BROADWAY_DISPLAY</envar> environment variable to the
port that you want to use.
</para>
<para>
It is also possible to use multiple GTK applications in the same
web browser window, by using the Broadway server,
<command>broadwayd</command>, that ships with GTK.
To use broadwayd, start it like this:
<programlisting>
broadwayd :5
</programlisting>
Then point your web browser at <literal>http://127.0.0.1:8085</literal>.
Start your applications like this:
<programlisting>
GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk4-demo
</programlisting>
</para>
<refsect2 id="broadway-envar">
<title>Broadway-specific environment variables</title>
</refsect2>
<formalpara>
<title><envar>BROADWAY_DISPLAY</envar></title>
<para>
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:
<programlisting>
<replaceable>port</replaceable> = 8080 + <replaceable>display</replaceable>
</programlisting>
</para>
</formalpara>
</refsect1>
</refentry>
......@@ -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',
......
# 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).
<?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="gtk-osx">
<refmeta>
<refentrytitle>Using GTK on Apple macOS</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Using GTK on Apple macOS</refname>
<refpurpose>
MacOS-specific aspects of using GTK
</refpurpose>
</refnamediv>
<refsect1>
<title>Using GTK on Apple macOS</title>
<para>
The Apple macOS port of GTK is an implementation of GDK (and therefore GTK)
on top of the Quartz API.
</para>
<para>
Currently, the macOS port does not use any additional commandline options
or environment variables.
</para>
<para>
For up-to-date information about the current status of this port, see the
<ulink url="https://wiki.gnome.org/Projects/GTK/OSX">project page</ulink>.
</para>
</refsect1>
</refentry>
<?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="gtk-wayland">
<refmeta>
<refentrytitle>Using GTK with Wayland</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>
# Using GTK with Wayland {#gtk-wayland}
<refnamediv>
<refname>Using GTK with Wayland</refname>
<refpurpose>
Wayland-specific aspects of using GTK
</refpurpose>
</refnamediv>
<refsect1>
<title>Using GTK with Wayland</title>
<para>
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 <literal>GDK_BACKEND=wayland</literal>.
</para>
the Wayland backend by setting `GDK_BACKEND=wayland`.
<para>
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."
</para>
<para>
Currently, the Wayland backend does not use any additional environment variables.
</para>
</refsect1>
</refentry>
<?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="gtk-windows">
<refmeta>
<refentrytitle>Using GTK on Windows</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK Library</refmiscinfo>
</refmeta>
# Using GTK on Windows {#gtk-windows}
<refnamediv>
<refname>Using GTK on Windows</refname>
<refpurpose>
Windows-specific aspects of using GTK
</refpurpose>
</refnamediv>
<refsect1>
<title>Using GTK on Windows</title>
<para>
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.
</para>
<refsect2 id="win32-envar">
<title>Windows-specific environment variables</title>
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}
<para>
The Win32 GDK backend can be influenced with some additional environment
variables.
</para>
<formalpara>
<title><envar>GDK_IGNORE_WINTAB</envar></title>
### GDK_IGNORE_WINTAB
<para>
If this variable is set, GTK doesn't use the Wintab API for tablet support.
</para>
</formalpara>
<formalpara>
<title><envar>GDK_USE_WINTAB</envar></title>
### GDK_USE_WINTAB
<para>
If this variable is set, GTK uses the Wintab API for tablet support.
This is the default.
</para>
</formalpara>
</refsect2>
<refsect2 id="win32-cursors">
<title>Windows-specific handling of cursors</title>
## Windows-specific handling of cursors {#win32-cursors}
<para>
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.
</para>
<para>
When any other cursor theme is used, GTK will prefer cursors from that theme,
falling back to Windows cursors and built-in X cursors.
</para>
<para>
Theme can be changed by setting <literal>gtk-cursor-theme-name</literal> GTK
setting. Users can override GTK settings in the <filename>settings.ini</filename>
file or at runtime in the GTK Inspector.
</para>
<para>
Themes are loaded from normal Windows variants of the XDG locations:
<filename>%HOME%/icons/THEME/cursors</filename>,
<filename>%APPDATA%/icons/THEME/cursors</filename>,
<filename>RUNTIME_PREFIX/share/icons/THEME/cursors</filename>.
</para>
<para>
The <literal>gtk-cursor-theme-size</literal> setting is ignored, GTK will use
the cursor size that Windows tells it to use.
</para>
</refsect2>
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.
<para>
More information about GTK on Windows, including detailed build
instructions, binary downloads, etc, can be found
<ulink url="https://wiki.gnome.org/Projects/GTK/Win32">online</ulink>.
</para>
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`
</refsect1>
The `gtk-cursor-theme-size`> setting is ignored, GTK will use
the cursor size that Windows tells it to use.
</refentry>
<?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="gtk-x11">
<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-specific aspects of using GTK
</refpurpose>
</refnamediv>
<refsect1>
<title>GTK for the X Window System</title>
<para>
# 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."
</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>
<refsect2 id="x11-envar">
<title>X11-specific environment variables</title>
[GDK X Window System interaction](#gdk-X-Window-System-Interaction)
in the GDK manual.
<para>
## X11-specific environment variables {#x11-envar}
:
The X11 GDK backend can be influenced with some additional environment variables.
</para>
<formalpara>
<title><envar>GDK_SYNCHRONIZE</envar></title>
<para>
If set, GDK makes all X requests synchronously. This is a useful
option for debugging, but it will slow down the performance considerably.
</para>
</formalpara>
### GDK_SYNCHRONIZE
<formalpara>
<title><envar>GDK_SCALE</envar></title>
If set, GDK makes all X requests synchronously. This is a useful
option for debugging, but it will slow down the performance considerably.
<para>
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.
</para>
</formalpara>
### GDK_SCALE
</refsect2>
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.
</refsect1>
## Understanding the X11 architecture {#gtk-X11-arch}
<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>
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. <ulink
url="http://www.freedesktop.org/standards/">freedesktop.org</ulink>
Hints specifications. [freedesktop.org](http://www.freedesktop.org/standards/)
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>
The GDK manual covers [using Xlib in a GTK program](#gdk-X-Window-System-Interaction).
### Server, client, window manager
<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>
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_.
<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>
established [convention](http://www.freedesktop.org/standards/).
<para>
GTK has functions for asking the window manager to do various things;
see for example <link
linkend="gtk-window-minimize">gtk_window_minimize()</link> or <link
linkend="gtk-window-maximize">gtk_window_maximize()</link>.
Keep in mind that most window managers <emphasis>will</emphasis> ignore
certain requests from time to time, in the interests of good user interface.
</para>
</refsect2>
</refsect1>
</refentry>
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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment