# Need suggestions for documenting the GTK file chooser **URL:** \ **Category:** Help\ **Created:** [September 13, 2021, 12:50pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820 "2021-09-13T12:50:29Z")\ **Posts on this page:** 10\ **Page:** 1
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [September 13, 2021, 12:50pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/1 "2021-09-13T12:50:29Z")
The idiosyncracies of the **[GTK file chooser](https://people.gnome.org/~ryanl/gtk/html/GtkFileChooserDialog.html)** used throughout Gramps has sparked confusion leading to a number of support issues. I know that the feature needs to be fully documented in its own wiki page. [now has a [File Chooser](https://gramps-project.org/wiki/index.php?title=Gramps_5.1_Wiki_Manual_-_Settings#File_Chooser) subsection on the Setting page] Nuggets of information are scattered, there is conflicting & incomplete introductory material in different places. It has to be consolidated and introduced in a structured way. Then the wiki has to be searched and cleaned so that all references (including the linking into a [new GUI Gramps Glossary entry](https://gramps-project.org/wiki/index.php/Gramps_Glossary#graphical_user_interface)) point at the new consolidation. But it will be such a different page that I’m waffling over HOW it should be structured. I need thoughts & direction. (There’s already a missing page hotlinked added in the latest revision to the [`example.gramps`](https://www.gramps-project.org/wiki/index.php/Example.gramps) page. So building a page has to be hurried before someone creates a sketchy patchwork just to fix the broken link.) It might follow the [How do I…?](https://gramps-project.org/wiki/index.php/Write_a_%22How_Do_I...%22_Article) tutorial template. But I’d like it to be cleaner and far less complex. I know that it needs to cover: - [GUI differences between Dialogs](https://gramps.discourse.group/t/macos-and-windows-gtk-file-chooser-dialog-capture-request/3364) for [Linux](https://www.gramps-project.org/wiki/index.php/File:Importfamilytree-dialogLinux-51.png), [Windows](https://www.gramps-project.org/wiki/index.php/File:Importfamilytree-dialog-51.png) & [macOS](https://www.gramps-project.org/wiki/index.php/File:Importfamilytree-dialogMac-51.png) OSes - URI & network support differences between OSes - themes and the GUI - switching between [breadcrumbs](https://gramps-project.org/wiki/index.php?title=Gramps_5.2_Wiki_Manual_-_Settings#Breadcrumbs_and_text-entry_address_bar) & filepaths (including changing the default) - relative paths for User Data & application data - the difference between GTK file chooser and and OS file chooser - [customizing bookmarked folders](https://gramps-project.org/wiki/index.php?title=Gramps_5.2_Wiki_Manual_-_Settings#Bookmarking_file_folders) - location & filename of the Bookmark GTK .ini for the dialog - resetting to factory defaults - cross pollination between GTK driven applications and customizations of the file chooser - [keybindings](https://gramps-project.org/wiki/index.php/Gramps_5.2_Wiki_Manual_-_Keybindings) (hotkeys, keyboard shortcuts) - persistent paths - link to developer docs ([GTK generic](https://python-gtk-3-tutorial.readthedocs.io/en/latest/dialogs.html#filechooserdialog) & Gramps specific) - a mention of why Gramps uses the generic GTK File Chooser instead of the GTK option of a Native File Chooser for each OS - bookmark/shortcut/volume information in Feature Request [0011623: Change Open/Save shortcuts for some standard file locations](https://gramps-project.org/bugs/view.php?id=11623) - [Sort order](https://gramps.discourse.group/t/macos-and-windows-gtk-file-chooser-dialog-capture-request/3364) (files and folders separately and by name or by last changed) What else? ---
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [September 13, 2021, 1:40pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/2 "2021-09-13T13:40:01Z")
By the way, this GTK file chooser document is for missing foundation material needed for improving the `example.gramps` documentation. And that document improvement was needed before fixing the beginner Import & experimentation documentation. Every time work begins on improving the New User experience, foundation material is discovered to be missing. The most frustrating piece that is missing are the absent [GUI icon illustrations](https://www.gramps-project.org/wiki/index.php/Template:Icon). Without them, describing use of the GUI is incredibly painful. (And that pain is multiplied dozens of times … for each of those icon verbal metaphors have to be translated.) But the process for filling them in is undocumented. And we’ve got a roadblock in getting that resolved. The implementer of the template has determined the wiki needs a new technology… so filling the current template in will require a lot of work that would be discarded. (Plus the [current template puts undue burden on the server](https://gramps.discourse.group/t/lost-icons-in-the-wiki/1282).) But the new tech requires webmaster do significant (and RISKY) work in iterative updates to the 2018 vintage MediaWiki installation. And those updates are NOT cooperating. ---
**Author:** ![codefarmer](https://avatars.discourse-cdn.com/v4/letter/c/b9e5f3/32.png) [@codefarmer](https://gramps.discourse.group/u/codefarmer)\ **Post date:** [September 25, 2021, 10:39pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/3 "2021-09-25T22:39:19Z")
@emyoulation Adding a wiki page blocked by a migration of MediaWiki…talk about following the rabbit! Curious, is the migration work broken down to a point where someone could help with the tasks? What skills would be required to be able to help? ---
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [September 25, 2021, 11:21pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/4 "2021-09-25T23:21:07Z")
I am unaware of what skills may be needed to upgrade the MediaWiki installation so that the Lua script support can be added which which, in turn, will support the new icon template. (Of course, missing Gramps icons aren’t the choke point for the “GTK file chooser” user doc wiki page. I am just having problems envisioning a form for that page that would be useful without being overly complex.) Perhaps you want to join the conversation with @Daleathan and @sam888 on [Daleathan’s talk page](https://www.gramps-project.org/wiki/index.php/User_talk:Daleathan) regarding the WikiMedia hangups? Sam has mentioned a testbed WikiMedia site before. ---
**Author:** ![codefarmer](https://avatars.discourse-cdn.com/v4/letter/c/b9e5f3/32.png) [@codefarmer](https://gramps.discourse.group/u/codefarmer)\ **Post date:** [September 25, 2021, 11:50pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/5 "2021-09-25T23:50:03Z")
DaleAthan’s talk page had a note about Lua scripting, Sam888’s talk page ([User talk:Sam888 - Gramps](https://www.gramps-project.org/wiki/index.php/User_talk:Sam888)) had notes on the wiki upgrade issues. Looks like Sam888’s last note in July 2021 was to research the option to install the latest version and then copy all existing wiki pages over. Perhaps that deserves a separate thread if @sam888 has more information on it. ---
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [March 11, 2023, 4:54pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/8 "2023-03-11T16:54:51Z")
> [@emyoulation](#): > > I know that the feature needs to be fully documented in its own wiki page. Nuggets of information are scattered, there is conflicting & incomplete introductory material in different places. It has to be consolidated and introduced in a structured way. Have added a [bare reference style subsection in the Settings chapter](https://gramps-project.org/wiki/index.php/Gramps_5.1_Wiki_Manual_-_Settings#File_Chooser) as a starting point. The File Chooser dialog capture for Fedora Linux and macOS have been posted in the following thread. But we still need the Windows version and for users of other Linux distributions to verify their variants do not have other significant differences. > [@macOS and Windows "GTK File Chooser" dialog capture request](https://gramps.discourse.group/t/macos-and-windows-gtk-file-chooser-dialog-capture-request/3364): > > Could a macOS and a Windows user post a window capture of the Import dialog (drilled down to the Example CSV and back up to the breadcrumb containing “example”) folder in a standard install of Gramps and with the Example folder clicked and the context menu showing? For Linux (Fedora), the final image (I will add the post-process hightlighting of the breadcrumbs and context menu option) looks like this: The File Chooser and path to example files (including Example.gramps and its media… ---
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [August 30, 2022, 2:29pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/9 "2022-08-30T14:29:22Z")
Note that if you decide to use an InBox or Media GTK File Chooser, you can set a button on that chooser to shortcut any saved filepaths: > **[Gtk.FileChooser](https://docs.gtk.org/gtk3/iface.FileChooser.html)** > > Reference for Gtk.FileChooser - **Bookmarks:** are created by the user, by dragging folders from the right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user. - **Shortcuts:** can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user. - **Volumes:** are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem. See also: [https://lazka.github.io/pgi-docs/Gtk-3.0/interfaces/FileChooser.html#Gtk.FileChooser.add\_shortcut\_folder](https://lazka.github.io/pgi-docs/Gtk-3.0/interfaces/FileChooser.html#Gtk.FileChooser.add_shortcut_folder) ---
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [November 13, 2022, 4:55pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/10 "2022-11-13T16:55:42Z")
There’s a another click behavior idiosyncrasy in Gtk’s File Chooser. In most file choosers, double-click initiates the dialog’s action (open, save, import, etc.) but the [`Gtk.FileChooser`](https://docs.gtk.org/gtk3/iface.FileChooser.html) perform the action upon a click on a selected item. A much fussier implementation that makes unintended actions very likely… ---
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [June 3, 2026, 2:44pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/11 "2026-06-03T14:44:57Z")
> [@emyoulation](#): > > - **Shortcuts:** can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user. Since the Gtk File Chooser allows setting Shortcuts specific to each application, perhaps a shortcutting option could be added to each of the “path” options in the Preferences → Family Tree dialog? And maybe a path to the Examples could be added to that Preferences? As an example, automatically add the **Family Tree’s Media path** from preferences ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/e/e8f7fb48535a240e2b01f8679937a7d25194705b.png) To the GTK File Chooser Shortcuts. (Every time a path is reset in Preferences, either reset that associated Shortcut to automatically sync… or add a button to the right of the folder button to set a GTK shortcut.) ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/1/14ed1ddef2c6df7a114130d2a8f7f1875c3cb6ab.png) There are lots of icons in the Themes and that are bundled with GTK that we could use to decorate the Preferences (Which tends to attract attention and invite more experimentation) : ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/1/1e390b32196eae1f1dc95647ecb097db36289244.png) ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/0/0eb094f054d13dfa5223a7ed8fda6622f7e8a837.png) ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/5/50b5f5d9f5b48b4ec9fcd7be73cba52ae24ed5ae.png) ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/0/0615e06364ad75c6ea57cf0c9f46a1fbcfd0bffa.png) ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/f/f8874bf07cebde65ae00acd941738f9eb6a4f0d9.png) ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/e/e578ff7ea99c717748ef309889171ca7b4a65c7d.png) _PS. The icon browser is a bit of a **Rabbit Hole** for developers. You can burn through a lot of valuable time exploring 2,500 icons._ ---
**Author:** ![emyoulation](https://yyz2.discourse-cdn.com/free1/user_avatar/gramps.discourse.group/emyoulation/32/67_2.png) [@emyoulation](https://gramps.discourse.group/u/emyoulation)\ **Post date:** [June 3, 2026, 3:12pm UTC](https://gramps.discourse.group/t/need-suggestions-for-documenting-the-gtk-file-chooser/1820/12 "2026-06-03T15:12:19Z")
It is also an option to add Shortcuts _on-the-fly_ for an appropriate paths from the Gramps Constants For example, the folder for the `HOME_DIR` is ‘hidden’ on the following system. And some maintenance features might want to help a user explore what is stored there. (Such as the geographical map tiles folder or the temp folder. Or a developer might want to see if their new experimental plug-in is polluting the file structure.) Here, the experimental **Environment Inspector** gramplet has `folder-symbolic` icons allowing a browse of any of the constants Directories and the `view-conceal-symbolic` icon indicates if they are ‘hidden’ at the OS level or `view-reveal-symbolic` revealed. ![image](https://global.discourse-cdn.com/free1/uploads/gramps/original/2X/2/2bfa0de0b38e8482348d22fc3622d2be6f63c11d.png)