new file selection box

[john giorgio hart bbk ac uk]

Hiya, people with long memories might recall some debate a week or so ago
about tarting up GtkFileSelection. I've had a stab at it (took *cough* longer
than I thought), if you're interested, take a peek at:

	http://giorgio.hart.bbk.ac.uk/~john/gtkfilesel2/

I'll gather comments/fixes for a couple of weeks, and if I get enough positive
feedback from gtk gtkurus, I'll submit this stuff as a patch for the official
distribution. If you have any stuff to add (flames etc. are welcome), email me
at:

        john@giorgio.hart.bbk.ac.uk

Here's the README:

--
Rationale:
==========

gtk_file_selection is nice (tab-completion is just great), but the directory,
filename, and extension are all edited together in one gtk_entry. It's hard to
change one without changing the others as well.

For example, an application might pop up a save box and be able to suggest a
sensible filename (maybe the name of the last thing the user loaded). Now if
the user wants to click into another directory to save the new version of the
file there, they are going to destroy the filename and will have to retype it.

Similarly, with the old gtk_file_selection, you can type *.tif into the entry
and press tab to see all the .tiff files, but you have to delete the filename
to do this.

The idea of this change to gtk_file_selection is to break the old file name
entry into three separate parts: a directory, a file name and an extension
set.  You can change them independently and applications can offer sensible
defaults for them.

There's a bunch of new stuff to handle files-of-type filtering. You can now
specify a filter through which all displayed files must pass. The default
filter (it's really simple) just tests whether a file has one of a set of
suffixes (eg. ".tif", ".tiff"), where the suffix set is specified by changing
an option_menu above the dir list. You can specify an alternative filter
yourself and override these controls if you want to do something better.

I've made a few other smaller changes too: directory history, single-click
navigation in file select mode, new refresh function, automatic suffix
stuff.

Done:
=====

- combo box at top
  * displays fs->history_list (most recent dir at top)
  * your app can add useful dirs to fs->history_list (eg. 
    "/usr/local/myapp/tutorial") with gtk_file_selection2_update_-
    history_menu()
  * filename completion stuff cleaned up
  * can use completion in top or bottom entry boxes, improved feedback for
    non-existent directories etc.

- new label widget above combo shows current directory and error messages
  * fs->selection_text is still there is you want to change it

- in file select mode (ie. GTK_WIDGET_VISIBLE (fs->file_list->parent)):
  * single click in directory list to change directories
  * doubleclick does nothing

- in dir select mode (ie. !GTK_WIDGET_VISIBLE (fs->file_list->parent)):
  * single click in dir list copies dir name to fs->selection_entry
  * doubleclick moves into directory

- use gtk_file_selection2_refresh() to force a reread of all files etc.
  * if your app has just written a new file, you might want to refresh any fs
    dialogs on the screen

- files-of-type option_menu above dir list
  * hidden by default ... use gtk_file_selection2_show_file_types() and
    gtk_file_selection2_hide_file_types() to add and remove
  * use gtk_file_selection2_set_file_types() to set a list of suffixes
    to allow ... associate a text description with each suffix set. 
    Example:

       {{"TIFF image files (*.tif; *.tiff)", {".tif", ".tiff", NULL}},
        {"JPEG/JFIF image files (*.jpg; *.jpeg)", {".jpg", ".jpeg", NULL}},
        {"All files (*)", {"", NULL}},
        NULL}

  * suffix used to select files displayed in file list, provided you've
    called gtk_file_selection2_set_file_types() and 
    gtk_file_selection2_show_file_types()
  * case-insensitive, so ".TIFF" will match too
  * use gtk_file_selection2_set_file_type() to set the current type ...
    example: gtk_file_selection2_set_type (fs,1); picks show-JPEG-files in 
    the example above
  * use gtk_file_selection2_get_file_type() to get the current type ...
    example: returns ".jpg" using example above ... not necessarily the 
    same as the actual file extension!
  * call gtk_file_selection2_set_filter() to replace the file name filter 
    with one of your own

- automatic filename extension mangling
  * only if files-of-type stuff is turned on
  * example: files-of-type is changed from TIFF to JPEG/JFIF, file name
    automatically changed from "fred.tif" to "fred.jpg"

Other stuff:
============

- 'dot' files and directories
  * as before, add a dot to the end of the pathname and hit Tab to see dirs
    and files starting with a '.'

- compatibility
  * by default, no new stuff visible, except the combo box for pathnames
  * sizeof (GtkFileSelection2) has grown, but new stuff is all at the end,
    so we may have binary compatibility, provided users haven't subclassed
    off gtkfilesel (?is this right?)

Questions:
==========

- is the single-click-dir-change a good idea? It means the filesel has to
  behave differently in dir-select mode, which might be confusing.
- GtkFileSelection2FilenamePredicate is only given file names, not whole
  paths, and not dirs. Is this a good idea?
- I decided against adding $NAME expansion, this is maybe confusing and
  better in the app layer. 
- You can get odd effects with files-of-type stuff. Example: if you have
  bizarre files called ".tiff.jpg". Is this a problem?

To do:
======

* click ".." in dir list, move up, leave old current dir selected in 
  new dir list

* test old API stuff more carefully

* test fileop stuff

* live with it a bit and see if it starts to grow or annoy

Compiling:
==========

Put gtkfilesel2.[hc] into your app src directory, in your app sources 
globally susbstitute:

        :1,$s/gtk_file_selection/gtk_file_selection2/g
        :1,$s/GtkFileSelection/GtkFileSelection2/g
        :1,$s/FILE_SELECTION/FILE_SELECTION2/g

You'll need to add -I$(GTKHOME) to your cc line as well. This is because
gtkfilesel2.c is not being compiled in the gtk+ area (as it rightfully
expects), and it needs to be able to #include "config.h"

You can add it to your gtk+ area as well (not recommended) if you change the
#includes at the start of gtkfilesel2.c. There are comments there to guide
you.

I've based this on the file_select in gtk+-1.2.1. I've tested it with
gtk+1.2.0, 1.2.1 and 1.2.2 on solaris and red hat.

I'll gather comments for a couple of weeks, and if I get enough positive
feedback from gtk gtkurus, I'll submit this stuff as a patch for the official
distribution. If you have anything to say (even flames are welcome), email me
at:

        john@giorgio.hart.bbk.ac.uk

Fri Apr 23 15:58:42 BST 1999
--
John Cupitt, john.cupitt@ng-london.org.uk, +44 (0)171 930 2108
VASARI Lab, The National Gallery, Trafalgar Square, London, WC2N 5DN