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