filesel notes

[Havoc Pennington <hp redhat com>]

Hi,

I got really sick of bugzilla today, and do think the filesel widget
is a very high priority post-GTK-2, so I went ahead and collected the
following data.

This document has _nothing_ to do with the UI, other than making sure
the API doesn't depend on it. So don't get excited about another
lengthy filesel thread about what buttons it has. ;-) This thread is
boring.

So the next steps after this discussion are: 

 - to draft a tentative GTK+ API, justifying that API in light of the
   appended information
 - design and implement the UI - discussion on usability gnome org
 - implement "plain filesystem" and "gnome-vfs" filesystem backends

The bugzilla bug on this is:
 http://bugzilla.gnome.org/show_bug.cgi?id=29087

Havoc

Possible Requirements, written before looking at prior art:

 a) UI design to be determined by UI team
    (includes keynav, what buttons there are, regular list or 
     icon list, is there a shortcuts bar, etc.)
 b) Choose a file to be loaded
 c) Enter a filename to save
 d) Choose a directory
 e) Possibility of different UI for load/save/directory modes,
    e.g. OS X has a pretty different dialog for saving
 f) Ability to insert a preview of the selected file/dir
    into the widget
 g) Ability to use the widget as a toplevel dialog or also embedded
    into a wizard or the like
 h) Ability to use the native platform file selector for
    GNOME/Win32/OSX/etc., or alternatively allow writing a
    per-platform filesel that emulates the native one closely.
 i) Allow filesel UI to be changed without breaking ABI/API
 j) Ability to use native MIME system, native icons, etc.
 k) Ability to use VFS with URIs 
 l) Ability to select multiple files
 m) Ability to supply a custom filter function for files to 
    be displayed

Survey of prior art:

 Winforms, Swing, and Qt all have pretty much the same UI for the
 dialog, the APIs aren't all that different either though there
 are different ideas on how to do some things.

System.Windows.Forms:

  http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformsfiledialogclasstopic.asp
  http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformsopenfiledialogclasstopic.asp
  http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemwindowsformssavefiledialogclasstopic.asp

  - Can't be embedded (at least not without ugly hacks), must be 
    in a dialog
  - Dialog is always modal
  - Different load/save dialogs, but most of the 
    API is shared, they have a common base class.
  - Has flag for whether to auto-append an extension to the 
    entered filename
  - Has flag for whether to warn if the chosen file does not 
    exist (not sure if it warns in the dialog or pops 
    up a separate dialog) 
  - Has flag for default file extension
  - Allows multiple file selection
  - get/set selected files
  - Optional help button 
  - Can set initial directory
  - Can set the title
  - Signals on Help and when closing dialog
  - Open dialog has an optional "open in read only mode" checkbutton
  - Save dialog can optionally do the "file foo does not exist, 
    create?" subdialog for you
  - Save dialog can optionally do the "file foo does exist,
    overwrite?" subdialog for you
  - Save dialog has an "open file" method that opens the 
    output file for you; thus the two subdialogs above

Qt:

  http://doc.trolltech.com/3.0/qfiledialog.html

  - Also dialog-only, no way to use inside another toplevel
  - Can use windows/OSX native dialog, but the docs make 
    it sound like this only happens if you use the 
    QFileDialog::getOpenFileName() API. Unclear.
  - API is mostly documented for modal use, but I think it can be used
    nonmodal
  - Uses a single dialog for load and save
  - Has these modes:    
    * QFileDialog::AnyFile - The name of a file, whether it exists
    or not.
    * QFileDialog::ExistingFile - The name of a single existing file.
    * QFileDialog::Directory - The name of a directory. Both files and
    directories are displayed.
    * QFileDialog::DirectoryOnly - The name of a directory. The file
    dialog will only display directories.
    * QFileDialog::ExistingFiles - The names of zero or more existing
    files.
  - Two kinds of preview:
    * QFileDialog::NoPreview - No preview is shown at all.
    * QFileDialog::Contents - Show a preview of the contents of the
    current file using the contents preview widget.
    * QFileDialog::Info - Show information about the current file
    using the info preview widget.
  - Optionally displays file metadata:
    * QFileDialog::List - Display file and directory names with
    icons.
    * QFileDialog::Detail - Display file and directory names with
    icons plus additional information, e.g. file size, modification
    date.
  - Method to reload the directory
  - Can choose to show hidden files or not
  - Can set the selected file
  - Can selectAll()
  - Can add filters as a glob (e.g. *.png) to appear 
    in the filters option menu. The API is kind of 
    strange, since the same string seems to be both 
    parsed as a glob and displayed to the user; 
    don't understand how i18n works
  - Can add a widget "on the right side of the dialog" (this 
    is separate from the preview feature)
  - Can addToolButton() to add a new button to the toolbar
  - Can add three widgets to the bottom aligned with the 
    existing three widgets along the bottom
  - Signal when the user changes directory
  - Signal when the user highlights a file
  - Signal when the user changes filter
  - When getting the selected files, can optionally 
    resolve symlinks before handing them back, 
    and can optionally get only existing files

