The Storage Kit Table of Contents | The Storage Kit Index |
Derived from: none
Declared in: be/storage/PreferencesPanel.h
Library: libstorage.so
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.
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.
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.
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.
Argument | Default | Function |
---|---|---|
BMessenger *target | be_app_messenger | SetTarget() |
The target represents the BLooper/BHandler that will receive the Property, Configuration, and Close messages.
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.
|
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.
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.
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.
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 Notifications are always sent to the target's MessageReceived() function. The message has the usual Scripting Messages semantics.
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.
There are two ways you can modify the look of your BPreferencesPanel object.
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");
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.
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).
|
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."
|
|
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.
|
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() 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.
|
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().
|
Sends BMessage message to the BHandler targeted by messenger.
See also: BMessenger::SendMessage()
|
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() 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:
|
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() 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.
|
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() 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.
|
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.
|
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 |
Copyright © 2002 Andrew Bachmann. All rights reserved..