Information Preview Popup API Specification

1 Overview

Preview popup component is a floating AVKON popup component. Its purpose is to provide a common popup frame that applications can utilize to show additional information to the user.

Preview popup can be used in two behavioral modes; in the default mode where the popup is hidden automatically as a result of timeout or input event (either a key press or a pointer event) or in permanent mode where the popup stays visible until it is dismissed by the application code.

API category	public
API type	c++
Existed since	Legacy S60 3.2
API libraries	avkon.lib
Location	`/sf/mw/classicui/classicui_pub/information_preview_popup_api`
Buildfiles	`/sf/mw/classicui/classicui_pub/information_preview_popup_api/group/bld.inf`

1.1 Description

Information Preview Popup API can be used by all GUI applications. It is a library API that provides an interface for construction and using the Preview Popup UI component. The interface contains only method calls that can be used for creating local objects of provided interface classes and then using these objects.

1.2 Changes

This API is available on S60 Release 3.2 and onwards.

1.3 Use Cases

The most important use cases of Information Preview Popup API are illustrated in [Information_Preview_Popup_API_Specification.topic2.1_fig1 Figure 1].

Information Preview Popup API use cases

The use cases are as follows:

Creating popup

Create controller for the popup
Set content for the popup, or provide interface for asynchronous

content building.

Set properties and timeouts for the popup.

Showing popup

Set the position for the popup.
Request popup to be shown after specified timeout.

Hiding popup

Request the popup to be hidden immediately.

Deleting popup

Release the resources reserved for the popup.

1.4 Class Structure

Summary of API classes and header files
Classes	Files

CAknPreviewPopUpController /epoc32/include/mw/AknPreviewPopUpController.h MAknPreviewPopUpContentProvider /epoc32/include/mw/AknPreviewPopUpContentProvider.h MAknPreviewPopUpObserver /epoc32/include/mw/AknPreviewPopUpObserver.h

The class structure for Information Preview Popup API consists of three classes: CAknPreviewPopUpController , MAknPreviewPopUpObserver , and MAknPreviewPopUpContentProvider . The API class structure is shown in [Information_Preview_Popup_API_Specification.topic2.2_fig2 Figure 2] below.

Information Preview Popup API class structure

The CAknPreviewPopUpController class provides an interface for controlling preview popups. A separate instance of this class is required for each preview popup.

The client application using preview popup, must realize the MAknPreviewPopUpObserver interface. This interface is used as a callback hook between the actual popup and the client application. The client application receives notifications through this interface when popup is shown or hidden.

The content for the preview popup can be provided either synchronously or asynchronously. When synchronous contend building is used, the client application sets the content for the popup when the popup up is constructed. Alternatively, the MAknPreviewPopUpContentProvider interface can be used for utilizing asynchronous content building for the preview popup. In this case, the client application has to provide realization for the interface, which builds the content when requested by the interface, and then notifies the popup when content has been build.

2 Using The API

The use of Information Preview Popup API usually contains the following steps:

Link the AVKON library to the project file of the application.
Provide an observer class that realizes the MAknPreviewPopUpObserver interface.
If asynchronous content building is used, provide a class that

realizes the MAknPreviewPopUpContentProvider interface.

Create an instance of the CAknPreviewPopUpController class.
Provide content for the preview popup either synchronously or

asynchronously.

Show and hide the popup.
Receive information of the visibility changes through the observer

interface.

Delete the popup and its controller.
Delete popup content

More detailed instruction on using the API can be found in the following sections.

2.1 Creating preview popup

A preview popup is created by creating a controller, an instance of CAknPreviewPopUpController , for the popup. During the construction, the style for the popup must be specified. The behavior flags used in specifying the style for the preview popup are defined in the CAknPreviewPopUpController::TAknPreviewStyle enumeration. These flags can be given as an argument to the constructors. Description for each flag is listed below:

ELayoutDefault specifies the popup to use the

default graphics and layout.

ELayoutSubMenu specifies the popup to use the

submenu graphics and layout instead of the default ones, even if the ELayoutDefault flag is set as well.

EPermanentMode sets the preview popup to permanent

mode. In permanent mode, the visible preview popup is not dismissed by pen or key events, and a timeout for hiding the popup is not used. Instead, the client application must hide the visible popup explicitly, when necessary.

EFixedMode sets the preview popup to use the

default size defined in the layout data instead of scaling itself to accommodate its content. The flag is intended for splitting the screen into two halves with preview popup occupying the other half.

EExcludeFrames can be used in conjunction with

the EFixedMode flag. When both of them are set, the preview popup uses the default size defined in the layout data, as with only the EFixedMode flag, but the areas reserved for the popup heading and frames are subtracted from the size of the popup content. This flag has no effect, when the EFixedMode flag is not set.

The preview popup itself is responsible for providing the frame for the popup, but the content of the popup has to be provided by the client application. The content must be implemented as a class, which is derived from CCoeControl , and an instance of that class must be given to the constructor of the popup's controller.

There are few important issues when implementing the content of a preview popup.

In default mode, the content defines the size for the whole preview

popup; the size of the popup is equal to the size of the content combined with the space reserved for the frames and optional heading pane. Preview popup uses the content's MinimumSize() method for determining the size of the content, thus, the method must be implemented properly.

In fixed mode, the preview popup uses the size and position defined

in the layout data, and the same size is also set for the content without reserving any space for its frames or optional heading text.

