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 default directory.
 188     */
 189     virtual wxString GetDirectory() const;
 190
 191     /**
 192         If functions SetExtraControlCreator() and ShowModal() were called,
 193         returns the extra window. Otherwise returns @NULL.
 194
 195         @since 2.9.0
 196     */
 197     wxWindow* GetExtraControl() const;
 198
 199     /**
 200         Returns the default filename.
 201     */
 202     virtual wxString GetFilename() const;
 203
 204     /**
 205         Fills the array @a filenames with the names of the files chosen.
 206
 207         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 208         use GetFilename() for the others.
 209
 210         Note that under Windows, if the user selects shortcuts, the filenames
 211         include paths, since the application cannot determine the full path
 212         of each referenced file by appending the directory containing the shortcuts
 213         to the filename.
 214     */
 215     virtual void GetFilenames(wxArrayString& filenames) const;
 216
 217     /**
 218         Returns the index into the list of filters supplied, optionally, in the
 219         wildcard parameter.
 220
 221         Before the dialog is shown, this is the index which will be used when the
 222         dialog is first displayed.
 223
 224         After the dialog is shown, this is the index selected by the user.
 225     */
 226     virtual int GetFilterIndex() const;
 227
 228     /**
 229         Returns the message that will be displayed on the dialog.
 230     */
 231     virtual wxString GetMessage() const;
 232
 233     /**
 234         Returns the full path (directory and filename) of the selected file.
 235     */
 236     virtual wxString GetPath() const;
 237
 238     /**
 239         Fills the array @a paths with the full paths of the files chosen.
 240
 241         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 242         use GetPath() for the others.
 243     */
 244     virtual void GetPaths(wxArrayString& paths) const;
 245
 246     /**
 247         Returns the file dialog wildcard.
 248     */
 249     virtual wxString GetWildcard() const;
 250
 251     /**
 252         Sets the default directory.
 253     */
 254     virtual void SetDirectory(const wxString& directory);
 255
 256     /**
 257         The type of function used as an argument for SetExtraControlCreator().
 258
 259         @since 2.9.0
 260     */
 261     typedef wxWindow *(*ExtraControlCreatorFunction)(wxWindow*);
 262
 263     /**
 264         Customize file dialog by adding extra window, which is typically placed
 265         below the list of files and above the buttons.
 266
 267         SetExtraControlCreator() can be called only once, before calling ShowModal().
 268
 269         The @c creator function should take pointer to parent window (file dialog)
 270         and should return a window allocated with operator new.
 271
 272         Supported platforms: wxGTK, wxMSW, wxUniv.
 273
 274         @since 2.9.0
 275     */
 276     bool SetExtraControlCreator(ExtraControlCreatorFunction creator);
 277
 278     /**
 279         Sets the default filename.
 280
 281         In wxGTK this will have little effect unless a default directory has previously been set.
 282     */
 283     virtual void SetFilename(const wxString& setfilename);
 284
 285     /**
 286         Sets the default filter index, starting from zero.
 287     */
 288     virtual void SetFilterIndex(int filterIndex);
 289
 290     /**
 291         Sets the message that will be displayed on the dialog.
 292     */
 293     virtual void SetMessage(const wxString& message);
 294
 295     /**
 296         Sets the path (the combined directory and filename that will be returned when
 297         the dialog is dismissed).
 298     */
 299     virtual void SetPath(const wxString& path);
 300
 301     /**
 302         Sets the wildcard, which can contain multiple file types, for example:
 303         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
 304
 305         Note that the native Motif dialog has some limitations with respect to
 306         wildcards; see the Remarks section above.
 307     */
 308     virtual void SetWildcard(const wxString& wildCard);
 309
 310     /**
 311         Shows the dialog, returning @c wxID_OK if the user pressed OK, and @c wxID_CANCEL
 312         otherwise.
 313     */
 314     virtual int ShowModal();
 315 };
 316
 317
 318
 319 // ============================================================================
 320 // Global functions/macros
 321 // ============================================================================
 322
 323 /** @addtogroup group_funcmacro_dialog */
 324 //@{
 325
 326 /**
 327     Pops up a file selector box. In Windows, this is the common file selector
 328     dialog. In X, this is a file selector box with the same functionality. The
 329     path and filename are distinct elements of a full file pathname. If path
 330     is empty, the current directory will be used. If filename is empty, no
 331     default filename will be supplied. The wildcard determines what files are
 332     displayed in the file selector, and file extension supplies a type
 333     extension for the required filename. Flags may be a combination of
 334     wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
 335
 336     @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
 337           this function only returns a single file name.
 338
 339     Both the Unix and Windows versions implement a wildcard filter. Typing a
 340     filename containing wildcards (*, ?) in the filename text item, and
 341     clicking on Ok, will result in only those files matching the pattern being
 342     displayed.
 343
 344     The wildcard may be a specification for multiple types of file with a
 345     description for each, such as:
 346
 347     @code
 348     "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 349     @endcode
 350
 351     The application must check for an empty return value (the user pressed
 352     Cancel). For example:
 353
 354     @code
 355     wxString filename = wxFileSelector("Choose a file to open");
 356     if ( !filename.empty() )
 357     {
 358         // work with the file
 359         ...
 360     }
 361     //else: cancelled by user
 362     @endcode
 363
 364     @header{wx/filedlg.h}
 365 */
 366 wxString wxFileSelector(const wxString& message,
 367                         const wxString& default_path = wxEmptyString,
 368                         const wxString& default_filename = wxEmptyString,
 369                         const wxString& default_extension = wxEmptyString,
 370                         const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
 371                         int flags = 0,
 372                         wxWindow* parent = NULL,
 373                         int x = wxDefaultCoord,
 374                         int y = wxDefaultCoord);
 375
 376 /**
 377     An extended version of wxFileSelector
 378 */
 379 wxString wxFileSelectorEx(const wxString& message = wxFileSelectorPromptStr,
 380                           const wxString& default_path = wxEmptyString,
 381                           const wxString& default_filename = wxEmptyString,
 382                           int *indexDefaultExtension = NULL,
 383                           const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
 384                           int flags = 0,
 385                           wxWindow *parent = NULL,
 386                           int x = wxDefaultCoord,
 387                           int y = wxDefaultCoord);
 388
 389 /**
 390     Ask for filename to load
 391 */
 392 wxString wxLoadFileSelector(const wxString& what,
 393                             const wxString& extension,
 394                             const wxString& default_name = wxEmptyString,
 395                             wxWindow *parent = NULL);
 396
 397 /**
 398     Ask for filename to save
 399 */
 400 wxString wxSaveFileSelector(const wxString& what,
 401                             const wxString& extension,
 402                             const wxString& default_name = wxEmptyString,
 403                             wxWindow *parent = NULL);
 404
 405 //@}
 406