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 .tif 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 each.

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, extra signals to help bits inside a fileselection, tab-complete
environment variables.

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:
    ".jpg" 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
      changed from "fred.tif" to "fred.jpg"

- three signals added to help application parts enbedded within a
  fileselection
    * "new_dir" when fsb goes into a new directory
    * "new_file" when a file is selected
    * "refresh" when file and dir are maybe the same, but should be refetched
      (maybe a file has been added to the dir, or the user has changed the
      suffix).

- tab-complete environment variables
    * try '$HO' then TAB

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 filesel (?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?
- 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

* what about ".c" and ".C"? case-insensitivity should be switchable

* Can you put a togglebutton with "show dotted file"?

* It should be very nice to do multiple selections.

* On single-dir-change-click: >I don't like this very much, I'd like
* doubleklick: first highligth and
>second select.

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

Put gtkfilesel2.[hc] into your app src directory, in your 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
