Public Member Functions | List of all members
BFilePanel Class Reference

Displays a standard Open/Save dialog. More...

Public Member Functions

 BFilePanel (file_panel_mode mode=B_OPEN_PANEL, BMessenger *target=NULL, const entry_ref *directory=NULL, uint32 nodeFlavors=0, bool allowMultipleSelection=true, BMessage *message=NULL, BRefFilter *refFilter=NULL, bool modal=false, bool hideWhenDone=true)
 Creates and initializes a BFilePanel object. More...
 
virtual ~BFilePanel ()
 Destroys the file panel object. More...
 
status_t GetNextSelectedRef (entry_ref *ref)
 Sets the ref pointer to the next entry in the directory. More...
 
void GetPanelDirectory (entry_ref *ref) const
 Gets the entry ref of the panel and sets ref to point to it. More...
 
void Hide ()
 Hides the file panel. More...
 
bool HidesWhenDone () const
 Gets whether or not the panel should hide on confirm or cancel. More...
 
bool IsShowing () const
 Determines whether or not the file panel is shown. More...
 
BMessenger Messenger () const
 Gets the panel's target messenger object. More...
 
file_panel_mode PanelMode () const
 Gets the panel mode, either B_OPEN_PANEL or B_SAVE_PANEL. More...
 
BRefFilterRefFilter () const
 Gets the BRefFilter object associated with the panel. More...
 
void Refresh ()
 Refresh the directory or the panel causing the entries to be re-run through the BRefFilter::Filter() method. More...
 
void Rewind ()
 Sets the entry ref back to the top of the list. More...
 
virtual void SendMessage (const BMessenger *target, BMessage *message)
 Sends the message to the target BHandler messenger. More...
 
void SetButtonLabel (file_panel_button button, const char *label)
 Set the button label specified by button to text. More...
 
void SetHideWhenDone (bool hideWhenDone)
 Sets whether or not the panel should hide on confirm or cancel. More...
 
void SetMessage (BMessage *message)
 Sets the target messenge. More...
 
void SetPanelDirectory (const BEntry *newDirectory)
 Sets the entry ref of the panel to the directory referenced by entry. More...
 
void SetPanelDirectory (const BDirectory *newDirectory)
 Sets the entry ref of the panel to the directory referenced by dir. More...
 
void SetPanelDirectory (const entry_ref *newDirectory)
 Sets the entry ref of the panel to the directory contained by ref. More...
 
void SetPanelDirectory (const char *newDirectory)
 Sets the entry ref of the panel to the directory referenced by path. More...
 
void SetRefFilter (BRefFilter *filter)
 Sets the BRefFilter used by the panel to filter entries. More...
 
void SetSaveText (const char *text)
 Set some save text to display in the save dialog. More...
 
void SetTarget (BMessenger target)
 Sets the target messenger. More...
 
void Show ()
 Displays the file panel on screen. More...
 
BWindowWindow () const
 Gets a pointer to the BWindow object used by the file panel. More...
 
Hook Methods
virtual void WasHidden ()
 Hook method that gets called when the file panel is hidden due to a user action. More...
 
virtual void SelectionChanged ()
 Hook method that gets called when the entry ref references by the file panel changes. More...
 

Detailed Description

Displays a standard Open/Save dialog.

A save panel looks like this:

BFilePanel_example.png

An 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 action for example the user clicks on a "Open" or "Save"/"Save As" menu item. Constructing an open or save panel is easy:

You can then call methods to indicate what directory to display, whether or not multiple selections are allowed, whether or not the user is allowed 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 the SetButtonLabel() and SetSaveText() methods. If you want to change the look even more radically you can get alter the panel's BWindow and BView objects. You get the window by calling the Window() method. With a pointer to the panel's BWindow object you can drill down to the various views contained therein.

Once you have constructed and customized your BFilePanel object you should call the Show() method to display the panel to the user.

When the user confirms or cancels a BMessage object is constructed and sent to the target of the BFilePanel object. You can specify a different target in the constructor or by calling the SetTarget() method.

Open Notifications

For open notifications the default target is be_app_messenger and is caught by the RefsReceived() method The what field is set to B_REFS_RECEIVED. You can set your own message by calling the SetMessage() method; in this case the message will be sent to the target's MessageReceived() method instead.

