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