Home · All Classes · Main Classes · Deprecated
Public Types | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions

MTheme Class Reference

MTheme abstracts the theming and styling of DirectUI applications and widgets. More...

Inherits QObject.

List of all members.

Public Types

enum  ThemeService { AnyTheme = 0, RemoteTheme, LocalTheme }
enum  InsertMode { Overwrite, Append }
typedef QString ViewType

Signals

void pixmapRequestsFinished ()
void themeIsChanging ()
void themeChangeCompleted ()

Public Member Functions

 MTheme (const QString &applicationName, const QString &imglistFilename=QString(), ThemeService themeService=AnyTheme)
virtual ~MTheme ()

Static Public Member Functions

static const MStylestyle (const char *styleClassName, const QString &objectName, const QString &mode, const QString &type, M::Orientation orientation, const MWidgetController *parent=NULL)
static const MStylestyle (const char *styleClassName, const QString &objectName, const QString &mode, const QString &type, M::Orientation orientation, const QList< QStringList > &parentClassHierarchies, const QString &parentStyleName)
static const MStylestyle (const char *styleClassName, const QString &objectName="")
static void releaseStyle (const MStyle *style)
static bool addPixmapDirectory (const QString &directoryName, M::RecursionMode mode=M::NonRecursive)
static void clearPixmapDirectories ()
static MThemeinstance ()
static const QPixmappixmap (const QString &id, const QSize &size=QSize(0, 0))
static const QPixmapasyncPixmap (const QString &id, const QSize &size=QSize(0, 0))
static QPixmappixmapCopy (const QString &id, const QSize &size=QSize(0, 0))
static const MScalableImagescalableImage (const QString &id, int left, int right, int top, int bottom)
static const MScalableImagescalableImage (const QString &id, int left, int right, int top, int bottom, const QTileRules &tileRules)
static void releaseScalableImage (const MScalableImage *image)
static void releasePixmap (const QPixmap *pixmap)
static QAbstractAnimationanimation (const QString &animationTypeName)
static QGraphicsEffecteffect (const QString &effectTypeName)
static MWidgetViewview (const MWidgetController *controller)
static const MPalettepalette ()
static const MDefaultFontsfonts ()
static bool loadCSS (const QString &filename, InsertMode mode=Append)
static QString currentTheme ()
static bool hasPendingRequests ()
static void cleanupGarbage ()

Protected Member Functions

void rebuildViewsForWidgets ()

Detailed Description

MTheme abstracts the theming and styling of DirectUI applications and widgets.

MTheme is a singleton class providing runtime access to the MeeGo Touch theming parameters, as well as factory methods for instantiating various theming resources such as shared graphical assets in the form of QPixmaps and MScalableImages, as well as style and view instances for the widgets.

MTheme communicates with a theme server whenever a graphical asset is requested. The theme server is responsible for loading the graphics (either from static image files, by rasterizing SVG or through procedural generation) and sharing them. The sharing of graphics assets is platform specific, MeeGo Touch ships with a reference theme server called mthemedaemon that shares assets using the X11 system. In case a theme server is not available, no sharing occurs and each graphical asset is duplicated for each application.


Member Typedef Documentation

ViewTypes are standardized widget variant names, as defined by the widgets themselves. For example, MButton::checkboxType can be expected to be implemented by each theme, while a random non-standard type is unlikely to be. There is a mapping of view types to view implementation class names in the theme configurations.


Member Enumeration Documentation

Defines the how resources that are registered with the theme at runtime are handled.

Enumerator:
Overwrite 

The resource replaces any existing resource of the same type.

Append 

The resource is appended to the theme data, leaving any existing resources active. The existing resources may be prioritized when making requests.

Defines the type of theme service the process will use.

Enumerator:
AnyTheme 

Default theme service will be used.

RemoteTheme 

Remote theme service will be used.

LocalTheme 

Local theme service will be used.


Constructor & Destructor Documentation

MTheme::MTheme ( const QString applicationName,
const QString imglistFilename = QString(),
ThemeService  themeService = AnyTheme 
)

Constructs the MTheme instance.

By default the theme system firsrt attempts to connect to a remote theme service, if this fails a local theme service is created unless overriden by the themeService parameter. Note that on some platforms failing to connect to a remote theme service at startup may be a fatal error. If the themeService is RemoteTheme, the constructor will not return until a remote theme service becomes available. This option should be used when the application may potentially start before the theme service during system bootup. The RemoteTheme option can also be toggled by the -remote-theme command line parameter as passed to MApplication. The RemoteTheme option cannot be used if imglistFilename is also set.

applicationName is used as the first part of the search path for resources, ensuring that application specific theme resources are prioritized. imglistFilename is not in use anymore.

MTheme::~MTheme (  )  [virtual]

