WinBeginEnumWindows

This function begins the enumeration process for all of the immediate child windows of a specified window.

Syntax

WinBeginEnumWindows(hwnd)

Parameters

hwnd (HWND) - input

Handle of the window whose child windows are to be enumerated.

HWND_DESKTOP

Enumerate all main windows

HWND_OBJECT

Enumerate all object windows

Other

Enumerate all immediate children of the specified window.

Returns

henumHenum (HENUM) - returns

Enumeration handle.

This is used in subsequent calls to the WinGetNextWindow function to return the immediate child-window handles in succession.

When the application has finished the enumeration, the enumeration handle must be destroyed with the WinEndEnumWindows call.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HWND (0x1001)

An invalid window handle was specified.

Remarks

This function remembers the window hierarchy at the time of invocation of the call. Thereafter the information is referenced by use of the henumHenum parameter and does not change during the enumeration by the WinGetNextWindow call. The windows are enumerated in the z-order at the time enumeration is begun, with the topmost child window enumerated first.

Only the immediate children of the specified window are enumerated; child windows of the child windows are excluded.

The enumerated windows are not locked by this function and can thus be destroyed between the time that it is called and the time that the WinGetNextWindow function is used to obtain the handle for the window.

Example Code

This example begins window enumeration of all main windows (i.e. all immediate children of the Desktop), after which WinGetNextWindow is called in a loop to enumerate all the children, until all children are found and the enumeration ends.

#define INCL_WINWINDOWMGR       /* Window Manager Functions     */
#include <os2.h>

HWND  hwndParent;       /* Handle of the window whose child windows
                           are to be enumerated                 */
HWND  hwndNext;         /* current enumeration handle           */
HENUM  henum;           /* enumeration handle                   */
BOOL  fSuccess;         /* success indicator                    */
SHORT sRetLen;          /* returned string length               */
SHORT sLength = 10;     /* string buffer length                 */
char  pchBuffer[10];    /* string buffer                        */

hwndParent = HWND_DESKTOP;

henum = WinBeginEnumWindows(hwndParent);

while ((hwndNext = WinGetNextWindow(henum)) != NULLHANDLE) {
  .
  .
  .
}

fSuccess = WinEndEnumWindows (henum);

Definition

#define INCL_WINWINDOWMGR /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HWND     hwnd;        /*  Handle of the window whose child windows are to be enumerated. */
HENUM    henumHenum;  /*  Enumeration handle. */

henumHenum = WinBeginEnumWindows(hwnd);

Related Functions

• WinBeginEnumWindows
• WinEndEnumWindows
• WinEnumDlgItem
• WinGetNextWindow
• WinIsChild
• WinMultWindowFromIDs
• WinQueryWindow
• WinSetOwner
• WinSetParent