PtContainerGiveFocus()

Give focus to a widget

Synopsis:

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

Description:

This function gives focus to the specified widget, even if the widget's Pt_GETS_FOCUS flag isn't set.

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

The event argument contains 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 isn't provided, a NULL event is generated 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:

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

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

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

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

main()
{
    PtWidget_t *window, *texta, *textb, *textc,
               *button;
    PhPoint_t pos ={ 0, 0 };
    PhRect_t rect;
    int n;
    PtArg_t argt[5];
    PtCallback_t focus_cbs[] = { 
        { first, NULL }, 
        { next, NULL }, 
        { prev, NULL },
        { none, NULL } 
    };

    window = PtAppInit( NULL, NULL, NULL, 0, NULL);
    
    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "First Field", 0 ); n++;
    texta = PtCreateWidget( PtText, NULL, n, argt );
    PtExtentWidget( texta );
    PtWidgetExtent( texta, &rect );
    pos.y += rect.lr.y + 10;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "First Field", 0 ); n++;
    textb = PtCreateWidget( PtText, NULL, n, argt );
    PtExtentWidget( textb );
    PtWidgetExtent( textb, &rect );
    pos.y += rect.lr.y + 10;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "First Field", 0 ); n++;
    textc = PtCreateWidget( PtText, NULL, n, argt );
    PtExtentWidget( textc );
    PtWidgetExtent( textc, &rect );
    pos.y += rect.lr.y + 15;

    focus_cbs[0].data = (void *)texta;

    n = 0;
    PtSetArg( &argt[n], Pt_ARG_POS, &pos, 0 ); n++;
    PtSetArg( &argt[n], Pt_CB_ACTIVATE, 
              focus_cbs[0], 1 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "First", 0 ); n++;
    button = PtCreateWidget( PtButton, NULL, n, argt );
    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_CB_ACTIVATE, 
              focus_cbs[1], 1 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "Next", 0 ); n++;
    button = PtCreateWidget( PtButton, NULL, n, argt );
    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_CB_ACTIVATE, 
              focus_cbs[2], 1 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "Prev", 0 ); n++;
    button = PtCreateWidget( PtButton, NULL, n, argt );
    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_CB_ACTIVATE, 
              focus_cbs[2], 1 ); n++;
    PtSetArg( &argt[n], Pt_ARG_TEXT_STRING, 
              "None", 0 ); n++;
    button = PtCreateWidget( PtButton, NULL, n, argt );
    PtExtentWidget( button );
    PtWidgetExtent( button, &rect );
    
    pos.x += rect.lr.x + 10;
    PtRealizeWidget( window );
    PtMainLoop();
}

Classification:

Photon

See also:

PtContainerFocusNext(), PtContainerFocusPrev(), PtContainerNullFocus()

PtWindowFocus() in the Photon Widget Reference