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