PtGiveFocus()

Give focus to a widget

Synopsis:

PtWidget_t *PtGiveFocus( PtWidget_t *widget,
                         PhEvent_t *event );

Library:

ph

Description:

This function gives focus to the specified widget, even if the widget's Pt_GETS_FOCUS flag isn't set. PtGiveFocus() is the same as PtContainerGiveFocus().

If the widget is a PtWindow, use PtWindowFocus() instead of this function -- see the Photon Widget Reference.

The event argument is a pointer to a PhEvent_t structure that describes the event that will be passed to the lost-focus callback of the widget losing focus and to the got-focus callback of the widget getting focus. If event is NULL, this function generates a PhEvent_t structure filled with zeros for you.

Returns:

A pointer to the newly focused widget. This is usually the same as the widget argument, but it could be NULL if one of the following is true:

• The widget argument is NULL.
• The given widget is disjoint (e.g. a window).
• The widget is blocked; that is, it has Pt_BLOCKED set in its Pt_ARG_FLAGS resource (see PtWidget in the Photon Widget Reference).
• The widget has been destroyed before the attempt to give it focus.
• The event passed (if not NULL) has already caused focus to change, as indicated by:

  event->processing_flags & Ph_DIRECTED_FOCUS
    

This function could also return a pointer to a different widget if that widget for some reason refused to relinquish focus (i.e. its Pt_CB_LOST_FOCUS callback returned Pt_END -- see PtBasic in the Photon Widget Reference). This usually happens if the requirements of an entry field haven't been met and must be met before any other action can be taken.

The widget library never refuses to relinquish focus. If a widget does this, it's because of a Pt_CB_LOST_FOCUS callback in your application.

Examples:

See PtContainerGiveFocus().

Classification:

Photon

See also:

PhEvent_t, PtContainerFocusNext(), PtContainerFocusPrev(), PtContainerGiveFocus(), PtContainerNullFocus()

PtWindowFocus() in the Photon Widget Reference