Gramps 5.1 Wiki Manual - Main Window

From Gramps
Jump to: navigation, search
Previous Index Next

Elements of Gramps main window or
A Visual Guide to the Gramps Interface.

Graphical User Interfaces (GUIs) are a way of arranging information on a computer screen that is easy to understand and use because it uses icons, menus, and a mouse rather than only text.

While a GUI is much more intuitive than memorizing keyboard commands, it is hard to learn from the feature documentation without knowing the feature’s name to lookup. Many elements are not labeled in Gramps to reduce clutter and maximize space for displaying Genealogical information. There are even preference options to not show text labels for the buttons (icons) in the Category Navigator panel.

So this section of the Wiki Manual gives the standardized names of Gramps screen elements. Armed with the standard names, you can more efficiently use a search engine (like Google) to find pages in the online manual that discuss that element. As an example, to search for Gramps Wiki Manual pages on the "Navigator Mode" phrase, use following the Google search terms:

  "navigator mode"

This particular search even finds descriptively named illustrations of selecting the modes for the Navigator sidebar. Selecting one of those images shows a webpage about the illustration and where it is used in the documentation. Those illustrated pages tend to have greater introductory material.

If a particular screen element does not appear among the images below, look through the Gramps Screenshot Gallery. This page shows the Gramps thumbnail screenshots that are used throughout the documentation. Click the thumbnail image to show the full sized image and variants of that image, then scroll down to the "File usage" section to find Wiki pages that illustrate the features within that screenshot. Likewise, the Gramps Icon Gallery identifies the proper names of icons used throughout Gramps.

Once you are familiar with the screen elements, explore the keybindings or hotkeys to learn the shortcuts for features used so frequently that keyboard shortcuts have been created.

Main Window

When opening a (new or existing) Family Tree database, the introductory Gramps Dashboard window will be shown in the "Display Area" with the Sidebar and Bottombar hidden. Upon selecting the People Category from the Navigator, the Main Window layout will updated to show the "Person (List) View" in the "Display Area". See Fig. 3.1:

Fig. 3.1 Annotated Main Gramps window parts, showing the People Category - People Tree View - example using the Grouped People option

The main Gramps window contains the following elements:

Window Title Bar

  • Window Title Bar shows the name of selected Family Tree, the name of the Category view, Gramps application name and buttons to minimize, maximize and close Gramps. The window can also be dragged from the Title Bar.


  • Menubar: The menubar (Main Menu) is located at the very top of the window (right below the window title) and provides access to all the features of Gramps.
  • Menus are contextual - the options shown depend on which category is active.
  • Clicking a menu's header label opens that particular submenu. Submenu items may be dimmed (unavailable) if they are not usable with the active item.

Typographically, Menu selections will look like this in the wiki manual: Menu -> Submenu -> Menu Item.

Visibility of elements

Using the View menu, you can hide or unhide several elements of Main Window.
In addition, there are Preference option to hide or reveal aspects of the elements -- such as text labels, scrollbars and Close gadgets.

Pull-down menus

Fig. 3.2 Gramplet Bar Menu the unlabeled Down Arrowhead pull-down menu button

Outside the menubar, the occurrence of the Gramplet Bar Menu an unlabeled Down Arrowhead pull-down menu button indicates additional options are available for the interface item to its left.

Pop-up menus

Fig. 3.3 Clipboard - with example contextual pop-up menu from right-clicking a Family

The most invisible interface option might be the contextual pop-up menu (aka "context menu").

Right-clicking an interface item (or on a selected record row in a table) will reveal a pop-up menu of shortcuts to some frequently useful features for that item (or record).

Note that the right-clicking on row in a table other than the selected (high-lighted or 'active') row still reveals the pop-up menu related to the selected row. So, left-click the row first to select then right-click for the menu.

Fig. 3.4 Person Editor - with example contextual pop-up menu from right-clicking the empty header space

Right-clicking on objects is a familiar theme in GUIs. But right-clicking in the empty header space of any Object Editor is less obvious. However, this right-click will reveal another contextual pop-up menu with other shortcuts to useful reporting and navigation options.


  • The Toolbar is located right below the menubar. Its buttons give faster access to the most frequently used functions for the active screen of Gramps.
  • The assortment of toolbar buttons is context sensitive. Which Tools are shown depends on which category is active. And only the buttons for submodes of the currently selected view category are included in the toolbar.
  • ⚙ Configurable Options: most Category views have a Gramps-config.pngConfigure... button as an alternative to choosing the View > Configure... from the View menu, or pressing the Configure active view keyboard keybinding. This option opens a dialog with choices for customizing the display records in the View. Basic customizations might include choice of sorting order and choice of whether to display specific details.
  • Configuration customizations are persistent. They are carried over to future sessions using Gramps.
  • Hovering over a toolbar icon shows a tip of its function
