AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-30 15:31:34 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'ebassi/rst-man' into 'master'

Browse Source 
Switch man pages to reStructuredFormat

See merge request GNOME/gtk!3995
This commit is contained in:
Matthias Clasen 2021-09-24 22:03:13 +00:00
commit b2b7118b8e
24 changed files with 474 additions and 893 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitlab-ci.yml
View File

@ -25,7 +25,7 @@ variables:
BACKEND_FLAGS: "-Dx11-backend=true -Dwayland-backend=true -Dbroadway-backend=true"
FEATURE_FLAGS: "-Dvulkan=enabled -Dcloudproviders=enabled"
MESON_TEST_TIMEOUT_MULTIPLIER: 3
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v34"
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gtk/fedora:v35"
FLATPAK_IMAGE: "registry.gitlab.gnome.org/gnome/gnome-runtime-images/gnome:master"
.only-default:

1
.gitlab-ci/fedora.Dockerfile
View File

@ -76,6 +76,7 @@ RUN dnf -y install \
pcre-devel \
pcre-static \
python3 \
python3-docutils \
python3-gobject \
python3-jinja2 \
python3-markdown \

57
docs/reference/gtk/gtk4-broadwayd.rst Normal file
View File

@ -0,0 +1,57 @@
.. _gtk4-broadwayd(1):
==============
gtk4-broadwayd
==============
---------------------------
The Broadway display server
---------------------------
SYNOPSIS
--------
| **gtk4-broadwayd** [OPTIONS...] <DISPLAY>
| **gtk4-broadwayd** --port=PORT --address=ADDRESS <DISPLAY>
| **gtk4-broadwayd** --unixaddress=ADDRESS <DISPLAY>
DESCRIPTION
-----------
``gtk4-broadwayd`` is a display server for the Broadway GDK backend. It allows
multiple GTK applications to display their windows in the same web browser, by
connecting to gtk4-broadwayd.
When using gtk4-broadwayd, specify the display number to use, prefixed with a
colon, similar to X. The default display number is 0.
::
gtk4-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
OPTIONS
-------
``--port PORT``
Use the given ``PORT`` for the HTTP connection, instead of the default ``8080 + (DISPLAY - 1)``.
``--address ADDRESS``
Use the given ``address`` for the HTTP connection, instead of the default ``http://127.0.0.1``.
``--unixsocket ADDRESS``
Use the given ``address`` as the unix domain socket address. This option
overrides ``--address`` and ``--port``, and it is available only on Unix-like
systems.

84
docs/reference/gtk/gtk4-broadwayd.xml
View File

@ -1,84 +0,0 @@
<?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="gtk4-broadwayd">
<refentryinfo>
<title>gtk4-broadwayd</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-broadwayd</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-broadwayd</refname>
<refpurpose>Broadway display server</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-broadwayd</command>
<arg choice="opt">--port <replaceable>PORT</replaceable></arg>
<arg choice="opt">--address <replaceable>ADDRESS</replaceable></arg>
<arg choice="opt">--unixsocket <replaceable>ADDRESS</replaceable></arg>
<arg choice="opt"><replaceable>:DISPLAY</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-broadwayd</command> is a display server for the Broadway
GDK backend. It allows multiple GTK applications to display their
windows in the same web browser, by connecting to gtk4-broadwayd.
</para>
<para>
When using gtk4-broadwayd, specify the display number to use, prefixed
with a colon, similar to X. The default display number is 0.
<programlisting>
gtk4-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>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term>--port</term>
<listitem><para>Use <replaceable>PORT</replaceable> as the HTTP
port, instead of the default 8080 + (<replaceable>DISPLAY</replaceable> - 1).
</para></listitem>
</varlistentry>
<varlistentry>
<term>--address</term>
<listitem><para>Use <replaceable>ADDRESS</replaceable> as the HTTP
address, instead of the default <literal>http://127.0.0.1:<replaceable>PORT</replaceable></literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--unixsocket</term>
<listitem><para>Use <replaceable>ADDRESS</replaceable> as the unix domain socket
address. This option overrides <literal>--address</literal> and <literal>--port</literal>.
It is available only on Unix-like systems.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

85
docs/reference/gtk/gtk4-builder-tool.rst Normal file
View File

