ardour/libs/gtkmm2/gtk/src/filechooser.hg

/* $Id: filechooser.hg,v 1.23 2006/04/18 13:28:56 murrayc Exp $ */

/* Copyright (C) 2003 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * 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; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <gtkmm/widget.h>
#include <gtkmm/filefilter.h>
#include <glibmm/interface.h>


_DEFS(gtkmm,gtk)
_PINCLUDE(glibmm/private/interface_p.h)

namespace Gtk
{

_WRAP_ENUM(FileChooserAction, GtkFileChooserAction)
_WRAP_ENUM(FileChooserConfirmation, GtkFileChooserConfirmation)

//Note that GTK_FILE_SYSTEM_ERROR is not currently public GTK+ API and should 
//never be instantiated by the GTK+ C API.

/** Exception class for Gdk::FileChooser errors.
 */
_WRAP_GERROR(FileChooserError,GtkFileChooserError,GTK_FILE_CHOOSER_ERROR)

/**
 * Gtk::FileChooser is an interface that can be implemented by file selection
 * widgets. In gtkmm, the main objects that implement this interface are
 * FileChooserWidget and FileChooserDialog. You do not need to write an
 * object that implements the FileChooser interface unless you are trying to
 * adapt an existing file selector to expose a standard programming interface.
 *
 * @par File Names and Encodings
 * When the user is finished selecting files in a FileChooser, your program
 * can get the selected names either as filenames or as URIs. For URIs, the
 * normal escaping rules are applied if the URI contains non-ASCII characters.
 * However, filenames are always returned in the character set specified by the
 * G_FILENAME_ENCODING environment variable. Please see the Glib documentation
 * for more details about this variable.
 *
 * @par Important
 * This means that while you can pass the result of FileChooser::get_filename()
 * to <tt>open(2)</tt> or <tt>fopen(3)</tt>, you may not be able to directly
 * set it as the text of a Gtk::Label widget unless you convert it first to
 * UTF-8, which all gtkmm widgets expect. You should use
 * Glib::filename_to_utf8() to convert filenames into strings that can be
 * passed to gtkmm widgets.
 *
 * @note
 * The gtkmm FileChooser API is broken in that methods return Glib::ustring
 * even though the returned string is not necessarily UTF-8 encoded.  Any
 * FileChooser method that takes or returns a filename (not a URI) should
 * have std::string as parameter or return type.  Fortunately this mistake
 * doesn't prevent you from handling filenames correctly in your application.
 * Just pretend that the API uses std::string and call Glib::filename_to_utf8()
 * or Glib::filename_from_utf8() as appropriate.
 *
 * See http://bugzilla.gnome.org/show_bug.cgi?id=142138 for more information.
 */
class FileChooser : public Glib::Interface
{
  _CLASS_INTERFACE(FileChooser, GtkFileChooser, GTK_FILE_CHOOSER, GtkFileChooserClass)
public:

  _WRAP_METHOD(void set_action(FileChooserAction action), gtk_file_chooser_set_action)
  _WRAP_METHOD(FileChooserAction get_action() const, gtk_file_chooser_get_action)
  _WRAP_METHOD(void set_local_only(bool local_only = true), gtk_file_chooser_set_local_only)
  _WRAP_METHOD(bool get_local_only() const, gtk_file_chooser_get_local_only)
  _WRAP_METHOD(void set_select_multiple(bool select_multiple = true), gtk_file_chooser_set_select_multiple)
  _WRAP_METHOD(bool get_select_multiple() const, gtk_file_chooser_get_select_multiple)

  _WRAP_METHOD(void set_show_hidden(bool show_hidden = true), gtk_file_chooser_set_show_hidden)
  _WRAP_METHOD(bool get_show_hidden() const, gtk_file_chooser_get_show_hidden)

  _WRAP_METHOD(void set_do_overwrite_confirmation(bool do_overwrite_confirmation = true), gtk_file_chooser_set_do_overwrite_confirmation)
  _WRAP_METHOD(bool get_do_overwrite_confirmation() const, gtk_file_chooser_get_do_overwrite_confirmation)

