NAME

XvhReturnSelectedWidgetId − Return the selected widget or gadget based on a users selection.

SYNOPSIS

#include <Xvh/HelpUtil.h> int XvhReturnSelectedWidgetId (parent, cursor, *widget)
        Widget  parent;
        Cursor  ursor;
        Widget * idgett;

DESCRIPTION

XvhReturnSelectedWidgetId provides a modal interface for selection of a component.  It is intended to support context sensitive help.  The function grabs the pointer, displays a question mark cursor and returns the widget in which a button press occurs.  Pressing the ESC key aborts this function. 

parentSpecifies the parent widget ID

cursorSpecifies the pointer cursor to use in the component selection. 

widgetSpecifies the widget ID of the widget to use as the basis of the modal interaction. XvhReturnSelectedWidgetId returns a widget within the widget’s hierarchy. 

XvhReturnSelectedWidgetId allows developers get the widget ID for any widget in their user interface that the user has selected via the pointer. The application then has the opportunity to directly display a help topic based on the selected widget, or can dynamically construct help information based on the current context of the selected item. 

At any point while the question mark cursor is displayed the user can select the escape key (e.g. ESC) to abort the function call.  If an error occurs or the user aborts the function via ESC, the function will return a status depicting the return condition and a NULL value for the widget parameter. 

RETURN VALUE

Returns an integer status. See below for a complete description of the return values. 

The following defines depict the status of the returning function call:

XvhSELECT_ERROR
A return status of XvhSELECT_ERROR informs the calling routine that and error occurred while attempting to process the function.

XvhSELECT_INVALID
A return status of XvhSELECT_INVALID informs the calling routine that the user selected a non-valid component outside the scope of the current widget hierarchy. occurred while attempting to process the function.

XvhSELECT_ABORT
A return status of XvhSELECT_ABORT informs the calling routine that the user aborted the function (e.g. pressed the "ESC" key).

XvhSELECT_VALID
A return status of XvhSELECT_VALID informs the calling routine that the user selected a valid component within the application.  The widget ID is returned via the widget parameter in the function.

RELATED INFORMATION

XvhQuickHelpDialog(3X), XvhHelpDialog(3X)

The HP Help Developer’s Guide

Hewlett-Packard Company  —  April 21, 1994