@ -0,0 +1,85 @@
.. _gtk4-builder-tool(1):
=================
gtk4-builder-tool
=================
-----------------------
GtkBuilder File Utility
-----------------------
SYNOPSIS
--------
| **gtk4-builder-tool** <COMMAND> [OPTIONS...] <FILE>
|
| **gtk4-builder-tool** validate <FILE>
| **gtk4-builder-tool** enumerate <FILE>
| **gtk4-builder-tool** simplify [OPTIONS...] <FILE>
| **gtk4-builder-tool** preview [OPTIONS...] <FILE>
DESCRIPTION
-----------
``gtk4-builder-tool`` can perform various operations on GtkBuilder UI definition
files.
COMMANDS
--------
Validation
^^^^^^^^^^
The ``validate`` command validates the given UI definition file and reports
errors to ``stderr``.
Enumeration
^^^^^^^^^^^
The ``enumerate`` command lists all the named objects that are present in the UI
definition file.
Preview
^^^^^^^
The ``preview`` command displays the UI dfinition file.
This command accepts options to specify the ID of the toplevel object and a CSS
file to use.
``--id=ID``
The ID of the object to preview. If not specified, gtk4-builder-tool will
choose a suitable object on its own.
``--css=FILE``
Load style information from the given CSS file.
Simplification
^^^^^^^^^^^^^^
The ``simplify`` command simplifies the UI definition file by removing
properties that are set to their default values and writes the resulting XML to
the standard output, or back to the input file.
When the ``--3to4`` option is specified, the ``simplify`` command interprets the
input as a GTK 3 UI definuition file and attempts to convert it to GTK 4
equivalents. It performs various conversions, such as renaming properties,
translating child properties to layout properties, rewriting the setup for
GtkNotebook, GtkStack, GtkAssistant or changing toolbars into boxes.
You should always test the modified UI definition files produced by
gtk4-builder-tool before using them in production.
Note in particular that the conversion done with ``--3to4`` is meant as a
starting point for a port from GTK 3 to GTK 4. It is expected that you will have
to do manual fixups after the initial conversion.
``--replace``
Write the content back to the UI definition file instead of using the standard
output.
``--3to4``
Transform a GTK 3 UI definition file to the equivalent GTK 4 definitions.

110
docs/reference/gtk/gtk4-builder-tool.xml
View File

@ -1,110 +0,0 @@
<?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="gtk4-builder-tool">
<refentryinfo>
<title>gtk4-builder-tool</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-builder-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-builder-tool</refname>
<refpurpose>GtkBuilder file utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-builder-tool</command>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-builder-tool</command> can perform various operations
on GtkBuilder .ui files.
</para>
<para>
The <option>validate</option> command validates the .ui file and reports
errors to stderr.
</para>
<para>
The <option>enumerate</option> command lists all the named objects that
are created in the .ui file.
</para>
<para>
The <option>preview</option> command displays the .ui file. This command
accepts options to specify the ID of the toplevel object and a .css file
to use.
</para>
<para>
The <option>simplify</option> command simplifies the .ui file by removing
properties that are set to their default values and writes the resulting XML
to stdout, or back to the input file.
</para>
<para>
When the <option>--3to4</option> is specified, <option>simplify</option>
interprets the input as a GTK 3 ui file and attempts to convert it to GTK 4
equivalents. It performs various conversions, such as renaming properties,
translating child properties to layout properties, rewriting the setup for
GtkNotebook, GtkStack, GtkAssistant or changing toolbars into boxes.
</para>
<para>
You should always test the modified .ui files produced by gtk4-builder-tool
before using them in production.
</para>
<para>
Note in particular that the conversion
done with <option>--3to4</option> is meant as a starting point for a port
from GTK 3 to GTK 4. It is expected that you will have to do manual fixups
after the initial conversion.
</para>
</refsect1>
<refsect1><title>Simplify Options</title>
<para>The <option>simplify</option> command accepts the following options:</para>
<variablelist>
<varlistentry>
<term><option>--replace</option></term>
<listitem><para>Write the content back to the .ui file instead of stdout.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--3to4</option></term>
<listitem><para>Transform a GTK 3 ui file to GTK 4</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Preview Options</title>
<para>The <option>preview</option> command accepts the following options:</para>
<variablelist>
<varlistentry>
<term><option>--id=<arg choice="plain">ID</arg></option></term>
<listitem><para>The ID of the object to preview. If not specified,
gtk4-builder-tool will choose a suitable object on its own.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--css=<arg choice="plain">FILE</arg></option></term>
<listitem><para>Load style information from the given .css file.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

