interface/wx/filedlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filedlg.h
   3 // Purpose:     interface of wxFileDialog
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 enum
  10 {
  11     wxFD_OPEN              = 0x0001,
  12     wxFD_SAVE              = 0x0002,
  13     wxFD_OVERWRITE_PROMPT  = 0x0004,
  14     wxFD_FILE_MUST_EXIST   = 0x0010,
  15     wxFD_MULTIPLE          = 0x0020,
  16     wxFD_CHANGE_DIR        = 0x0080,
  17     wxFD_PREVIEW           = 0x0100
  18 };
  19
  20 #define wxFD_DEFAULT_STYLE      wxFD_OPEN
  21
  22 /**
  23     Default wildcard string used in wxFileDialog corresponding to all files.
  24
  25     It is defined as "*.*" under MSW and OS/2 and "*" everywhere else.
  26 */
  27 const char wxFileSelectorDefaultWildcardStr[];
  28
  29 /**
  30     @class wxFileDialog
  31
  32     This class represents the file chooser dialog.
  33
  34     The path and filename are distinct elements of a full file pathname.
  35     If path is ::wxEmptyString, the current directory will be used.
  36     If filename is ::wxEmptyString, no default filename will be supplied.
  37     The wildcard determines what files are displayed in the file selector,
  38     and file extension supplies a type extension for the required filename.
  39
  40     The typical usage for the open file dialog is:
  41     @code
  42     void MyFrame::OnOpen(wxCommandEvent& WXUNUSED(event))
  43     {
  44         if (...current content has not been saved...)
  45         {
  46             if (wxMessageBox(_("Current content has not been saved! Proceed?"), _("Please confirm"),
  47                              wxICON_QUESTION | wxYES_NO, this) == wxNO )
  48                 return;
  49             //else: proceed asking to the user the new file to open
  50         }
  51
  52         wxFileDialog
  53             openFileDialog(this, _("Open XYZ file"), "", "",
  54                            "XYZ files (*.xyz)|*.xyz", wxFD_OPEN|wxFD_FILE_MUST_EXIST);
  55
  56         if (openFileDialog.ShowModal() == wxID_CANCEL)
  57             return;     // the user changed idea...
  58
  59         // proceed loading the file chosen by the user;
  60         // this can be done with e.g. wxWidgets input streams:
  61         wxFileInputStream input_stream(openFileDialog.GetPath());
  62         if (!input_stream.IsOk())
  63         {
  64             wxLogError("Cannot open file '%s'.", openFileDialog.GetPath());
  65             return;
  66         }
  67
  68         ...
  69     }
  70     @endcode
  71
  72     The typical usage for the save file dialog is instead somewhat simpler:
  73     @code
  74     void MyFrame::OnSaveAs(wxCommandEvent& WXUNUSED(event))
  75     {
  76         wxFileDialog
  77             saveFileDialog(this, _("Save XYZ file"), "", "",
  78                            "XYZ files (*.xyz)|*.xyz", wxFD_SAVE|wxFD_OVERWRITE_PROMPT);
  79
  80         if (saveFileDialog.ShowModal() == wxID_CANCEL)
  81             return;     // the user changed idea...
  82
  83         // save the current contents in the file;
  84         // this can be done with e.g. wxWidgets output streams:
  85         wxFileOutputStream output_stream(saveFileDialog.GetPath());
  86         if (!output_stream.IsOk())
  87         {
  88             wxLogError("Cannot save current contents in file '%s'.", saveFileDialog.GetPath());
  89             return;
  90         }
  91
  92         ...
  93     }
  94     @endcode
  95
  96     @remarks
  97     All implementations of the wxFileDialog provide a wildcard filter. Typing a filename
  98     containing wildcards (*, ?) in the filename text item, and clicking on Ok, will
  99     result in only those files matching the pattern being displayed.
 100     The wildcard may be a specification for multiple types of file with a description
 101     for each, such as:
 102     @code
 103          "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png"
 104     @endcode
 105     It must be noted that wildcard support in the native Motif file dialog is quite
 106     limited: only one file type is supported, and it is displayed without the
 107     descriptive test; "BMP files (*.bmp)|*.bmp" is displayed as "*.bmp", and both
 108     "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" and "Image files|*.bmp;*.gif"
 109     are errors.
 110
 111     @beginStyleTable
 112     @style{wxFD_DEFAULT_STYLE}
 113            Equivalent to @c wxFD_OPEN.
 114     @style{wxFD_OPEN}
 115            This is an open dialog; usually this means that the default
 116            button's label of the dialog is "Open". Cannot be combined with @c wxFD_SAVE.
 117     @style{wxFD_SAVE}
 118            This is a save dialog; usually this means that the default button's
 119            label of the dialog is "Save". Cannot be combined with @c wxFD_OPEN.
 120     @style{wxFD_OVERWRITE_PROMPT}
 121            For save dialog only: prompt for a confirmation if a file will be
 122            overwritten.
 123     @style{wxFD_FILE_MUST_EXIST}
 124            For open dialog only: the user may only select files that actually
 125            exist. Notice that under OS X the file dialog with @c wxFD_OPEN
 126            style always behaves as if this style was specified, because it is
 127            impossible to choose a file that doesn't exist from a standard OS X
 128            file dialog.
 129     @style{wxFD_MULTIPLE}
 130            For open dialog only: allows selecting multiple files.
 131     @style{wxFD_CHANGE_DIR}
 132            Change the current working directory (when the dialog is dismissed)
 133            to the directory where the file(s) chosen by the user are.
 134     @style{wxFD_PREVIEW}
 135            Show the preview of the selected files (currently only supported by
 136            wxGTK).
 137     @endStyleTable
 138
 139     @library{wxcore}
 140     @category{cmndlg}
 141
 142     @see @ref overview_cmndlg_file, ::wxFileSelector()
 143 */
 144 class wxFileDialog : public wxDialog
 145 {
 146 public:
 147     /**
 148         Constructor. Use ShowModal() to show the dialog.
 149
 150         @param parent
 151             Parent window.
 152         @param message
 153             Message to show on the dialog.
 154         @param defaultDir
 155             The default directory, or the empty string.
 156         @param defaultFile
 157             The default filename, or the empty string.
 158         @param wildcard
 159             A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
 160             Note that the native Motif dialog has some limitations with respect to
 161             wildcards; see the Remarks section above.
 162         @param style
 163             A dialog style. See @c wxFD_* styles for more info.
 164         @param pos
 165             Dialog position. Not implemented.
 166         @param size
 167             Dialog size. Not implemented.
 168         @param name
 169             Dialog name. Not implemented.
 170     */
 171     wxFileDialog(wxWindow* parent,
 172                  const wxString& message = wxFileSelectorPromptStr,
 173                  const wxString& defaultDir = wxEmptyString,
 174                  const wxString& defaultFile = wxEmptyString,
 175                  const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
 176                  long style = wxFD_DEFAULT_STYLE,
 177                  const wxPoint& pos = wxDefaultPosition,
 178                  const wxSize& size = wxDefaultSize,
 179                  const wxString& name = wxFileDialogNameStr);
 180
 181     /**
 182         Destructor.
 183     */
 184     virtual ~wxFileDialog();
 185
 186     /**
 187         Returns the path of the file currently selected in dialog.
 188
 189         Notice that this file is not necessarily going to be accepted by the
 190         user, so calling this function mostly makes sense from an update UI
 191         event handler of a custom file dialog extra control to update its state
 192         depending on the currently selected file.
 193
 194         Currently this function is fully implemented under GTK and MSW and
 195         always returns an empty string elsewhere.
 196
 197         @since 2.9.5
 198
 199         @return The path of the currently selected file or an empty string if
 200             nothing is selected.
 201
 202         @see SetExtraControlCreator()
 203     */
 204     virtual wxString GetCurrentlySelectedFilename() const;
 205
 206     /**
 207         Returns the default directory.
 208     */
 209     virtual wxString GetDirectory() const;
 210
 211     /**
 212         If functions SetExtraControlCreator() and ShowModal() were called,
 213         returns the extra window. Otherwise returns @NULL.
 214
 215         @since 2.9.0
 216     */
 217     wxWindow* GetExtraControl() const;
 218
 219     /**
 220         Returns the default filename.
 221     */
 222     virtual wxString GetFilename() const;
 223
 224     /**
 225         Fills the array @a filenames with the names of the files chosen.
 226
 227         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 228         use GetFilename() for the others.
 229
 230         Note that under Windows, if the user selects shortcuts, the filenames
 231         include paths, since the application cannot determine the full path
 232         of each referenced file by appending the directory containing the shortcuts
 233         to the filename.
 234     */
 235     virtual void GetFilenames(wxArrayString& filenames) const;
 236
 237     /**
 238         Returns the index into the list of filters supplied, optionally, in the
 239         wildcard parameter.
 240
 241         Before the dialog is shown, this is the index which will be used when the
 242         dialog is first displayed.
 243
 244         After the dialog is shown, this is the index selected by the user.
 245     */
 246     virtual int GetFilterIndex() const;
 247
 248     /**
 249         Returns the message that will be displayed on the dialog.
 250     */
 251     virtual wxString GetMessage() const;
 252
 253     /**
 254         Returns the full path (directory and filename) of the selected file.
 255     */
 256     virtual wxString GetPath() const;
 257
 258     /**
 259         Fills the array @a paths with the full paths of the files chosen.
 260
 261         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 262         use GetPath() for the others.
 263     */
 264     virtual void GetPaths(wxArrayString& paths) const;
 265
 266     /**
 267         Returns the file dialog wildcard.
 268     */
 269     virtual wxString GetWildcard() const;
 270
 271     /**
 272         Sets the default directory.
 273     */
 274     virtual void SetDirectory(const wxString& directory);
 275
 276     /**
 277         The type of function used as an argument for SetExtraControlCreator().
 278
 279         @since 2.9.0
 280     */
 281     typedef wxWindow *(*ExtraControlCreatorFunction)(wxWindow*);
 282
 283     /**
 284         Customize file dialog by adding extra window, which is typically placed
 285         below the list of files and above the buttons.
 286
 287         SetExtraControlCreator() can be called only once, before calling ShowModal().
 288
 289         The @c creator function should take pointer to parent window (file dialog)
 290         and should return a window allocated with operator new.
 291
 292         Supported platforms: wxGTK, wxMSW, wxUniv.
 293
 294         @since 2.9.0
 295     */
 296     bool SetExtraControlCreator(ExtraControlCreatorFunction creator);
 297
 298     /**
 299         Sets the default filename.
 300
 301         In wxGTK this will have little effect unless a default directory has previously been set.
 302     */
 303     virtual void SetFilename(const wxString& setfilename);
 304
 305     /**
 306         Sets the default filter index, starting from zero.
 307     */
 308     virtual void SetFilterIndex(int filterIndex);
 309
 310     /**
 311         Sets the message that will be displayed on the dialog.
 312     */
 313     virtual void SetMessage(const wxString& message);
 314
 315     /**
 316         Sets the path (the combined directory and filename that will be returned when
 317         the dialog is dismissed).
 318     */
 319     virtual void SetPath(const wxString& path);
 320
 321     /**
 322         Sets the wildcard, which can contain multiple file types, for example:
 323         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
 324
 325         Note that the native Motif dialog has some limitations with respect to
 326         wildcards; see the Remarks section above.
 327     */
 328     virtual void SetWildcard(const wxString& wildCard);
 329
 330     /**
 331         Shows the dialog, returning @c wxID_OK if the user pressed OK, and @c wxID_CANCEL
 332         otherwise.
 333     */
 334     virtual int ShowModal();
 335 };
 336
 337
 338
 339 // ============================================================================
 340 // Global functions/macros
 341 // ============================================================================
 342
 343 /** @addtogroup group_funcmacro_dialog */
 344 //@{
 345
 346 /**
 347     Pops up a file selector box. In Windows, this is the common file selector
 348     dialog. In X, this is a file selector box with the same functionality. The
 349     path and filename are distinct elements of a full file pathname. If path
 350     is empty, the current directory will be used. If filename is empty, no
 351     default filename will be supplied. The wildcard determines what files are
 352     displayed in the file selector, and file extension supplies a type
 353     extension for the required filename. Flags may be a combination of
 354     wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
 355
 356     @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
 357           this function only returns a single file name.
 358
 359     Both the Unix and Windows versions implement a wildcard filter. Typing a
 360     filename containing wildcards (*, ?) in the filename text item, and
 361     clicking on Ok, will result in only those files matching the pattern being
 362     displayed.
 363
 364     The wildcard may be a specification for multiple types of file with a
 365     description for each, such as:
 366
 367     @code
 368     "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 369     @endcode
 370
 371     The application must check for an empty return value (the user pressed
 372     Cancel). For example:
 373
 374     @code
 375     wxString filename = wxFileSelector("Choose a file to open");
 376     if ( !filename.empty() )
 377     {
 378         // work with the file
 379         ...
 380     }
 381     //else: cancelled by user
 382     @endcode
 383
 384     @header{wx/filedlg.h}
 385 */
 386 wxString wxFileSelector(const wxString& message,
 387                         const wxString& default_path = wxEmptyString,
 388                         const wxString& default_filename = wxEmptyString,
 389                         const wxString& default_extension = wxEmptyString,
 390                         const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
 391                         int flags = 0,
 392                         wxWindow* parent = NULL,
 393                         int x = wxDefaultCoord,
 394                         int y = wxDefaultCoord);
 395
 396 /**
 397     An extended version of wxFileSelector
 398 */
 399 wxString wxFileSelectorEx(const wxString& message = wxFileSelectorPromptStr,
 400                           const wxString& default_path = wxEmptyString,
 401                           const wxString& default_filename = wxEmptyString,
 402                           int *indexDefaultExtension = NULL,
 403                           const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
 404                           int flags = 0,
 405                           wxWindow *parent = NULL,
 406                           int x = wxDefaultCoord,
 407                           int y = wxDefaultCoord);
 408
 409 /**
 410     Ask for filename to load
 411 */
 412 wxString wxLoadFileSelector(const wxString& what,
 413                             const wxString& extension,
 414                             const wxString& default_name = wxEmptyString,
 415                             wxWindow *parent = NULL);
 416
 417 /**
 418     Ask for filename to save
 419 */
 420 wxString wxSaveFileSelector(const wxString& what,
 421                             const wxString& extension,
 422                             const wxString& default_name = wxEmptyString,
 423                             wxWindow *parent = NULL);
 424
 425 //@}
 426