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 /** @ingroup group_funcmacro_dialog */
 209 //@{
 210
 211 /**
 212     Pops up a file selector box. In Windows, this is the common file selector
 213     dialog. In X, this is a file selector box with the same functionality. The
 214     path and filename are distinct elements of a full file pathname. If path
 215     is empty, the current directory will be used. If filename is empty, no
 216     default filename will be supplied. The wildcard determines what files are
 217     displayed in the file selector, and file extension supplies a type
 218     extension for the required filename. Flags may be a combination of
 219     wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
 220
 221     @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
 222           this function only returns a single file name.
 223
 224     Both the Unix and Windows versions implement a wildcard filter. Typing a
 225     filename containing wildcards (*, ?) in the filename text item, and
 226     clicking on Ok, will result in only those files matching the pattern being
 227     displayed.
 228
 229     The wildcard may be a specification for multiple types of file with a
 230     description for each, such as:
 231
 232     @code
 233     "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 234     @endcode
 235
 236     The application must check for an empty return value (the user pressed
 237     Cancel). For example:
 238
 239     @code
 240     wxString filename = wxFileSelector("Choose a file to open");
 241     if ( !filename.empty() )
 242     {
 243         // work with the file
 244         ...
 245     }
 246     //else: cancelled by user
 247     @endcode
 248
 249     @header{wx/filedlg.h}
 250 */
 251 wxString wxFileSelector(const wxString& message,
 252                         const wxString& default_path = "",
 253                         const wxString& default_filename = "",
 254                         const wxString& default_extension = "",
 255                         const wxString& wildcard = ".",
 256                         int flags = 0,
 257                         wxWindow* parent = NULL,
 258                         int x = -1,
 259                         int y = -1);
 260
 261 //@}
 262