22
docs/reference/gtk/gtk4-demo-application.rst Normal file
View File

@ -0,0 +1,22 @@
.. _gtk4-demo-application(1):
=====================
gtk4-demo-application
=====================
--------------------------
Demonstrate GtkApplication
--------------------------
SYNOPSIS
--------
| **gtk4-demo-application**
DESCRIPTION
-----------
``gtk4-demo-application`` is an example application used by ``gtk4-demo``.
There is no need to call it manually.

44
docs/reference/gtk/gtk4-demo-application.xml
View File

@ -1,44 +0,0 @@
<?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="gtk4-demo-application">
<refentryinfo>
<title>gtk4-demo-application</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-demo-application</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-demo-application</refname>
<refpurpose>Demonstrate GtkApplication</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-demo-application</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-demo-application</command> is an example application
used by <command>gtk4-demo</command>. There is no need to call it
manually.
</para>
</refsect1>
</refentry>

48
docs/reference/gtk/gtk4-demo.rst Normal file
View File

@ -0,0 +1,48 @@
.. _gtk4-demo(1):
=========
gtk4-demo
=========
-----------------------
Demonstrate GTK widgets
-----------------------
SYNOPSIS
--------
| **gtk4-demo** [OPTIONS...]
DESCRIPTION
-----------
``gtk4-demo`` is a collection of examples.
Its purpose is to demonstrate many GTK widgets in a form that is useful to
application developers.
The application shows the source code for each example, as well as other used
resources, such as UI description files and image assets.
OPTIONS
-------
``-h, --help``
Show help options.
``--version``
Show program version.
``--list``
List available examples.
``--run EXAMPLE``
Run the named example. Use ``--list`` to see the available examples.
``--autoquit``
Quit after a short timeout. This is intended for use with ``--run``, e.g. when profiling.

81
docs/reference/gtk/gtk4-demo.xml
View File

@ -1,81 +0,0 @@
<?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="gtk4-demo">
<refentryinfo>
<title>gtk4-demo</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-demo</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-demo</refname>
<refpurpose>Demonstrate GTK widgets</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-demo</command>
<arg choice="opt">--help</arg>
<arg choice="opt">--version</arg>
<arg choice="opt">--list</arg>
<arg choice="opt">--run <replaceable>EXAMPLE</replaceable></arg>
<arg choice="opt">--autoquit</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-demo</command> is a collection of examples.
Its purpose is to demonstrate many GTK widgets in a form
that is useful to application developers.
</para>
<para>
The application shows the source code for each example, as well as
other used resources, such as ui files and icons.
</para>
</refsect1>
<refsect1><title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>Show help options</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>Show program version</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list</option></term>
<listitem><para>List available examples.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-run <replaceable>EXAMPLE</replaceable></option></term>
<listitem><para>Run the named example. Use <option>--list</option> to
see the available examples.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--autoquit</option></term>
<listitem><para>Quit after a short timeout. This is intended for use
with <option>--run</option>, e.g. when profiling.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

40
docs/reference/gtk/gtk4-encode-symbolic-svg.rst Normal file
View File

@ -0,0 +1,40 @@
.. _gtk4-encode-symbolic-svg(1):
========================
gtk4-encode-symbolic-svg
========================
--------------------------------
Symbolic icon conversion utility
--------------------------------
SYNOPSIS
--------
| **gtk4-encode-symbolic-svg** [OPTIONS...] <PATH> <WIDTH>x<HEIGHT>
DESCRIPTION
-----------
``gtk4-encode-symbolic-svg`` converts symbolic SVG icons into specially prepared
PNG files. GTK can load and recolor these PNGs, just like original SVGs, but
loading them is much faster.
``PATH`` is the name of a symbolic SVG file, ``WIDTH`` x ``HEIGHT`` are the
desired dimensions for the generated PNG file.
To distinguish them from ordinary PNGs, the generated files have the extension
``.symbolic.png``.
OPTIONS
-------
``-o, --output DIRECTORY``
Write png files to ``DIRECTORY`` instead of the current working directory.
``--debug``
Generate PNG files of the various channels during the conversion. If these
files are not monochrome green, they are often helpful in pinpointing the
problematic parts of the source SVG.

