PtContainerGiveFocus()

Give focus to a widget

Synopsis:

PtWidget_t *PtContainerGiveFocus( 
                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. PtContainerGiveFocus() is the same as PtGiveFocus().

---

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:

#include <stdlib.h>
#include <Pt.h>

int first( PtWidget_t *widget, void *data, 
       PtCallbackInfo_t *cbinfo )
{
    //like selecting texta
    PtWidget_t *text = (PtWidget_t *)data;
    PtContainerGiveFocus( text, cbinfo->event );
    return Pt_CONTINUE;
}

int next( PtWidget_t *widget, void *data, 
      PtCallbackInfo_t *cbinfo )
{
    //like hitting tab
    PtGlobalFocusNext( widget, cbinfo->event );
    return Pt_CONTINUE;
}

int prev( PtWidget_t *widget, void *data, 
      PtCallbackInfo_t *cbinfo )
{
    //like hitting shift-tab
    PtGlobalFocusPrev( widget, cbinfo->event );
    return Pt_CONTINUE;
}

int none( PtWidget_t *widget, void *data, 
      PtCallbackInfo_t *cbinfo )
{
    PtContainerNullFocus( PtFindDisjoint (widget), 
                          cbinfo->event );
    return Pt_CONTINUE;
}

int main()
{
    PtWidget_t *window, *texta, *textb, *textc,
               *button;
    PhPoint_t pos ={ 0, 0 };
    PhArea_t area ={ {0, 0}, {100, 20} };
    PhRect_t rect;
    int n;
    PtArg_t argt[5];

    if (PtInit(NULL) == -1)
       exit(EXIT_FAILURE);

    if ((window = PtCreateWidget(PtWindow, Pt_NO_PARENT,
                                 0, NULL)) == NULL)
      PtExit(EXIT_FAILURE);
    
    n = 0;
    PtSetArg( &argt[n], Pt_ARG_AREA, &area, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "First Field", 0 ); n++;
    texta = PtCreateWidget( PtText, Pt_DEFAULT_PARENT,
                            n, argt );
    PtExtentWidget( texta );
    PtWidgetExtent( texta, &rect );
    area.pos.y = rect.lr.y + 10;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_AREA, &area, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "Second Field", 0 ); n++;
    textb = PtCreateWidget( PtText, Pt_DEFAULT_PARENT,
                            n, argt );
    PtExtentWidget( textb );
    PtWidgetExtent( textb, &rect );
    area.pos.y = rect.lr.y + 10;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_AREA, &area, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "Third Field", 0 ); n++;
    textc = PtCreateWidget( PtText, Pt_DEFAULT_PARENT,
                            n, argt );
    PtExtentWidget( textc );
    PtWidgetExtent( textc, &rect );
    pos.y += rect.lr.y + 15;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_FLAGS, Pt_FALSE, Pt_GETS_FOCUS);
    n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING,
          "First", 0 ); n++;
    button = PtCreateWidget( PtButton, Pt_DEFAULT_PARENT,
                             n, argt );
    PtAddCallback (button, Pt_CB_ACTIVATE, first, (void *)texta);
    PtExtentWidget( button );
    PtWidgetExtent( button, &rect );
    pos.x += rect.lr.x + 10;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_FLAGS, Pt_FALSE, Pt_GETS_FOCUS);
    n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "Next", 0 ); n++;
    button = PtCreateWidget( PtButton, Pt_DEFAULT_PARENT,
                             n, argt );
    PtAddCallback (button, Pt_CB_ACTIVATE, next, NULL);
    PtExtentWidget( button );
    PtWidgetExtent( button, &rect );
    pos.x += rect.lr.x + 10;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_FLAGS, Pt_FALSE, Pt_GETS_FOCUS);
    n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "Prev", 0 ); n++;
    button = PtCreateWidget( PtButton, Pt_DEFAULT_PARENT,
                             n, argt );
    PtAddCallback (button, Pt_CB_ACTIVATE, prev, NULL);
    PtExtentWidget( button );
    PtWidgetExtent( button, &rect );
    pos.x += rect.lr.x + 10;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_FLAGS, Pt_FALSE, Pt_GETS_FOCUS);
    n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "None", 0 ); n++;
    button = PtCreateWidget( PtButton, Pt_DEFAULT_PARENT,
                             n, argt );
    PtAddCallback (button, Pt_CB_ACTIVATE, none, NULL);

    PtRealizeWidget( window );
    PtMainLoop();
    return EXIT_SUCCESS;
}

Classification:

Photon

See also:

PhEvent_t, PtContainerFocusNext(), PtContainerFocusPrev(), PtContainerNullFocus(), PtGiveFocus()

PtWindowFocus() in the Photon Widget Reference