Pileus Git - ~andy/gtk/blob - gtk/gtkfilechooser.h

   1 /* GTK - The GIMP Toolkit
   2  * gtkfilechooser.h: Abstract interface for file selector GUIs
   3  * Copyright (C) 2003, Red Hat, Inc.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
  22 #error "Only <gtk/gtk.h> can be included directly."
  23 #endif
  24
  25 #ifndef __GTK_FILE_CHOOSER_H__
  26 #define __GTK_FILE_CHOOSER_H__
  27
  28 #include <gtk/gtkfilefilter.h>
  29 #include <gtk/gtkwidget.h>
  30
  31 G_BEGIN_DECLS
  32
  33 #define GTK_TYPE_FILE_CHOOSER             (gtk_file_chooser_get_type ())
  34 #define GTK_FILE_CHOOSER(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_FILE_CHOOSER, GtkFileChooser))
  35 #define GTK_IS_FILE_CHOOSER(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_FILE_CHOOSER))
  36
  37 typedef struct _GtkFileChooser      GtkFileChooser;
  38
  39 /**
  40  * GtkFileChooserAction:
  41  * @GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode.  The file chooser
  42  *  will only let the user pick an existing file.
  43  * @GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode.  The file chooser
  44  *  will let the user pick an existing file, or type in a new
  45  *  filename.
  46  * @GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for
  47  *  selecting folders.  The file chooser will let the user pick an
  48  *  existing folder.
  49  * @GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a
  50  *  new folder.  The file chooser will let the user name an existing or
  51  *  new folder.
  52  *
  53  * Describes whether a #GtkFileChooser is being used to open existing files
  54  * or to save to a possibly new file.
  55  */
  56 typedef enum
  57 {
  58   GTK_FILE_CHOOSER_ACTION_OPEN,
  59   GTK_FILE_CHOOSER_ACTION_SAVE,
  60   GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER,
  61   GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER
  62 } GtkFileChooserAction;
  63
  64 /**
  65  * GtkFileChooserConfirmation:
  66  * @GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM: The file chooser will present
  67  *  its stock dialog to confirm about overwriting an existing file.
  68  * @GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME: The file chooser will
  69  *  terminate and accept the user's choice of a file name.
  70  * @GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN: The file chooser will
  71  *  continue running, so as to let the user select another file name.
  72  *
  73  * Used as a return value of handlers for the
  74  * #GtkFileChooser::confirm-overwrite signal of a #GtkFileChooser. This
  75  * value determines whether the file chooser will present the stock
  76  * confirmation dialog, accept the user's choice of a filename, or
  77  * let the user choose another filename.
  78  *
  79  * Since: 2.8
  80  */
  81 typedef enum
  82 {
  83   GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM,
  84   GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME,
  85   GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN
  86 } GtkFileChooserConfirmation;
  87
  88 GType gtk_file_chooser_get_type (void) G_GNUC_CONST;
  89
  90 /* GError enumeration for GtkFileChooser */
  91 /**
  92  * GTK_FILE_CHOOSER_ERROR:
  93  *
  94  * Used to get the #GError quark for #GtkFileChooser errors.
  95  */
  96 #define GTK_FILE_CHOOSER_ERROR (gtk_file_chooser_error_quark ())
  97
  98 /**
  99  * GtkFileChooserError:
 100  * @GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
 101  * @GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
 102  * @GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS: Indicates a duplicate path (e.g. when
 103  *  adding a bookmark).
 104  * @GTK_FILE_CHOOSER_ERROR_INCOMPLETE_HOSTNAME: Indicates an incomplete hostname (e.g. "http://foo" without a slash after that).
 105  *
 106  * These identify the various errors that can occur while calling
 107  * #GtkFileChooser functions.
 108  */
 109 typedef enum {
 110   GTK_FILE_CHOOSER_ERROR_NONEXISTENT,
 111   GTK_FILE_CHOOSER_ERROR_BAD_FILENAME,
 112   GTK_FILE_CHOOSER_ERROR_ALREADY_EXISTS,
 113   GTK_FILE_CHOOSER_ERROR_INCOMPLETE_HOSTNAME
 114 } GtkFileChooserError;
 115
 116 GQuark gtk_file_chooser_error_quark (void);
 117
 118 /* Configuration
 119  */
 120 void                 gtk_file_chooser_set_action          (GtkFileChooser       *chooser,
 121                                                            GtkFileChooserAction  action);
 122 GtkFileChooserAction gtk_file_chooser_get_action          (GtkFileChooser       *chooser);
 123 void                 gtk_file_chooser_set_local_only      (GtkFileChooser       *chooser,
 124                                                            gboolean              local_only);
 125 gboolean             gtk_file_chooser_get_local_only      (GtkFileChooser       *chooser);
 126 void                 gtk_file_chooser_set_select_multiple (GtkFileChooser       *chooser,
 127                                                            gboolean              select_multiple);
 128 gboolean             gtk_file_chooser_get_select_multiple (GtkFileChooser       *chooser);
 129 void                 gtk_file_chooser_set_show_hidden     (GtkFileChooser       *chooser,
 130                                                            gboolean              show_hidden);
 131 gboolean             gtk_file_chooser_get_show_hidden     (GtkFileChooser       *chooser);
 132
 133 void                 gtk_file_chooser_set_do_overwrite_confirmation (GtkFileChooser *chooser,
 134                                                                      gboolean        do_overwrite_confirmation);
 135 gboolean             gtk_file_chooser_get_do_overwrite_confirmation (GtkFileChooser *chooser);
 136
 137 void                 gtk_file_chooser_set_create_folders  (GtkFileChooser       *chooser,
 138                                                           gboolean               create_folders);
 139 gboolean             gtk_file_chooser_get_create_folders (GtkFileChooser *chooser);
 140
 141 /* Suggested name for the Save-type actions
 142  */
 143 void     gtk_file_chooser_set_current_name   (GtkFileChooser *chooser,
 144                                               const gchar    *name);
 145
 146 /* Filename manipulation
 147  */
 148 gchar *  gtk_file_chooser_get_filename       (GtkFileChooser *chooser);
 149 gboolean gtk_file_chooser_set_filename       (GtkFileChooser *chooser,
 150                                               const char     *filename);
 151 gboolean gtk_file_chooser_select_filename    (GtkFileChooser *chooser,
 152                                               const char     *filename);
 153 void     gtk_file_chooser_unselect_filename  (GtkFileChooser *chooser,
 154                                               const char     *filename);
 155 void     gtk_file_chooser_select_all         (GtkFileChooser *chooser);
 156 void     gtk_file_chooser_unselect_all       (GtkFileChooser *chooser);
 157 GSList * gtk_file_chooser_get_filenames      (GtkFileChooser *chooser);
 158 gboolean gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
 159                                               const gchar    *filename);
 160 gchar *  gtk_file_chooser_get_current_folder (GtkFileChooser *chooser);
 161
 162
 163 /* URI manipulation
 164  */
 165 gchar *  gtk_file_chooser_get_uri                (GtkFileChooser *chooser);
 166 gboolean gtk_file_chooser_set_uri                (GtkFileChooser *chooser,
 167                                                   const char     *uri);
 168 gboolean gtk_file_chooser_select_uri             (GtkFileChooser *chooser,
 169                                                   const char     *uri);
 170 void     gtk_file_chooser_unselect_uri           (GtkFileChooser *chooser,
 171                                                   const char     *uri);
 172 GSList * gtk_file_chooser_get_uris               (GtkFileChooser *chooser);
 173 gboolean gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
 174                                                   const gchar    *uri);
 175 gchar *  gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser);
 176
 177 /* GFile manipulation */
 178 GFile *  gtk_file_chooser_get_file                (GtkFileChooser  *chooser);
 179 gboolean gtk_file_chooser_set_file                (GtkFileChooser  *chooser,
 180                                                    GFile           *file,
 181                                                    GError         **error);
 182 gboolean gtk_file_chooser_select_file             (GtkFileChooser  *chooser,
 183                                                    GFile           *file,
 184                                                    GError         **error);
 185 void     gtk_file_chooser_unselect_file           (GtkFileChooser  *chooser,
 186                                                    GFile           *file);
 187 GSList * gtk_file_chooser_get_files               (GtkFileChooser  *chooser);
 188 gboolean gtk_file_chooser_set_current_folder_file (GtkFileChooser  *chooser,
 189                                                    GFile           *file,
 190                                                    GError         **error);
 191 GFile *  gtk_file_chooser_get_current_folder_file (GtkFileChooser  *chooser);
 192
 193 /* Preview widget
 194  */
 195 void       gtk_file_chooser_set_preview_widget        (GtkFileChooser *chooser,
 196                                                        GtkWidget      *preview_widget);
 197 GtkWidget *gtk_file_chooser_get_preview_widget        (GtkFileChooser *chooser);
 198 void       gtk_file_chooser_set_preview_widget_active (GtkFileChooser *chooser,
 199                                                        gboolean        active);
 200 gboolean   gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser);
 201 void       gtk_file_chooser_set_use_preview_label     (GtkFileChooser *chooser,
 202                                                        gboolean        use_label);
 203 gboolean   gtk_file_chooser_get_use_preview_label     (GtkFileChooser *chooser);
 204
 205 char  *gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser);
 206 char  *gtk_file_chooser_get_preview_uri      (GtkFileChooser *chooser);
 207 GFile *gtk_file_chooser_get_preview_file     (GtkFileChooser *chooser);
 208
 209 /* Extra widget
 210  */
 211 void       gtk_file_chooser_set_extra_widget (GtkFileChooser *chooser,
 212                                               GtkWidget      *extra_widget);
 213 GtkWidget *gtk_file_chooser_get_extra_widget (GtkFileChooser *chooser);
 214
 215 /* List of user selectable filters
 216  */
 217 void    gtk_file_chooser_add_filter    (GtkFileChooser *chooser,
 218                                         GtkFileFilter  *filter);
 219 void    gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
 220                                         GtkFileFilter  *filter);
 221 GSList *gtk_file_chooser_list_filters  (GtkFileChooser *chooser);
 222
 223 /* Current filter
 224  */
 225 void           gtk_file_chooser_set_filter (GtkFileChooser *chooser,
 226                                            GtkFileFilter  *filter);
 227 GtkFileFilter *gtk_file_chooser_get_filter (GtkFileChooser *chooser);
 228
 229 /* Per-application shortcut folders */
 230
 231 gboolean gtk_file_chooser_add_shortcut_folder    (GtkFileChooser *chooser,
 232                                                   const char     *folder,
 233                                                   GError        **error);
 234 gboolean gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
 235                                                   const char     *folder,
 236                                                   GError        **error);
 237 GSList *gtk_file_chooser_list_shortcut_folders   (GtkFileChooser *chooser);
 238
 239 gboolean gtk_file_chooser_add_shortcut_folder_uri    (GtkFileChooser *chooser,
 240                                                       const char     *uri,
 241                                                       GError        **error);
 242 gboolean gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser *chooser,
 243                                                       const char     *uri,
 244                                                       GError        **error);
 245 GSList *gtk_file_chooser_list_shortcut_folder_uris   (GtkFileChooser *chooser);
 246
 247 G_END_DECLS
 248
 249 #endif /* __GTK_FILE_CHOOSER_H__ */