The Storage Kit Table of Contents     The Storage Kit Index

BPreferencesPanel

Derived from: none

Declared in: be/storage/PreferencesPanel.h

Library: libstorage.so

Summary

BPreferencesPanel knows how to create and display an "Apply Preferences" or "Live Preferences" panel, and provides the means for filtering and responding to the user's actions on the panel. The Apply Panel looks like this:

The Live Panel looks pretty much the same, but without the revert and apply buttons.


Creating and Using a BPreferencesPanel

To create and use a BPreferencesPanel, follow these steps:

1.    Construct a BPreferencesPanel object in response to the user's request (most likely, a click on a "Preferences..." menu item). When you construct the panel, you have to specify its "mode" (Live or Apply).

2.    Fine-tune the panel by telling it which configuration file to display, whether it allows opening and saving configuration files, whether or not it should use apply semantics or live update, and so on. (Most of these parameters can also be set in the constructor.)

3.    Invoke Show() on the panel, and then wait for the user to change a preference, reset the configuration, load a new configuration, or close the panel.

4.    Receive a message. When one of the above happens, a notification message (Property, Configuration, Close) is sent to the panel's target. A Property message corresponds to a standard Scripting Message. A Configuration message corresponds to a standard B_REFS_RECEIVED message.

5.    Delete the BPreferencesPanel object...or don't. When the user closes a preferences panel, the object is not automatically deleted; you have to do it yourself. But you may not want to. If you don't delete the panel, you can simply call Show() the next time you want to display it; the state from the previous invocation (the panel's size and location, the preference that has the focus) is remembered.


Constructing and Fine-tuning the Panel

The BPreferencesPanel constructor has about two thousand arguments. They all have default values, and most of the parameters that they control can be set through individual functions. The following sections list and describe the constructor arguments and tell you if there's an analogous function.

Panel Mode

Argument Default Function
preferences_panel_mode mode B_LIVE_PANEL none

There are two preferences panel modes: B_LIVE_PANEL and B_APPLY_PANEL. You've got to make up your mind in the constructor.

Target

Argument Default Function
BMessenger *target be_app_messenger SetTarget()

The target represents the BLooper/BHandler that will receive the Property, Configuration, and Close messages.

Configuration File

Argument Default Function
entry_ref *configuration_file NULL SetConfigurationFile()

When a panel is first displayed, it has to determine the tree to show in the outline view and how the tree maps to a set of add-ons to be displayed on the right; this is called the "configuration file." If no file is specified, the outline and the add-on mapping can be specified through methods described below.
 
Note that if you don't provide a configuration file, some functionality such as Revert to Saved may not be available.


Notification Message

Argument Default Function
BMessage *message a default BMessage SetMessage()

By default, the format of the message that's sent to your target when the user changes the configuration or closes the dialog is defined by the preferences panel (the default formats are defined later). You can override the default by specifying your own BMessage. The BMessage is copied by the BPreferencesPanel object. You can change this message using the SetMessage() function.

Hide When Confirmed

Argument Default Function
bool hide_when_confirmed false SetHideWhenConfirmed()

This only makes sense in apply mode. By default, a preference panel is not hidden when the user clicks apply. If you set hide_when_confirmed to true, the panel will display an "Ok" button instead of "Apply", and it will close when it is clicked. Clicking the panel's close box always hides the panel.

Hide When Canceled

Argument Default Function
bool hide_when_canceled false SetHideWhenCanceled()

This only makes sense in apply mode. By default, a preference panel is not hidden when the user clicks revert. If you set hide_when_canceled to true, the panel will display a "Cancel" button instead of "Revert", and it will close when it is clicked. Clicking the panel's close box always hides the panel.


The Target and the Messages it Sees

When the user changes a preference, resets the configuration, loads a new configuration, or closes the panel, a BMessage is constructed and sent to the target of the BPreferencesPanel object. By default, the target is be_app_messenger. You can specify a different target (as a BMessenger) through the BPreferencesPanel constructor, or through the SetTarget() function.

The format of the BMessage that the target receives depends on whether the user is changing a preference, resetting the configuration, loading a new configuration, or closing the panel.

Property Notification

Property Notifications are always sent to the target's MessageReceived() function. The message has the usual Scripting Messages semantics.

Configuration Notification

If the target is be_app_messenger and the what field is B_REFS_RECEIVED, the BMessage shows up in the RefsReceived() function. Otherwise it's sent to the target's MessageReceived().

Close Notification

A close notification is sent whenever the preferences panel is hidden. This includes the Okay button being clicked and the panel being closed.

Close notifications are always sent to the target's MessageReceived() function.

Keep in mind that when a preferences panel is closed—regardless of how it's closed—the BPreferencesPanel object is not destroyed. It's merely hidden.


Modifying the Look of the Preferences Panel

There are two ways you can modify the look of your BPreferencesPanel object.

Finding Views in the Panel

The views in the panel are (mostly) named, as listed and shown below

The background view doesn't have a name, but it's always the first in the window's list of views:

   BView *background = prefspanel->Window()->ChildAt(0);

The other views can be found by name, reckoning off of the background view. For example, here we get the "OutlineView" view (the view at the left):

   BView *outline = background->FindView("OutlineView");


The C Functions

You can also display Live and Apply Panels through the global C functions run_live_panel() and run_apply_panel() (which are declared in PreferencesPanel.h). The functions create BPreferencesPanel objects using the default constructor settings (modulo the preferences_panel_mode, of course).

The C functions create a new preferences panel each time they're called, and delete the panel when the user is finished with it.


Hook Functions

SelectionChanged()   
Invoked whenever the user changes the selection in the outline view.

WasHidden()   
Invoked just after the preferences panel is hidden because of the user's actions (it's not invoked if you call Hide() yourself).


