Pictograph API Specification


1 Overview

Provides pictograph rendering functionality.

API categorypublic
API typec++
API librariesaknpictograph.lib

1.1 Description

The Pictograph API is an interface to render pictography. Using this API, the device user can be allowed to enter pictographs in different editors. All Symbian Platform UI components implement support for rendering pictographs.

The Pictograph API enables implementing support for pictograph rendering also in custom UI controls developed by third parties.

1.2 Class Structure

Summary of API classes and header files
CAknPictographInterface /epoc32/include/mw/AknPictographInterface.h, /epoc32/include/mw/AknPictographInterface.inl MAknPictographAnimatorCallBack /epoc32/include/mw/AknPictographDrawerInterface.h MAknPictographDrawer /epoc32/include/mw/AknPictographDrawerInterface.h

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.

2 Using The API

2.1 Rendering pictographs

A simple example is used to illustrate how to render 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 by calling DrawNow menthod to redraw the whole control. However, it can be optimized to draw only the regions necessary to update the pictographs.

   void CPictoContainer::DrawPictographArea()

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 to render text and the possible pictographs with it.

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

The instance of Pictograph interface is deleted in the destructor.

   // ...
   delete iPictographInterface;

2.2 Limitations of the API

The Pictograph feature is not enabled in Japanese SDK emulator environment because the actual pictograph bitmaps need to be licensed from operators separately. So the pictograph rendering can be verified only on hardware.