BFilePanel

Constructor and Destructor

BFilePanel()

BFilePanel::BFilePanel(file_panel_mode mode = B_OPEN_PANEL, BMessenger *target = NULL, entry_ref *panel_directory = NULL, uint32 node_flavors = 0, bool allow_multiple_selection = true, BMessage *message = NULL, BRefFilter *filter = NULL, bool modal = false, bool hide_when_done = true)

The constructor creates a new BFilePanel object and initializes it according to the arguments. The panel isn’t displayed until you invoke Show(). The arguments are thoroughly described in “Constructing and Fine-tuning the Panel.”

Note

You may notice that some of the default arguments shown here don’t jibe with the defaults listed in the section “Constructing and Fine-tuning the Panel”. In particular, the node_flavors argument was described as defaulting to B_FILE_NODE, but is shown here as 0. The “Constructing…” descriptions are correct: The default values shown here are caught and converted by the BFilePanel constructor.

~BFilePanel()

virtual BFilePanel::~BFilePanel()

Destroys the BFilePanel. The object’s target and BRefFilter are not touched by this destruction. If the object is currently displaying a file panel, the panel is closed.

Hook Functions

SelectionChanged()

virtual void BFilePanel::SelectionChanged()

This hook function is invoked whenever the user changes the set of selected files. Within your implementation of this function, you iterate over GetNextSelectedRef() to retrieve refs to the currently selected files.

WasHidden()

virtual void BFilePanel::WasHidden()

WasHidden() is a hook function that’s invoked whenever the user’s actions causes the file panel to be hidden. If you call Hide() yourself, WasHidden() is not invoked.

Member Functions

GetNextSelectedRef(), Rewind()

status_t BFilePanel::GetNextSelectedRef(entry_ref *ref)

void BFilePanel::Rewind()

GetNextSelectedRef() initializes its arguments to point to the “next” ref in the file panel’s set of currently selected items. The function returns B_ENTRY_NOT_FOUND when it reaches the end of the list. Rewind() gets you back to the top of the list.

Although you can call these functions anytime you want, they’re intended to be used in implementations of the SelectionChanged() hook function.

PanelMode()

file_panel_mode BFilePanel::PanelMode() const

Returns the object’s mode, either B_OPEN_PANEL or B_SAVE_PANEL. The mode is set in the constructor and can’t be changed thereafter.

Refresh()

void BFilePanel::Refresh()

Refresh() tells the file panel to re-read the contents of the panel directory, which causes the directory’s entries to be re-run through the ref filter.

You don’t have to call Refresh() in order to keep the panel in sync with the directory’s contents—the directory and file panel are kept in sync automatically.

SendMessage()

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

Sends BMessage message to the BHandler targeted by messenger.

See Also: BMessenger::SendMessage()

SetButtonLabel(), SetSaveText()

void BFilePanel::SetButtonLabel(file_panel_button which_button, const char *label)

void BFilePanel::SetSaveText(const char *label)

SetButtonLabel() lets you set the label that’s displayed in the panel’s buttons. The button that a specific invocation affects depends on the value of which_button:

Constant	Description
B_DEFAULT_BUTTON	Is the Open button for an Open Panel and the Save button for a Save Panel.
B_CANCEL_BUTTON	Is the “Cancel” button.

SetSaveText() sets the text that’s displayed in the Save Panel’s text view (the area in which the user types and confirms a file name).

SetHideWhenDone(), HidesWhenDone()

void BFilePanel::SetHideWhenDone(bool hide_when_done)

bool BFilePanel::HidesWhenDone() const

By default, a file panel is hidden when the user confirms or Cancels. You can control this behavior using the SetHideWhenDone() function. If you set hide_when_done to false, the panel remains on the screen; if you specify true, the panel hides when the user confirms or Cancels. Clicking the panel’s close box always hides the panel.

HidesWhenDone() returns the current setting of this option: true if the panel hides when the user is done with it or false if it remains on the screen.

SetMessage()

void BFilePanel::SetMessage(BMessage *message)

SetMessage() allows you to set the format of the file panel’s notification messages. The message can also be set through the constructor. See “The Target and the Messages it Sees” for more information.

A copy is made of the BMessage, so it is your responsibility to delete msg when you no longer need it.

SetPanelDirectory(), GetPanelDirectory()

void BFilePanel::SetPanelDirectory(BEntry *dirEntry)
void BFilePanel::SetPanelDirectory(BDirectory *dirObj)
void BFilePanel::SetPanelDirectory(entry_ref *dirRef)
void BFilePanel::SetPanelDirectory(const char *dirStr)

void BFilePanel::GetPanelDirectory(entry_ref *ref) const

The SetPanelDirectory() function sets the panel’s “panel directory.” This is the directory whose contents are displayed in the panel’s file list. You can also set the panel directory through the constructor. If you don’t supply a directory, the current working directory is used.

GetPanelDirectory() initializes ref to point to the current panel directory. The argument must be allocated.

SetRefFilter(), RefFilter()

void BFilePanel::SetRefFilter(BRefFilter *filter)

BRefFilter *BFilePanel::RefFilter() const

Whenever the file panel’s panel directory is changed or refreshed (Refresh()), or when a new entry is added to the current panel directory, the “new” entries are run through the panel’s “ref filter.” The BRefFilter class defines a single boolean hook function called Filter(). The function receives the entries, one-by-one, and can reject specific entries (because they’re the wrong file type, for example). Rejected entries are not shown in the panel’s file list.

The SetRefFilter() function sets the panel’s ref filter. You can also set it through the constructor. Ownership of the filter is not handed to the panel. You mustn’t delete the ref filter while the panel is still extant.

RefFilter() returns a pointer to the panel’s ref filter.

SetTarget(), Messenger()

void BFilePanel::SetTarget(BMessenger bellhop)

BMessenger BFilePanel::Messenger() const

SetTarget() sets the target of the file panel’s notification messages. The target can also be set through the constructor. If you don’t set a target, be_app_messenger is used. See the BInvoker class (in the Application Kit) for an explanation of how a BMessenger can be used as a target.

A copy is made of the BMessenger, so it is your responsibility to delete bellhop when you no longer need it.

Messenger() returns (a copy of) the messenger that’s used as the file panel’s target.

Show(), Hide(), IsShowing()

void BFilePanel::Show()

void BFilePanel::Hide()

bool BFilePanel::IsShowing() const

These functions show and hide the file panel, and tell if you the panel is currently showing.

Window()

BWindow *BFilePanel::Window() const

Returns a pointer to the file panel’s window. If you want to mess around with the window’s views, see “Modifying the Look of the File Panel.”