74
docs/reference/gtk/gtk4-encode-symbolic-svg.xml
View File

@ -1,74 +0,0 @@
<?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="gtk4-encode-symbolic-svg">
<refentryinfo>
<title>gtk4-encode-symbolic-svg</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-encode-symbolic-svg</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-encode-symbolic-svg</refname>
<refpurpose>Symbolic icon conversion utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-encode-symbolic-svg</command>
<arg choice="opt">OPTION...</arg>
<arg choice="plain"><replaceable>PATH</replaceable></arg>
<arg choice="plain"><replaceable>WIDTH</replaceable>x<replaceable>HEIGHT</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-encode-symbolic-svg</command> converts symbolic svg icons into
specially prepared png files. GTK can load and recolor these pngs, just like
original svgs, but loading them is much faster.
</para>
<para>
<replaceable>PATH</replaceable> is the name of a symbolic svg file,
<replaceable>WIDTH</replaceable>x<replaceable>HEIGHT</replaceable> are the
desired dimensions for the generated png file.
</para>
<para>
To distinguish them from ordinary pngs, the generated files have the extension
<filename>.symbolic.png</filename>.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term>-o <replaceable>DIRECTORY</replaceable></term>
<term>--output <replaceable>DIRECTORY</replaceable></term>
<listitem><para>Write png files to <replaceable>DIRECTORY</replaceable>
instead of the current working directory.</para></listitem>
</varlistentry>
<varlistentry>
<term>--debug</term>
<listitem><para>Generate png files of the various channels during
the conversion. If these files are not monochrome green, they
are often helpful in pinpointing the problematic parts of
the source svg.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

28
docs/reference/gtk/gtk4-icon-browser.rst Normal file
View File

@ -0,0 +1,28 @@
.. _gtk4-icon-browser(1):
=================
gtk4-icon-browser
=================
-----------------
List themed icons
-----------------
SYNOPSIS
--------
| **gtk4-icon-browser** [OPTIONS...]
DESCRIPTION
-----------
``gtk4-icon-browser`` is a utility to explore the icons in the current icon
theme. It shows icons in various sizes, their symbolic variants where available,
as well as a description of the icon and its context.
OPTIONS
-------
``-h, --help``
Show the application help.

55
docs/reference/gtk/gtk4-icon-browser.xml
View File

@ -1,55 +0,0 @@
<?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="gtk4-icon-browser">
<refentryinfo>
<title>gtk4-icon-browser</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-icon-browser</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-icon-browser</refname>
<refpurpose>List themed icons</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-icon-browser</command>
<arg choice="opt">--help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-icon-browser</command> is a utility to explore the icons
in the current icon theme. It shows icons in various sizes, their symbolic
variants where available, as well as a description of the icon and its context.
</para>
</refsect1>
<refsect1><title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>Show help options</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

50
docs/reference/gtk/gtk4-launch.rst Normal file
View File

@ -0,0 +1,50 @@
.. _gtk4-launch(1):
===========
gtk4-launch
===========
---------------------
Launch an application
---------------------
SYNOPSIS
--------
| **gtk4-launch** [OPTIONS...] <APPLICATION> [URI...]
DESCRIPTION
-----------
``gtk4-launch`` launches an application using the given name. The application is
started with proper startup notification on a default display, unless specified
otherwise.
``gtk4-launch`` takes at least one argument, the name of the application to
launch. The name should match application desktop file name, as residing in the
applications subdirectories of the XDG data directories, with or without the
``.desktop`` suffix.
If called with more than one argument, the rest of them besides the application
name are considered URI locations and are passed as arguments to the launched
application.
OPTIONS
-------
``-?, -h, --help``
Print the command's help and exit.
``--version``
Print the command's version and exit.
ENVIRONMENT
-----------
Some environment variables affect the behavior of ``gtk4-launch``:
``XDG_DATA_HOME, XDG_DATA_DIRS``
The environment variables specifying the XDG data directories.

85
docs/reference/gtk/gtk4-launch.xml
View File

