QPimDelegate Class Reference
[QtMessagingModule, QtPimModule, QtTelephonyModule, QtUiModule]

Detailed Description

The QPimDelegate class provides an abstract delegate for rendering multiple lines of text for a PIM record.

QPimDelegate draws an item with the following features.

• A background.
• An optional number of decorations.
• A main line of text, displayed in bold at the top.
• A variable number of subsidiary lines of text, each consisting of a 'header' string rendered in bold, and a 'value' string rendered in a normal weight font. The subsidiary lines of text are rendered slightly smaller than the main line of text. Each subsidiary line can be rendered independently, or all subsidiary lines in a given item can have the header and value strings lined up consistently.
• An optional foreground.

All text lines will be elided if they are too wide.

Much like QAbstractItemDelegate, this class is not intended to be used directly. Subclasses are expected to override some or all of the customization functions providing the above pieces of information or style settings.

See also QAbstractItemDelegate, QContactDelegate, QPimRecord, and Pim Library.

Member Type Documentation

enum QPimDelegate::BackgroundStyle

Enumerates the ways that the background of an item can be rendered by the drawBackground() function.

See also backgroundStyle().

enum QPimDelegate::SubTextAlignment

Enumerates the ways that the header and value pairs of the subsidiary lines can be rendered.

See also subTextAlignment().

Member Function Documentation

QPimDelegate::QPimDelegate ( QObject * parent = 0 )

Constructs a QPimDelegate, with the given parent.

QPimDelegate::~QPimDelegate ()

Destroys a QPimDelegate.

BackgroundStyle QPimDelegate::backgroundStyle ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns a value that indicates how the background of this item should be rendered.

The default implementation returns QPimDelegate::SelectedOnly, and ignores the supplied index and option parameters.

See also drawBackground().

QSize QPimDelegate::decorationsSizeHint ( const QStyleOptionViewItem & option, const QModelIndex & index, const QSize & textSizeHint ) const   [virtual protected]

Returns the size hint for the whole delegate, which will include the space required for decorations, if any. The returned value is calculated by adding any space required for decorations to the given textSizeHint parameter.

The default implementation returns the supplied textSizeHint, and ignores the supplied index and option parameters.

QFont QPimDelegate::differentFont ( const QFont & start, int step ) const   [protected]

Attempts to return a font that is similar to start but has the given size difference of step. If no matching font for the given step value is found, it will try increasingly larger/smaller fonts (depending on whether step was originally positive or negative). If no suitable font is found after trying different sizes, the original font start will be returned.

