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