View switcher pattern migration

The initiative: #16

Requirements

Using GtkStackSwitcher. If the application is using a box of GtkRadioButtons or something similar, it must be migrated to GtkStack and GtkStackSwitcher first.

Adding libhandy dependency

If your application already uses libhandy, this step can be skipped.

Add the following module into your Flatpak manifest:

	
        {
            "name" : "libhandy",
            "buildsystem" : "meson",
            "config-opts" : [
                "-Dintrospection=disabled",
                "-Dtests=false",
                "-Dexamples=false",
                "-Dvapi=false",
                "-Dglade_catalog=disabled"
            ],
            "cleanup" : [ "/include", "/lib/pkgconfig" ],
            "sources" : [
                {
                    "type" : "git",
                    "url" : "https://gitlab.gnome.org/GNOME/libhandy.git"
                }
            ]
        },

For languages like Python and JavaScript change "-Dintrospection=disabled" to "-Dintrospection=enabled", for Vala change "-Dvapi=false" to "-Dvapi=true".

Add libhandy dependency to your meson.build file:

dependency ('libhandy-1', version: '>= 0.80.0')

For C or Vala, define HANDY_USE_UNSTABLE_API:

add_project_arguments (
  '-DHANDY_USE_UNSTABLE_API',
  language: 'c'
)

For Vala, also add:

# FIXME Disable --disable-since-check after libhandy 1.0 is released
add_project_arguments (
  '--disable-since-check',
  language: 'vala'
)

Making use of `HdyViewSwitcher`

After importing libhandy into the project, replace GtkStackSwitcher in the headerbar with HdyStackSwitcher. It's a drop-in replacement, so replace the API usage as follows:

`GtkStackSwitcher`	`HdyViewSwitcher`
`gtk_stack_switcher_new()`	`hdy_view_switcher_new()`
`gtk_stack_switcher_get_stack()`	`hdy_view_switcher_get_stack()`
`gtk_stack_switcher_set_stack()`	`hdy_view_switcher_set_stack()`

Set the policy to wide:

<object class="HdyViewSwitcher">
    <property name="visible">True</property>
    <property name="stack">stack</property>
    <property name="policy">wide</property>
</object>

hdy_view_switcher_set_policy (HDY_VIEW_SWITCHER (switcher), HDY_VIEW_SWITCHER_POLICY_WIDE);

Adding icons for `GtkStack` pages:

While HdyViewSwitcher technically works without icons, it's designed to only ever be used with them.

For every page in the GtkStack, set an icon using the icon-name child property:

<object class="GtkStack">
    <child>
        <object class="...">
            ...
        </object>
        <packing>
            <property name="title">Example</property>
            <property name="icon-name">face-smile-symbolic</property>
        </packing>
    </child>
</object>

gtk_container_child_set (GTK_CONTAINER (stack), child,
                         "icon-name", "face-smile-symbolic",
                         NULL);

Using the correct `GtkStack` transition type:

The recommended transition type to use with HdyViewSwitcher is crossfade.

It can be achieved by setting the transition-type property to GTK_STACK_TRANSITION_TYPE_CROSSFADE:

<object class="GtkStack" id="stack">
    <property name=visible">True</property>
    <property name="transition-type">crossfade</property>
    ...
</object>

gtk_stack_set_transition_type (GTK_STACK (stack), GTK_STACK_TRANSITION_TYPE_CROSSFADE);