FAQ-1129 What is an embeddable application?


FAQ-1129 What is an embeddable application?

» Symbian OS » Developer Knowledgebase » FAQ-1129

Classification:	C++	Category:	Application Architecture
Created:	09/07/2004	Modified:	10/13/2004
Number:	FAQ-1129
Platform:	Symbian OS v6.0, Symbian OS v6.1, Symbian OS v7.0, Symbian OS v7.0s, Symbian OS v8.0, Symbian OS v8.0a, Symbian OS v8.0b, Symbian OS v8.1a, Symbian OS v8.1b

Question:
How does this work?
How do I make an application embeddable ?
What are the differences between an embeddable and a non-embeddable application ?
How can I check if a particular embeddable application is running?
How can I check if a particular embeddable application has been installed?

Answer:
This FAQ covers Symbian OS versions up to (and including) Symbian OS v8.x.

What is an embeddable application ?

An embeddable application is one in which the document type can be opened/viewed from within another application's documents. Depending on how the embedding application is written, the embedded document may be displayed, using the CApaDoor object, as an icon, or a 'glass' to a partial view of the data in the embeddable document (this needs to be supported by the embedded document).

For example, a Symbian "Sheet" document can be embedded in a Symbian "Word" document. The sheet may be shown as an icon, or as a partially displayed spreadsheet. When you select the sheet icon or view, the Sheet application is launched to allow the embedded document to be edited. Similarly, a Symbian "Paint" image can be embedded in a word image.

How does this work?

An embedded document (application) is started and run from within the "parent" application's thread - rather than within in its own process (the normal case for applications launced from the system shell).

Within each application environment, the App Framework keeps a handle to an application stack. The application at the top of the stack is considered to be active and is the only one in the stack to receive events from the user. By default when you run a non-embeddable application its CEikAppUiobject gets loaded at the top of the application stack and runs as the only active application. When an embeddable app is launched from a 'host' application, the embedabble app gets loaded at the top of the 'host' application's stack, 'hides' the host's application furniture and runs in the foreground.

The Application Framework in Symbian OS allows apps to be embeddable by setting the 'embeddability' capability in the AIF data (see below).

How do I make an application embeddable ?

This link Developer Library » Tools and Utilities » Application resource tools guide » The application information file format gives information on application capabilities. Information on AIF file format can be found here » Developer Library » Tools and Utilities » Application resource tools reference » Application information file source format. Below is an AIF resource example that would make an application embeddable.

RESOURCE AIF_DATA
{
app_uid=0x10202C0b;
num_icons=2;
embeddability=KAppEmbeddable
newfile=KAppDoesNotSupportNewFile;
}

The embeddability enum 'TEmbeddability' is defined in Apaid.h and the equivalent RSS definitions are defined in Aiftool.rh. Note that the enum was extended from 7.0s to include 2 more definitions i.e. EEmbeddableUiOrStandAlone and EEmbeddableUiNotStandAlone. There are no differences in how an application is defined between a non-embeddable and a embeddable app except for the capability in the resource file.

DevKit users can look at the Rich Text Editor source '...src/common/techview/toolkit/eikstd/ctlsrc/eikrted.cpp' for reference which embeds documents. Also, Series60 SDks ship with a document named '../Series60Doc/document handler.pdf'that further explains about application embeddibility.

What are the differences between an embeddable and a non-embeddable application ?

1. An embeddable app is launched using AddNewDocumentL(..) or OpenNewDocumentL(..) and a non-embeddable app is launched with the RApaLsSession API.
2. Whilst the embeddable application is running it does not appear in the application task list using TApaTaskList.
3. The embeddable application runs within the host application's thread whilst other apps run in their own process.
4. An embeddable application can run as a non-embeddable app if launched outside an application e.g from a process. This would cause it to appear in the task list. Note that an embeddable application can only be run stand-alone if its embeddability is not one of the "EmbeddableXxx" only values.
How can I check if a particular embeddable application is running?

You can't. As the application does not appear in task list there is no way to say if an embeddable application is currently running or not. Code used generally (see snippet below which is not complete) will not work. Nor will using TFindThread to search for the app work as the embedded application runs in the host application's thread. There is an exception to the above if the application is launched using the RApaLsSession API.

for (TInt index=0; index < RWsSession.NumWindowGroups; index++)
{
TApaTask *task= new (ELeave) TApaTask(taskList.FindByPos(index));
CApaWindowGroupName* wgName=CApaWindowGroupName::NewLC(window,task->WgId());
TPtrC taskCaption = wgName->DocName();
...
}

OR

RWsSession.WindowGroupList(ids);
for (TInt count=0; countCount(); count++)
{
TBuf<50> nameBuf;
err=window.GetWindowGroupNameFromIdentifier((*ids)[count],nameBuf);
...
}

How can I check if a particular embeddable application has been installed ?

You can call RApaLsSession::GetAppInfo(..) with the correct Uid and check the return error code. A KErrNotFound indicates that the application has not been installed. You can also use the following sample code to get a list of all applications that have been installed.

RApaLsSession ls;
User::LeaveIfError(ls.Connect());

// Get all applications installed
User::LeaveIfError(ls.GetAllApps()); // Or use other methods

TApaAppInfo info;
while(ls.GetNextApp(info) == KErrNone)
{
TApaAppInfo info1;
ls.GetAppInfo(info1,info.iUid);

// Don't want full path so just show name
print(info1.iFullName);
}

;