Pictograph API: Technical Specification

Type of the Interface

Logical type: Library API.

Technical type: Method call.

Interface Class Structure

Class: CAknPictographInterface

Encapsulates access to the MAknPictographDrawer interface. Instantiated by the user code.

Class: MAknPictographDrawer

An interface for the following operations:

• Querying the supported pictograph codes.

• Querying whether a given character is a supported pictograph.

• Querying whether a given text contains pictographs or not.

• Querying whether a given pictograph is animated or not.

• Querying a suitable pictograph height for a given font.

• Rendering pictographs in fixed positions.

• Rendering pictographs amongst text.

• Setting the drawing mode for single pictograph drawing.

Class: MAknPictographAnimatorCallBack

A callback which the user code must implement to support animations of the pictographs. It is invoked by the pictograph framework when the next frame of the animated pictographs should be updated. It should do the following:

1. Draw or clear the background of pictographs.

2. If the pictographs are amongst text, draw the text.

3. Draw the pictographs using the MAknPictographDrawer interface.

In many cases, it is sufficient to implement this simply by calling CCoeControl::DrawNow for the appropriate control.

Usage

Protocol

User code first instantiates the CAknPictographInterface class. Then it can access all the other Pictograph API methods via the MAknPictographDrawer class. All API calls are synchronous.

Error Handling

Error situations are handled with the Symbian OS leave mechanism.

Memory Overhead

The memory overhead caused by the usage of the interface is minimal.

Extensions to the API

The MAknPictographDrawer API may be extended in future releases by adding new virtual functions.

Example

This simple example illustrates how to implement support for rendering pictographs in a UI control that handles rendering text by itself.

The user class is derived from MAknPictographAnimatorCallBack.

class CPictoContainer: public CCoeControl, public MaknPictographAnimatorCallBack
    {
    // ...
    private: // from MAknPictographAnimatorCallBack
        void DrawPictographArea();    
    };

MAknPictographAnimatorCallBack::DrawPictographArea is implemented by the user code. In this case, it is done simply by calling DrawNow to redraw the whole control. However, it may also be optimized to draw only the regions necessary to update the pictographs. In this case, the user code must find out what those regions are.

void CPictoContainer::DrawPictographArea()
    {
    DrawNow();
    }

CAknPictographInterface is instantiated by the user code.

// This returns NULL if pictograph feature is not supported.
// Remember NULL check always before accessing iPictographInterface.
iPictographInterface = CAknPictographInterface::NewL( *this, *this );

Drawing code uses the MAknPictographDrawer API methods to render text and the possible pictographs amongst it.

void CPictoContainer::Draw( const TRect& aRect ) const
    {
    // ...
    gc.DrawText( text, adjustedBox, ascent, align, margin );
    // remember NULL check always with pictograph interface
    if ( iPictographInterface )
        {
        iPictographInterface->Interface()->DrawPictographsInText(
            gc, *iFont, text, adjustedBox, ascent, align, margin );
        }
    }

The Pictograph interface is normally deleted in the destructor.

CPictoContainer::~CPictoContainer()
    {
    // ...
    delete iPictographInterface;
    }

Detailed Description

See the header file AknPictographDrawerInterface.H.

Code Architecture

The public header files are the following:

• AknPictographInterface.H

• AknPictographInterface.INL

• AknPictographDrawerInterface.H

The user code links against AknPictograph.LIB.

The main implementation resides in the polymorphic DLL AknPictographImpl.DLL.