  _WRAP_METHOD(void set_current_name(const Glib::ustring& name), gtk_file_chooser_set_current_name)
  _WRAP_METHOD(Glib::ustring get_filename() const, gtk_file_chooser_get_filename)
  _WRAP_METHOD(bool set_filename(const Glib::ustring& filename), gtk_file_chooser_set_filename)
  _WRAP_METHOD(bool select_filename(const Glib::ustring& filename), gtk_file_chooser_select_filename)
  _WRAP_METHOD(void unselect_filename(const Glib::ustring& filename), gtk_file_chooser_unselect_filename)
  _WRAP_METHOD(void select_all(), gtk_file_chooser_select_all)
  _WRAP_METHOD(void unselect_all(), gtk_file_chooser_unselect_all)
  _WRAP_METHOD(Glib::SListHandle<Glib::ustring> get_filenames() const, gtk_file_chooser_get_filenames)
  _WRAP_METHOD(bool set_current_folder(const Glib::ustring& filename), gtk_file_chooser_set_current_folder)
  _WRAP_METHOD(Glib::ustring get_current_folder() const, gtk_file_chooser_get_current_folder)


/* URI manipulation
 */
  _WRAP_METHOD(Glib::ustring get_uri() const, gtk_file_chooser_get_uri)
  _WRAP_METHOD(bool set_uri(const Glib::ustring& uri), gtk_file_chooser_set_uri)
  _WRAP_METHOD(bool select_uri(const Glib::ustring& uri), gtk_file_chooser_select_uri)
  _WRAP_METHOD(void unselect_uri(const Glib::ustring& uri), gtk_file_chooser_unselect_uri)
  _WRAP_METHOD(Glib::SListHandle<Glib::ustring> get_uris() const, gtk_file_chooser_get_uris)

  _WRAP_METHOD(bool set_current_folder_uri(const Glib::ustring& uri), gtk_file_chooser_set_current_folder_uri)
  _WRAP_METHOD(Glib::ustring get_current_folder_uri() const, gtk_file_chooser_get_current_folder_uri)

/* Preview widget
 */
  _WRAP_METHOD(void set_preview_widget(Gtk::Widget& preview_widget), gtk_file_chooser_set_preview_widget)
  _WRAP_METHOD(const Gtk::Widget* get_preview_widget() const, gtk_file_chooser_get_preview_widget, constversion)
  _WRAP_METHOD(Gtk::Widget* get_preview_widget(), gtk_file_chooser_get_preview_widget)
  _WRAP_METHOD(void set_preview_widget_active(bool active = true), gtk_file_chooser_set_preview_widget_active)
  _WRAP_METHOD(bool get_preview_widget_active() const, gtk_file_chooser_get_preview_widget_active)

  _WRAP_METHOD(void set_use_preview_label(bool use_label = true), gtk_file_chooser_set_use_preview_label)
  _WRAP_METHOD(bool get_use_preview_label() const, gtk_file_chooser_get_use_preview_label)

  _WRAP_METHOD(Glib::ustring get_preview_filename() const, gtk_file_chooser_get_preview_filename)
  _WRAP_METHOD(Glib::ustring get_preview_uri() const, gtk_file_chooser_get_preview_uri)

/* Extra widget
 */
  _WRAP_METHOD(void set_extra_widget(Gtk::Widget& extra_widget), gtk_file_chooser_set_extra_widget)
  _WRAP_METHOD(Gtk::Widget* get_extra_widget(), gtk_file_chooser_get_extra_widget)
  _WRAP_METHOD(const Gtk::Widget* get_extra_widget() const, gtk_file_chooser_get_extra_widget, constversion)

/* List of user selectable filters
 */
  _WRAP_METHOD(void add_filter(const FileFilter& filter), gtk_file_chooser_add_filter)
  _WRAP_METHOD(void remove_filter (const FileFilter& filter), gtk_file_chooser_remove_filter)

  _WRAP_METHOD(Glib::SListHandle< FileFilter* > list_filters(), gtk_file_chooser_list_filters)
  _WRAP_METHOD(Glib::SListHandle< const FileFilter* > list_filters() const, gtk_file_chooser_list_filters)
  
/* Current filter
 */
  _WRAP_METHOD(void set_filter(const FileFilter& filter), gtk_file_chooser_set_filter)
  _WRAP_METHOD(FileFilter* get_filter(), gtk_file_chooser_get_filter, refreturn)
  _WRAP_METHOD(const FileFilter* get_filter() const, gtk_file_chooser_get_filter, refreturn, constversion)
  
/* Per-application shortcut folders */

