WinFocusChange

This function changes the focus window. This function is used to set the focus to a specified window and send a WM_SETFOCUS message to that window.

Syntax

WinFocusChange(hwndDeskTop, hwndNewFocus, flFocusChange);

Parameters

hwndDeskTop (HWND) - input

Desktop-window handle.

HWND_DESKTOP

The desktop-window handle

Other

Specified desktop-window handle.

hwndNewFocus (HWND) - input

Window handle to receive the focus.

flFocusChange (ULONG) - input

Focus changing indicators.

These indicators are passed on in the WM_FOCUSCHANGE message:

FC_NOSETFOCUS

Do not send the WM_SETFOCUS message to the window receiving the focus.

FC_NOLOSEFOCUS

Do not send the WM_SETFOCUS message to the window losing the focus.

FC_NOSETACTIVE

Do not send the WM_ACTIVATE message to the window being activated.

FC_NOLOSEACTIVE

Do not send the WM_ACTIVATE message to the window being deactivated.

FC_NOSETSELECTION

Do not send the WM_SETSELECTION message to the window being selected.

FC_NOLOSESELECTION

Do not send the WM_SETSELECTION message to the window being deselected.

FC_NOBRINGTOTOP

Do not bring any window to the top.

FC_NOBRINGTOTOPFIRSTWINDOW

Do not bring the first frame window to the top.

Returns

rc (BOOL) - returns

Success indicator.

TRUE

Successful completion

FALSE

Error occurred.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

Remarks

This function sends a WM_FOCUSCHANGE message to the window that is losing the focus and a WM_FOCUSCHANGE message to the window that is receiving the focus.

This function fails if another process or thread is currently using this function.

Other messages may be sent as a consequence of the frame control processing of the WM_FOCUSCHANGE (in Frame Controls) message, depending on the value of the flFocusChange parameter. These messages, if sent, are sent in this order:

   WM_SETFOCUS to the window losing the focus.
   WM_SETSELECTION to the windows losing their selection.
   WM_ACTIVATE to the windows being deactivated.
   WM_ACTIVATE to the windows being activated.
   WM_SETSELECTION to the windows being selected.
   WM_SETFOCUS to the window receiving the focus.

Note: If the WinQueryFocus function is used during processing of this function:

   The window handle of the window losing the focus is returned while the WM_FOCUSCHANGE message with the is being processed.
   The window handle of the window receiving the focus is returned while the WM_FOCUSCHANGE (in Frame Controls) message with the is being processed.

If the WinQueryActiveWindow function is used during processing of this function:

   The window handle of the window being deactivated is returned while the WM_ACTIVATE message with the is being processed.
   The window handle of the window being activated is returned while the WM_ACTIVATE message with the is being processed.

Also, there is a short period during the time after the old active window has acted on the deactivation message and before the new active window has acted on the activation message when the WinQueryActiveWindow function returns NULLHANDLE.

This function should not be made unless it is directly or indirectly the result of operator input.

Even if FC_NOSETSELECTION is not specified, the WM_SETSELECTION is not sent to a frame window that is already selected. This can occur if the focus is being transferred from a parent to a child window and FC_NOLOSESELECTION was specified.

Example Code

This example sets the focus to a specified window.

#define INCL_WININPUT           /* Window Input Functions       */
#include <os2.h>

HWND  hwndNewFocus;     /* Handle of new focus window           */
BOOL  fSuccess;         /* success indicator                    */
MPARAM  mpParam1;       /* Parameter 1 (select boolean)         */

case WM_SETSELECTION:
     /* if window is being selected, change focus to the window */
     if (SHORTFROMMP(mpParam1))
        {
        if ((hwndNewFocus =
             WinQueryFocus(HWND_DESKTOP)) != 0L)
           fSuccess = WinFocusChange(HWND_DESKTOP, hwndNewFocus,
                                     0L);
        }

Definition

#define INCL_WININPUT /* Or use INCL_WIN, INCL_PM, Also in COMMON section */
#include <os2.h>

HWND     hwndDeskTop;    /*  Desktop-window handle. */
HWND     hwndNewFocus;   /*  Window handle to receive the focus. */
ULONG    flFocusChange;  /*  Focus changing indicators. */
BOOL     rc;             /*  Success indicator. */

rc = WinFocusChange(hwndDeskTop, hwndNewFocus,
       flFocusChange);

Related Functions

• WinEnablePhysInput
• WinGetKeyState
• WinGetPhysKeyState
• WinQueryFocus
• WinSetFocus
• WinSetKeyboardStateTable

Related Messages

• WM_ACTIVATE
• WM_FOCUSCHANGE
• WM_SETFOCUS
• WM_SETSELECTION