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         In wxGTK this will have little effect unless a default directory has previously been set.
 202     */
 203     virtual void SetFilename(const wxString& setfilename);
 204
 205     /**
 206         Sets the default filter index, starting from zero.
 207     */
 208     virtual void SetFilterIndex(int filterIndex);
 209
 210     /**
 211         Sets the message that will be displayed on the dialog.
 212     */
 213     virtual void SetMessage(const wxString& message);
 214
 215     /**
 216         Sets the path (the combined directory and filename that will be returned when
 217         the dialog is dismissed).
 218     */
 219     virtual void SetPath(const wxString& path);
 220
 221     /**
 222         Sets the wildcard, which can contain multiple file types, for example:
 223         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
 224
 225         Note that the native Motif dialog has some limitations with respect to
 226         wildcards; see the Remarks section above.
 227     */
 228     virtual void SetWildcard(const wxString& wildCard);
 229
 230     /**
 231         Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
 232         otherwise.
 233     */
 234     virtual int ShowModal();
 235 };
 236
 237
 238
 239 // ============================================================================
 240 // Global functions/macros
 241 // ============================================================================
 242
 243 /** @addtogroup group_funcmacro_dialog */
 244 //@{
 245
 246 /**
 247     Pops up a file selector box. In Windows, this is the common file selector
 248     dialog. In X, this is a file selector box with the same functionality. The
 249     path and filename are distinct elements of a full file pathname. If path
 250     is empty, the current directory will be used. If filename is empty, no
 251     default filename will be supplied. The wildcard determines what files are
 252     displayed in the file selector, and file extension supplies a type
 253     extension for the required filename. Flags may be a combination of
 254     wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
 255
 256     @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
 257           this function only returns a single file name.
 258
 259     Both the Unix and Windows versions implement a wildcard filter. Typing a
 260     filename containing wildcards (*, ?) in the filename text item, and
 261     clicking on Ok, will result in only those files matching the pattern being
 262     displayed.
 263
 264     The wildcard may be a specification for multiple types of file with a
 265     description for each, such as:
 266
 267     @code
 268     "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 269     @endcode
 270
 271     The application must check for an empty return value (the user pressed
 272     Cancel). For example:
 273
 274     @code
 275     wxString filename = wxFileSelector("Choose a file to open");
 276     if ( !filename.empty() )
 277     {
 278         // work with the file
 279         ...
 280     }
 281     //else: cancelled by user
 282     @endcode
 283
 284     @header{wx/filedlg.h}
 285 */
 286 wxString wxFileSelector(const wxString& message,
 287                         const wxString& default_path = wxEmptyString,
 288                         const wxString& default_filename = wxEmptyString,
 289                         const wxString& default_extension = wxEmptyString,
 290                         const wxString& wildcard = ".",
 291                         int flags = 0,
 292                         wxWindow* parent = NULL,
 293                         int x = -1,
 294                         int y = -1);
 295
 296 //@}
 297