Swing:

  http://java.sun.com/j2se/1.4/docs/api/javax/swing/JFileChooser.html
  http://java.sun.com/docs/books/tutorial/uiswing/components/filechooser.html  
  http://java.sun.com/j2se/1.4/docs/api/javax/swing/filechooser/FileView.html
  http://java.sun.com/j2se/1.4/docs/api/javax/swing/filechooser/FileSystemView.html

  - Also dialog-only 
  - Also modal at least normally 
  - Can have a preview widget on the right
  - Has custom filters in the filter dropdown
  - Can do previews/thumbnails for each file in the file list, 
    not just the selected file in a special widget. 
    i.e. can basically override the icon for each file with 
    a thumbnail.
  - More flexible/pluggable filtering than Qt (apparently, 
    I could be confused)
  - The Java look and feel (equivalent to the theme) 
    can I believe plug in different file icons, and 
    rearrange the widget itself
  - There's an isTraversable() method you can override
    that prevents entering certain directories, I believe this 
    is intended for NeXT-type directories that are supposed to 
    look like single objects to users
  - Modes are: FILES_ONLY, DIRECTORIES_ONLY, FILES_AND_DIRECTORIES
  - Has multiple/single modes
  - "Scroll to" method to force a certain file to be visible
  - Rescan directory method
  - Has a setDragEnabled() to turn on DND support. I'm not sure 
    what the DND support does.
  - Pluggable "get file metadata" object (FileView)
  - Pluggable filesystem object (FileSystemView)


Thoughts:

  Java's FileView and FileSystemView objects are essentially the
  answer to "how do we support win32/gnome-vfs/etc. file metadata and
  filesystems with the GTK filesel".  However for simplicity it makes
  sense to me to merge these two, i.e. FileSystemView could just have
  a get_icon_for_file() method etc.

  FileSystemView interface should by no means contain all 
  of gnome-vfs; it is just the bare essential high-level 
  operations to display files, such as listing files, changing
  directory, getting file metainfo.

  FileSystemView might implement the GtkTreeModel interface?

  I believe Qt exposes the layout and contents of the dialog in the
  API more than we would like. For example it doesn't look like you
  could wrap the OS X Save dialog very well with their API.

  GTK should have both get_selected_uri() and get_selected_file()
  methods on the widget; for the default implementation,
  get_selected_uri() would always return a file: URI, but if you were
  using gnome-vfs you'd potentially get a remote URI.

  We need to figure out how the implementation to be used will be
  determined and loaded. It is some combination of a) platform
  (including gnome-vfs as a platform) and b) user preference.  It's
  also possible to mix-and-match the "model implementation"
  (FileSystemView) and "view implementation" (the filesel dialog).

  No one else supports using the filesel outside of a dialog, 
  and allowing that might impede the use of native widgets e.g. 
  on Windows, so maybe we shouldn't have that as a requirement.

  I don't like the Qt "magic strings" filter API that seems to combine
  the user-visible and programmatically-parsed string, but setting the
  filter as a glob does seem important. Setting a callback function as
  filter is also important, and maybe setting a MIME type as a
  filter. How could we implement an easy API for something that spans
  multiple MIME types or extensions, such as "image files"?

  I'd make the default implementation of the widget totally private; 
  i.e. it is not part of the public API as GtkListStore is, you can 
  only access the abstract interface.