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

Detailed Description

Displays a standard Open/Save dialog.

A save panel looks like this:

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:

BFilePanel* openPanel = new BFilePanel(B_OPEN_PANEL);
BFilePanel* savePanel = new BFilePanel(B_SAVE_PANEL);

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

mode	Set to B_OPEN_PANEL for an open panal or B_SAVE_PANEL for a save panel. Default is B_OPEN_PANEL.
target	The BMessenger object that sends messages to the BLooper or BHandler controlled by the file panel.
ref	The directory to display, by default the current working directory.
nodeFlavors	One 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.
multipleSelection	Whether or not the user is allowed to select more than one item to open. Save panels should always set this to false.
message	Message sent by the file panel on confirms or cancels.
filter	Hook method to call.
modal	Whether or not the panel is modal, defaults to false.
hideWhenDone	Set 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_OK	Everything went fine.
B_ERROR	Couldn't attain a lock on the window.
B_ENTRY_NOT_FOUND	End 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

ref	The 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

messenger	The target BHandler to send the message to.
message	The 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

button	The button to set the label of.
text	The 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

on	true to hide, false to not hide when done.

Since

BeOS R3

SetMessage()

void BFilePanel::SetMessage

(

BMessage *

message

)

Sets the target messenge.

Parameters

message

The BMessage object to send on confirm.

Since

BeOS R3

SetPanelDirectory() [1/4]

void BFilePanel::SetPanelDirectory

(

const BDirectory *

dir

)

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

Parameters

dir	The BDirectory object pointing to the desired directory.

Since

BeOS R3

SetPanelDirectory() [2/4]

void BFilePanel::SetPanelDirectory

(

const BEntry *

entry

)

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

Parameters

entry

The BEntry object pointing to the desired directory.

Since

BeOS R3

SetPanelDirectory() [3/4]

void BFilePanel::SetPanelDirectory

(

const char *

path

)

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

Parameters

path	The path of the desired directory.

Since

BeOS R3

SetPanelDirectory() [4/4]

void BFilePanel::SetPanelDirectory

(

const entry_ref *

ref

)

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

Parameters

ref	The entry contained by the desired panel directory.

Since

BeOS R3

SetRefFilter()

void BFilePanel::SetRefFilter

(

BRefFilter *

filter

)

Sets the BRefFilter used by the panel to filter entries.

Parameters

filter

The 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

text	The text to display.

Since

BeOS R3

SetTarget()

void BFilePanel::SetTarget

(

BMessenger

target

)

Sets the target messenger.

Parameters

target

the 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