Fig. 3.5 Tip for the Tools button of the Dashboard category toolbar

The Toolbar can be hidden or revealed by the option in menu View ->Toolbar.


allows Gramps to show toolbar text labels for each Toolbar button. The Themes addon augments the Preferences dialog with a Theme tab.

One of options of the Theme tab is a ☑ Toolbar Text checkbox. Selecting the checkbox causes the text labels to appear.
This checkbox isdeselected by default.

Fig. 3.6 Added Theme tab options for the Preferences dialog.


  • Navigator: The navigator is an optional sidebar located at the left of the window and allows selection of the different categories. See Categories of the Navigator
The Navigator is shown by default but this sidebar can be optionally hidden or revealed from the menu View ->Navigator or the keybinding CTRL+M. ( Cmd+M on MacOS.)

Also see:

  • Switching Navigator modes
  • You can hide the text labels by deselecting the ☑Show text label beside Navigator buttons option in the Edit -> Preferences Display tab.
  • Navigator sidebar features (View categories, View Modes, and Navigator interface styles) can be added, removed, hidden or revealed using the Plugin Manager.

Display area

Status Bar and Progress Bar

  • Status Bar and Progress Bar: These are located at the very bottom of the Gramps window.
    • The Progress Bar is located in the lower left corner of the Gramps window. It displays the progress of time consuming operations, such as opening and saving large Family Tree databases, importing and exporting to other formats, generating web sites, etc. When you are not doing these types of operations, the Progress Bar is not shown.
    • The Status Bar is located to the right of the Progress Bar. It displays information about current Gramps activity and contextual information about the selected items. (You can also edit the Display Preferences to show the Active Person's Relationship to the home person.)
    • The Status Bar may occasionally show a passing alert, warning of unusual conditions. An informative Warning button with a superficial summary (like the one below) will be displayed for three minutes at the left of the Status Bar. Clicking this lightbulb icon will show details of these minor alerts.
Fig. 3.7 Gramps Main Window showing Warning button on the Status Bar

Bottombar and Sidebar

The Gramplet Bar is also known as the Bottombar and Sidebar.

  • Bottombar: The bottombar is located below the display area.
  • Sidebar: The sidebar is located to the right of the display area.

The Bottombar and Sidebar can be individually hidden or revealed by options in menu View or the relevant keybinding. If the Sidebar is hidden the Search bar will be displayed.

The Bottombar and the Sidebar allow Gramplets and filters to be displayed alongside a view.

Gramplet Bar Menu

Fig. 3.8 Location of Gramplet Bar Menu unlabeled Down Arrowhead (∨) Add/Remove/Restore Gramplets Menu

You can also add / remove and restore the default Gramplets by clicking the (Down Arrowhead button) also known as the Gramplet Bar Menu at the far top right of the bars titles, and then using one of the options from the drop-down menu eg:

  • Gramplet Bar Menu
    • Add a gramplet - Displays a list of Gramplets available for use on that Gramplet Bar
    • Remove a gramplet - Displays a list of Gramplets currently shown on the Gramplet Bar available for removal.
    • Restore default gramplets - Displays the Restore to defaults? confirmation dialog, that allows you to restores the Gramplet Bar to its default Gramplets.

Restore to defaults? dialog
Fig. 3.9 Restore to defaults? dialog

The Restore to defaults? dialog, allows you to restore the Gramplet Bar to its default Gramplets. This action cannot be undone. Select OK to confirm or select Cancel.

Search Bar

Fig. 3.10 People Category View - showing Search Bar after Sidebar has been hidden

If the Sidebar is not displayed in a Category view with a list, then the Search Bar is displayed instead. Available search options vary depending on Category View you are in. But a visible sidebar makes the Search Bar Invisible.

Fig. 3.11 People Category View - showing the sidebar superseding the Search Bar

A Search Bar is available for the following Views and the Select windows for the following Categories: People, Relationships, Families, Events, Places, Sources, Citations, Repositories, Media, Notes. Not Available in the following Category Views: Dashboard, Relationships, Charts, Geography.

Typing the characters into the Search Bar and clicking the Find button will display only lines that match the text.

Note that various Selectors also have search bars:

Fig. 3.12 Family Selector - showing Search Bar

Switching Navigator modes

Fig. 3.13 Navigator mode selection drop down list

You can choose the navigator mode from the sidebar Category drop down list:

When labels have been disabled for the Navigator in Preferences, this Category drop-down list control becomes the widest object. Its width limits how narrow the sidebar may be resized. The control can be made to disappear by using the Plugin Manager to hide (or remove) all but your single preferred Navigator sidebar mode. (When only one mode remains unhidden, there is no need for a menu and it will also become hidden.)

Category navigator mode (default)

Fig. 3.14 Category (default) Navigator mode

Category Sidebar - A sidebar to allow the selection of view categories.

Expander navigator mode

Fig. 3.15 Expander navigator mode

Expander Sidebar - Selection of views from lists with expanders arrows.

Drop-Down navigator mode

Fig. 3.16 Drop-Down navigator mode

Drop-down Sidebar - Selection of categories and views from drop-down lists.

Switching Categories

Gramps comes with number of different standard View categories built in, each of which has one or more standard View modes. The built-in categories are described in the introduction to the Categories of the Navigator.

Expanding the Views

You can download addon a 'Gramps View' in the General tab Preferences menu (or activate or remove previously downloaded Addon Views) via the Plugin Manager.

  • If the view is a new mode (subcategory), the toolbar, menus and Navigator mode lists are modified to give access to the new layout.
  • If it is a View of a existing category, then the view layout is replaced for that category.
  • If it is a new category of view, then an entire new visualization will be added with an additional icon appended to the navigator selections.

The way you change the currently displayed category depends on the navigator mode. Normally (for most navigator modes) you can select the category you want by clicking one of the navigator icons.

Alternatively you can use the keyboard shortcuts CTRL+N and CTRL+P ( Cmd+N and Cmd+P on a Mac) go to the next or previous category respectively or use keyboard shortcuts CTRL+Alt+<number> ( Cmd+ Opt+<number> on a Mac) Shortcut are only available for the first 10 categories (e.g. Repositories/Media/Notes categories miss out on shortcuts.) If you have hidden the Navigator then shortcuts will be the only way to change categories until you turn the Navigator on again.

Switching Views

A View category can contain different ways of presenting the data, called a View mode. If there are several viewing modes, you can switch between modes interactively. The way you change between the modes depends on the Category View. The Configuration options for each mode are independently controlled.

In Views styled in tables of data with rows and columns, the modes are typically between a hierarchically grouped outline or a simple single-level sortable list. Table style view modes are configured with the Column Editor and have have sorting options.

In some graphical Category Views (like Charts and Geography) there may be a wide variety of viewing modes.

Fig. 3.17 Navigator sidebar in Expander mode

When there are multiple viewing modes, will be additional icon buttons on the toolbar to switch between those different viewing modes.

You can also switch via the View menu, or the View menu keybindings by pressing Ctrl+Alt+<number> (for Linux & Windows) or Cmd+Alt+<number> (for MacOS), where <number> corresponds to the order of viewing modes listed in the category's View menu.

Modes are also selectable from the Navigator sidebar when using the Drop-down or Expander arrangements. The Navigator sidebar defaults to the Category arrangement which has no mode selector. Using the Drop-Down or Expander mode makes the additional viewing modes available as Navigator icons.


Fig. 3.18 Filter Controls Displayed

Genealogical databases can contain information on many people, families, places, and objects. That means it is possible for a View to contain a list of data so long that is difficult to navigate. Beyond the basic seek-as-you-type Find box for precision navigation of the list, Gramps gives you two different means for filtering a list to a more manageable size.

These methods are Search and Filtering.

A search will search the text displayed in list, whereas filters display people whose data match the criteria of the filter.

Search is a simple but fast method of searching the columns displayed on the screen. When the sidebar is not displayed, the Search bar is displayed. Typing the characters into the Search bar and clicking the Find button will display only lines that match the text.

Alternatively, you can enable a filter in either the bottombar or the sidebar. When the filter sidebar is displayed, the Search bar is not displayed. The Filter allows you to interactively build a set of filter rules that can be applied to the display. The filter is applied based on the rules and the data, not on the screen display. Filters of the displayed category can also be constructed by clicking on the corresponding 'editor' button in the Edit menu.

Further details of how filters work is given in the Filters Chapter

Searching vs. Filtering

Searching only searches for exact text matches. If the date displayed is "Jan 1, 2000", a search of "1/1/2000" will fail, but a filter of "1/1/2000" will match because it matches the date value rather than the formatted date.

When Gramps opens a Family Tree, no filtering is in effect. In People View, for example, all people in the Family Tree are listed by default.

Troubleshooting a misbehaving interface

If your Gramps GUI is behaving contrary to the manner described in this guide, you may have an installation or minor compatibility issue.

It is likely that the behavior has been seen before and a solution has been identified.

Please review the Troubleshooting pages. If you are unable to discover the solution there, post a description of the problem to the general Gramps community on our user maillist. We help each other constantly there.

Previous Index Next
Gnome-important.png Special copyright notice: All edits to this page need to be under two different copyright licenses:

These licenses allow the Gramps project to maximally use this wiki manual as free content in future Gramps versions. If you do not agree with this dual license, then do not edit this page. You may only link to other pages within the wiki which fall only under the GFDL license via external links (using the syntax: []), not via internal links.
Also, only use the known Typographical conventions