How to add context sensitivity to an application

Context phrases are defined for each topic in the rtf source file. The CS Help compiler generates a C++ header file, which contains literal descriptors created from the context phases. This header file must be included in the C++ applications, and is used to link each control to the appropriate topic.

In the rtf source file the process is:

1. Create a new line before the topic text in the source rtf file.

2. Enter a string which describes the context for the particular topic.

3. Mark the context in Context style.

4. Repeat the above for each topic.

5. Generate the CS Help file and C++ header file.

In a C++ application the process is:

1. Create the CCoeControl derived view or control for each context.

2. #include the header file from the CS Help compiler.

3. Overload the CCoeControl::GetHelpContext(TCoeHelpContext& aContext) function for the new control. The function should return a TCoeHelpContext which contains the UID of the help file and the literal descriptor for the appropriate help topic context. This is all that is required to link the control and the appropriate Help topic.

4. Compile the application.

OPL has two new key words to support CS Help—their use is discussed in the OPL SDK:

• SETHELP attach a particular context Id to a menu, dialog or view.

• SHOWHELP - launches the CSHelp app to display the current contexts

The three CS Help topics for the Shapes example project have the context text “This is a circle”, “This is a square” and “This is a dialog”. When the project is compiled, a header file containing descriptors for each of these is written to \epoc32\wins\c\system\help\.

The descriptor for each context is created by prefixing the context string with a K, and replacing any spaces with underscores. The C++ comments are generated from text in context comment style in the source rtf file. A listing of the header file for the shapes application—Shapes.hlp.hrh—is given below:

_LIT(KThis_is_a_circle,"This_is_a_circle"); //with a comment (round)
_LIT(KThis_is_a_square,"This_is_a_square"); //with a comment(square)
_LIT(KThis_is_a_dialog,"This_is_a_dialog"); //with a comment(dialog)

Context sensitivity is added to each of the three controls by overloading their inherited GetHelpContext() function. When help is requested, the function for the control which has focus is called, and hence the appropriate help topic is displayed.

The overload for the square control is shown below:

void CShapesAppViewSquare::GetHelpContext(TCoeHelpContext& aContext) const
 {
 aContext.iMajor = TUid(0x01123456);
 aContext.iContext = KThis_is_a_square;
 }