169) How do I make context sensitive help? The Motif Style Guide

says that an application must initiate context-sensitive help by changing the
shape of the pointer to the question pointer. When the user moves the pointer
to the component help is wanted on and presses BSelect, any available context
sensitive help for the component must be presented, and the pointer reverts
from the question pointer.
[Last modified: August 92]


Answer: A widget that gives context sensitive help would place this help in
the XmNhelpCallback function. To trigger this function: (from Martin G C
Davies, mgcd@se.alcbel.be)

I use the following callback that is called when the "On Context" help
pulldown menu is selected. It does the arrow bit and calls the help callbacks
for the widget. It also zips up the widget tree looking for help if needs be.
I don't restrict the arrows motion so I can get help on dialog boxes. No
prizes for guessing what "popup_message" does.


static void ContextHelp(
    Widget              w ,
    Opaque              * tag ,
    XmAnyCallbackStruct * callback_struct
)
{
    static Cursor   context_cursor = NULL ;
    Widget          context_widget ;

    if ( context_cursor == NULL )
        context_cursor = XCreateFontCursor( display, XC_question_arrow ) ;

    context_widget = XmTrackingLocate( top_level_widget,
                                context_cursor, FALSE ) ;

    if ( context_widget != NULL ) /* otherwise its not a widget */
    {
        XmAnyCallbackStruct cb ;

        cb.reason = XmCR_HELP ;
        cb.event = callback_struct->event ;

        /*
         * If there's no help at this widget we'll track back
           up the hierarchy trying to find some.
         */

        do
        {
            if ( ( XtHasCallbacks( context_widget, XmNhelpCallback ) ==
                                                XtCallbackHasSome ) )
            {
                XtCallCallbacks( context_widget, XmNhelpCallback, & cb ) ;
                return ;
            }
            else
                context_widget = XtParent( context_widget ) ;
        } while ( context_widget != NULL ) ;
    }

    popup_message( "No context-sensitive help found\n\
for the selected object." ) ;
}



Dave Bonnett suggested, to use the following translations for XmText (and
XmTextField) widgets to get the same help with key strokes, and to provide an
accelerator label in the Context help menu entry.

MyApp*XmText*translations: #override\n\
                                <Key>F1:    Help()

MyApp*Help_menu*Contextual Help.acceleratorText:   F1

MyApp*defaultVirtualBindings:           osfBackSpace : <Key>Delete\n\
                                        osfRight : <Key>Right\n\
                                        osfLeft  : <Key>Left\n\
                                        osfUp    : <Key>Up\n\
                                        osfHelp  : <Key>F1\n\
                                        osfDown  : <Key>Down