interface/filedlg.h

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