Commit 7ec0283c authored by Guido Günther's avatar Guido Günther

Merge branch 'titlebar' into 'master'

GTK+: Update the titlebar related sections

See merge request Librem5/developer.puri.sm!48
parents 19029889 886ba1a9
......@@ -18,8 +18,11 @@
.. _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
.. _HdyTitleBar : https://honk.sigxcpu.org/projects/libhandy/doc/HdyTitleBar.html
GTK+
====
......@@ -64,20 +67,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