Destroys the theme instance.


Member Function Documentation

bool MTheme::addPixmapDirectory ( const QString directoryName,
M::RecursionMode  mode = M::NonRecursive 
) [static]

Adds a directory to the theme service search path for this application.

The theme service will look for PNG and SVG files in the location specified by directoryName, which can be either an relative or absolute path. If mode is defined as Recursive, subdirectories of the specified directory are searched as well. The default is not to search subdirectories.

Note: A custom pixmap directory path must be added prior requesting a pixmap from it, otherwise an invalid pixmap will be displayed.

See also:
pixmap
QAbstractAnimation * MTheme::animation ( const QString animationTypeName  )  [static]

Returns an animation instance with the given type.

Parameters:
animationTypeName Name of the animation type.

The returned animation is theme specific.

const QPixmap * MTheme::asyncPixmap ( const QString id,
const QSize size = QSize(0, 0) 
) [static]

Returns a QPixmap that contains the graphical asset specified by the logical ID.

Loads the pixmap specified by id of size size.

Note: Prior requesting a pixmap from a custom path, the path must be added through addPixmapDirectory() method.

The requested pixmap is loaded asynchronously. The returned pixmap can be one of the following:

  • The real pixmap if the pixmap was already loaded by the system.
  • A transparent (or green, if GConf key /meegotouch/debug/show_async_requests is set to true), size sized (QSize(0,0) by default) pixmap, serving as a placeholder while the pixmap data is loading.
  • A red pixmap of 50x50 size, indicating that the pixmap with the requested id was not found in the theme.

In the first two cases, the pixmap data can be changed at any time by the theme. This may happen when the theme changes, as pixmaps are updated, pixmaps finish loading or for any other reason.

The returned pixmap is owned by the theme and should be freed with releasePixmap() when no longer needed.

See also:
pixmap
releasePixmap
addPixmapDirectory
void MTheme::cleanupGarbage (  )  [static]
void MTheme::clearPixmapDirectories (  )  [static]

Clear all pixmap directories from the theme service search path for this application.

QString MTheme::currentTheme (  )  [static]

Returns the name of the current theme in use or an empty string no theme is selected.

QGraphicsEffect * MTheme::effect ( const QString effectTypeName  )  [static]

Returns an effect instance with the given type.

Parameters:
effectTypeName Name of the effect type.

The returned effect is theme specific.

const MDefaultFonts & MTheme::fonts (  )  [static]

Returns the theme's logical font information.

The font information can be used to programmatically query the common fonts defined in the theme.

bool MTheme::hasPendingRequests (  )  [static]

Returns true if there are pending asynchronous pixmap requests in the system.

MTheme * MTheme::instance (  )  [static]

Returns the singleton MTheme instance.

bool MTheme::loadCSS ( const QString filename,
InsertMode  mode = Append 
) [static]

Loads the requested CSS file to the current active theme.

Either appends to or replaces the existing theme CSS using the style sheet located by filename, depending on the mode. The method returns true if the CSS file was successfully loaded.

Note that CSS files should be loaded before constructing the style objects.

const MPalette & MTheme::palette (  )  [static]

Returns the theme's logical color palette.

The palette can be used to programmatically query the common colors defined in the theme.

const QPixmap * MTheme::pixmap ( const QString id,
const QSize size = QSize(0, 0) 
) [static]

Returns a QPixmap that contains the graphical asset specified by the logical ID.

Note: While loading the graphics the application UI thread is blocked. In case the graphics is large or you do not need to immediately know the final size of the requested graphics, consider using the asyncPixmap() method instead to keep the UI responsive.

Prior requesting a pixmap from a custom path, the path must be added through addPixmapDirectory() method.

The id is a logical identifier for a single graphical theme asset. The source format of the graphics is abstracted and determined by the theme service. The default graphics loading policy is as follows:

  • Static images such as PNG have a higher priority than assets which are dynamic or require rasterization (SVG), thus allowing for static caching of assets. For static images the id is the filename without the filetype suffix.
  • Application supplied assets have higher priority than base theme assets, while assets in a theme for a specific application has higher priority than assets supplied by the application itself.

The size parameter determines the size of the returned pixmap. The default size of QSize(0,0) marks that the original source graphics size should be used.

The returned pixmap is owned by the theme and should be freed with releasePixmap() when no longer needed.

See also:
releasePixmap
asyncPixmap
addPixmapDirectory
QPixmap * MTheme::pixmapCopy ( const QString id,
const QSize size = QSize(0, 0) 
) [static]

Returns a copy of the graphical asset with the given logical ID.

Loads the pixmap specified by id of size size synchronously and returns a copy to the caller. This method can be very slow, use the pixmap() or asyncPixmap() methods instead if possible.