The refs field of the message contains an entry_ref structure for each entry that the user has selected. The refs field is of type B_REF_TYPE. If the selected entry is a symlink to a file you'll need to dereference the file yourself. You can do this more easily by turning the ref into a BEntry passing true into the traverse argument like this:

BEntry entry(ref, true);

Save Notifications

Save notifications are always sent to the target's MessageReceived() method unlike open notifications. The what field of the message is set to B_SAVE_REQUESTED. The directory field contain a single entry_ref structure that points to the directory that the entry is saved to. The text that the user typed in the save panel's text view is put in the name field and is of type B_STRING_TYPE.

Cancel Notifications

Cancel notifications are sent when the panel is hidden whether by the user clicking the cancel button, closing the dialog, or confirming the action (assuming hide-when-done is turned on).

Cancel notifications can be caught by the MessageReceived() method of the target. The what field is set to B_CANCEL. The old_what field is set to the previous what value which is useful if you have overridden the default message. The what field of the message you sent is put in the old_what field.

The source field is a pointer of B_POINTER_TYPE to the closed BFilePanel object. When the BFilePanel object is closed it is not destroyed, it is hidden instead. You can then delete the BFilePanel object or leave it be and simply call Show() to use the panel next time you need it.

Since
BeOS R3

Constructor & Destructor Documentation

◆ BFilePanel()

BFilePanel::BFilePanel ( file_panel_mode  mode = B_OPEN_PANEL,
BMessenger target = NULL,
const entry_ref ref = NULL,
uint32  nodeFlavors = 0,
bool  multipleSelection = true,
BMessage message = NULL,
BRefFilter filter = NULL,
bool  modal = false,
bool  hideWhenDone = true 
)

Creates and initializes a BFilePanel object.

The constructor has many parameters but they may generally be set after the object has been constructed. The only parameters that must be set during construction are the mode, nodeFlavors, multipleSelection, and modal parameters. The rest may be set after the object has been constructed by the SetTarget(), SetPanelDirectory(), SetMessage(), SetRefFilter(), and SetHideWhenDone() methods.

Parameters
modeSet to B_OPEN_PANEL for an open panal or B_SAVE_PANEL for a save panel. Default is B_OPEN_PANEL.
targetThe BMessenger object that sends messages to the BLooper or BHandler controlled by the file panel.
refThe directory to display, by default the current working directory.
nodeFlavorsOne or more option flags, this applies to open panels only.
  • B_FILE_NODE Can select files and symlinks to files.
  • B_DIRECTORY_NODE Can select directories and symlinks to directories.
  • B_SYMLINK_NODE Can select symlinks only.
multipleSelectionWhether or not the user is allowed to select more than one item to open. Save panels should always set this to false.
messageMessage sent by the file panel on confirms or cancels.
filterHook method to call.
modalWhether or not the panel is modal, defaults to false.
hideWhenDoneSet to false to keep the panel even after the user confirms or cancels. The close button will hide the panel regardless.
Since
BeOS R3

◆ ~BFilePanel()

BFilePanel::~BFilePanel ( )
virtual

Destroys the file panel object.

If file panel is currently being displayed it is closed. The BRefFilter object references by this panel is not destroyed by this method.

Since
BeOS R3

Member Function Documentation

◆ GetNextSelectedRef()

status_t BFilePanel::GetNextSelectedRef ( entry_ref ref)

Sets the ref pointer to the next entry in the directory.

Returns
a status message.
Return values
B_OKEverything went fine.
B_ERRORCouldn't attain a lock on the window.
B_ENTRY_NOT_FOUNDEnd of the entry list.
See also
Rewind()
SelectionChanged()
Since
BeOS R3

◆ GetPanelDirectory()

void BFilePanel::GetPanelDirectory ( entry_ref ref) const

Gets the entry ref of the panel and sets ref to point to it.

Parameters
refThe entry_ref pointer you want set.
Since
BeOS R3

◆ Hide()

void BFilePanel::Hide ( )

Hides the file panel.

Since
BeOS R3

◆ HidesWhenDone()

bool BFilePanel::HidesWhenDone ( void  ) const

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
true if panel will hide, false if panel will not hide.
See also
SetHideWhenDone()
Since
BeOS R3

◆ IsShowing()

bool BFilePanel::IsShowing ( ) const

Determines whether or not the file panel is shown.

Returns
true if visible, false if hidden.
See also
Show()
Since
BeOS R3

◆ Messenger()

