Information Preview Popup API
Changes in Information Preview Popup API documentation
Changes in Information Preview Popup API
Purpose
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.
Constraints
This API is available on S60 3rd Edition, Feature Pack 2.
API 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.
Use cases
The most important use cases of Information Preview Popup API are
illustrated in
Figure 1
.
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
Hiding popup
Deleting popup
API class structure
The class structure for Information Preview Popup API consists
of three classes:
CAknPreviewPopUpController
,
MAknPreviewPopUpObserver
, and
MAknPreviewPopUpContentProvider
. The API class structure is shown in
Figure 2
below.
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.
Related APIs
-
CAknPreviewPopUpController
-
MAknPreviewPopUpContentProvider
-
MAknPreviewPopUpObserver
Using Information Preview Popup 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.
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.
Related APIs
-
MAknPreviewPopUpContentProvider
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.
Related APIs
-
CAknPreviewPopUpController
-
CAknPreviewPopUpController::AddObserverL()
-
CAknPreviewPopUpController::RemoveObserver()
-
CAknPreviewPopUpController::SetHeadingTextL()
-
CAknPreviewPopUpController::SetPopUpHideDelay()
-
CAknPreviewPopUpController::SetPopUpShowDelay()
-
KNullDesC
-
MAknPreviewPopUpObserver
Related APIs
-
CAknPreviewPopUpController
-
CAknPreviewPopUpController::TAknPreviewStyle
-
CCoeControl
-
EExcludeFrames
-
EFixedMode
-
ELayoutDefault
-
ELayoutSubMenu
-
EPermanentMode
-
HandlePointerEventL()
-
MinimumSize()
-
Rect()
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.
Related APIs
-
CAknPreviewPopUpController::ShowPopUp()
-
MAknPreviewPopUpObserver::EPreviewPopUpHidden
-
MAknPreviewPopUpObserver::EPreviewPopUpShown
-
MAknPreviewPopUpObserver::HandlePreviewPopUpEventL()
-
SetPosition()
-
SetPositionByHighlight()
-
ShowPopUp()
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.
Related APIs
-
CAknPreviewPopUpController::HidePopUp()
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.
Related APIs
-
CAknPreviewPopUpController
Error handling
The leave mechanism of Symbian OS environment is used to handle
memory exhaustion.
Extensions to the API
None.
Related APIs
-
CAknPreviewPopUpController
-
MAknPreviewPopUpContentProvider
-
MAknPreviewPopUpObserver
|