void QPimDelegate::drawBackground ( QPainter * p, const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Paints the background of the item.

The rectangle to paint in (using p) should be obtained from option (option.rect) and the index of the item to paint.

The default implementation fetches the background style to paint by calling backgroundStyle() for the given option and index.

void QPimDelegate::drawDecorations ( QPainter * p, bool rtl, const QStyleOptionViewItem & option, const QModelIndex & index, QList<QRect> & leadingFloats, QList<QRect> & trailingFloats ) const   [virtual protected]

Paints any decorations, and assigns to the given lists of rectangles, which the caller can then use to align painted text, if required. The rtl argument is a convenience parameter that is true if the decorations should be painted right-to-left, or false if they should be painted left-to-right. This may affect which side of the rectangle a decoration is painted on.

The rectangle to paint in (using p) should be obtained from option (option.rect) and the index of the item to paint.

This function should return (in the leadingFloats and trailingFloats parameters) lists of rectangles that the rendered text will be wrapped around. Rectangles on the leading side of the text should be returned in leadingFloats, and rectangles on the trailing side should be returned in trailingFloats. This allows some flexibility in deciding whether decorations should be drawn behind or beside the text.

The default implementation does not draw anything, and returns two empty lists.

See also textRectangle().

void QPimDelegate::drawForeground ( QPainter * p, const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Paints the foreground of the item.

The rectangle to paint in (using p) should be obtained from option (option.rect) and the index of the item to paint.

This function is called after painting all other visual elements (background, decorations, text etc) and could be used to apply a transparent effect to the rendered items.

The default implementation does not paint anything.

QFont QPimDelegate::mainFont ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns the font to use for painting the main label text of the item for the given index and style option option.

The default behavior is to return the font of the style option option, modified for bold rendering, and to ignore index.

QString QPimDelegate::mainText ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns the string to be displayed as the main text element of the delegate. The default implementation returns the DisplayRole of the supplied index, and ignores option.

void QPimDelegate::paint ( QPainter * painter, const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual]

Paints the item specified by index, using the supplied painter and style option option.

The default implementation will first draw the background and decorations, then the text items, and finally, any foreground items. All the drawing is accomplished using basic methods in this class.

Reimplemented from QAbstractItemDelegate.

See also drawBackground(), drawDecorations(), mainFont(), secondaryFont(), secondaryHeaderFont(), subTextAlignment(), textRectangle(), and drawForeground().

QFont QPimDelegate::secondaryFont ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns the font to use for painting the subsidiary value texts of the item, for the given index and style option option.

The default return value is a font that is at least two point sizes smaller than the font of the style option option. The supplied index is ignored in this case.

See also mainFont() and secondaryHeaderFont().

QFont QPimDelegate::secondaryHeaderFont ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns the font to use for painting the subsidiary header texts of the item, for the given index and style option option.

The default return value is a bold font that is at least two point sizes smaller than the font of the style option option. The supplied index is ignored in this case.

See also mainFont() and secondaryFont().

QSize QPimDelegate::sizeHint ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual]

Returns the delegate's size hint for a specific index index and item style option.

Reimplemented from QAbstractItemDelegate.

See also decorationsSizeHint().

SubTextAlignment QPimDelegate::subTextAlignment ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns the alignment of the header and value pairs of the subsidiary lines of text.

The default implementation returns QPimDelegate::Independent, and ignores the supplied index and option parameters.

QList<StringPair> QPimDelegate::subTexts ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns the list of subsidiary lines to render. This is stored in a list of pairs of strings, where the first member of the pair is the "header" string, and the second member of the pair is the "value" string.

If either member of the pair is a null QString (QString()), then the subsidiary line is considered to consist of a single string that will take up the entire line. You can specify an empty QString (QString("")) if you wish to have blank space.

The default implementation returns an empty list, and ignores the supplied index and option parameters.

int QPimDelegate::subTextsCountHint ( const QStyleOptionViewItem & option, const QModelIndex & index ) const   [virtual protected]

Returns a hint for the number of subsidiary lines of text to render for an item, which is used to calculate the sizeHint of this delegate.

The default implementation obtains the actual list of subsidiary lines of text to render with the supplied option and index, and returns the size of this list.

This method should be overridden if it can be slow to retrieve the list of subsidiary lines but fast to estimate the number of lines, for example, if all items are rendered with two subsidiary lines of text, but each subsidiary line of text requires a database lookup.

See also subTexts().

QRect QPimDelegate::textRectangle ( const QRect & entireRect, const QList<QRect> & leftFloats, const QList<QRect> & rightFloats, int top, int height ) const   [virtual protected]

Returns the rectangle that a line of text should be rendered in, given the following parameters.

• top - The top pixel coordinate of a line of text.
• height - The height of a line of text, in pixels.
• entireRect - The area of the entire delegate.
• leftFloats - The areas for any decorations at the left of the delegate.
• rightFloats - The areas for any decorations at the right of the delegate.

Note that the drawDecorations() function returns lists of rectangles that are RTL independent (e.g. leading and trailing instead of left and right). The lists of rectangles passed to this function are in absolute terms (left and right) - for an LTR language, they are equivalent, but for an RTL language the two lists will be exchanged.

This function is used while rendering each line of text, including any subsidiary lines.

See also drawDecorations().