interface/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     @wxheader{filedlg.h}
  12
  13     This class represents the file chooser dialog.
  14
  15     It pops up a file selector box (native for Windows and GTK2.4+).
  16
  17     The path and filename are distinct elements of a full file pathname.
  18     If path is "", the current directory will be used. If filename is "", no default
  19     filename will be supplied. The wildcard determines what files are displayed in the
  20     file selector, 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          "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png"
  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 using GTK+ 2.4 or later).
  57     @endStyleTable
  58
  59     @library{wxcore}
  60     @category{cmndlg}
  61
  62     @see @ref overview_wxfiledialog, ::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 = "Choose a file",
  93                  const wxString& defaultDir = "",
  94                  const wxString& defaultFile = "",
  95                  const wxString& wildcard = ".",
  96                  long style = wxFD_DEFAULT_STYLE,
  97                  const wxPoint& pos = wxDefaultPosition,
  98                  const wxSize& sz = wxDefaultSize,
  99                  const wxString& name = "filedlg");
 100
 101     /**
 102         Destructor.
 103     */
 104     ~wxFileDialog();
 105
 106     /**
 107         Returns the default directory.
 108     */
 109     wxString GetDirectory() const;
 110
 111     /**
 112         If functions SetExtraControlCreator() and ShowModal() were called,
 113         returns the extra window. Otherwise returns @NULL.
 114     */
 115     wxWindow* GetExtraControl() const;
 116
 117     /**
 118         Returns the default filename.
 119     */
 120     wxString GetFilename() const;
 121
 122     /**
 123         Fills the array @a filenames with the names of the files chosen.
 124
 125         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 126         use GetFilename() for the others.
 127
 128         Note that under Windows, if the user selects shortcuts, the filenames
 129         include paths, since the application cannot determine the full path
 130         of each referenced file by appending the directory containing the shortcuts
 131         to the filename.
 132     */
 133     void GetFilenames(wxArrayString& filenames) const;
 134
 135     /**
 136         Returns the index into the list of filters supplied, optionally, in the
 137         wildcard parameter.
 138
 139         Before the dialog is shown, this is the index which will be used when the
 140         dialog is first displayed.
 141
 142         After the dialog is shown, this is the index selected by the user.
 143     */
 144     int GetFilterIndex() const;
 145
 146     /**
 147         Returns the message that will be displayed on the dialog.
 148     */
 149     wxString GetMessage() const;
 150
 151     /**
 152         Returns the full path (directory and filename) of the selected file.
 153     */
 154     wxString GetPath() const;
 155
 156     /**
 157         Fills the array @a paths with the full paths of the files chosen.
 158
 159         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
 160         use GetPath() for the others.
 161     */
 162     void GetPaths(wxArrayString& paths) const;
 163
 164     /**
 165         Returns the file dialog wildcard.
 166     */
 167     wxString GetWildcard() const;
 168
 169     /**
 170         Sets the default directory.
 171     */
 172     void SetDirectory(const wxString& directory);
 173
 174     /**
 175         Customize file dialog by adding extra window, which is typically placed
 176         below the list of files and above the buttons.
 177
 178         SetExtraControlCreator() can be called only once, before calling ShowModal().
 179
 180         The @c creator function should take pointer to parent window (file dialog)
 181         and should return a window allocated with operator new.
 182
 183         Supported platforms: wxGTK, wxUniv.
 184     */
 185     bool SetExtraControlCreator(t_extraControlCreator creator);
 186
 187     /**
 188         Sets the default filename.
 189     */
 190     void SetFilename(const wxString& setfilename);
 191
 192     /**
 193         Sets the default filter index, starting from zero.
 194     */
 195     void SetFilterIndex(int filterIndex);
 196
 197     /**
 198         Sets the message that will be displayed on the dialog.
 199     */
 200     void SetMessage(const wxString& message);
 201
 202     /**
 203         Sets the path (the combined directory and filename that will be returned when
 204         the dialog is dismissed).
 205     */
 206     void SetPath(const wxString& path);
 207
 208     /**
 209         Sets the wildcard, which can contain multiple file types, for example:
 210         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
 211
 212         Note that the native Motif dialog has some limitations with respect to
 213         wildcards; see the Remarks section above.
 214     */
 215     void SetWildcard(const wxString& wildCard);
 216
 217     /**
 218         Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
 219         otherwise.
 220     */
 221     int ShowModal();
 222 };
 223
 224
 225
 226 // ============================================================================
 227 // Global functions/macros
 228 // ============================================================================
 229
 230 /** @ingroup group_funcmacro_dialog */
 231 //@{
 232
 233 /**
 234     Pops up a file selector box. In Windows, this is the common file selector
 235     dialog. In X, this is a file selector box with the same functionality. The
 236     path and filename are distinct elements of a full file pathname. If path
 237     is empty, the current directory will be used. If filename is empty, no
 238     default filename will be supplied. The wildcard determines what files are
 239     displayed in the file selector, and file extension supplies a type
 240     extension for the required filename. Flags may be a combination of
 241     wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
 242
 243     @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
 244           this function only returns a single file name.
 245
 246     Both the Unix and Windows versions implement a wildcard filter. Typing a
 247     filename containing wildcards (*, ?) in the filename text item, and
 248     clicking on Ok, will result in only those files matching the pattern being
 249     displayed.
 250
 251     The wildcard may be a specification for multiple types of file with a
 252     description for each, such as:
 253
 254     @code
 255     "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 256     @endcode
 257
 258     The application must check for an empty return value (the user pressed
 259     Cancel). For example:
 260
 261     @code
 262     wxString filename = wxFileSelector("Choose a file to open");
 263     if ( !filename.empty() )
 264     {
 265         // work with the file
 266         ...
 267     }
 268     //else: cancelled by user
 269     @endcode
 270
 271     @header{wx/filedlg.h}
 272 */
 273 wxString wxFileSelector(const wxString& message,
 274                         const wxString& default_path = "",
 275                         const wxString& default_filename = "",
 276                         const wxString& default_extension = "",
 277                         const wxString& wildcard = ".",
 278                         int flags = 0,
 279                         wxWindow* parent = NULL,
 280                         int x = -1,
 281                         int y = -1);
 282
 283 //@}
 284