<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="primary-windows">

  <info>
    <link type="guide" xref="patterns#primary"/>
    <desc>The main window(s) for your application</desc> 
    <credit type="author">
      <name>Allan Day</name>
      <email>aday@gnome.org</email>
    </credit>
    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  </info>

<title>Primary windows</title>

<media type="image" mime="image/svg" src="figures/patterns/primary-windows.svg"/>

<p>Primary windows are the basic high-level container for your application user interface, and should present the core functionality of your application.</p>

<section id="when-to-use">
<title>When to use</title>

<p>Every application should show a primary window when its launcher is activated. This includes applications that mainly provide a background service.</p>

</section>

<section id="application-types">
<title>Application types</title>

<p>There are two main models for primary windows:</p>

<section id="single-instance-applications">
<title>Single instance applications</title>

<p>Single instance applications have a single primary window. This model is common for messaging applications, such as email, chat, or contacts.</p>

</section>

<section id="multiple-instance-applications">
<title>Multiple instance applications</title>

<p>Multiple instance applications can have multiple primary windows. Typically, each primary window will be identical. Multi-instance applications are frequently viewers or editors, such as for documents or images.</p>

<p>Both single and multiple instance applications can allow multiple content items to be opened, either through the use of <link xref="tabs">tabs</link> or browser-style navigation. However, multiple windows do offer additional capabilities, which include:</p>

<list>
<item><p>Viewing several content items alongside each other.</p></item>
<item><p>Placing content on different workspaces.</p></item>
<item><p>Organizing sets of content into different windows (if using tabs).</p></item>
</list>

<section id="parent-child-primary-windows">
<title>Parent/child primary windows</title>

<p>Multiple instance applications typically have identical primary windows (in the case multiple web browser windows, for example). However, this is not always the case.</p>

<p>Primary windows can have a parent/child relationship. In this type of application, there is only ever one parent window. This typically contains an overview of content items which can be opened in the parent window, or in a separate child window. This allows multiple content items to be simultaneously open.</p>

<p>While child windows can only be opened through a parent window, they are not dependent on them in order to stay open: closing the parent window does not result in the closure of the application's child windows.</p>

<p>GNOME's <app>Notes</app> application is a good example of parent/child primary windows.</p>

</section>

</section>
</section>

<section id="general-guidelines">
<title>General guidelines</title>

<list>
<item><p>A single primary window should always be displayed when your application is launched.</p></item>
<item><p>If your application launcher is activated while your application is running, all its primary windows should be displayed.</p></item>
<item><p>Primary windows should host the main functionality of your application. Do not rely on dialogs or secondary windows in order to present basic functionality.</p></item>
<item><p>Primary windows should be independent — closing one primary window should not result in other primary windows being closed.</p></item>
<item><p>Dialog windows should always be dependent on a primary window. See the <link xref="dialogs">dialogs page</link> guidelines.</p></item>
<item><p>The guidelines on <link xref="display-compatibility">display compatibility</link> are particularly relevant for primary windows: be careful to ensure that they follow the advice on minimum display sizes, display orientation, and half-screen snap.</p></item>
<item><p><gui>Quit</gui> should close all primary windows.</p></item>
</list>

</section>

<section id="api-reference">
<title>API reference</title>

<list>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkWindow.html">GtkWindow</link></p></item>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html">GtkApplicationWindow</link></p></item>
</list>

</section>

</page>
