xmlns:uix="http://projectmallard.org/experimental/ui/"

      type="topic"

      id="popovers">

  <info>

    <credit type="author">

      <name>Allan Day</name>

      <email>aday@gnome.org</email>

    </credit>

    <link type="guide" xref="ui-elements"/>

    <uix:thumb mime="image/svg" src="figures/ui-elements/popover.svg"/>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  </info>

<title>Popovers</title>

A popover is a transient container that appears over its parent window in response to a user action. Popovers can contain a variety of UI elements, including buttons, lists or menus. They are often used as a part of button menus or context menus.

<media type="image" mime="image/svg" src="figures/ui-elements/popover.svg"/>

<section id="when-to-use">

<title>When to use</title>

Popovers can be used to reveal additional controls that are not always needed by the user. They can can allow the user to take actions or they can contain settings and preferences. They are a very flexible interface element that lend themselves to creative design solutions.

A popover should always relate to a specific interface element which acts as the source of the popover. Typically, this is either a button or a content item. When they are triggered by a button, a popover can be used as a more flexible version of a button menu, allowing groups of controls to be accessed when needed. Examples of this include:

<list>

<item>
Revealing a small toolbox of text formatting controls.
</item>

<item>
A find interface, with a search entry box and a space for a list of results.
</item>

<item>
A collection of view controls, such as zoom, list/grid and content ordering.
</item>

</list>

As a mechanism for disclosing additional controls or information, popovers are similar to <link xref="dialogs">dialog windows</link>. Their main advantage over dialogs is that they are less disruptive and have a close relationship with a single element which the popover points to. However, you should still consider using a dialog if you want to display large amounts of information, or more complex arrangements of controls, or if the situation requires one of the common conventions for dialog usage, such as a confirmation dialog.

</section>

<section id="popover-content">

<title>Popover content</title>

<list>

<item>
A popover is a generic container, and can include a wide variety of controls, such as buttons, sliders, lists, switches and text fields. However, don’t mix too many different types of control within the same popover, and try to group controls of the same type together.
</item>

<item>
Popovers can function as a container for a menu, or for a menu in combination with a small number of supplementary controls.
</item>

<item>
If the purpose of a popover’s controls is ambiguous, the popover can be given a heading.
</item>

<item>
<gui>Close</gui> or <gui>Done</gui> buttons are not usually required in a popover.
</item>

</list>

</section>

<section id="general-guidelines">

<title>General guidelines</title>

Popovers should always be small in size (as a rule of thumb, they should not cover more than a third of their parent window) and low in complexity. They should always appear as subordinates to their parent windows.

A popover should only ever appear in response to a user action, and should never appear in a surprising or unintended manner.

</section>

<section id="api-reference">

<title>API reference</title>

<list>

<item>
<link href="https://developer.gnome.org/gtk3/stable/GtkPopover.html">GtkPopover</link>
</item>

<item>
<link href="https://developer.gnome.org/gtk3/stable/GtkPopoverMenu.html">GtkPopoverMenu</link>
</item>

</list>

</section>

</page>