Function SetAppFocus() Foundation

Sets or returns the Xbase Part or window which has input focus.

Syntax
SetAppFocus( [<oXbp>] ) --> oOldXbp
Parameters
<oXbp>
<oXbp> is an Xbase Part or a window which is to receive input focus.
Return

The return value of SetAppFocus() is the Xbase Part or window which has input focus. If <oXbp> is specified, the function returns the Xbase Part or the window which had input focus before this call to SetAppFocus().

Description

SetAppFocus() determines the Xbase Part or window which has input focus. Only one window or one Xbase Part within a window can have input focus at any time. When a window has input focus, it receives the messages for events produced by the keyboard or the mouse (it processes the keyboard and mouse input). Input focus can be directly changed by specifying an Xbase Part in a call to SetAppFocus().

Xbase++ differentiates between input and output focus. The window in which screen output is shown always has output focus (see the function SetAppWindow()).

Focus changes automatically when windows are clicked with the mouse. During a focus change a total of 4 events is normally created. Note that the exact sequence of events is platform dependent.

Events sent during a focus change

Event Description
xbeP_KillInputFocus Previous object lost focus
xbeP_KillDisplayFocus Previous object deactivated
xbeP_SetDisplayFocus New object activated
xbeP_SetInputFocus New object got focus

Events sent during a focus change

Event Description
xbeP_KillDisplayFocus Previous object deactivated
xbeP_SetDisplayFocus New object activated
xbeP_KillInputFocus Previous object lost focus
xbeP_SetInputFocus New object got focus

If a dialog window is to react to one of these events, callback code blocks must be assigned to the corresponding instance variables :killDisplayFocus:killInputFocus, :setInputFocus or :setDisplayFocus. It is important that a focus change is complete before SetAppFocus() is called again. Interrupting a focus change by calling SetAppFocus() from a callback code block can lead to unpredictable situations. In case the focus must be reset within this sequence of events for any reasons, it is recommended that SetAppFocus() only be called after the xbeP_SetDisplayFocus event is retrieved with AppEvent().

Examples
Determine Xbase Part with input focus

// In the example, two entry fields are created (single and 
// multiple line). A pushbutton is displayed which transfers 
// input focus from one entry field to the other. 

#include "Appevent.ch" 

PROCEDURE Main 
   LOCAL nEvent, mp1, mp2, oXbp, oBtn, oSLE, oMLE 

   SetMouse(.T.)                    // process mouse events 
   SetColor( "N/W" )                // fill window pale gray 
   CLS 

                                    // single line entry field 
   oSLE := XbpSLE():new (,, {20, 200}, {150, 30} ) 
   oSLE:create() 
   oSLE:setData( "Xbase++ - single line entry field" ) 

                                    // multiple line entry field 
   oMLE := XbpMLE():new(,, {320,200}, {300,150} ) 
   oMLE:create() 
   oMLE:setData( "Xbase++ - multiple line entry field" ) 

   oBtn := XbpPushButton():new(,, {25, 25}, {120, 30} ) 
   oBtn:caption := "Input focus"    // pushbutton to change 
   oBtn:pointerFocus := .F.         // the input focus' 
   oBtn:create() 
   oBtn:activate := ; 
      {|| SetAppFocus( IIf(SetAppFocus()==oSLE, oMLE, oSLE) ) } 

   SetAppFocus( oSLE )              // SLE receives initial input 
                                    // focus 
   nEvent := 0 
   DO WHILE nEvent <> xbeP_Close 
      nEvent := AppEvent( @mp1, @mp2, @oXbp, 0 ) 
      IF nEvent == xbeK_ESC 
         EXIT 
      ELSEIF nEvent < xbeB_Event 
         ? "The key has the event code:", nEvent 
      ELSEIF oXbp <> NIL 
         oXbp:handleEvent( nEvent, mp1, mp2, oXbp ) 
      ENDIF 
   ENDDO 

RETURN 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.