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