/*******************************************************************************
 *
 * Copyright (C) 2003 Scott Wheeler
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License version 2 as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 *
 *******************************************************************************/

#ifndef __TOOLKIT_ABSTRACTION_H__
#define __TOOLKIT_ABSTRACTION_H__

#ifdef __cplusplus
extern "C" {
#endif

struct FileList
{
    /*!
     * A UTF-8 array of file names
     */
    char **files;
    /*!
     * The number of files in the array
     */
    int size;
};

/*!
 * Create a dialog to select a single file with the window name \a caption.
 * The dialog with be initialized at the directory \a start_dir and will return
 * a currently existing file that matches \a filter, where \a filter is composed
 * of standard wildcard characters.
 *
 * The dialog will be positioned by the window manager over the window identified
 * by \a over_window_id.
 *
 * Toolkit defaults will be used if any of these paramaters are NULL.
 *
 * The function will return NULL if the operation is canceled.
 *
 * \note All strings should be UTF-8 encoded and NULL terminated.
 */
char *get_open_file_name( const char *caption,
                          const char *start_dir,
                          const char *filter,
                          WId over_window_id )

/*!
 * Create a dialog to select a list of files with the window name \a caption.
 * The dialog with be initialized at the directory \a start_dir and will return
 * a currently existing file that matches \a filter, where \a filter is composed
 * of standard wildcard characters.
 *
 * The dialog will be positioned by the window manager over the window identified
 * by \a over_window_id.
 *
 * Toolkit defaults will be used if any of these paramaters are NULL.
 *
 * The function will return an empty FileList (size set to zero) if the operation
 * is canceled.
 *
 * \note All strings should be UTF-8 encoded and NULL terminated.
 */
FileList get_open_file_names( const char *caption,
                              const char *start_dir,
                              const char *filter,
                              WId over_window_id )

/*!
 * Create a dialog to select a file to be saved to with the window name
 * \a caption.  This file may or may not already exist. The dialog with be
 * initialized at the directory \a start_dir and will return a file that matches
 * \a filter, where \a filter is composed of standard wildcard characters.
 *
 * The dialog will be positioned by the window manager over the window identified
 * by \a over_window_id.
 *
 * Toolkit defaults will be used if any of these paramaters are NULL.
 *
 * The function will return NULL if the operation is canceled.
 *
 * \note All strings should be UTF-8 encoded and NULL terminated.
 */
char *get_save_file_name( const char *caption,
                          const char *start_dir,
                          const char *filter,
                          WId over_window_id )

/*!
 * Create a dialog to select a single directory with the window name \a caption.
 * The dialog with be initialized at the directory \a start_dir and will return
 * a currently existing directory.
 *
 * The dialog will be positioned by the window manager over the window identified
 * by \a over_window_id.
 *
 * Toolkit defaults will be used if any of these paramaters are NULL.
 *
 * The function will return NULL if the operation is canceled.
 *
 * \note All strings should be UTF-8 encoded and NULL terminated.
 */
char *get_existing_directory( const char *caption,
                              const char *start_dir,
                              WId over_window_id )


#ifdef __cplusplus
}
#endif
#endif // __TOOLKIT_ABSTRACTION_H__