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