Derived from: none
Declared in: be/media/MediaTheme.h
Library: libmedia.so
Allocation: Constructor only
A BMediaTheme is an object that, given a BParameterWeb, can create a BView containing all the controls needed to configure the BControllable node represented by the BParameterWeb. You can then add the returned BView to a window so the user can configure the node to their liking.
The resulting BView contains not only the controls for configuring the parameters available in the node, but also indicates the data flow path through the node.
The BeOS includes the standard theme, which provides the system default look to media controls, as seen in the Audio and Video preference applications beginning with Release 4.
If you want to change the look of media controls within the BeOS, you can write your own BMediaTheme and install it as the default system theme by calling SetPreferredTheme(). If you want to write a new theme and provide the ability for the user to enable it as the new system theme, you'll need to write an application that calls SetPreferredTheme().
protected:
BMediaTheme(const char *name,|
const char *info,
const entry_ref *addOn = NULL,
int32 themeID = 0)
The BMediaTheme constructor initializes the theme so it can be used by the system or by an application. The user-readable theme name is passed as the name argument, and some longer description of the theme in info.
The name and info strings are copied; you can dispose of the original strings if you wish. Both strings should be human-readable, as they may be presented to the user in a user interface for selecting a theme to be used.
If the theme lives in an add-on on disk, specify the entry_ref of the add-on file in addOn and the ID assigned to the theme by its add-on in themeID.
virtual ~BMediaTheme()
Disposes of memory used by the theme. If you create a theme, be sure the destructor frees any memory allocated by the theme.
BBitmap *BackgroundBitmapFor(bg_kind backgroundKind)
Returns the BBitmap that should be used as the background for the specified type of user interface object. Possible values for backgroundKind are:
| Constant | Description |
|---|---|
| B_GENERAL_BG | Used when nothing else is applicable. |
| B_SETTINGS_BG | Used for panels or windows full of controls. |
| B_PRESENTATION_BG | Used for windows that present actual media content. |
| B_EDIT_BG | Used for windows that edit media content. |
| B_CONTROL_BG | Used for drawing controls. |
| B_HILITE_BG | Used when highlighting information, such as selected media data. |
rgb_color BackgroundColorFor(bg_kind backgroundKind)
Returns the rgb_color that should be used as the background for the specified type of user interface object. Possible values for backgroundKind are:
| Constant | Description |
|---|---|
| B_GENERAL_BG | Used when nothing else is applicable. |
| B_SETTINGS_BG | Used for panels or windows full of controls. |
| B_PRESENTATION_BG | Used for windows that present actual media content. |
| B_EDIT_BG | Used for windows that edit media content. |
| B_CONTROL_BG | Used for drawing controls. |
| B_HILITE_BG | Used when highlighting information, such as selected media data. |
rgb_color ForegroundColorFor(bg_kind foregroundKind)
Returns the rgb_color that should be used as the foreground for the specified type of user interface object. Possible values for foregroundKind are:
| Constant | Description |
|---|---|
| B_GENERAL_FG | Used when nothing else is applicable. |
| B_SETTINGS_FG | Used for panels or windows full of controls. |
| B_PRESENTATION_FG | Used for windows that present actual media content. |
| B_EDIT_FG | Used for windows that edit media content. |
| B_CONTROL_FG | Used for drawing controls. |
| B_HILITE_FG | Used when highlighting information, such as selected media data. |
bool GetRef(entry_ref *outRef)
Sets outRef to be a reference to the add-on file from which the theme was loaded and returns true. If the theme wasn't loaded froman add-on, this function returns false.
int32 ID(void)
Returns the theme's ID, as assigned by the add-on in which the theme resides. The ID is unique only within that add-on.
If the theme isn't in an add-on, 0 is returned.
const char *Info(void)
Returns the user-readable long description of the theme, as specified when the theme was created.
virtual BControl *MakeControlFor(BParameter *parameter) = 0
If you create your own theme, your implementation of this function should return an appropriate BControl to operate on the specified BParameter.
Applications that want to use the theme to create the controls, but handle their layout themselves, can call this function for each parameter in the web, rather than rely upon ViewFor(). However, if an application uses MakeControlFor() to create individual controls rather than letting ViewFor() set up the entire view, the application assumes responsibility for setting the control's value in response to value change messages.
static BControl *MakeFallbackViewFor(BParameter *control)
If you're implementing your own theme, and for whatever reason you want a BParameter to use the standard system theme's BControl, call MakeFallbackViewFor() to obtain that BControl.
This can be used if your theme is only intended to augment certain controls, or if you receive a BParameter you don't know anything about.
|
Your MakeControlFor() implementation should always call MakeFallbackViewFor() if it's asked to create a BControl for a BParameter it doesn't understand. This way, all BParameters will get some form of user interface, even if your theme doesn't specifically know how to handle some of them. This will let your theme remain compatible with future versions of the BeOS. |
virtual BView *MakeViewFor(BParameterWeb *web,
const BRect *hintRect = NULL) = 0
Given the specified BParameterWeb and hintRect, your implementation of this function should construct a BView that contains the BControls for manipulating the BParameters in the web. The hintRect is an area the caller thinks is appropriate for you to fill with your BView; your theme should try to stay within that rectangle if possible.
This function is called by ViewFor().
static BMediaTheme *PreferredTheme(void)
static status_t *SetPreferredTheme(BMediaTheme *newPreferredTheme)
PreferredTheme() returns the current preferred theme; SetPreferredTheme() changes the preferred theme to the theme specified by newPreferredTheme.
The preferred theme is the theme that will be used for creating node controlling user interfaces if no specific theme is requested when the interface is created.
RETURN CODES
B_OK. The preferred theme was changed without error.
B_NOT_ALLOWED. Access to the settings file denied.
Other errors. Directory and file I/O errors may occur while updating the settings file.
See also: ViewFor(), MakeViewFor()
const char *Name(void)
Returns the user-readable name of the theme, as specified when the theme was created.
static BView *ViewFor(BParameterWeb *web,
const BRect *hintRect = NULL,
BMediaTheme *usingTheme = NULL)
Given a BParameterWeb web, typically returned by BMediaRoster::GetControlWeb(), this function creates a BView suitable for adding to a BWindow to allow the user to configure the node the web describes, including a diagram indicating the data flow path through the node, and controls to let the user configure each control point.
|
This function is the public interface for creating a view for configuring a node (the MakeViewFor() function is the hook you override if you're implementing your own theme). |
The returned view is created using the theme specified by usingTheme; if this argument is NULL, the preferred theme is used. The hintRect parameter specifies the rectangle the view should try to occupy, and is passed to MakeViewFor().
status_t get_nth_theme(int32 n, const char **outName,
const char **outInfo, int32 *outID)
This function is called after the theme add-on is loaded, to determine what themes are available in the add-on. It's called repeatedly, with successively-higher values of n, until it returns an error.
Your add-on's implementation of this function should set outName to point to the nth theme's name, outInfo to point to information describing the nth theme, and outID should be set to the nth theme's ID number, which used internally by your add-on to distinguish among the themes it supports.
BMediaTheme *make_theme(int32 themeID, image_id imageID)
If you're writing a theme to be loaded from an add-on file, you must implement make_theme() to create a BMediaTheme for the specified themeID. imageID is the image_id of the add-on in which the theme is located.
| Constant | Description |
|---|---|
| B_GENERAL_BG | Used when nothing else is applicable. |
| B_SETTINGS_BG | Used for panels or windows full of controls. |
| B_PRESENTATION_BG | Used for windows that present actual media content. |
| B_EDIT_BG | Used for windows that edit media content. |
| B_CONTROL_BG | Used for drawing controls. |
| B_HILITE_BG | Used when highlighting information, such as selected media data. |
These constants identify parts of the user interface that a theme can customize the appearance of by altering the color or bitmap that's used in the background for various user interface elements. They're used when calling BackgroundBitmapFor() and BackgroundColorFor().
For example, the B_PRESENTATION_BG color and/or bitmap would be used as the background of a window in which an oscilloscope display shows the waveform of a sound wave being played back, and a window used for editing the waveform would have its' background in the color specified by B_EDIT_BG (or using the bitmap specified by B_EDIT_BG, if one exists), except for the part of the wave that's selected by the user, which would have the background color or bitmap specified by B_HILITE_BG.
| Constant | Description |
|---|---|
| B_GENERAL_FG | Used when nothing else is applicable. |
| B_SETTINGS_FG | Used for panels or windows full of controls. |
| B_PRESENTATION_FG | Used for windows that present actual media content. |
| B_EDIT_FG | Used for windows that edit media content. |
| B_CONTROL_FG | Used for drawing controls. |
| B_HILITE_FG | Used when highlighting information, such as selected media data. |
The foreground color kinds are used when calling ForegroundColorFor() to obtain the color to use when drawing the foreground portions of various interface elements.
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified December 11, 1998.