File custom dialog box for cygwin
=================================

Provides a file selector dialog box which works using the cygwin file system.

Compilation:
  link with dbe.o and filebox.o
  #include "filebox.h"

  "make ex" to build example program

Functions:
  int filebox_dialog (char *dialog_title, char *file_ext, int ext_strip, int save_flag, char *default_name, int default_size, char *full_name, int full_size);

  dialog_title: character string to use as dialog title bar
  file_ext: character string of file extensions to use, separated by semicolons
    (include the dot, e.g. ".c" or ".c;.cxx"). The file extensions are not
    case-sensitive. The first extension (if there is one) is appended to any
    filename returned that doesn't match any of the file extensions.
  ext_strip: FILEBOX_STRIP to strip file_ext from filenames shown, or
    FILEBOX_NO_STRIP to leave them. It is not advisable to use this flag
    where multiple extensions have been given.
  save_flag: FILEBOX_SAVE to indicate a save dialog (query if filename exists),
    or FILEBOX_LOAD for a load dialog (query if filename doesn't exist)
  default_name: character string containing default filename for dialog. This
    string is overwritten with the current filename if one is selected
  default_size: the size of the buffer pointed to by default_name
  full_name: character string that is overwritten with the full path and
    filename if one is selected
  full_size: the size of the buffer pointed to be full_name

  return value: FILEBOX_OK if a valid filename has been chosen, or 
    FILEBOX_CANCELLED if not. If the name buffers are not large enough to
    set the chosen path and filename then the function fails and returns
    FILEBOX_OVERFLOW.

filebox_dialog shows all valid filenames in the current working directory, and
allows the user to make a selection. Only files with the extension given by
file_ext are shown or allowed to be selected. Set file_ext to "" to show all
files.

**********

  void filebox_set_path (char *path_name);

  path_name: character string containing a valid path

filebox_set_path sets the current working directory.

**********

  int filebox_get_path (char *path_name, int buffer_size);

  path_name: pointer to a character buffer to receive the current path
  buffer_size: the size of the buffer pointed to by path_name

  return value: 0 if path_name has been successfully set, otherwise the
    return value is the required size of the buffer

filebox_get_path retrieves the current working directory.

**********

Martin Keates
martin@jabadaw.fsnet.co.uk
last updated: 13th May 2001