  _WRAP_METHOD(bool add_shortcut_folder(const Glib::ustring& folder), gtk_file_chooser_add_shortcut_folder, errthrow)
  _WRAP_METHOD(bool remove_shortcut_folder(const Glib::ustring& folder), gtk_file_chooser_remove_shortcut_folder, errthrow)
  _WRAP_METHOD(Glib::SListHandle<Glib::ustring> list_shortcut_folders() const, gtk_file_chooser_list_shortcut_folders)

  _WRAP_METHOD(bool add_shortcut_folder_uri(const Glib::ustring& uri), gtk_file_chooser_add_shortcut_folder_uri, errthrow)
  _WRAP_METHOD(bool remove_shortcut_folder_uri(const Glib::ustring& uri), gtk_file_chooser_remove_shortcut_folder_uri, errthrow)
  _WRAP_METHOD(Glib::SListHandle<Glib::ustring> list_shortcut_folder_uris() const, gtk_file_chooser_list_shortcut_folder_uris)

  
  /** This signal is emitted when the current folder in a FileChooser
   * changes.  This can happen due to the user performing some action that
   * changes folders, such as selecting a bookmark or visiting a folder on the
   * file list.  It can also happen as a result of calling a function to
   * explicitly change the current folder in a file chooser.
   *
   * Normally you do not need to connect to this signal, unless you need to keep
   * track of which folder a file chooser is showing.
   *
   * @see set_current_folder(), get_current_folder(),
   * set_current_folder_uri(), get_current_folder_uri().
   */
  _WRAP_SIGNAL(void current_folder_changed(), "current_folder_changed", no_default_handler)
  
  /** This signal is emitted when there is a change in the set of selected files
   * in a #GtkFileChooser.  This can happen when the user modifies the selection
   * with the mouse or the keyboard, or when explicitly calling functions to
   * change the selection.
   *
   * Normally you do not need to connect to this signal, as it is easier to wait
   * for the file chooser to finish running, and then to get the list of
   * selected files using the functions mentioned below.
   *
   * @see select_filename(), unselect_filename(), get_filename(),
   * get_filenames(), select_uri(),
   * unselect_uri(), get_uri(),
   * get_uris().
   */
  _WRAP_SIGNAL(void selection_changed(), "selection_changed", no_default_handler)
  
  /** This signal is emitted when the preview in a file chooser should be
   * regenerated.  For example, this can happen when the currently selected file
   * changes.  You should use this signal if you want your file chooser to have
   * a preview widget.
   *
   * Once you have installed a preview widget with
   * set_preview_widget(), you should update it when this
   * signal is emitted.  You can use the functions
   * get_preview_filename() or get_preview_uri() to get the name of the file to preview.
   * Your widget may not be able to preview all kinds of files; your signal handler
   * must call set_preview_wiget_active() to inform the file
   * chooser about whether the preview was generated successfully or not.
   *
   * @see set_preview_widget(), set_preview_widget_active(),
   * set_use_preview_label(), get_preview_filename(), get_preview_uri().
   */
  _WRAP_SIGNAL(void update_preview(), "update_preview", no_default_handler)
  
  /** This signal is emitted when the user "activates" a file in the file
   * chooser.  This can happen by double-clicking on a file in the file list, or
   * by pressing <keycap>Enter</keycap>.
   *
   * Normally you do not need to connect to this signal.  It is used internally
   * by FileChooserDialog to know when to activate the default button in the
   * dialog.
   *
   * @see get_filename(), get_filenames(), get_uri(), get_uris().
   */
  _WRAP_SIGNAL(void file_activated(), "file_activated", no_default_handler)

  _WRAP_SIGNAL(FileChooserConfirmation confirm_overwrite(), "confirm-overwrite", no_default_handler)

  _WRAP_PROPERTY("action", FileChooserAction)
  //TODO: _WRAP_PROPERTY("file-system", FileSystem) //FileSystem is not really public API.
  _WRAP_PROPERTY("filter", FileFilter*)
  _WRAP_PROPERTY("folder-mode", bool)
  _WRAP_PROPERTY("local-only", bool)
  _WRAP_PROPERTY("preview-widget", Widget*)
  _WRAP_PROPERTY("preview-widget-active", bool)
  _WRAP_PROPERTY("use-preview-label", bool)
  _WRAP_PROPERTY("extra-widget", Widget*)
  _WRAP_PROPERTY("select-multiple", bool)
  _WRAP_PROPERTY("show-hidden", bool)
  _WRAP_PROPERTY("do-overwrite-confirmation", bool)
};

} // namespace Gtk