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_DISABLE_SINGLE_INCLUDES) && !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:
 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 #ifdef G_OS_WIN32
 149 /* Reserve old names for DLL ABI backward compatibility */
 150 #define gtk_file_chooser_get_filename gtk_file_chooser_get_filename_utf8
 151 #define gtk_file_chooser_set_filename gtk_file_chooser_set_filename_utf8
 152 #define gtk_file_chooser_select_filename gtk_file_chooser_select_filename_utf8
 153 #define gtk_file_chooser_unselect_filename gtk_file_chooser_unselect_filename_utf8
 154 #define gtk_file_chooser_get_filenames gtk_file_chooser_get_filenames_utf8
 155 #define gtk_file_chooser_set_current_folder gtk_file_chooser_set_current_folder_utf8
 156 #define gtk_file_chooser_get_current_folder gtk_file_chooser_get_current_folder_utf8
 157 #define gtk_file_chooser_get_preview_filename gtk_file_chooser_get_preview_filename_utf8
 158 #define gtk_file_chooser_add_shortcut_folder gtk_file_chooser_add_shortcut_folder_utf8
 159 #define gtk_file_chooser_remove_shortcut_folder gtk_file_chooser_remove_shortcut_folder_utf8
 160 #define gtk_file_chooser_list_shortcut_folders gtk_file_chooser_list_shortcut_folders_utf8
 161 #endif
 162
 163 gchar *  gtk_file_chooser_get_filename       (GtkFileChooser *chooser);
 164 gboolean gtk_file_chooser_set_filename       (GtkFileChooser *chooser,
 165                                               const char     *filename);
 166 gboolean gtk_file_chooser_select_filename    (GtkFileChooser *chooser,
 167                                               const char     *filename);
 168 void     gtk_file_chooser_unselect_filename  (GtkFileChooser *chooser,
 169                                               const char     *filename);
 170 void     gtk_file_chooser_select_all         (GtkFileChooser *chooser);
 171 void     gtk_file_chooser_unselect_all       (GtkFileChooser *chooser);
 172 GSList * gtk_file_chooser_get_filenames      (GtkFileChooser *chooser);
 173 gboolean gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
 174                                               const gchar    *filename);
 175 gchar *  gtk_file_chooser_get_current_folder (GtkFileChooser *chooser);
 176
 177
 178 /* URI manipulation
 179  */
 180 gchar *  gtk_file_chooser_get_uri                (GtkFileChooser *chooser);
 181 gboolean gtk_file_chooser_set_uri                (GtkFileChooser *chooser,
 182                                                   const char     *uri);
 183 gboolean gtk_file_chooser_select_uri             (GtkFileChooser *chooser,
 184                                                   const char     *uri);
 185 void     gtk_file_chooser_unselect_uri           (GtkFileChooser *chooser,
 186                                                   const char     *uri);
 187 GSList * gtk_file_chooser_get_uris               (GtkFileChooser *chooser);
 188 gboolean gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
 189                                                   const gchar    *uri);
 190 gchar *  gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser);
 191
 192 /* GFile manipulation */
 193 GFile *  gtk_file_chooser_get_file                (GtkFileChooser  *chooser);
 194 gboolean gtk_file_chooser_set_file                (GtkFileChooser  *chooser,
 195                                                    GFile           *file,
 196                                                    GError         **error);
 197 gboolean gtk_file_chooser_select_file             (GtkFileChooser  *chooser,
 198                                                    GFile           *file,
 199                                                    GError         **error);
 200 void     gtk_file_chooser_unselect_file           (GtkFileChooser  *chooser,
 201                                                    GFile           *file);
 202 GSList * gtk_file_chooser_get_files               (GtkFileChooser  *chooser);
 203 gboolean gtk_file_chooser_set_current_folder_file (GtkFileChooser  *chooser,
 204                                                    GFile           *file,
 205                                                    GError         **error);
 206 GFile *  gtk_file_chooser_get_current_folder_file (GtkFileChooser  *chooser);
 207
 208 /* Preview widget
 209  */
 210 void       gtk_file_chooser_set_preview_widget        (GtkFileChooser *chooser,
 211                                                        GtkWidget      *preview_widget);
 212 GtkWidget *gtk_file_chooser_get_preview_widget        (GtkFileChooser *chooser);
 213 void       gtk_file_chooser_set_preview_widget_active (GtkFileChooser *chooser,
 214                                                        gboolean        active);
 215 gboolean   gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser);
 216 void       gtk_file_chooser_set_use_preview_label     (GtkFileChooser *chooser,
 217                                                        gboolean        use_label);
 218 gboolean   gtk_file_chooser_get_use_preview_label     (GtkFileChooser *chooser);
 219
 220 char  *gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser);
 221 char  *gtk_file_chooser_get_preview_uri      (GtkFileChooser *chooser);
 222 GFile *gtk_file_chooser_get_preview_file     (GtkFileChooser *chooser);
 223
 224 /* Extra widget
 225  */
 226 void       gtk_file_chooser_set_extra_widget (GtkFileChooser *chooser,
 227                                               GtkWidget      *extra_widget);
 228 GtkWidget *gtk_file_chooser_get_extra_widget (GtkFileChooser *chooser);
 229
 230 /* List of user selectable filters
 231  */
 232 void    gtk_file_chooser_add_filter    (GtkFileChooser *chooser,
 233                                         GtkFileFilter  *filter);
 234 void    gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
 235                                         GtkFileFilter  *filter);
 236 GSList *gtk_file_chooser_list_filters  (GtkFileChooser *chooser);
 237
 238 /* Current filter
 239  */
 240 void           gtk_file_chooser_set_filter (GtkFileChooser *chooser,
 241                                            GtkFileFilter  *filter);
 242 GtkFileFilter *gtk_file_chooser_get_filter (GtkFileChooser *chooser);
 243
 244 /* Per-application shortcut folders */
 245
 246 gboolean gtk_file_chooser_add_shortcut_folder    (GtkFileChooser *chooser,
 247                                                   const char     *folder,
 248                                                   GError        **error);
 249 gboolean gtk_file_chooser_remove_shortcut_folder (GtkFileChooser *chooser,
 250                                                   const char     *folder,
 251                                                   GError        **error);
 252 GSList *gtk_file_chooser_list_shortcut_folders   (GtkFileChooser *chooser);
 253
 254 gboolean gtk_file_chooser_add_shortcut_folder_uri    (GtkFileChooser *chooser,
 255                                                       const char     *uri,
 256                                                       GError        **error);
 257 gboolean gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser *chooser,
 258                                                       const char     *uri,
 259                                                       GError        **error);
 260 GSList *gtk_file_chooser_list_shortcut_folder_uris   (GtkFileChooser *chooser);
 261
 262 G_END_DECLS
 263
 264 #endif /* __GTK_FILE_CHOOSER_H__ */