libhandy 0.0.10 just got released, and it comes with a few new adaptive widgets for your GTK app.

You can get this new version here.

The View Switcher

GNOME applications typically use a GtkStackSwitcher to switch between their views. This design works fine on a desktop, but not so well on really narrow devices like mobile phones, so Tobias Bernard designed a more modern and adaptive replacement — now available in libhandy as the HdyViewSwitcher.

In many ways, the HdyViewSwitcher functions very similarly to a GtkStackSwitcher: you assign it a GtkStack containing your application’s pages, and it will display a row of side-by-side, homogeneously-sized buttons, each representing a page. It differs in that it can display both the title and the icon of your pages, and that the layout of the buttons automatically adapts to a narrower version, depending on the available width.

We have also added a view switcher bar, designed to be used at he bottom of the window: HdyViewSwitcherBar.

Thanks a lot to Zander Brown for their prototypes!

The view switchers in action in a modified GNOME Clocks.

The Squeezer

To complete the view switcher design, we needed a way to automatically switch between having a view switcher in the header bar and a view switcher bar at the bottom of the window.

For that we added HdySqueezer: give it widgets, and it will show the first one that fits the available space. A common way to use it would be:

<object class="GtkHeaderBar">
  <property name="title">Application</property>
  <child type="title">
    <object class="HdySqueezer">
      <property name="transition-type">crossfade</property>
      <signal name="notify::visible-child" handler="on_child_changed"/>
        <object class="HdyViewSwitcher" id="view_switcher">
          <property name="stack">pages</property>
        <object class="GtkLabel" id="title_label">
          <property name="label">Application</property>
            <class name="title"/>

In the example above, if there is enough space the view switcher will be visible in the header bar; if not, a widget mimicking the window’s title will be displayed. Additionally, you can reveal or conceal a HdyViewSwitcherBar at the bottom of your window, depending on which widget is presented by the squeezer to only show a single view switcher at a time.

Another Header Bar?

To make the view switcher work as intended, we need to make sure it is always strictly centered; we also need to make sure the view switcher fills all the height of the header bar. Both of these are unfortunately not possible with GtkHeaderBar in GTK 3, so I forked it as HdyHeaderBar to, first, make it not force its title widget to be vertically centered, and hence to allow it to fill all the available height, and second, to allow for choosing between strictly centering its title widget or loosely centering it (similar to GtkHeaderBar).

The Preferences Window

To simplify writing modern, adaptive and featureful applications, I wrote a generic preferences window you can use to implement your application’s preferences window: HdyPreferencesWindow.

It is organized this way:

  • the window contains pages implemented via HdyPreferencesPage;
  • pages have a title, and contain preferences groups implemented via HdyPreferencesGroup;
  • groups can have a title, description, and preferences implemented via rows (HdyPreferencesRow) or any other widget;
  • preferences implemented via HdyPreferencesRow have a name, and can be searched via their page title, group title or name;
  • HdyActionRow is a derivative of HdyPreferencesRow, so you can use it (and its derivatives) to easily implement your preferences.

GNOME Web’s preferences window re-implemented as a HdyPreferencesWindow.


The next expected version of libhandy is libhandy 1.0. It will come with quite a few API fixes, which is why a major version number bump is required. libhandy’s API has been stable since many version, and we will guarantee that stability starting from version 1.0.