@ -1,85 +0,0 @@
<?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="gtk4-launch">
<refentryinfo>
<title>gtk4-launch</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tomáš</firstname>
<surname>Bžatek</surname>
<email>tbzatek@redhat.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-launch</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-launch</refname>
<refpurpose>Launch an application</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-launch</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="plain">APPLICATION</arg>
<arg choice="opt" rep="repeat">URI</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-launch</command> launches an application using the given name.
The application is started with proper startup notification on a default
display, unless specified otherwise.
</para>
<para>
<command>gtk4-launch</command> takes at least one argument, the name of
the application to launch. The name should match application desktop file name,
as residing in the applications subdirectories of the XDG data directories, with
or without the '.desktop' suffix.
</para>
<para>
If called with more than one argument, the rest of them besides the application
name are considered URI locations and are passed as arguments to the launched
application.
</para>
</refsect1>
<refsect1><title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>-?</option>, <option>--help</option></term>
<listitem><para>Prints a short help text and exits.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>Prints the program version and exits.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Environment</title>
<para>Some environment variables affect the behavior of <command>gtk4-launch</command>.</para>
<variablelist>
<varlistentry>
<term><option>XDG_DATA_HOME</option>, <option>XDG_DATA_DIRS</option></term>
<listitem><para>The environment variables specifying the XDG dta directories.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

21
docs/reference/gtk/gtk4-query-settings.rst Normal file
View File

@ -0,0 +1,21 @@
.. _gtk4-query-settings(1):
===================
gtk4-query-settings
===================
------------------------------------
Print name and value of GTK settings
------------------------------------
SYNOPSIS
--------
| **gtk4-query-settings** [PATTERN]
DESCRIPTION
-----------
``gtk4-query-settings`` prints both name and value of all properties available
in the ``GtkSettings`` class. Optionally, you can filter which properties to
list by specifying a ``PATTERN``.

45
docs/reference/gtk/gtk4-query-settings.xml
View File

@ -1,45 +0,0 @@
<?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="gtk4-query-settings">
<refentryinfo>
<title>gtk4-query-settings</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Timm</firstname>
<surname>Bäder</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-query-settings</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-query-settings</refname>
<refpurpose>Utility to print name and value of all GtkSettings properties</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-query-settings</command>
<arg choice="opt"><replaceable>PATTERN</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-query-settings</command> prints both name and value of all properties
available in the GtkSettings class. Optionally, you can filter which properties
to list by specifying a PATTERN.
</para>
</refsect1>
</refentry>

65
docs/reference/gtk/gtk4-update-icon-cache.rst Normal file
View File

@ -0,0 +1,65 @@
.. _gtk4-update-icon-cache(1):
======================
gtk4-update-icon-cache
======================
--------------------------
Icon theme caching utility
--------------------------
SYNOPSIS
--------
| **gtk4-update-icon-cache** [OPTIONS...] <PATH>
DESCRIPTION
-----------
``gtk4-update-icon-cache`` creates ``mmap(2)``-able cache files for icon themes.
It expects to be given the ``PATH`` to an icon theme directory containing an
``index.theme``, e.g. ``/usr/share/icons/hicolor``, and writes a
``icon-theme.cache`` containing cached information about the icons in the
directory tree below the given directory.
GTK can use the cache files created by ``gtk4-update-icon-cache`` to avoid a lot
of system call and disk seek overhead when the application starts. Since the
format of the cache files allows them to be shared across multiple processes,
for instance using the POSIX ``mmap(2)`` system call, the overall memory
consumption is reduced as well.
OPTIONS
-------
``-f, --force``
Overwrite an existing cache file even if it appears to be up-to-date.
``-t, --ignore-theme-index``
Don't check for the existence of ``index.theme`` in the icon theme directory.
Without this option, ``gtk4-update-icon-cache`` refuses to create an icon
cache in a directory which does not appear to be the toplevel directory of an
icon theme.
``-i, --index-only``
Don't include image data in the cache.
``--include-image-data``
Include image data in the cache.
``-c, --source <NAME>``
Output a C header file declaring a constant ``NAME`` with the contents of the
icon cache.
``-q, --quiet``
Turn off verbose output.
``-v, --validate``
Validate existing icon cache.

123
docs/reference/gtk/gtk4-update-icon-cache.xml
View File