Component controls of the content class must always be positioned

relative to the content's rectangle, returned by the Rect() method, because the content does not own the whole window. This should also be taken into account when drawing the content, for example, by setting correct clipping rectangle, so that the drawing is not done over the popup frame or heading.

The content cannot receive any key events since the preview popup

cannot gain focus. Pen events are mediated normally to the HandlePointerEventL() method.

The preview popup elects to be a background drawer of the popup

content, which means that the content is not responsible for drawing the background and should only draw the content, for example, text and icons, over the already drawn background

The following subsections describe how the content can be build either synchronously or asynchronously.

2.1.1 Synchronous content building

The sequence diagram for constructing the preview popup controller with synchronous content building is illustrated in [Information_Preview_Popup_API_Specification.topic3.1.1_fig3 Figure 3] below.

Creating preview popup

Note that the constructor takes only reference to the popup content and the ownership of this content is not passed to the controller. Thus, the client application is responsible for deleting the content after the controller has been deleted.

2.1.2 Asynchronous content building

The sequence diagram for constructing the preview popup controller with asynchronous content building is illustrated in [Information_Preview_Popup_API_Specification.topic3.1.2_fig4 Figure 4] below.

Creating preview popup with asynchronous content provider

Although the application specific content class has to be provided to the controller also with asynchronous content building, the content does not have to complete until the preview popup is displayed. The client application will receive request through the MAknPreviewPopUpContentProvider interface to build the content before the popup is displayed. The realization for this interface has to be given to the constructor as well.

2.1.3 Setting properties

After the instance of the CAknPreviewPopUpController class has been successfully constructed, the client application can add observers for the popup and change its default properties. An example of this is illustrated in [Information_Preview_Popup_API_Specification.topic3.1.3_fig5 Figure 5].

Changing popup properties

In order to receive notifications of changes in the visibility of the popup, the client application can provide realizations for the MAknPreviewPopUpObserver interface, and register those to the preview popup controller with the CAknPreviewPopUpController::AddObserverL() method. The number of registered observers is not restricted. Registered observers can later be removed with the CAknPreviewPopUpController::RemoveObserver() method.

The show and hide delays can be changed from the default with CAknPreviewPopUpController::SetPopUpShowDelay() and CAknPreviewPopUpController::SetPopUpHideDelay() methods. The show delay is the time interval between the request to display the popup and the moment when the popup is actually displayed. The hide delay is the time interval for how long the popup is displayed unless hidden by key or pen event, or explicitly by the client application. Setting hide delay for popup has no effect, if the popup is used in permanent mode. Default values for show and hide delays are 0.1 and 10 seconds respectively. If hide delay is set to zero, no timeout for hiding the popup is used.

By default, preview popup's heading pane is hidden, and it is shown when heading text is provided with the CAknPreviewPopUpController::SetHeadingTextL() method. The heading text can later be changed with the same method, and the heading pane can be hidden by replacing the heading text with KNullDesC . Setting the heading text also shows the closing button that resides in the same heading pane. The closing button is suppressed if stylus is not supported by the currently active layout or the popup is used in permanent mode.

2.2 Showing popup

Displaying a preview popup instance consists of setting up the position for the popup and then requesting the popup controller to show the popup after the previously specified delay.

The position for the popup can be set through the controller using two possible methods: SetPosition() and SetPositionByHighlight() . The first of these sets the top-right corner to the given coordinate and, if necessary, moves the location to make the popup fully visible when shown. The latter of these can be used, for example, in conjunction with list or grids. The method requires the highlight rectangle of currently focused list or grid item, which is used to position the popup near the focused item. These methods have no effect in fixed mode.

After the location for the popup has been set, the client application must request the controller to display the popup with the CAknPreviewPopUpController::ShowPopUp() method. The sequence for this is shown in [Information_Preview_Popup_API_Specification.topic3.2_fig6 Figure 6]. The ShowPopUp() call starts the timer and returns to the caller. When the timer expires, it first initiates the asynchronous content building, if such is used, and when the content provider signals that the content for the popup has been build, the popup is set visible. The controller notifies all the registered observers of the event by calling the MAknPreviewPopUpObserver::HandlePreviewPopUpEventL() method with MAknPreviewPopUpObserver::EPreviewPopUpShown as the event.

After the preview popup is shown, the controller starts the timer to count the hide delay. When the timer expires again, the controller hides the visible popup, and notifies the registered observers, this time with the MAknPreviewPopUpObserver::EPreviewPopUpHidden event.

Showing popup using asynchronous content

The sequence for showing a popup without asynchronous content building would otherwise be similar to this sequence, but with synchronous content building the popup is shown right after the show delay without content building request.

2.3 Hiding popup

Unless the preview popup is in permanent mode, it is dismissed after the specified popup hide delay, or when the user dismisses it with key event or with pen event outside of the popup. Note also that, if the user is keeping the pen pressed over the popup when the hide timer expires, the popup is not hidden before the user releases the pen from the screen.

A visible popup can be hidden immediately by calling the function CAknPreviewPopUpController::HidePopUp() .

Whenever the preview popup is hidden, all of its observers are notified of the event.

2.4 Deleting popup

After the preview popup is no longer needed, the client can delete the CAknPreviewPopUpController instance. Note that neither the content, content provider, nor the observers are owned by the controller, so they are not automatically deleted.

2.5 Error handling

The leave mechanism of Symbian OS environment is used to handle memory exhaustion.