Help AIW Provider Specification: Using the Help AIW Provider

This sections gives a detailed description for using the Help AIW Provider to launch the Help Application.

Context Sensitive Help Launch

This section describes how to invoke the Help application with the context sensitive information from the client application.

Linking the Client Application with the Help topics

A context sensitive help topic typically maps to a UI/view in the consumer applications. The following code snippet explains how to link a view with a context sensitive help topic. The function GetHelpContext()function needs to be overridden in the container class of the view. The help context ID will be provided by the help content authors in a hrh file.

void CMyAppContainer::GetHelpContext(TCoeHelpContext& aContext) const
    {
    aContext.iMajor = KUidMyApp;//Consumer application's UID
    aContext.iContext = KMYAPP_HLP_MAIN;/*Will be provided by the Help content author in a hrh file*/
    }

Expressing Interest in Help AIW Provider

The consumer application has to specify it's interest in help AIW Provider using a criteria item and provide a placeholder in its menu where the help AIW provider can attach itself. For more information, please refer to the AIW Consumer API documentation.

RESOURCE AIW_INTEREST r_aiwhelpapp_interest
{	
	items =	{
		 AIW_CRITERIA_ITEM
			{
		 	id = ECmdAiwPlaceHolder; //From the application's .hrh file
		 	serviceCmd = KAiwCmdHelp;     //from aiwcommon.hrh
		 	serviceClass = KAiwClassMenu; //from aiwcommon.hrh
		 	contentType = "*";
		 	defaultProvider = 0x10207465; //Implementation ID of the Help AIW Provider. Optional
		 	}
		};
}

RESOURCE MENU_PANE r_myapp_menu     
{     
items =         
	{
	MENU_ITEM
		{
		command = ESomeCmd1;
		txt = qtn_some_text_1;
		},
	MENU_ITEM     
		{
		command=ECmdAiwPlaceHolder;
		txt = "PlaceHolder";//Text will changed dynamically by Help AIW Provider
		cascade = AIW_INTELLIGENT_CASCADE_ID;
		},
	MENU_ITEM
		{
		command = ESomeCmd2;
		txt = qtn_some_text_2;
		}
	};
}

Attaching & Initializing the Help AIW Provider

The consumer application must attach its interest to the AIW framework using the CAiwServiceHandler::AttachMenuL() function. Menu panes containing AIW placeholders must be initialized in the consumer application's DynInitMenuPaneL(). At the initialization phase (InitializeMenuPaneL ) any input and output parameters are ignored:

class CMyAppView : public CAknView
	{
	private:
      		CAiwServiceHandler* iServiceHandler;
    	};

void CMyAppView ::ConstructL()
	{
	iServiceHandler = CAiwServiceHandler::NewL();
	iServiceHandler->AttachMenuL(R_MYAPP_MENU, R_AIWHELPAPP_INTEREST);
	}

void CMyAppView::DynInitMenuPaneL(TInt aResourceId, CEikMenuPane* aMenuPane) 
	{
	if(iServiceHandler->HandleSubmenuL(*aMenuPane))
		return;

	switch (aResourceId)
		{
		case (R_MYAPP_MENU):
			{
			DynInitMainMenuPane(aMenuPane);
		 	iServiceHandler->InitializeMenuPaneL(*aMenuPane, aResourceId, ECmdLast, iServiceHandler->InParamListL()); 
			break;
			}
		}   
	}

Menu Command Handling

When the consumer application notices that it does not recognize a particular menu command ID in its HandleCommandL()function, it must forward the menu command to the service handler module with the appropriate input parameters.

void CMyAppView::HandleCommandL( TInt aCommand ) 
	{
	case ESomeCmd1:
		//Handle the command
		break;
	case ESomeCmd2:
		//Handle the command
		break;
	default:
		{
			CArrayFix< TCoeHelpContext >* buf = AppUi()->AppHelpContextL();
			TCoeHelpContext& helpContext = buf->At(0); 		
			TAiwVariant uidVariant;
			TAiwVariant contextVariant; 		
			uidVariant.Set(helpContext.iMajor); 		
			TAiwGenericParam uidParam(EGenericParamHelpItem, uidVariant); 		
			contextVariant.Set(helpContext.iContext); 		
			TAiwGenericParam contextParam(EGenericParamHelpItem, contextVariant); 	
			CAiwGenericParamList* list = CAiwGenericParamList::NewLC(); 		
			list->AppendL(uidParam);
			list->AppendL(contextParam); 
			iServiceHandler->ExecuteMenuCmdL(aCommand,*list,iServiceHandler->OutParamListL()); 	
			CleanupStack::PopAndDestroy(list);
			delete buf;
			break;
		}
	}

Error handling

Some methods may leave, for example if running out of memory. Normal Symbian error handling practises should be used, including e.g. using cleanup stack and trap harness.

Memory overhead

The memory usage of the Help AIW Provider does not exceed usual overhead related to object creation.