@ -1,123 +0,0 @@
<?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="gtk4-update-icon-cache">
<refentryinfo>
<title>gtk4-update-icon-cache</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-update-icon-cache</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-update-icon-cache</refname>
<refpurpose>Icon theme caching utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-update-icon-cache</command>
<arg choice="opt">--force</arg>
<arg choice="opt">--ignore-theme-index</arg>
<group>
<arg choice="plain">--index-only</arg>
<arg choice="plain">--include-image-data</arg>
</group>
<arg choice="opt">--source <arg choice="plain"><replaceable>NAME</replaceable></arg></arg>
<arg choice="opt">--quiet</arg>
<arg choice="opt">--validate</arg>
<arg choice="plain"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-update-icon-cache</command> creates mmapable cache
files for icon themes.
</para>
<para>
It expects to be given the <replaceable>PATH</replaceable> to an icon theme
directory containing an <filename>index.theme</filename>, e.g.
<filename>/usr/share/icons/hicolor</filename>, and writes a
<filename>icon-theme.cache</filename> containing cached information about
the icons in the directory tree below the given directory.
</para>
<para>
GTK can use the cache files created by <command>gtk4-update-icon-cache</command>
to avoid a lot of system call and disk seek overhead when the application
starts. Since the format of the cache files allows them to be shared across
multiple processes, for instance using the POSIX <command>mmap()</command> system
call, the overall memory consumption is reduced as well.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term>--force</term>
<term>-f</term>
<listitem><para>Overwrite an existing cache file even if it appears to be
up-to-date.</para></listitem>
</varlistentry>
<varlistentry>
<term>--ignore-theme-index</term>
<term>-t</term>
<listitem><para>Don't check for the existence of <filename>index.theme</filename>
in the icon theme directory. Without this option, <command>gtk4-update-icon-cache</command>
refuses to create an icon cache in a directory which does not appear to
be the toplevel directory of an icon theme.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--index-only</term>
<term>-i</term>
<listitem><para>Don't include image data in the cache.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--include-image-data</term>
<listitem><para>Include image data in the cache.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--source</term>
<term>-c</term>
<listitem><para>Output a C header file declaring a constant
<replaceable>NAME</replaceable> with the contents of the icon
cache.</para></listitem>
</varlistentry>
<varlistentry>
<term>--quiet</term>
<term>-q</term>
<listitem><para>Turn off verbose output.
</para></listitem>
</varlistentry>
<varlistentry>
<term>--validate</term>
<term>-v</term>
<listitem><para>Validate existing icon cache.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

34
docs/reference/gtk/gtk4-widget-factory.rst Normal file
View File

@ -0,0 +1,34 @@
.. _gtk4-widget-factory(1):
===================
gtk4-widget-factory
===================
-------------------------------
Showcase GTK widgets and styles
-------------------------------
SYNOPSIS
--------
| **gtk4-widget-factory** [OPTIONS...]
DESCRIPTION
-----------
``gtk4-widget-factory`` is a collection of examples.
Its purpose is to demonstrate many GTK widgets in a form that is useful to GTK theme developers.
The application shows widgets in different, typical combinations and states.
OPTIONS
-------
``-h, --help``
Show the application help.
``--version``
Show the application version.

63
docs/reference/gtk/gtk4-widget-factory.xml
View File

@ -1,63 +0,0 @@
<?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="gtk4-widget-factory">
<refentryinfo>
<title>gtk4-widget-factory</title>
<productname>GTK</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtk4-widget-factory</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtk4-widget-factory</refname>
<refpurpose>Demonstrate GTK widgets</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtk4-widget-factory</command>
<arg choice="opt">--help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para>
<command>gtk4-widget-factory</command> is a collection of examples.
Its purpose is to demonstrate many GTK widgets in a form
that is useful to GTK theme developers.
</para>
<para>
The application shows widgets in different, typical combinations
and states.
</para>
</refsect1>
<refsect1><title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>Show help options</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>Show program version</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

49
docs/reference/gtk/meson.build
View File

