Need suggestions for documenting the GTK file chooser

The idiosyncracies of the GTK file chooser 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. 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) 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 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…? 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 for Linux, Windows & macOS OSes
  • URI & network support differences between OSes
  • themes and the GUI
  • switching between breadcrumbs & 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
  • 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 (hotkeys, keyboard shortcuts)
  • persistent paths
  • link to developer docs (GTK generic & 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

What else?

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. 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.) 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.

@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?

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 regarding the WikiMedia hangups?

Sam has mentioned a testbed WikiMedia site before.

DaleAthan’s talk page had a note about Lua scripting, Sam888’s talk page (User talk:Sam888 - Gramps) 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.

1 Like

Have added a bare reference style subsection in the Settings chapter 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.

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:

  • 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:

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 perform the action upon a click on a selected item. A much fussier implementation that makes unintended actions very likely…