Information Preview Popup API: Using Information Preview Popup API

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

1. Link the AVKON library to the project file of the application.
2. Provide an observer class that realizes the MAknPreviewPopUpObserver interface.
3. If asynchronous content building is used, provide a class that realizes the MAknPreviewPopUpContentProvider interface.
4. Create an instance of the CAknPreviewPopUpController class.
5. Provide content for the preview popup either synchronously or asynchronously.
6. Show and hide the popup.
7. Receive information of the visibility changes through the observer interface.
8. Delete the popup and its controller.
9. Delete popup content

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

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.

Synchronous content building

The sequence diagram for constructing the preview popup controller with synchronous content building is illustrated in Figure 3 below.

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.

Asynchronous content building

The sequence diagram for constructing the preview popup controller with asynchronous content building is illustrated in Figure 4 below.

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.

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 Figure 5.

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.

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 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.

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.

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.

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.

Error handling

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

Memory overhead

None.

Extensions to the API

None.