BMediaTheme

Derived from: none
Declared in:  be/media/MediaTheme.h
Library: libmedia.so
Allocation: Constructor only
Summary:  more...

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().

If you want to return to the default system theme, you should call SetPreferredTheme(NULL). Make sure you don't have any theme views instantiated in your application when you do so.

Installing a Theme Add-on

Theme add-ons belong at /boot/home/config/add-ons/media/themes. They can have any name you like.

At this time, theme add-on support has not been sufficiently tested and may or may not work. If you have problems with it, please file a bug report at http://bebugs.be.com.

Hook Functions

• BackgroundBitmapFor()

• BackgroundColorFor()

• ForegroundColorFor()

• MakeControlFor()

• MakeViewFor()

Constructor and Destructor

BMediaTheme()

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.

~BMediaTheme()

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.

Member Functions

BackgroundBitmapFor()

virtual 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.

BackgroundColorFor()

virtual 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.

ForegroundColorFor()

virtual 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.

GetRef()

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.

ID()

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.

Info()

const char *Info(void)

Returns the user-readable long description of the theme, as specified when the theme was created.

MakeControlFor()

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.

If you want the control to send a specific message when invoked, you should call BControl::SetMessage() on it.

MakeFallbackViewFor()

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.

MakeViewFor()

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.

The web returned by this function belongs to the theme; applications shouldn't delete it (a properly-written theme will automatically dispose of the web when the view is closed).

This function is called by ViewFor().

PreferredTheme() , SetPreferredTheme()

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()

Name()

const char *Name(void)

Returns the user-readable name of the theme, as specified when the theme was created.

Set see PreferredTheme()

ViewFor()

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().

Global C Functions

get_nth_theme()

status_t get_theme_at(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.

make_theme()

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.

Constants

Background Color and Bitmap Kinds

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.

Foreground Color Kinds

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.