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