Note: Prior requesting a pixmap from a custom path, the path must be added through addPixmapDirectory() method.

The ownership of the returned pixmap is transferred to caller, and the pixmap may be modified.

See also:
pixmap
asyncPixmap
addPixmapDirectory
void MTheme::pixmapRequestsFinished (  )  [signal]

This signal is emitted when all pixmap requests have finished.

The signal is emitted regardless of if the request was successfull or not.

Note that for regular applications, listening for this signal is not necessary, since any change automatically triggers an update of the interface.

Widget implementations must not connect to this signal. All widgets are repainted after the outstanding requests have finished.

See also:
asyncPixmap
void MTheme::rebuildViewsForWidgets (  )  [protected]

Causes all widgets to update their views when the theme is changed.

void MTheme::releasePixmap ( const QPixmap pixmap  )  [static]

Releases a shared QPixmap acquired through MTheme.

releasePixmap performs cleanup and frees the pixmap if there are no other clients using it.

See also:
pixmap
void MTheme::releaseScalableImage ( const MScalableImage image  )  [static]

Releases a shared MScalableImage acquired through MTheme.

releaseScalableImage performs cleanup and frees the image if there are no other clients using it.

See also:
scalableImage
void MTheme::releaseStyle ( const MStyle style  )  [static]

This method should be called on style objects when they are no longer needed.

releaseStyle performs cleanup and frees the style if there are no other clients using it.

const MScalableImage * MTheme::scalableImage ( const QString id,
int  left,
int  right,
int  top,
int  bottom,
const QTileRules tileRules 
) [static]

This is an overloaded function.

Returns a MScalableImage with the wanted tiling rules.

const MScalableImage * MTheme::scalableImage ( const QString id,
int  left,
int  right,
int  top,
int  bottom 
) [static]

Returns a MScalableImage that contains the graphical asset specified by the logical ID.

The logic for acquiring a scalable image is the same as that for a regular pixmap. The left, right, top and bottom parameters specify the non-scaled border values of the image.

The returned image is owned by the theme and should be freed with releaseScalableImage() when no longer needed.

See also:
pixmap
releaseScalableImage
const MStyle * MTheme::style ( const char *  styleClassName,
const QString objectName,
const QString mode,
const QString type,
M::Orientation  orientation,
const QList< QStringList > &  parentClassHierarchies,
const QString parentStyleName 
) [static]

This is an overloaded function.

Returns the style object matching the given parameters. Instead of taking the controller of the widget to get the contextual information for the style, this function gets a list of QStringLists, describing the metaclass hierarchy of each parent, starting from the most direct.

This overload is not for using in regular MeeGo Touch applications. It is intended to be used by other libraries that need the styling information but do not have widget controllers or views instantiated.

const MStyle * MTheme::style ( const char *  styleClassName,
const QString objectName,
const QString mode,
const QString type,
M::Orientation  orientation,
const MWidgetController parent = NULL 
) [static]

Returns the style object matching the given parameters.

A style object is a collection of data properties, from which widget views (or any other type of class) access their run time parameters. The data is in the form of standard Qt properties and the style object is automatically filled through Qt property introspection based on values defined in CSS sylesheets.

Ownership of the returned object remains with MTheme, the caller must not delete it as it may be shared by multiple users. Once the caller no longer needs the object, it should be passed to the releaseStyle method of MTheme.

The parameters are:

  • styleClassName, the name of the class (e.g. "MLabelStyle")
  • objectName, the name of the object (e.g. "MyButton")
  • mode, the name of the mode of the widget (e.g. "active", "selected", "disabled")
  • type, the type of view that is used (e.g. for the button: "default", "checkbox", "toggle")
  • orientation, the orientation that the style should be optimized for (e.g portrait or landscape)
  • parent (optional), the controller of the widget for which the style is used
See also:
releaseStyle
const MStyle * MTheme::style ( const char *  styleClassName,
const QString objectName = "" 
) [static]

This is an overloaded function.

Returns the style object with the given styleClassName and objectName

void MTheme::themeChangeCompleted (  )  [signal]

This signal is emitted when the theme service and all applications have changed the theme.

Note that for regular applications, listening for this signal is not necessary, since when this signal is emitted the applications are already running with the new theme.

void MTheme::themeIsChanging (  )  [signal]

This signal is emitted when the current theme was changed but before the old resources are deleted. This allows for applications to stop using the old pixmaps before they become invalid.

Note that for regular application, listening to this signal is not necessary. This is mostly useful for custom applications that only use selected parts of MeegoTouch Framework.

MWidgetView * MTheme::view ( const MWidgetController controller  )  [static]

Returns a view instance for the given controller.

The returned view is theme specific and can be changed in the theme configuration.


Copyright © 2010 Nokia Corporation
MeeGo Touch