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