interface/filepicker.h

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