Commit f57fbb57 authored by David Boddie's avatar David Boddie

Refactor GTK documentation, moving adaptive UI content into a guide

parent 8aeff57a
This diff is collapsed.
.. _design_adaptive_ui:
Designing Adaptive User Interfaces
==================================
This guide aims to show developers and designers how to use the components provided by GTK with those from the `libhandy library`_ to create applications both for the Librem 5 phone and for traditional desktop and laptop systems.
.. contents::
:local:
This guide assumes that you are familiar with the basics of GTK application development. It also assumes you are using GTK 3.30 or newer and libhandy 0.0.9 or newer as these versions have improved support for adaptive apps over previous versions.
Introduction
------------
`libhandy <libhandy website_>`_ is a widget library for GTK that contains widgets useful for both phone applications and adaptive applications. It extends the standard collection of widgets provided by GTK for this purpose. The `libhandy documentation`_ covers the range of widgets available.
This library is central to the way that adaptive applications are created using GTK. The following sections show how each of its components are employed to make new or existing GTK-based user interfaces adaptable. The :ref:`porting_gnome_apps_guide` guide covers more specific issues related to converting traditional applications to fit the adaptive paradigm.
For general GTK+ and GNOME development resources please consult the :ref:`gnome_resources` page and the `GTK+ 3 documentation`_.
Style Guidelines
----------------
Applications are expected to follow the `GNOME Human Interface Guidelines`_ where possible, to the extent that they apply to the application's environment.
.. _design_adaptive_ui_header_bars:
Header Bars
-----------
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. A simple example that uses HdyTitleBar_ can be found in the `first part <Adaptive_UI_tutorial_part1>`_ of the :ref:`tutorial_Adaptive_UI`.
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.
To help spread the window decoration across all header bars as if they were only one, just show the close button on all of your header bars and put them into a HdyHeaderGroup_ in the same order they appear in the title bar. This is also the correct way to manage header bars when using them with leaflets.
Here is an simple `GtkBuilder` example showing this section's advice:
.. literalinclude:: /Apps/_files/window.ui
Application Menus
-----------------
To demonstrate the use of primary menus, we created an `example application <application menu example application_>`_, just clone it in :ref:`gbuilder` and check the ``app-menu`` branch out.
.. figure:: /Apps/GNOME/images/menu.png
:align: center
:alt: A primary menu in action
A primary menu in action
Adaptive Labels
---------------
A GtkLabel_ can prevent your application's UI from reaching really small sizes, but there are simple tricks to make them do so. Consider using one of the following tricks on each of your labels!
Allowing your label to ellipsize will cut a part of your string when there isn't enough space for it, you can enable it and choose which part will be cut with the `GtkLabel ellipize property`_. Use it if you really need your label to be on a single line.
.. note:: If you allow your label to be ellipsized, make sure that its `xalign property <GtkLabel xalign property_>`_ matches its justification or your label may not be properly aligned when ellipsized: 0 for left, 1 for right, or 0.5 for center.
.. note:: If an ellipsized label has an HdyLeaflet_ for ancestor and you want the label to be ellipsized before the leaflet folds itself, try wrapping your label in a GtkScrolledWindow_, optionally expanding the scrolled window horizontally. Don't worry, it won't surround your label with scrollbars but just trick the sizing system into doing what you expected it to do.
Letting your label wrap will preserve the integrity of the text at the expense of more height, you can enable it with the `GtkLabel wrap property`_ and choose how to wrap with the `GtkLabel wrap-mode property`_.
.. note:: By allowing the label to wrap, it will always request enough height when fully wrapped. Consider putting your label or a widget containing it into a scrollable window to avoid height becoming a problem.
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.
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.
Adaptive Grid Layout
--------------------
Some applications have a grid layout where several panels sit side-by-side and extend to the title bar.
To make an application with a adaptive grid layout, follow these steps:
The basic layout:
* In the title bar put a HdyTitleBar_, put a HdyLeaflet_ in it in which you will put your sidebar's GtkHeaderBar_, a GtkSeparator_ and your content's GtkHeaderBar_.
* In the window put a HdyLeaflet_ in which you will put your sidebar widget, a GtkSeparator_ and your content widget.
* Add the `sidebar` style class to the separators from the titelbar and the window.
* Make the close buttons of your header bars visible.
Make it a grid:
* Put your sidebar widget and its header bar into the same horizontal `GtkSizeGroup` to ensure they request the same minimum width.
* Put your separators into the same horizontal `GtkSizeGroup` to ensure they request the same minimum width.
* Put your content widget and its header bar into the same horizontal `GtkSizeGroup` to ensure they request the same minimum width.
* Horizontally expand the content widget and the content header bar.
Solidify the layout:
* Give the `sidebar` child name to your sidebar widget and its header bar.
* Give the `content` child name to your content widget and its header bar.
* Make your header bar leaflet's child and mode transitions to `slide` to improve spacial navigation semantics.
* Bind your window's leaflet's visible child name and your child and mode transitions (duration and type) to your header bar leaflet's in a bidirectional way to ensure they always appear as a single unified panel.
* When the leaflets are folded, make the header group focus on the currently visible header bar, make it focus on nothing otherwise.
Navigate in the layout:
* Add a back button at the start of your content header bar.
* When your header bar leaflet is folded, make the back button visible, make it invisible otherwise.
* When the back button is clicked, make the sidebar the visible child of the leaflets.
* When an entry of your sidebar is clicked, make the content visible.
.. image:: images/adaptive-grid-layout.png
:width: 600px
:height: 300px
:align: center
To help you implement these, we created an `example application <adaptive grid layout example application_>`_, just clone it in :ref:`gbuilder` and check the ``adaptive-grid-layout-0-0-3`` branch out.
.. _selection mode : https://developer.gnome.org/hig/stable/selection-mode.html.en
.. _enable dconf access : http://docs.flatpak.org/en/latest/sandbox-permissions.html#dconf-access
.. _application menu design : https://gitlab.gnome.org/Community/Design/os-mockups/tree/master/app-menu
.. _application menu example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/app-menu
.. _adaptive labels example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/adaptive-labels
.. _adaptive grid layout example application : https://source.puri.sm/Librem5/purism-gtk-3-examples/tree/adaptive-grid-layout-0-0-4
.. include:: /links.txt
......@@ -9,3 +9,4 @@ Design
.. toctree::
Constraints
Adaptive_UI/index
......@@ -29,14 +29,11 @@ A typical developer workflow for porting will involve something like this:
Hints and Tips
--------------
There are some UI elements in GTK+ that are touch friendly
(and therefore good to use on a phone) while others are not
(e.g. combo boxes).
There are some UI elements in GTK+ that are touch-friendly, and therefore ready to use on a phone, while others are not.
This page will explain how to make the currently non touch
friendly parts of an app more touch friendly. This page is
still a work in progress. Until more is written, please
take a look at these touch friendly applications as examples:
A collection of `application mock-ups`_ for GNOME applications should help to give an overview of the presentation and user interface paradigms that developers are using.
This page will explain how to make the currently non-touch-friendly parts of an app more touch-friendly. This page is still a work in progress. Until more is written, please take a look at these touch friendly applications as examples:
* `Photos <https://wiki.gnome.org/Apps/Photos>`_
* `Calendar <https://wiki.gnome.org/Apps/Calendar>`_
......@@ -46,3 +43,5 @@ take a look at these touch friendly applications as examples:
Any touch friendly UI elements should be good for apps
on the Librem5.
.. _`application mock-ups`: https://gitlab.gnome.org/Teams/Design/app-mockups/
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