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