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 /**
  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 file type 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
 105            exist. Notice that under OS X the file dialog with @c wxFD_OPEN
 106            style always behaves as if this style was specified, because it is
 107            impossible to choose a file that doesn't exist from a standard OS X
 108            file dialog.
 109     @style{wxFD_MULTIPLE}
 110            For open dialog only: allows selecting multiple files.
 111     @style{wxFD_CHANGE_DIR}
 112            Change the current working directory (when the dialog is dismissed)
 113            to the directory where the file(s) chosen by the user are.
 114     @style{wxFD_PREVIEW}
 115            Show the preview of the selected files (currently only supported by
 116            wxGTK).
 117     @endStyleTable
 118
 119     @library{wxcore}
 120     @category{cmndlg}
 121
 122     @see @ref overview_cmndlg_file, ::wxFileSelector()
 123 */
 124 class wxFileDialog : public wxDialog
 125 {
 126 public:
 127     /**
 128         Constructor. Use ShowModal() to show the dialog.
 129
 130         @param parent
 131             Parent window.
 132         @param message
 133             Message to show on the dialog.
 134         @param defaultDir
 135             The default directory, or the empty string.
 136         @param defaultFile
 137             The default filename, or the empty string.
 138         @param wildcard
 139             A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
 140             Note that the native Motif dialog has some limitations with respect to
 141             wildcards; see the Remarks section above.
 142         @param style
 143             A dialog style. See @c wxFD_* styles for more info.
 144         @param pos
 145             Dialog position. Not implemented.
 146         @param size
 147             Dialog size. Not implemented.
 148         @param name
 149             Dialog name. Not implemented.
 150     */
 151     wxFileDialog(wxWindow* parent,
 152                  const wxString& message = wxFileSelectorPromptStr,
 153                  const wxString& defaultDir = wxEmptyString,
 154                  const wxString& defaultFile = wxEmptyString,
 155                  const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
 156                  long style = wxFD_DEFAULT_STYLE,
 157                  const wxPoint& pos = wxDefaultPosition,
 158                  const wxSize& size = wxDefaultSize,
 159                  const wxString& name = wxFileDialogNameStr);
 160
 161     /**
 162         Destructor.
 163     */
 164     virtual ~wxFileDialog();
 165
 166     /**
 167         Returns the default directory.
 168     */
 169     virtual wxString GetDirectory() const;
 170
 171     /**
 172         If functions SetExtraControlCreator() and ShowModal() were called,
 173         returns the extra window. Otherwise returns @NULL.
 174
 175         @since 2.9.0
 176     */
 177     wxWindow* GetExtraControl() const;
 178
 179     /**
 180         Returns the default filename.
 181     */
 182     virtual wxString GetFilename() const;
 183
 184     /**
 185         Fills the array @a filenames with the names of the files chosen.
 186
 187         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 188         use GetFilename() for the others.
 189
 190         Note that under Windows, if the user selects shortcuts, the filenames
 191         include paths, since the application cannot determine the full path
 192         of each referenced file by appending the directory containing the shortcuts
 193         to the filename.
 194     */
 195     virtual void GetFilenames(wxArrayString& filenames) const;
 196
 197     /**
 198         Returns the index into the list of filters supplied, optionally, in the
 199         wildcard parameter.
 200
 201         Before the dialog is shown, this is the index which will be used when the
 202         dialog is first displayed.
 203
 204         After the dialog is shown, this is the index selected by the user.
 205     */
 206     virtual int GetFilterIndex() const;
 207
 208     /**
 209         Returns the message that will be displayed on the dialog.
 210     */
 211     virtual wxString GetMessage() const;
 212
 213     /**
 214         Returns the full path (directory and filename) of the selected file.
 215     */
 216     virtual wxString GetPath() const;
 217
 218     /**
 219         Fills the array @a paths with the full paths of the files chosen.
 220
 221         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 222         use GetPath() for the others.
 223     */
 224     virtual void GetPaths(wxArrayString& paths) const;
 225
 226     /**
 227         Returns the file dialog wildcard.
 228     */
 229     virtual wxString GetWildcard() const;
 230
 231     /**
 232         Sets the default directory.
 233     */
 234     virtual void SetDirectory(const wxString& directory);
 235
 236     /**
 237         The type of function used as an argument for SetExtraControlCreator().
 238
 239         @since 2.9.0
 240     */
 241     typedef wxWindow *(*ExtraControlCreatorFunction)(wxWindow*);
 242
 243     /**
 244         Customize file dialog by adding extra window, which is typically placed
 245         below the list of files and above the buttons.
 246
 247         SetExtraControlCreator() can be called only once, before calling ShowModal().
 248
 249         The @c creator function should take pointer to parent window (file dialog)
 250         and should return a window allocated with operator new.
 251
 252         Supported platforms: wxGTK, wxMSW, wxUniv.
 253
 254         @since 2.9.0
 255     */
 256     bool SetExtraControlCreator(ExtraControlCreatorFunction creator);
 257
 258     /**
 259         Sets the default filename.
 260
 261         In wxGTK this will have little effect unless a default directory has previously been set.
 262     */
 263     virtual void SetFilename(const wxString& setfilename);
 264
 265     /**
 266         Sets the default filter index, starting from zero.
 267     */
 268     virtual void SetFilterIndex(int filterIndex);
 269
 270     /**
 271         Sets the message that will be displayed on the dialog.
 272     */
 273     virtual void SetMessage(const wxString& message);
 274
 275     /**
 276         Sets the path (the combined directory and filename that will be returned when
 277         the dialog is dismissed).
 278     */
 279     virtual void SetPath(const wxString& path);
 280
 281     /**
 282         Sets the wildcard, which can contain multiple file types, for example:
 283         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
 284
 285         Note that the native Motif dialog has some limitations with respect to
 286         wildcards; see the Remarks section above.
 287     */
 288     virtual void SetWildcard(const wxString& wildCard);
 289
 290     /**
 291         Shows the dialog, returning @c wxID_OK if the user pressed OK, and @c wxID_CANCEL
 292         otherwise.
 293     */
 294     virtual int ShowModal();
 295 };
 296
 297
 298
 299 // ============================================================================
 300 // Global functions/macros
 301 // ============================================================================
 302
 303 /** @addtogroup group_funcmacro_dialog */
 304 //@{
 305
 306 /**
 307     Pops up a file selector box. In Windows, this is the common file selector
 308     dialog. In X, this is a file selector box with the same functionality. The
 309     path and filename are distinct elements of a full file pathname. If path
 310     is empty, the current directory will be used. If filename is empty, no
 311     default filename will be supplied. The wildcard determines what files are
 312     displayed in the file selector, and file extension supplies a type
 313     extension for the required filename. Flags may be a combination of
 314     wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
 315
 316     @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
 317           this function only returns a single file name.
 318
 319     Both the Unix and Windows versions implement a wildcard filter. Typing a
 320     filename containing wildcards (*, ?) in the filename text item, and
 321     clicking on Ok, will result in only those files matching the pattern being
 322     displayed.
 323
 324     The wildcard may be a specification for multiple types of file with a
 325     description for each, such as:
 326
 327     @code
 328     "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 329     @endcode
 330
 331     The application must check for an empty return value (the user pressed
 332     Cancel). For example:
 333
 334     @code
 335     wxString filename = wxFileSelector("Choose a file to open");
 336     if ( !filename.empty() )
 337     {
 338         // work with the file
 339         ...
 340     }
 341     //else: cancelled by user
 342     @endcode
 343
 344     @header{wx/filedlg.h}
 345 */
 346 wxString wxFileSelector(const wxString& message,
 347                         const wxString& default_path = wxEmptyString,
 348                         const wxString& default_filename = wxEmptyString,
 349                         const wxString& default_extension = wxEmptyString,
 350                         const wxString& wildcard = ".",
 351                         int flags = 0,
 352                         wxWindow* parent = NULL,
 353                         int x = -1,
 354                         int y = -1);
 355
 356 //@}
 357