interface/wx/filedlg.h

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