ThemedView Class Reference
[QtBaseModule]

Detailed Description

The ThemedView widget constructs, manages and displays themed views in Qtopia.

A Qt Extended theme is made up of multiple themed views, each described by an XML document called the themed view XML. You construct a new ThemedView by passing a themed view XML file to the ThemedView::loadSource() function. The ThemedView widget parses the XML, creates the theme item tree and renders it to the widget.

The theme item tree is the run-time representation of a themed view. Each node in the tree derives from ThemeItem and implements some specific functionality eg. ThemeTextItem displays text, ThemeRectItem draws rectangles, ThemeLayoutItem positions and sizes other items etc. The ThemedView widget manages the theme item tree, instructing items to layout and paint themselves at the appropriate times.

As the ThemedView is basically a customizeable user interface component, a core part of a themed view is its ability to display data to the user. There are 2 different methods of getting data into a themed view for display to the user. 1. Using the ThemedView::findItem() function, you can get access to theme items in the tree and set data on them directly. Eg.

    ThemedView *view;
    ..
    ThemeTextItem* myTextItem = static_cast<ThemeTextItem*>(view->findItem("myTextItem", ThemedView::Text);
    if (myTextItem != 0)
        myTextItem->setText("Hello, World!");

The above example finds the item with name "myTextItem" and a ThemeItem::rtti() value of ThemedView::Text and sets its contents to be "Hello, World!".

2. ThemeLevelItem, ThemeStatusItem, ThemeTextItem and ThemeImageItem can source their data through a QExpressionEvaluator. This method allows items to source data from the system without any tight-coupling. See the item-specific documentation for details.

The ThemedView is also responsible for handling user interactivity with theme items. You can monitor user interactivity programatically by connecting to the ThemedView::itemPressed(), ThemedView::itemClicked() and ThemedView::itemReleased() signals. Alternatively, theme items can send IPC messages to services or a specific channel when clicked. This allows themed views to effect the system without tight coupling. See the documentation of ThemeItem for details.

Member Type Documentation

enum ThemedView::Type

See also ThemeItem::rtti().

Member Function Documentation

ThemedView::ThemedView ( QWidget * parent = 0, Qt::WFlags f = 0 )

Constructs a ThemedView object passing the parent widget and widget flags f to the QWidget constructor.

ThemedView::~ThemedView ()   [virtual]

Destroys the ThemedView object and all of its data.

const QString ThemedView::base () const

Returns the base directory for this ThemedView. This function simply accesses the root theme item and returns ThemePageItem::base(). As such, you cannot call this function before the root item has been constructed (ie. before a themed view XML has been successfully loaded).

const QString ThemedView::defaultPics () const

Returns the default directory for theme images. The default is $QPEDIR/themes/default.

ThemeItem * ThemedView::findItem ( const QString & name, ThemedView::Type type = ThemedView::Item, ThemeItem::State state = ThemeItem::All ) const

Finds the item in the theme item tree that has the name name, the type type and the state state. If the value of type is ThemedView::Item, items with any type are searched for. The default value of state is ThemeItem::All which matches the state of all items. Returns a pointer to the item if found, otherwise returns 0.

ThemeItem * ThemedView::findItem ( const QString & name, int type, int state = ThemeItem::All ) const

This function is deprecated.

This is an overloaded member function, provided for convenience.

QList<ThemeItem *> ThemedView::findItems ( const QString & name, ThemedView::Type type = ThemedView::Item, ThemeItem::State state = ThemeItem::All ) const

Finds all of the items in the theme item tree that have the name name, the type type and the state state. If the value of type is ThemedView::Item, items with any type are searched for. By default, state if set to ThemeItem::All, and so items with any state are search for. Returns any items found.

QList<ThemeItem *> ThemedView::findItems ( const QString & name, int type, int state = ThemeItem::All ) const

This function is deprecated.

This is an overloaded member function, provided for convenience.

ThemeItem * ThemedView::itemAt ( const QPoint & pos ) const

Returns the ThemeItem located at the point pos in this ThemedView. pos is in local coordinates.

void ThemedView::itemClicked ( ThemeItem * item )   [signal]

Emitted when the interactive item item is clicked. A click is a press and a release.

void ThemedView::itemPressed ( ThemeItem * item )   [signal]

Emitted when the interactive item item is pressed.

void ThemedView::itemReleased ( ThemeItem * item )   [signal]

Emitted when the interactive item item is released.

void ThemedView::layout ( ThemeItem * item = 0 )   [protected]

Lays out item an of its children.

bool ThemedView::loadSource ( const QString & fileName = QString() )

Loads the themed view XML specified by fileName. If fileName is empty (the default) but ThemedView::setSourceFile() has been called, the fileName value from that call will be used. Returns true if a source was successfully loaded, otherwise returns false.

void ThemedView::loaded ()   [signal]

Emitted when the theme is successfully loaded.

QWidget * ThemedView::newWidget ( ThemeWidgetItem * item, const QString & name )   [virtual]

Called by the ThemeWidgetItem item when it wishes to construct the widget corresponding to the specified name. name is the name attribute from the themed view XML. This function must be overriden by subclasses for themed views that have a ThemeWidgetItem in them. The default implementation always returns 0.

See also ThemeWidgetItem.

const QString ThemedView::pageName () const

Returns the name attribute of the page element from the themed view XML.

void ThemedView::paint ( QPainter * painter, const QRect & clip, ThemeItem * item = 0 )

Paints item using the painter painter within the given clip rect. You normally don't want to call this function directly, but it is useful for painting template items to a user-specified painter.

void ThemedView::registerExpression ( ThemeItem * item, QExpressionEvaluator * expression )   [protected]

Registers the expression expression for the given theme item. The ThemedView will unregister the expression when expression is deleted, and call the expressionChanged() call-back on item whenever the QExpressionEvaluator::termsChanged() signal is emitted.

void ThemedView::setGeometryAndLayout ( const QRect & rect )

If the rectangle rect is different to the current rect(), sets the new geometry to rect and calls layout() immediately.

void ThemedView::setGeometryAndLayout ( int gx, int gy, int w, int h )

This is an overloaded member function, provided for convenience.

Equivalent to calling ThemedView::setGeometryAndLayout(QRect(gx, gy, w, h))

void ThemedView::setSourceFile ( const QString & fileName )

Set the themed view XML file to be fileName. If ThemedView::loadSource() is called with an empty argument (the default) the themed view XML file fileName will be loaded.

void ThemedView::setThemeName ( const QString & themeName )

Sets the name of the theme this ThemedView belongs to be themeName. The name of the theme will be used as the key for text translations. themeName() simply returns this value.

See also themeName().

bool ThemedView::sourceLoaded () const

Returns true if a themed view XML document has been loaded using ThemedView::loadSource() for this ThemedView, otherwise returns false.

void ThemedView::themeLoaded ( const QString & file )   [virtual protected]

Called whenever the theme, file, is loaded. This allows derived classes to configure themselves appropriately for the new theme.

The default implementation does nothing.

QString ThemedView::themeName () const

Returns the name of the theme this ThemedView belongs to as set by setThemeName().

See also setThemeName().

void ThemedView::visibilityChanged ( ThemeItem * item, bool visible )   [signal]

Emitted when the visibility of item changes. The visible parameter is true if item is visible or false otherwise.