BMessenger BFilePanel::Messenger ( ) const

Gets the panel's target messenger object.

Returns
The BMessenger object that sends messages for this panel.
Since
BeOS R3

◆ PanelMode()

file_panel_mode BFilePanel::PanelMode ( ) const

Gets the panel mode, either B_OPEN_PANEL or B_SAVE_PANEL.

Returns
B_OPEN_PANEL if the panel is an open panel, or B_SAVE_PANEL if the panel is a save panel.
Since
BeOS R3

◆ RefFilter()

BRefFilter * BFilePanel::RefFilter ( ) const

Gets the BRefFilter object associated with the panel.

Returns
The BRefFilter set to the panel.
See also
BRefFilter::Filter()
Since
BeOS R3

◆ Refresh()

void BFilePanel::Refresh ( )

Refresh the directory or the panel causing the entries to be re-run through the BRefFilter::Filter() method.

Since
BeOS R3

◆ Rewind()

void BFilePanel::Rewind ( )

Sets the entry ref back to the top of the list.

See also
SelectionChanged()
Since
BeOS R3

◆ SelectionChanged()

void BFilePanel::SelectionChanged ( )
virtual

Hook method that gets called when the entry ref references by the file panel changes.

See also
GetNextSelectedRef()
Rewind()
Since
BeOS R3

◆ SendMessage()

void BFilePanel::SendMessage ( const BMessenger messenger,
BMessage message 
)
virtual

Sends the message to the target BHandler messenger.

Parameters
messengerThe target BHandler to send the message to.
messageThe message to send.
See also
BMessenger::SendMessage()
Since
BeOS R3

◆ SetButtonLabel()

void BFilePanel::SetButtonLabel ( file_panel_button  button,
const char *  text 
)

Set the button label specified by button to text.

Parameters
buttonThe button to set the label of.
textThe text to set the button label to.
Since
BeOS R3

◆ SetHideWhenDone()

void BFilePanel::SetHideWhenDone ( bool  on)

Sets whether or not the panel should hide on confirm or cancel.

Parameters
ontrue to hide, false to not hide when done.
Since
BeOS R3

◆ SetMessage()

void BFilePanel::SetMessage ( BMessage message)

Sets the target messenge.

Parameters
messageThe BMessage object to send on confirm.
Since
BeOS R3

◆ SetPanelDirectory() [1/4]

void BFilePanel::SetPanelDirectory ( const BEntry entry)

Sets the entry ref of the panel to the directory referenced by entry.

Parameters
entryThe BEntry object pointing to the desired directory.
Since
BeOS R3

◆ SetPanelDirectory() [2/4]

void BFilePanel::SetPanelDirectory ( const BDirectory dir)

Sets the entry ref of the panel to the directory referenced by dir.

Parameters
dirThe BDirectory object pointing to the desired directory.
Since
BeOS R3

◆ SetPanelDirectory() [3/4]

void BFilePanel::SetPanelDirectory ( const entry_ref ref)

Sets the entry ref of the panel to the directory contained by ref.

Parameters
refThe entry contained by the desired panel directory.
Since
BeOS R3

◆ SetPanelDirectory() [4/4]

void BFilePanel::SetPanelDirectory ( const char *  path)

Sets the entry ref of the panel to the directory referenced by path.

Parameters
pathThe path of the desired directory.
Since
BeOS R3

◆ SetRefFilter()

void BFilePanel::SetRefFilter ( BRefFilter filter)

Sets the BRefFilter used by the panel to filter entries.

Parameters
filterThe BRefFilter object to set.
See also
BRefFilter::Filter()
Since
BeOS R3

◆ SetSaveText()

void BFilePanel::SetSaveText ( const char *  text)

Set some save text to display in the save dialog.

Parameters
textThe text to display.
Since
BeOS R3

◆ SetTarget()

void BFilePanel::SetTarget ( BMessenger  target)

Sets the target messenger.

Parameters
targetthe target BMessenger object to set.
Since
BeOS R3

◆ Show()

void BFilePanel::Show ( )

Displays the file panel on screen.

Since
BeOS R3

◆ WasHidden()

void BFilePanel::WasHidden ( )
virtual

Hook method that gets called when the file panel is hidden due to a user action.

WasHidden() is not called if you call Hide() manually.

Since
BeOS R3

◆ Window()

BWindow * BFilePanel::Window ( ) const

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