◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WININPUT
 
BOOL WinSetFocus(hwndDesktop, hwndSetFocus)
HWND hwndDesktop;     /* handle of the desktop                    */
HWND hwndSetFocus;    /* handle of the window receiving the focus */
 
The WinSetFocus function sets the focus window.
 
Parameter     Description
────────────────────────────────────────────────────────────────────────────
 
hwndDesktop   Identifies the desktop window. This parameter can be
              HWND_DESKTOP or the desktop window handle.
 
hwndSetFocus  Identifies the window that receives the focus. This parameter
              must be equal to or be a descendant of the window identified
              by the hwndDesktop parameter. If hwndSetFocus identifies a
              desktop window or is NULL, no window on the device associated
              with hwndDesktop receives the focus.
 
Return Value
 
The return value is TRUE if the function is successful or FALSE if an error
occurs.
 
Comments
 
If hwndSetFocus does not have the focus when this function is called, the
following events occur:
 
♦  If a window currently has the focus, it receives a WM_SETFOCUS message,
   indicating the loss of the focus.
 
♦  If a window currently is selected, it receives a WM_SETSELECTION message,
   indicating the window is deselected.
 
♦  If changing the focus causes a change in the active window, a
   WM_ACTIVATE message is sent to the active window, indicating the loss of
   active status.
 
♦  If a new application is being made the active application, a WM_ACTIVATE
   message is sent to the active application, indicating loss of active
   status.
 
♦  The new active and focus windows and the active application are
   established.
 
♦  If a new application is being made the active application, a WM_ACTIVATE
   message is sent to the new application, indicating the acquisition of
   active status.
 
♦  If the active window is changing, a WM_ACTIVATE message is sent to the
   new main window, indicating the acquisition of active status.
 
♦  If a new window is selected, it receives a WM_SETSELECTION message,
   indicating the window has been selected.
 
♦  The new focus window is sent a WM_SETFOCUS message, indicating the
   acquisition of focus.
 
Using the WinQueryActiveWindow or the WinQueryFocus function during
processing of the WinSetFocus function results in the previous active and
focus windows being returned until the new active and focus windows are
established. In other words, even though a WM_SETFOCUS message with the
fFocus parameter set to FALSE or a WM_ACTIVATE message with the fActive
parameter set to FALSE may have been sent to the previous windows, those
windows are considered to be active and have the focus until the system
establishes the new active and focus windows.
 
If WinSetFocus is called during WM_ACTIVATE message processing, a
WM_SETFOCUS message with the fFocus parameter set to FALSE is not sent,
since no window has the focus.
 
If no window has the input focus, then WM_CHAR messages are posted to the
active window's queue.
 
Example
 
This example retrieves an integer from a dialog entry field. It then checks
for a valid number. If not found, it displays a message box indicating that
an error occurred, and then calls WinSetFocus to set the focus back to the
entry field that caused the error.
 
fError = WinQueryDlgItemShort(hwndDlg, idEntryField, &ivalue, TRUE);
if (fError || (ivalue < iLoRange) || (ivalue > iHiRange)) {
    WinMessageBox(HWND_DESKTOP, hwndFrame, (PSZ) szErrMsg,
        (PSZ) NULL, idMessageBox, MB_OK );
    WinSetFocus(HWND_DESKTOP, WinWindowFromID(hwndDlg, idEntryField));
}
else {
 
See Also
 
WinFocusChange, WinQueryActiveWindow, WinQueryFocus, WinSetActiveWindow,
WM_ACTIVATE, WM_FOCUSCHANGE, WM_SETFOCUS, WM_SETSELECTION
 
                                      ♦