Context Sensitive Help (CSH)

Context Sensitive Help (CSH)

There are 2 ways in which user can invoke the context sensitive help.

1. By pressing the SHIFT+F1 keys and then clicking on the topic for which help is wanted.

2. By pressing the F1 key when a menu item is selected, to get help on that menu item.

Some applications provide context sensitive help and some don't. Even if you do not provide CSH in your application, you must follow the guidelines (described below), so that the other applications involved in the inplace editing would be able to provide the CSH.

To support CSH we added the method IOleWindow::ContextSensitiveHelp (BOOL fEnterMode). All the inplace interfaces inherit from IOleWindow, so the interfaces IOleInPlaceFrame, IOleInPlaceUIWindow, IOleInPlaceSite, IOleInPlaceObject and IOleInPlaceActiveObject have the same method in them. See the following diagram from the spec..

Relationship of Object, Container, and Frame Interfaces

SHIFT+F1 based CSH

The top level container implements IOleInPlaceFrame (associated with its frame window). In addition to that it must implement IOleInPlaceUIWindow (associated with its document windows) if it is a MDI application. With this structure in place, at any given moment, objects can be UI active in more than one document, but at the most only one object can share the frame level real estate. Each one of these UI active objects can receive the mouse clicks directly without the other UI active objects knowing about the event. So, it is important that all the UI active objects know about this (CSH) modal state, so that when the mouse click is made on their windows, they can provide the CSH help or ignore the click (if they don't have help for that context or if they don't support CSH), instead of deactivating the inplace objects active in them.

When an object is UI active and shares the frame level real estate, the keyboard focus will be with the object window. When the SHIFT+F1 is done, either the top level container or active object can receive the keystrokes.

If the top level container receives the key stroke, then it calls its containing documents' ContextSensitiveHelp() method with fEnterMode = TRUE..

See the pseudo code for ContextSensitiveHelp() method in various interfaces, which shows how the state is propagated from top level container to all the UI active objects, so that they can do the appropriate thing when they receive the mouse click or WM_COMMAND.

Frame's private ContextSensitiveHelp (BOOL fEnterMode) // FRAME window

// Note: This is not the implementation of IOleInPlaceFrame::ContextSensitiveHelp(), and that method gets used in giving CSH when

F1 key is pressed while menu processing is going on.

// only if MDI app

IOleUIWindow::ContextSensitiveHelp(BOOL fEnterMode) // Document window

IOleInPlaceObject::ContextSensitiveHelp(BOOL fEnterMode)

As described above the state will be propagated from the frame to all the UI active objects.

Now let me describe how the state propagates in the other direction from the UI active object (which has the keyboard focus) to all the UI active objects in the tree of which the frame window is the root.

If the UI active object receives the SHIFT+F1 keystroke then it remembers that it has entered the CSH mode and calls its inplace site IOleInPlaceSite::ContextSensitveHelp(TRUE).

IOleInPlaceSite::ContextSensitveHelp (BOOL fEnterMode)

}

As you can see, each inplace site in turn calls its inplace (parent)site recursively. The top most inplace site will be associated with the document only if that app is a MDI app. In that case it should call the frame's private CSH method, which in turn will call the CSH method of each one of its documents. Otherwise it will be associated with the frame, and the propagation stops there.

With the above described mechanism, all the inplace objects which are UI active, enter the CSH mode when the SHIFT+F1 is pressed. In this state any of the visible windows can receive either the mouse click (in addition to that frame and active inplace object can receive WM_COMMAND). All the apps that can do inplace editing must provide the support for CSH mode as described below.

1. Implement the above described code for CSH in all the relevant interfaces.

2. When in CSH mode, if you receive mouse click, you can

a) either ignore the mouse click (i.e. don't perform your normal action) if you don't provide CSH.

b) or tell all the others to come out of CSH mode and then provide help for that context.

3. When in CSH mode, if you receive WM_COMMAND, tell all the others to come out of the CSH mode, and then provide help for the command if you can, but don't execute the command.

When you decide to tell the others to come out of the CSH mode you should do the following.

CSH on selected menu item

When an application enters the menu processing mode, windows USER code take over the control and does GetMessage() and Dispatches only some messages and throws away the remaining. When a menu item is selected, if the F1 key pressed, then the application would not receive the keystroke because USER's code throws it away. So, if the applications want to provide CSH on menu items, they typically install their own message filters so that they can intercept the F1 key and provide the help on the currently selected menu item.

Now coming to the inplace editing situations, the active inplace object tells its frame to set the combined menu on the menu bar calling IOleInPlaceFrame::SetMenu(). The frame in turn calls OleSetMenuDescriptor(), at which time we sub class the frame window of the application so that we can do the proper menu dispatching.

Normally it is up to the app to decide whether to provide CSH on menu item or not. But, if the app wants to be a container for inplace edited objects, then it must do one of the following.

1. Add its own message filter, so that it can intercept the F1 key. [Implement the message filter as explained later].

2. It can ask OLE dll to add a message filter by passing valid (non-null) values for 'IOleInPlaceFrame * lpFrame' and 'IOleInPlaceActiveObject * lpActiveObj' parameters of OleSetMenuDescriptor().

Refer to the above diagram..

Box exists as long as menu processing is going on.

Box in the above diagram exists if the app is an inplace container and an object is getting inplace edited in it.

Box 1 must be there when an object is getting inplace edited and the menu processing is in progress, whether the container has support for F1 based context sensitive help or not.

If the app is going to write the message filter, then it should be written as shown below.

(Note: there could be some other mechanisms through which the container can find out that the F1 key is pressed while menu processing is going on. Even in that case most of the following would be relevant).

MessageFilterProc(int nCode, WPARAM wParam, LPARAM lParam)

else

// Change message value to be WM_CANCELMODE and then call the next proc in the message filter chain. When windows

// USER's menu processing code sees this message it will bring down menu state and come out of its menu processing loop.

lpMsg->message = WM_CANCELMODE;

lpMsg->wParam = NULL;

lpMsg->lParam = NULL;

}

return CallNextHookEx (hMsgHook, nCode, wParam, lParam);

The code for ContextSensitiveHelp method in IOleInPlaceFrame and IOleInPlaceActiveObject interfaces is as simple as remembering the flag passed in.

IOleInPlaceFrame::ContextSensitiveHelp(BOOL fEnterMode)

IOleInPlaceActiveObject::ContextSensitiveHelp(BOOL fEnterMode)

The following code shows what the app can do when either WM_COMMAND or mouse click happens.

WM_COMMAND:

if (m_fMenuMode || m_fCSHMode)

if (m_fMenuMode)

call WinHelp if you provide help.

return;

}

do the normal thing.

Mouse click:

if (m_fCSHMode) else

return;

}