Constructor and Destructor


BPreferencesPanel()

                                                         
  

BPreferencesPanel(preferences_panel_mode mode = B_LIVE_PANEL,
      BMessenger* target = NULL,
      entry_ref *configuration_file = NULL,
      BMessage *message = NULL,
      bool modal = false,
      
bool hide_when_confirmed = false,
      
bool hide_when_canceled = false)

The constructor creates a new BPreferencesPanel 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."

 
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 target argument was described as defaulting to be_app_messenger, but is shown here as NULL. The "Constructing..." descriptions are correct: The default values shown here are caught and converted by the BPreferencesPanel constructor.



~BPreferencesPanel()

                                                         
  

virtual ~BPreferencesPanel()

Destroys the BPreferencesPanel. The object's target is not touched by this destruction. If the object is currently displaying a preferences panel, the panel is closed. If the panel is in apply mode, any pending changes are discarded.


Member Functions


GetConfigurationFile() see SetConfigurationFile()


Hide() see Show()


HidesWhenConfirmed() see SetHideWhenConfirmed()


HidesWhenCanceled() see SetHideWhenCanceled()


IsShowing() see Show()


Messenger() see SetTarget()


PanelMode()

                                                         
  

preferences_panel_mode PanelMode(void) const

Returns the object's mode, either B_LIVE_PANEL or B_APPLY_PANEL. The mode is set in the constructor and can't be changed thereafter.


Refresh()

                                                         
  

void Refresh(void)

Refresh() tells the preferences panel to re-read the contents of the configuration file, which causes the the outline and the add-on mapping to be updated. If no file was specified, it simply returns.


SelectionChanged()

                                                         
  

virtual void SelectionChanged(void)

This hook function is invoked whenever the user changes the selection in the outline view. Within your implementation of this function, you can get the outline view's CurrentSelection() if you want to do something with the selected item.

If you want to ensure that the user has applied or reverted all changes before the user selects a new outline item, use SetApplyBeforeOutlineSelection().


SendMessage()

                                                         
  

virtual void SendMessage(const BMessenger *messenger, BMessage *message)

Sends BMessage message to the BHandler targeted by messenger.

See also: BMessenger::SendMessage()


SetApplyBeforeOutlineSelection() , ApplyBeforeOutlineSelection()

                                                         
  

void SetApplyBeforeOutlineSelection(bool apply_before_outline_selection)

bool ApplyBeforeOutlineSelection(void) const

This only makes sense in apply mode. By default, if the user makes a change to a preference, the user can select another item on the outline before confirming the change, thus obscuring their change. If you set apply_before_outline_selection to true, the panel will prompt the user to revert the changes, apply the changes, or cancel the outline selection action.


SetButtonLabel()

                                                         
  

void SetButtonLabel(preferences_panel_button which_button, 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:


SetHideWhenCanceled() , HidesWhenCanceled() , SetHideWhenConfirmed() , HidesWhenConfirmed()

                                                         
  

void SetHideWhenCanceled(bool hide_when_canceled)

bool HidesWhenCanceled(void) const

void SetHideWhenConfirmed(bool hide_when_confirmed)

bool HidesWhenConfirmed(void) const

By default, a preferences panel is not hidden when the user Applys or Reverts. You can control this behavior using the SetHideWhenCanceled() and SetHideWhenConfirmed() functions.

If you set hide_when_canceled to true, the "Revert" button will change to a "Cancel" button, and if the user clicks it, the panel will hide. If you set hide_when_confirmed to true, the "Apply" button will change to an "Okay" button, and if the user clicks it, the panel will hide. Clicking the panel's close box always hides the panel.

HidesWhenCanceled() returns the current setting of this option: true if the panel hides when the user cancels or false if it remains on the screen. HidesWhenConfirmed() returns the current setting of this option: true if the panel hides when the user confirms or false if it remains on the screen.


SetMessage()

                                                         
  

void SetMessage(BMessage *msg)

SetMessage() allows you to set the format of the preferences 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.


SetConfigurationFile() , GetConfigurationFile()

                                                         
  

void SetConfigurationFile(BEntry *configEntry)

void SetConfigurationFile(entry_ref *configRef)

void SetConfigurationFile(const char *confStr)

void GetConfigurationFile(entry_ref *ref) const

The SetConfigurationFile() function sets the panel's "configuration file." This is the file whose contents determine the tree to show in the outline view and how the tree maps to the set of add-ons to be displayed on the right. You can also set the configuration file through the constructor. If no file is specified, the outline and the add-on mapping can be specified through other methods.

GetConfigurationFile() initializes ref to point to the current configuration file. The argument must be allocated.


SetTarget() , Messenger()

                                                         
  

void SetTarget(BMessenger bellhop)

BMessenger Messenger(void) const

SetTarget() sets the target of the preferences 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 preferences panel's target.


Show() , Hide() , IsShowing() , WasHidden()

                                                         
  

void Show(void)

void Hide(void)

bool IsShowing(void) const

virtual void WasHidden(void)

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

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.


WasHidden() see Show()


Window()

                                                         
  

BWindow *Window(void) 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 Preferences Panel."


The Storage Kit Table of Contents     The Storage Kit Index


The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2002 Andrew Bachmann. All rights reserved..