@ -59,24 +59,15 @@ if get_option('gtk_doc')
)
endif
xsltproc = find_program('xsltproc', required: false)
if get_option('man-pages') and not xsltproc.found()
error('No xsltproc found, but man pages were explicitly enabled')
rst2man = find_program('rst2man', required: false)
if get_option('man-pages') and not rst2man.found()
error('No rst2man found, but man pages were explicitly enabled')
endif
if get_option('man-pages') and xsltproc.found()
xlstproc_flags = [
'--nonet',
'--stringparam', 'man.output.quietly', '1',
'--stringparam', 'funcsynopsis.style', 'ansi',
'--stringparam', 'man.th.extra1.suppress', '1',
'--stringparam', 'man.authors.section.enabled', '0',
'--stringparam', 'man.copyright.section.enabled', '0',
]
man_files = [
[ 'gtk4-broadwayd', '1', ],
[ 'gtk4-builder-tool', '1', ],
if get_option('man-pages') and rst2man.found()
rst_files = [
[ 'gtk4-broadwayd', '1' ],
[ 'gtk4-builder-tool', '1' ],
[ 'gtk4-encode-symbolic-svg', '1', ],
[ 'gtk4-launch', '1', ],
[ 'gtk4-query-settings', '1', ],
@ -84,7 +75,7 @@ if get_option('man-pages') and xsltproc.found()
]
if get_option('demos')
man_files += [
rst_files += [
[ 'gtk4-demo', '1', ],
[ 'gtk4-demo-application', '1', ],
[ 'gtk4-widget-factory', '1', ],
@ -92,21 +83,25 @@ if get_option('man-pages') and xsltproc.found()
]
endif
foreach man: man_files
man_name = man.get(0)
man_section = man.get(1, '1')
custom_target('@0@.@1@'.format(man_name, man_section),
input: '@0@.xml'.format(man_name),
rst2man_flags = [
'--syntax-highlight=none',
]
foreach rst: rst_files
man_name = rst[0]
man_section = rst.get(1, '1')
custom_target('man-@0@'.format(man_name),
input: '@0@.rst'.format(man_name),
output: '@0@.@1@'.format(man_name, man_section),
command: [
xsltproc,
xlstproc_flags,
'-o', '@OUTPUT@',
'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
rst2man,
rst2man_flags,
'@INPUT@',
],
capture: true,
install: true,
install_dir: join_paths(get_option('mandir'), 'man@0@'.format(man_section)),
install_dir: get_option('mandir') / 'man@0@'.format(man_section),
)
endforeach
endif

101
docs/reference/gtk/overview.xml
View File

@ -1,101 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE partintro PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<partintro>
<para>
GTK is a library for creating graphical user interfaces. It
works on many UNIX-like platforms, Windows, and OS X.
GTK is released under the GNU Library General Public License
(GNU LGPL), which allows for flexible licensing of client
applications. GTK has a C-based object-oriented architecture that
allows for maximum flexibility. Bindings for many other languages have
been written, including C++, Objective-C, Guile/Scheme, Perl, Python,
TOM, Ada95, Free Pascal, and Eiffel. The GTK library itself contains
<firstterm>widgets</firstterm>, that is, GUI components such as GtkButton
or GtkTextView.
</para>
<para>
GTK depends on the following libraries:
<variablelist>
<varlistentry>
<term>GLib</term>
<listitem><para>
A general-purpose utility library, not specific to graphical user interfaces.
GLib provides many useful data types, macros, type conversions,
string utilities, file utilities, a main loop abstraction, and so on.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GObject</term>
<listitem><para>A library that provides a type system, a collection of
fundamental types including an object type, a signal system.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GIO</term>
<listitem><para>A modern, easy-to-use VFS API including abstractions for
files, drives, volumes, stream IO, as well as network programming and
DBus communication.
</para></listitem>
</varlistentry>
<varlistentry>
<term>cairo</term>
<listitem><para>Cairo is a 2D graphics library with support for multiple
output devices.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Pango</term>
<listitem><para>
Pango is a library for internationalized text handling. It centers
around the PangoLayout object, representing a paragraph of text.
Pango provides the engine for GtkTextView, GtkLabel, GtkEntry, and
other widgets that display text.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GdkPixbuf</term>
<listitem><para>
This is a small library which allows you to create GdkPixbuf
("pixel buffer") objects from image data or image files.
Use a GdkPixbuf in combination with GtkImage to display images.
</para></listitem>
</varlistentry>
<varlistentry>
<term>graphene</term>
<listitem><para>
This is a small library which provides vector and matrix datatypes
and operations. graphene provides optimized implementations using
various SIMD instruction sets such as SSE.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GDK</term>
<listitem><para>
GDK is the abstraction layer that allows GTK to support multiple
windowing systems. GDK provides window system facilities on Wayland,
X11, Windows, and OS X.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GSK</term>
<listitem><para>
GSK is a library for creating a scene graph from render nodes,
and rendering it using different rendering APIs. GSK provides renderers
for OpenGL, Vulkan and cairo.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</partintro>