[Initiatives.wiki] Create View switcher pattern migration

[Alexander Mikhaylenko <alexm src gnome org>]

commit ca0584c19749c27c79ca23481a6ddf2c2a86a977
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Mon May 25 14:27:42 2020 +0000

    Create View switcher pattern migration

 View-switcher-pattern-migration.md | 110 +++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
---
diff --git a/View-switcher-pattern-migration.md b/View-switcher-pattern-migration.md
new file mode 100644
index 0000000..90ce229
--- /dev/null
+++ b/View-switcher-pattern-migration.md
@@ -0,0 +1,110 @@
+### Requirements
+
+- Using [`GtkStackSwitcher`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html). If the 
application is using a box of 
[`GtkRadioButton`](https://developer.gnome.org/gtk3/stable/GtkRadioButton.html)s or something similar, it 
must be migrated to [`GtkStack`](https://developer.gnome.org/gtk3/stable/GtkStack.html) and 
[`GtkStackSwitcher`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html) first.
+
+### Adding libhandy dependency
+
+If your application already uses libhandy, this step can be skipped.
+
+Add the following module into your Flatpak manifest:
+
+```json
+       
+        {
+            "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:
+
+```meson
+dependency ('libhandy-1', version: '>= 0.80.0')
+```
+
+For C or Vala, define `HANDY_USE_UNSTABLE_API`:
+
+```meson
+add_project_arguments (
+  '-DHANDY_USE_UNSTABLE_API',
+  language: 'c'
+)
+```
+
+For Vala, also add:
+
+```meson
+# FIXME Disable --disable-since-check after libhandy 1.0 is released
+add_project_arguments (
+  '--disable-since-check',
+  language: 'vala'
+)
+```
+
+### Making use of [`HdyViewSwitcher`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html)
+
+After importing libhandy into the project, replace 
[`GtkStackSwitcher`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html) in the headerbar with 
[`HdyStackSwitcher`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html). It's a drop-in 
replacement, so replace the API usage as follows:
+
+[`GtkStackSwitcher`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html) | 
[`HdyViewSwitcher`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html)
+--- | ---
+[`gtk_stack_switcher_new()`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html#gtk-stack-switcher-new)
 | 
[`hdy_view_switcher_new()`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html#hdy-view-switcher-new)
+[`gtk_stack_switcher_get_stack()`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html#gtk-stack-switcher-get-stack)
 | 
[`hdy_view_switcher_get_stack()`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html#hdy-view-switcher-get-stack)
+[`gtk_stack_switcher_set_stack()`](https://developer.gnome.org/gtk3/stable/GtkStackSwitcher.html#gtk-stack-switcher-set-stack)
 | 
[`hdy_view_switcher_set_stack()`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html#hdy-view-switcher-set-stack)
+
+Set the [policy](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html#HdyViewSwitcher--policy) 
to [`wide`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html#HdyViewSwitcherPolicy):
+```xml
+<property name="policy">wide</property>
+```
+
+```c
+hdy_view_switcher_set_policy (HDY_VIEW_SWITCHER (switcher), HDY_VIEW_SWITCHER_POLICY_WIDE);
+```
+
+### Adding icons for [`GtkStack`](https://developer.gnome.org/gtk3/stable/GtkStack.html) pages:
+
+While [`HdyViewSwitcher`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html) technically 
works without icons, it's designed to only ever be used with them.
+
+For every page in the [`GtkStack`](https://developer.gnome.org/gtk3/stable/GtkStack.html), set an icon using 
the [`icon-name`](https://developer.gnome.org/gtk3/stable/GtkStack.html#GtkStack--c-icon-name) child property:
+
+```xml
+<packing>
+    <property name="title">Example</property>
+    <property name="icon-name">face-smile-symbolic</property>
+</packing>
+```
+
+```c
+gtk_container_child_set (GTK_CONTAINER (stack), child,
+                         "icon-name", "face-smile-symbolic",
+                         NULL);
+```
+
+### Using the correct [`GtkStack`](https://developer.gnome.org/gtk3/stable/GtkStack.html) transition type:
+
+The recommended transition type to use with 
[`HdyViewSwitcher`](https://gnome.pages.gitlab.gnome.org/libhandy/HdyViewSwitcher.html) is crossfade.
+
+It can be achieved by setting the 
[`transition-type`](https://developer.gnome.org/gtk3/stable/GtkStack.html#GtkStack--transition-type) property 
to 
[`GTK_STACK_TRANSITION_TYPE_CROSSFADE`](https://developer.gnome.org/gtk3/stable/GtkStack.html#GtkStackTransitionType):
+
+```xml
+<property name="transition-type">crossfade</property>
+```
+
+```c
+gtk_stack_set_transition_type (GTK_STACK (stack), GTK_STACK_TRANSITION_TYPE_CROSSFADE);
+```