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