Commit 751caca3 authored by Adrien Plazas's avatar Adrien Plazas

GTK+: Update the titlebar related sections

Replace the Header Bar and Separators section by the Title Bar section
and the Selection Mode section.

These explain how to handle these UI elements in a simpler and better
way, taking recent improvements to GTK+ and libhandy into accounts.
parent 19029889
Pipeline #1136 passed with stage
in 46 seconds
......@@ -18,8 +18,12 @@
.. _GtkLabel ellipize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
.. _GtkLabel wrap property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap
.. _GtkLabel wrap-mode property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap-mode
.. _GtkSeparator : https://developer.gnome.org/gtk3/stable/GtkSeparator.html
.. _GtkSizeGroup : https://developer.gnome.org/gtk3/stable/GtkSizeGroup.html
.. _HdyHeaderGroup : https://honk.sigxcpu.org/projects/libhandy/doc/HdyHeaderGroup.html
.. _HdyTitleBar : https://honk.sigxcpu.org/projects/libhandy/doc/HdyTitleBar.html
GTK+
====
......@@ -64,20 +68,57 @@ Letting your label wrap will preserve the integrity of the text at the expense o
To help you implement these, we created an `example application <adaptive labels example application_>`_, just clone it in :ref:`gbuilder` and check the ``adaptive-labels`` branch out.
Header Bars and Separators
--------------------------
A GtkHeaderBar_ is meant to be used as a window's title bar, typically presenting to the user the application's title, various controls and a `close` button.
Some applications want to split their header bar into two or more pieces, a typical way to implement this is by having a `GtkBox` containing two header bars separated by a `GtkSeparator` as you title bar.
.. note:: There currently is a bug in GTK+ 3 that `may` make a separator in a title bar appear black. You can fix this with the following custom style:
``.titlebar:not(headerbar) separator { background-color: @theme_borders_color; }``
As per the GNOME human interface guidelines, applications may enter a special `selection mode`_. A common way to implement it is by adding the `selection-mode` style class to your header bars and the separators between them.
.. note:: A separator with the `selection-mode` style class won't appear blue in GTK+ 3 and will look out of place. The bug has been fixed in GTK+ 4 and for GTK+ 3 you can apply the same effect with the following custom style:
``separator.selection-mode { background-color: mix(@theme_selected_bg_color, #000, 0.2); }``
Title Bars
----------
A GtkHeaderBar_ is meant to be used in a window's title bar, typically presenting to the user the application's title, various controls and a `close` button.
HdyTitleBar_ is a simple container that takes care of the look of the title bar.
It is a very convenient widget as it allows header bars to look good when animated by ensuring they don't draw the title bar's background themselves, which is a requirement for adaptive apps, and it simplifies common operations like setting the selection mode a lot.
Some title bars are composed of multiple header bars, in such a case it is advised to separate them with a GtkSeparator_ with the `sidebar` style class.
Here is an simple `GtkBuilder` example showing this section's advises:
.. code:: xml
<?xml version="1.0" encoding="UTF-8"?>
<interface>
<object class="GtkWindow">
<child type="titlebar">
<object class="HdyTitleBar">
<child>
<object class="GtkBox">
<child>
<object class="GtkHeaderBar" id="start_header">
<property name="show-close-button">True</property>
</object>
</child>
<child>
<object class="GtkSeparator">
<style>
<class name="sidebar"/>
</style>
</object>
</child>
<child>
<object class="GtkHeaderBar" id="end_header">
<property name="show-close-button">True</property>
</object>
</child>
</object>
</child>
</object>
</child>
</object>
</interface>
Selection Mode
--------------
As per the GNOME human interface guidelines, applications may enter a special `selection mode`_. Setting the selection mode to an application in previous versions of GTK+ was complicated as it implied having to manually add or remove the `selection-mode` style class to each of your header bars, while their separators were condamned to look ugly as they were not styled accordingly.
HdyTitleBar_ and recent improvements in the default theme of GTK+ simplifies that a lot, simply toggle the `selection-mode` boolean property of HdyTitleBar_ for their descendants to be styled accordingly, including separators with the `sidebar` style class.
Grid Layout
-----------
......
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