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