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.
|Existed since||Legacy S60 3.2|
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.
This API is available on S60 Release 3.2 and onwards.
The most important use cases of Information Preview Popup API are illustrated in [Information_Preview_Popup_API_Specification.topic2.1_fig1 Figure 1].
The use cases are as follows:
The class structure for Information Preview Popup API consists of three classes:, , and . The API class structure is shown in [Information_Preview_Popup_API_Specification.topic2.2_fig2 Figure 2] below.
Theclass 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 theinterface. 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, theinterface 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.
The use of Information Preview Popup API usually contains the following steps:
More detailed instruction on using the API can be found in the following sections.
A preview popup is created by creating a controller, an instance of, 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 enumeration. These flags can be given as an argument to the constructors. Description for each flag is listed below:
default graphics and layout.
submenu graphics and layout instead of the default ones, even if theflag is set as well.
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.
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.
theflag. When both of them are set, the preview popup uses the default size defined in the layout data, as with only the 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 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, 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.
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'smethod for determining the size of the content, thus, the method must be implemented properly.
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.
relative to the content's rectangle, returned by themethod, 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.
cannot gain focus. Pen events are mediated normally to themethod.
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.
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.
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.
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.
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 theinterface to build the content before the popup is displayed. The realization for this interface has to be given to the constructor as well.
After the instance of theclass 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].
In order to receive notifications of changes in the visibility of the popup, the client application can provide realizations for theinterface, and register those to the preview popup controller with the method. The number of registered observers is not restricted. Registered observers can later be removed with the method.
The show and hide delays can be changed from the default withand 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 themethod. The heading text can later be changed with the same method, and the heading pane can be hidden by replacing the heading text with . 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.
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:and . 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 themethod. The sequence for this is shown in [Information_Preview_Popup_API_Specification.topic3.2_fig6 Figure 6]. The 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 method with 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 theevent.
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.
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.
Whenever the preview popup is hidden, all of its observers are notified of the event.
After the preview popup is no longer needed, the client can delete theinstance. Note that neither the content, content provider, nor the observers are owned by the controller, so they are not automatically deleted.
The leave mechanism of Symbian OS environment is used to handle memory exhaustion.