BMediaTheme¶

Constructor and Destructor¶

BMediaTheme()

BMediaTheme::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::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 *BMediaTheme::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 detailed in bg_kind.

BackgroundBitmapFor()

virtual rgb_color BMediaTheme::BackgroundBitmapFor(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 detailed in bg_kind.

BackgroundBitmapFor()

virtual rgb_color BMediaTheme::BackgroundBitmapFor(fg_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 detailed in fg_kind.

GetRef()

bool BMediaTheme::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 from an add-on, this function returns false.

ID()

int32 BMediaTheme::ID()

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 *BMediaTheme::Info()

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

MakeControlFor()

virtual BControl *BMediaTheme::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 BInvoker::SetMessage() on it.

MakeFallbackViewFor()

static BControl *BMediaTheme::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.

Note

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 *BMediaTheme::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 *BMediaTheme::PreferredTheme()

static status_t BMediaTheme::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 Code	Description
`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.

Name()

const char *BMediaTheme::Name()

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

ViewFor()

static BView *BMediaTheme::ViewFor(BParameterWeb *web, const BRect *hintRect = NULL, BMediaTheme *usingTheme = NULL)

Given a BParameterWeb web, typically returned by BMediaRoster::GetParameterWebFor(), 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.

Note

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

status_t get_theme_at(int32 n, const char **outName, 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.