interface/wx/filepicker.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filepicker.h
   3 // Purpose:     interface of wxFilePickerCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFilePickerCtrl
  11
  12     This control allows the user to select a file. The generic implementation is
  13     a button which brings up a wxFileDialog when clicked. Native implementation
  14     may differ but this is usually a (small) widget which give access to the
  15     file-chooser dialog.
  16     It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default).
  17
  18     @beginStyleTable
  19     @style{wxFLP_DEFAULT_STYLE}
  20            The default style: includes wxFLP_OPEN | wxFLP_FILE_MUST_EXIST and,
  21            under wxMSW only, wxFLP_USE_TEXTCTRL.
  22     @style{wxFLP_USE_TEXTCTRL}
  23            Creates a text control to the left of the picker button which is
  24            completely managed by the wxFilePickerCtrl and which can be used by
  25            the user to specify a path (see SetPath). The text control is
  26            automatically synchronized with button's value. Use functions
  27            defined in wxPickerBase to modify the text control.
  28     @style{wxFLP_OPEN}
  29            Creates a picker which allows the user to select a file to open.
  30     @style{wxFLP_SAVE}
  31            Creates a picker which allows the user to select a file to save.
  32     @style{wxFLP_OVERWRITE_PROMPT}
  33            Can be combined with wxFLP_SAVE only: ask confirmation to the user
  34            before selecting a file.
  35     @style{wxFLP_FILE_MUST_EXIST}
  36            Can be combined with wxFLP_OPEN only: the selected file must be an
  37            existing file.
  38     @style{wxFLP_CHANGE_DIR}
  39            Change current working directory on each user file selection change.
  40     @endStyleTable
  41
  42
  43     @beginEventTable{wxFileDirPickerEvent}
  44     @event{EVT_FILEPICKER_CHANGED(id, func)}
  45         The user changed the file selected in the control either using the
  46         button or using text control (see wxFLP_USE_TEXTCTRL; note that in
  47         this case the event is fired only if the user's input is valid,
  48         e.g. an existing file path if wxFLP_FILE_MUST_EXIST was given).
  49     @endEventTable
  50
  51     @library{wxcore}
  52     @category{pickers}
  53     @appearance{filepickerctrl.png}
  54
  55     @see wxFileDialog, wxFileDirPickerEvent
  56 */
  57 class wxFilePickerCtrl : public wxPickerBase
  58 {
  59 public:
  60     /**
  61         Initializes the object and calls Create() with
  62         all the parameters.
  63     */
  64     wxFilePickerCtrl(wxWindow* parent, wxWindowID id,
  65                      const wxString& path = wxEmptyString,
  66                      const wxString& message = "Select a file",
  67                      const wxString& wildcard = ".",
  68                      const wxPoint& pos = wxDefaultPosition,
  69                      const wxSize& size = wxDefaultSize,
  70                      long style = wxFLP_DEFAULT_STYLE,
  71                      const wxValidator& validator = wxDefaultValidator,
  72                      const wxString& name = "filepickerctrl");
  73
  74     /**
  75         Creates this widget with the given parameters.
  76
  77         @param parent
  78             Parent window, must not be non-@NULL.
  79         @param id
  80             The identifier for the control.
  81         @param path
  82             The initial file shown in the control. Must be a valid path to a file or
  83             the empty string.
  84         @param message
  85             The message shown to the user in the wxFileDialog shown by the control.
  86         @param wildcard
  87             A wildcard which defines user-selectable files (use the same syntax as for
  88             wxFileDialog's wildcards).
  89         @param pos
  90             Initial position.
  91         @param size
  92             Initial size.
  93         @param style
  94             The window style, see wxFLP_* flags.
  95         @param validator
  96             Validator which can be used for additional data checks.
  97         @param name
  98             Control name.
  99
 100         @return @true if the control was successfully created or @false if
 101                 creation failed.
 102     */
 103     bool Create(wxWindow* parent, wxWindowID id,
 104                 const wxString& path = wxEmptyString,
 105                 const wxString& message = "Select a file",
 106                 const wxString& wildcard = ".",
 107                 const wxPoint& pos = wxDefaultPosition,
 108                 const wxSize& size = wxDefaultSize,
 109                 long style = wxFLP_DEFAULT_STYLE,
 110                 const wxValidator& validator = wxDefaultValidator,
 111                 const wxString& name = "filepickerctrl");
 112
 113     /**
 114         Similar to GetPath() but returns the path of the currently selected
 115         file as a wxFileName object.
 116     */
 117     wxFileName GetFileName() const;
 118
 119     /**
 120         Returns the absolute path of the currently selected file.
 121     */
 122     wxString GetPath() const;
 123
 124     /**
 125         This method does the same thing as SetPath() but takes a wxFileName
 126         object instead of a string.
 127     */
 128     void SetFileName(const wxFileName& filename);
 129
 130     /**
 131         Sets the absolute path of the currently selected file.
 132         This must be a valid file if the @c wxFLP_FILE_MUST_EXIST style was given.
 133     */
 134     void SetPath(const wxString& filename);
 135 };
 136
 137
 138
 139 /**
 140     @class wxDirPickerCtrl
 141
 142     This control allows the user to select a directory. The generic implementation
 143     is a button which brings up a wxDirDialog when clicked. Native implementation
 144     may differ but this is usually a (small) widget which give access to the
 145     dir-chooser dialog.
 146     It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default).
 147
 148     @beginStyleTable
 149     @style{wxDIRP_DEFAULT_STYLE}
 150            The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW
 151            only, wxDIRP_USE_TEXTCTRL.
 152     @style{wxDIRP_USE_TEXTCTRL}
 153            Creates a text control to the left of the picker button which is
 154            completely managed by the wxDirPickerCtrl and which can be used by
 155            the user to specify a path (see SetPath). The text control is
 156            automatically synchronized with button's value. Use functions
 157            defined in wxPickerBase to modify the text control.
 158     @style{wxDIRP_DIR_MUST_EXIST}
 159            Creates a picker which allows to select only existing directories.
 160            wxGTK control always adds this flag internally as it does not
 161            support its absence.
 162     @style{wxDIRP_CHANGE_DIR}
 163            Change current working directory on each user directory selection change.
 164     @endStyleTable
 165
 166     @beginEventTable{wxFileDirPickerEvent}
 167     @event{EVT_DIRPICKER_CHANGED(id, func)}
 168         The user changed the directory selected in the control either using the
 169         button or using text control (see wxDIRP_USE_TEXTCTRL; note that in this
 170         case the event is fired only if the user's input is valid, e.g. an
 171         existing directory path).
 172     @endEventTable
 173
 174
 175     @library{wxcore}
 176     @category{pickers}
 177     @appearance{dirpickerctrl.png}
 178
 179     @see wxDirDialog, wxFileDirPickerEvent
 180 */
 181 class wxDirPickerCtrl : public wxPickerBase
 182 {
 183 public:
 184     /**
 185         Initializes the object and calls Create() with
 186         all the parameters.
 187     */
 188     wxDirPickerCtrl(wxWindow* parent, wxWindowID id,
 189                     const wxString& path = wxEmptyString,
 190                     const wxString& message = "Select a folder",
 191                     const wxPoint& pos = wxDefaultPosition,
 192                     const wxSize& size = wxDefaultSize,
 193                     long style = wxDIRP_DEFAULT_STYLE,
 194                     const wxValidator& validator = wxDefaultValidator,
 195                     const wxString& name = "dirpickerctrl");
 196
 197     /**
 198         Creates the widgets with the given parameters.
 199
 200         @param parent
 201             Parent window, must not be non-@NULL.
 202         @param id
 203             The identifier for the control.
 204         @param path
 205             The initial directory shown in the control. Must be a valid path to a
 206             directory or the empty string.
 207         @param message
 208             The message shown to the user in the wxDirDialog shown by the control.
 209         @param pos
 210             Initial position.
 211         @param size
 212             Initial size.
 213         @param style
 214             The window style, see wxDIRP_* flags.
 215         @param validator
 216             Validator which can be used for additional date checks.
 217         @param name
 218             Control name.
 219
 220         @return @true if the control was successfully created or @false if
 221                 creation failed.
 222     */
 223     bool Create(wxWindow* parent, wxWindowID id,
 224                 const wxString& path = wxEmptyString,
 225                 const wxString& message = "Select a folder",
 226                 const wxPoint& pos = wxDefaultPosition,
 227                 const wxSize& size = wxDefaultSize,
 228                 long style = wxDIRP_DEFAULT_STYLE,
 229                 const wxValidator& validator = wxDefaultValidator,
 230                 const wxString& name = "dirpickerctrl");
 231
 232     /**
 233         Returns the absolute path of the currently selected directory as a
 234         wxFileName object.
 235         This function is equivalent to GetPath().
 236     */
 237     wxFileName GetDirName() const;
 238
 239     /**
 240         Returns the absolute path of the currently selected directory.
 241     */
 242     wxString GetPath() const;
 243
 244     /**
 245         Just like SetPath() but this function takes a wxFileName object.
 246     */
 247     void SetDirName(const wxFileName& dirname);
 248
 249     /**
 250         Sets the absolute path of  (the default converter uses current locale's
 251         charset)the currently selected directory.
 252         This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given.
 253     */
 254     void SetPath(const wxString& dirname);
 255 };
 256
 257
 258
 259 /**
 260     @class wxFileDirPickerEvent
 261
 262     This event class is used for the events generated by
 263     wxFilePickerCtrl and by wxDirPickerCtrl.
 264
 265     @beginEventTable{wxFileDirPickerEvent}
 266     @event{EVT_FILEPICKER_CHANGED(id, func)}
 267         Generated whenever the selected file changes.
 268     @event{EVT_DIRPICKER_CHANGED(id, func)}
 269         Generated whenever the selected directory changes.
 270     @endEventTable
 271
 272     @library{wxcore}
 273     @category{events}
 274
 275     @see wxFilePickerCtrl, wxDirPickerCtrl
 276 */
 277 class wxFileDirPickerEvent : public wxCommandEvent
 278 {
 279 public:
 280     /**
 281         The constructor is not normally used by the user code.
 282     */
 283     wxFileDirPickerEvent(wxEventType type, wxObject* generator,
 284                          int id,
 285                          const wxString path);
 286
 287     /**
 288         Retrieve the absolute path of the file/directory the user has just selected.
 289     */
 290     wxString GetPath() const;
 291
 292     /**
 293         Set the absolute path of the file/directory associated with the event.
 294     */
 295     void SetPath(const wxString& path);
 296 };
 297