/** Copyright 2009-2014 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* John Scipione, jscipione@gmail.com** Corresponds to:* headers/os/storage/FilePanel.h hrev47402* src/kits/tracker/FilePanel.cpp hrev47402*//*!\file FilePanel.h\ingroup storage\ingroup libtracker\brief Provides the BFilePanel and BRefFilter classes and support enums.*//*!\enum file_panel_mode\ingroup storage\brief Whether the file panel is a save or open panel.\since BeOS R3*//*!\var file_panel_mode B_OPEN_PANELOpen panel\since BeOS R3*//*!\var file_panel_mode B_SAVE_PANEL\since BeOS R3Save panel*//*!\enum file_panel_button\ingroup storage\brief List of buttons used by the file panel.\since BeOS R3*//*!\var file_panel_button B_CANCEL_BUTTONCancel button\since BeOS R3*//*!\var file_panel_button B_DEFAULT_BUTTONDefault button\since BeOS R3*//*!\class BRefFilter\ingroup storage\ingroup libtracker\brief Allows you to filter the items displayed in a file panel.\since BeOS R3*//*!\fn virtual bool BRefFilter::Filter(const entry_ref* ref, BNode* node,struct stat_beos* stat, const char* mimeType)\brief Hook method that's called on each file in the target directorydisplayed by a file panel.\param ref The file currently under consideration.\param node The node currently under consideration.\param stat The stat information of the file.\param mimeType The MIME type of the file.\returns Whether or not the entry is a valid candidate for an open/savedialog.\see BFilePanel::SetRefFilter()\since BeOS R3*//*!\class BFilePanel\ingroup storage\ingroup libtracker\brief Displays a standard Open/Save dialog.A save panel looks like this:\image html BFilePanel_example.pngAn open dialog looks similar but doesn't have a text box for the file name.You generally construct a BFilePanel object in response to a user actionfor example the user clicks on a "Open" or "Save"/"Save As" menu item.Constructing an open or save panel is easy:\codeBFilePanel* openPanel = new BFilePanel(B_OPEN_PANEL);BFilePanel* savePanel = new BFilePanel(B_SAVE_PANEL);\endcodeYou can then call methods to indicate what directory to display, whetheror not multiple selections are allowed, whether or not the user isallowed to open a directory, what target view to send send notifications,and more. See the constructor for details.You can modify the look of your BFilePanel object by calling theSetButtonLabel() and SetSaveText() methods. If you want to change the lookeven more radically you can get alter the panel's BWindow and BViewobjects. You get the window by calling the Window() method. With a pointerto the panel's BWindow object you can drill down to the various viewscontained therein.Once you have constructed and customized your BFilePanel object you shouldcall the Show() method to display the panel to the user.When the user confirms or cancels a BMessage object is constructed and sentto the target of the BFilePanel object. You can specify a differenttarget in the constructor or by calling the SetTarget() method.<b>Open Notifications</b>For open notifications the default target is \c be_app_messenger and iscaught by the RefsReceived() method The \c what field is set to\c B_REFS_RECEIVED. You can set your own message by calling theSetMessage() method; in this case the message will be sent to the target'sMessageReceived() method instead.The \c refs field of the message contains an \c entry_ref structurefor each entry that the user has selected. The \c refs field is oftype \c B_REF_TYPE. If the selected entry is a symlink to a file you'llneed to dereference the file yourself. You can do this more easily byturning the \c ref into a BEntry passing \c true into the \c traverseargument like this:\codeBEntry entry(ref, true);\endcode<b>Save Notifications</b>Save notifications are always sent to the target's MessageReceived()method unlike open notifications. The \c what field of the message isset to \c B_SAVE_REQUESTED. The \c directory field contain a single\c entry_ref structure that points to the directory that the entry issaved to. The text that the user typed in the save panel's text viewis put in the \c name field and is of type \c B_STRING_TYPE.<b>Cancel Notifications</b>Cancel notifications are sent when the panel is hidden whether by theuser clicking the cancel button, closing the dialog, or confirming theaction (assuming hide-when-done is turned on).Cancel notifications can be caught by the MessageReceived() method ofthe target. The \c what field is set to \c B_CANCEL. The \c old_whatfield is set to the previous what value which is useful if you haveoverridden the default message. The \c what field of the message yousent is put in the \c old_what field.The \c source field is a pointer of \c B_POINTER_TYPE to the closedBFilePanel object. When the BFilePanel object is closed it is notdestroyed, it is hidden instead. You can then delete the BFilePanelobject or leave it be and simply call Show() to use the panel next timeyou need it.\since BeOS R3*//*!\fn BFilePanel::BFilePanel(file_panel_mode mode, BMessenger* target,const entry_ref* ref, uint32 nodeFlavors, bool multipleSelection,BMessage* message, BRefFilter* filter, bool modal, bool hideWhenDone)\brief Creates and initializes a BFilePanel object.The constructor has many parameters but they may generally be set afterthe object has been constructed. The only parameters that must be setduring construction are the \a mode, \a nodeFlavors, \a multipleSelection,and \a modal parameters. The rest may be set after the object has beenconstructed by the SetTarget(), SetPanelDirectory(), SetMessage(),SetRefFilter(), and SetHideWhenDone() methods.\param mode Set to \c B_OPEN_PANEL for an open panal or \c B_SAVE_PANELfor a save panel. Default is \c B_OPEN_PANEL.\param target The BMessenger object that sends messages to the BLooperor BHandler controlled by the file panel.\param ref The directory to display, by default the current workingdirectory.\param nodeFlavors One or more option flags, this applies to open panelsonly.- \c B_FILE_NODE Can select files and symlinks to files.- \c B_DIRECTORY_NODE Can select directories and symlinks todirectories.- \c B_SYMLINK_NODE Can select symlinks only.\param multipleSelection Whether or not the user is allowed to select morethan one item to open. Save panels should always set this to\c false.\param message Message sent by the file panel on confirms or cancels.\param filter Hook method to call.\param modal Whether or not the panel is modal, defaults to \c false.\param hideWhenDone Set to \c false to keep the panel even after the userconfirms or cancels. The close button will hide the panelregardless.\since BeOS R3*//*!\fn BFilePanel::~BFilePanel()\brief Destroys the file panel object.If file panel is currently being displayed it is closed. The BRefFilterobject references by this panel is not destroyed by this method.\since BeOS R3*//*!\fn void BFilePanel::Show()\brief Displays the file panel on screen.\since BeOS R3*//*!\fn void BFilePanel::Hide()\brief Hides the file panel.\since BeOS R3*//*!\fn bool BFilePanel::IsShowing() const\brief Determines whether or not the file panel is shown.\returns \c true if visible, \c false if hidden.\see Show()\since BeOS R3*//*!\fn void BFilePanel::SendMessage(const BMessenger* messenger,BMessage* message)\brief Sends the \a message to the target BHandler \a messenger.\param messenger The target BHandler to send the message to.\param message The message to send.\see BMessenger::SendMessage()\since BeOS R3*//*!\fn file_panel_mode BFilePanel::PanelMode() const\brief Gets the panel mode, either \c B_OPEN_PANEL or \c B_SAVE_PANEL.\returns \c B_OPEN_PANEL if the panel is an open panel, or \c B_SAVE_PANELif the panel is a save panel.\since BeOS R3*//*!\fn BMessenger BFilePanel::Messenger() const\brief Gets the panel's target messenger object.\returns The BMessenger object that sends messages for this panel.\since BeOS R3*//*!\fn void BFilePanel::SetTarget(BMessenger target)\brief Sets the target messenger.\param target the target BMessenger object to set.\since BeOS R3*//*!\fn void BFilePanel::SetMessage(BMessage* message)\brief Sets the target messenge.\param message The BMessage object to send on confirm.\since BeOS R3*//*!\fn void BFilePanel::Refresh()\brief Refresh the directory or the panel causing the entries to be re-runthrough the BRefFilter::Filter() method.\since BeOS R3*//*!\fn BRefFilter* BFilePanel::RefFilter() const\brief Gets the BRefFilter object associated with the panel.\returns The BRefFilter set to the panel.\see BRefFilter::Filter()\since BeOS R3*//*!\fn void BFilePanel::SetRefFilter(BRefFilter* filter)\brief Sets the BRefFilter used by the panel to filter entries.\param filter The BRefFilter object to set.\see BRefFilter::Filter()\since BeOS R3*//*!\fn void BFilePanel::SetButtonLabel(file_panel_button button,const char* text)\brief Set the button label specified by \a button to \a text.\param button The button to set the label of.\param text The text to set the button label to.\since BeOS R3*//*!\fn void BFilePanel::GetPanelDirectory(entry_ref* ref) const\brief Gets the entry ref of the panel and sets \a ref to point to it.\param ref The \c entry_ref pointer you want set.\since BeOS R3*//*!\fn void BFilePanel::SetSaveText(const char* text)\brief Set some save text to display in the save dialog.\param text The text to display.\since BeOS R3*//*!\fn void BFilePanel::SetPanelDirectory(const entry_ref* ref)\brief Sets the entry ref of the panel to the directory containedby \a ref.\param ref The entry contained by the desired panel directory.\since BeOS R3*//*!\fn void BFilePanel::SetPanelDirectory(const char* path)\brief Sets the entry ref of the panel to the directory referencedby \a path.\param path The path of the desired directory.\since BeOS R3*//*!\fn void BFilePanel::SetPanelDirectory(const BEntry* entry)\brief Sets the entry ref of the panel to the directory referencedby \a entry.\param entry The BEntry object pointing to the desired directory.\since BeOS R3*//*!\fn void BFilePanel::SetPanelDirectory(const BDirectory* dir)\brief Sets the entry ref of the panel to the directory referencedby \a dir.\param dir The BDirectory object pointing to the desired directory.\since BeOS R3*//*!\fn BWindow* BFilePanel::Window() const\brief Gets a pointer to the BWindow object used by the file panel.\returns A pointer to the BWindow object used by the file panel.\since BeOS R3*//*!\fn void BFilePanel::Rewind()\brief Sets the entry ref back to the top of the list.\see SelectionChanged()\since BeOS R3*//*!\fn status_t BFilePanel::GetNextSelectedRef(entry_ref* ref)\brief Sets the \a ref pointer to the next entry in the directory.\returns a status message.\retval B_OK Everything went fine.\retval B_ERROR Couldn't attain a lock on the window.\retval B_ENTRY_NOT_FOUND End of the entry list.\see Rewind()\see SelectionChanged()\since BeOS R3*//*!\fn void BFilePanel::SetHideWhenDone(bool on)\brief Sets whether or not the panel should hide on confirm or cancel.\param on \c true to hide, \c false to not hide when done.\since BeOS R3*//*!\fn bool BFilePanel::HidesWhenDone(void) const\brief Gets whether or not the panel should hide on confirm or cancel.Panel always hides if the user clicks the window's close button.\returns \c true if panel will hide, \c false if panel will not hide.\see SetHideWhenDone()\since BeOS R3*//*!\name Hook Methods*///! @{/*!\fn void BFilePanel::WasHidden()\brief Hook method that gets called when the file panel is hidden due toa user action.WasHidden() is not called if you call Hide() manually.\since BeOS R3*//*!\fn void BFilePanel::SelectionChanged()\brief Hook method that gets called when the entry ref references by thefile panel changes.\see GetNextSelectedRef()\see Rewind()\since BeOS R3*///! @}