1/* 2 * Copyright 2009-2012 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/storage/FilePanel.h hrev45162 10 * src/kits/tracker/FilePanel.cpp hrev45162 11 */ 12 13 14/*! 15 \file FilePanel.h 16 \ingroup storage 17 \ingroup libbe 18 \brief Provides the BFilePanel and BRefFilter classes and support enums. 19*/ 20 21 22/*! 23 \enum file_panel_mode 24 \ingroup storage 25 \brief Whether the file panel is a save or open panel. 26*/ 27 28 29/*! 30 \var file_panel_mode B_OPEN_PANEL 31 32 Open panel 33*/ 34 35 36/*! 37 \var file_panel_mode B_SAVE_PANEL 38 39 Save panel 40*/ 41 42 43/*! 44 \enum file_panel_button 45 \ingroup storage 46 \brief List of buttons used by the file panel 47*/ 48 49 50/*! 51 \var file_panel_button B_CANCEL_BUTTON 52 53 Cancel button 54*/ 55 56 57/*! 58 \var file_panel_button B_DEFAULT_BUTTON 59 60 Default button 61*/ 62 63 64/*! 65 \class BRefFilter 66 \ingroup storage 67 \ingroup libbe 68 \brief Allows you to filter the items displayed in a file panel. 69*/ 70 71 72/*! 73 \fn virtual bool BRefFilter::Filter(const entry_ref* ref, BNode* node, 74 struct stat_beos* stat, const char* mimeType) 75 \brief Hook method that's called on each file in the target directory 76 displayed by a file panel. 77 78 \param ref The file currently under consideration. 79 \param node The node currently under consideration. 80 \param stat The stat information of the file. 81 \param mimeType The MIME type of the file. 82 83 \returns Whether or not the entry is a valid candidate for an open/save 84 dialog. 85 86 \see BFilePanel::SetRefFilter() 87*/ 88 89 90/*! 91 \class BFilePanel 92 \ingroup storage 93 \ingroup libbe 94 \brief Displays a standard Open/Save dialog. 95 96 A save panel looks like this: 97 98 \image html BFilePanel_example.png 99 100 An open dialog looks similar but doesn't have a text box for the file name. 101 102 You generally construct a BFilePanel object in response to a user action 103 for example the user clicks on a "Open" or "Save"/"Save As" menu item. 104 Constructing an open or save panel is easy: 105 106\code 107 BFilePanel* openPanel = new BFilePanel(B_OPEN_PANEL); 108 BFilePanel* savePanel = new BFilePanel(B_SAVE_PANEL); 109\endcode 110 111 You can then call methods to indicate what directory to display, whether 112 or not multiple selections are allowed, whether or not the user is 113 allowed to open a directory, what target view to send send notifications, 114 and more. See the constructor for details. 115 116 You can modify the look of your BFilePanel object by calling the 117 SetButtonLabel() and SetSaveText() methods. If you want to change the look 118 even more radically you can get alter the panel's BWindow and BView 119 objects. You get the window by calling the Window() method. With a pointer 120 to the panel's BWindow object you can drill down to the various views 121 contained therein. 122 123 Once you have constructed and customized your BFilePanel object you should 124 call the Show() method to display the panel to the user. 125 126 When the user confirms or cancels a BMessage object is constructed and sent 127 to the target of the BFilePanel object. You can specify a different 128 target in the constructor or by calling the SetTarget() method. 129 130 <b>Open Notifications</b> 131 132 For open notifications the default target is \c be_app_messenger and is 133 caught by the RefsReceived() method The \c what field is set to 134 \c B_REFS_RECEIVED. You can set your own message by calling the 135 SetMessage() method; in this case the message will be sent to the target's 136 MessageReceived() method instead. 137 138 The \c refs field of the message contains an \c entry_ref structure 139 for each entry that the user has selected. The \c refs field is of 140 type \c B_REF_TYPE. If the selected entry is a symlink to a file you'll 141 need to dereference the file yourself. You can do this more easily by 142 turning the \c ref into a BEntry passing \c true into the \c traverse 143 argument like this: 144 145\code 146 BEntry entry(ref, true); 147\endcode 148 149 <b>Save Notifications</b> 150 151 Save notifications are always sent to the target's MessageReceived() 152 method unlike open notifications. The \c what field of the message is 153 set to \c B_SAVE_REQUESTED. The \c directory field contain a single 154 \c entry_ref structure that points to the directory that the entry is 155 saved to. The text that the user typed in the save panel's text view 156 is put in the \c name field and is of type \c B_STRING_TYPE. 157 158 <b>Cancel Notifications</b> 159 160 Cancel notifications are sent when the panel is hidden whether by the 161 user clicking the cancel button, closing the dialog, or confirming the 162 action (assuming hide-when-done is turned on). 163 164 Cancel notifications can be caught by the MessageReceived() method of 165 the target. The \c what field is set to \c B_CANCEL. The \c old_what 166 field is set to the previous what value which is useful if you have 167 overridden the default message. The \c what field of the message you 168 sent is put in the \c old_what field. 169 170 The \c source field is a pointer of \c B_POINTER_TYPE to the closed 171 BFilePanel object. When the BFilePanel object is closed it is not 172 destroyed, it is hidden instead. You can then delete the BFilePanel 173 object or leave it be and simply call Show() to use the panel next time 174 you need it. 175*/ 176 177 178/*! 179 \fn BFilePanel::BFilePanel(file_panel_mode mode, BMessenger* target, 180 const entry_ref* ref, uint32 nodeFlavors, bool multipleSelection, 181 BMessage* message, BRefFilter* filter, bool modal, bool hideWhenDone) 182 \brief Creates and initializes a BFilePanel object. 183 184 The constructor has many parameters but they may generally be set after 185 the object has been constructed. The only parameters that must be set 186 during construction are the \a mode, \a nodeFlavors, \a multipleSelection, 187 and \a modal parameters. The rest may be set after the object has been 188 constructed by the SetTarget(), SetPanelDirectory(), SetMessage(), 189 SetRefFilter(), and SetHideWhenDone() methods. 190 191 \param mode Set to \c B_OPEN_PANEL for an open panal or \c B_SAVE_PANEL 192 for a save panel. Default is \c B_OPEN_PANEL. 193 \param target The BMessenger object that sends messages to the BLooper 194 or BHandler controlled by the file panel. 195 \param ref The directory to display, by default the current working 196 directory. 197 \param nodeFlavors One or more option flags, this applies to open panels only. 198 - \c B_FILE_NODE Can select files and symlinks to files. 199 - \c B_DIRECTORY_NODE Can select directories and symlinks to directories. 200 - \c B_SYMLINK_NODE Can select symlinks only. 201 \param multipleSelection Whether or not the user is allowed to select more 202 than one item to open. Save panels should always set this to \c false. 203 \param message Message sent by the file panel on confirms or cancels. 204 \param filter Hook method to call. 205 \param modal Whether or not the panel is modal, defaults to \c false. 206 \param hideWhenDone Set to \c false to keep the panel even after the user 207 confirms or cancels. The close button will hide the panel regardless. 208*/ 209 210 211/*! 212 \fn BFilePanel::~BFilePanel() 213 \brief Destroys the file panel object. 214 215 If file panel is currently being displayed it is closed. The BRefFilter 216 object references by this panel is not destroyed by this method. 217*/ 218 219 220/*! 221 \fn void BFilePanel::Show() 222 \brief Displays the file panel on screen. 223*/ 224 225 226/*! 227 \fn void BFilePanel::Hide() 228 \brief Hides the file panel. 229*/ 230 231 232/*! 233 \fn bool BFilePanel::IsShowing() const 234 \brief Determines whether or not the file panel is shown. 235 236 \returns \c true if visible, \c false if hidden. 237*/ 238 239 240/*! 241 \fn void BFilePanel::SendMessage(const BMessenger* messenger, 242 BMessage* message) 243 \brief Sends the \a message to the target BHandler \a messenger. 244 245 \param messenger The target BHandler to send the message to. 246 \param message The message to send. 247 248 \see BMessenger::SendMessage() 249*/ 250 251 252/*! 253 \fn file_panel_mode BFilePanel::PanelMode() const 254 \brief Gets the panel mode, either \c B_OPEN_PANEL or \c B_SAVE_PANEL. 255 256 \returns \c B_OPEN_PANEL if the panel is an open panel or \c B_SAVE_PANEL 257 if the panel is a save panel. 258*/ 259 260 261/*! 262 \fn BMessenger BFilePanel::Messenger() const 263 \brief Gets the panel's target messenger object. 264 265 \returns The BMessenger object that sends messages for this panel. 266*/ 267 268 269/*! 270 \fn void BFilePanel::SetTarget(BMessenger target) 271 \brief Sets the target messenger. 272 273 \param target the target BMessenger object to set. 274*/ 275 276 277/*! 278 \fn void BFilePanel::SetMessage(BMessage* message) 279 \brief Sets the target messenge. 280 281 \param message The BMessage object to send on confirm. 282*/ 283 284 285/*! 286 \fn void BFilePanel::Refresh() 287 \brief Refresh the directory or the panel causing the entries to be re-run 288 through the BRefFilter::Filter() method. 289*/ 290 291 292/*! 293 \fn BRefFilter* BFilePanel::RefFilter() const 294 \brief Gets the BRefFilter object associated with the panel. 295 296 \returns The BRefFilter set to the panel. 297 298 \see BRefFilter::Filter() 299*/ 300 301 302/*! 303 \fn void BFilePanel::SetRefFilter(BRefFilter* filter) 304 \brief Sets the BRefFilter used by the panel to filter entries. 305 306 \param filter The BRefFilter object to set. 307 308 \see BRefFilter::Filter() 309*/ 310 311 312/*! 313 \fn void BFilePanel::SetButtonLabel(file_panel_button button, 314 const char* text) 315 \brief Set the button label specified by \a button to \a text. 316 317 \param button The button to set the label of. 318 \param text The text to set the button label to. 319*/ 320 321 322/*! 323 \fn void BFilePanel::GetPanelDirectory(entry_ref* ref) const 324 \brief Gets the entry ref of the panel and sets \a ref to point to it. 325 326 \param ref The \c entry_ref pointer you want set. 327*/ 328 329 330/*! 331 \fn void BFilePanel::SetSaveText(const char* text) 332 \brief Set some save text to display in the save dialog. 333 334 \param text The text to display. 335*/ 336 337 338/*! 339 \fn void BFilePanel::SetPanelDirectory(const entry_ref* ref) 340 \brief Sets the entry ref of the panel to the directory contained 341 by \a ref. 342 343 \param ref The entry contained by the desired panel directory. 344*/ 345 346 347/*! 348 \fn void BFilePanel::SetPanelDirectory(const char* path) 349 \brief Sets the entry ref of the panel to the directory referenced 350 by \a path. 351 352 \param path The path of the desired directory. 353*/ 354 355 356/*! 357 \fn void BFilePanel::SetPanelDirectory(const BEntry* entry) 358 \brief Sets the entry ref of the panel to the directory referenced 359 by \a entry. 360 361 \param entry The BEntry object pointing to the desired directory. 362*/ 363 364 365/*! 366 \fn void BFilePanel::SetPanelDirectory(const BDirectory* dir) 367 \brief Sets the entry ref of the panel to the directory referenced 368 by \a dir. 369 370 \param dir The BDirectory object pointing to the desired directory. 371*/ 372 373 374/*! 375 \fn BWindow* BFilePanel::Window() const 376 \brief Gets a pointer to the BWindow object used by the file panel. 377 378 \returns A pointer to the BWindow object used by the file panel. 379*/ 380 381 382/*! 383 \fn void BFilePanel::Rewind() 384 \brief Sets the entry ref back to the top of the list. 385 386 \see SelectionChanged() 387*/ 388 389 390/*! 391 \fn status_t BFilePanel::GetNextSelectedRef(entry_ref* ref) 392 \brief Sets the \a ref pointer to the next entry in the directory. 393 394 \returns a status message. 395 \retval B_OK Everything went fine. 396 \retval B_ERROR Couldn't attain a lock on the window. 397 \retval B_ENTRY_NOT_FOUND End of the entry list. 398 399 \see SelectionChanged() 400*/ 401 402 403/*! 404 \fn void BFilePanel::SetHideWhenDone(bool on) 405 \brief Sets whether or not the panel should hide on confirm or cancel. 406 407 \param on \c true to hide, \c false to not hide when done. 408*/ 409 410 411/*! 412 \fn bool BFilePanel::HidesWhenDone(void) const 413 \brief Gets whether or not the panel should hide on confirm or cancel. 414 415 Panel always hides if the user clicks the window's close button. 416 417 \returns \c true if panel will hide, \c false if panel will not hide. 418*/ 419 420 421/*! 422 \fn void BFilePanel::WasHidden() 423 \brief Hook method that gets called when the file panel is hidden due to 424 a user action. 425 426 WasHidden() is not called if you call Hide() manually. 427*/ 428 429 430/*! 431 \fn void BFilePanel::SelectionChanged() 432 \brief Hook method that gets called when the entry ref references by the 433 file panel changes. 434 435 \see GetNextSelectedRef() 436 \see Rewind() 437*/ 438
