WinCreateSwitchEntry

This function adds an entry to the Window List.

Syntax

WinCreateSwitchEntry(hab, pswctlSwitchData)

Parameters

hab (HAB) - input

Anchor-block handle.

pswctlSwitchData (PSWCNTRL) - input

Switch data.

Contains information about the newly created Window List entry.

If the field of the SWCNTRL structure is NULL, the system uses the name under which the application is started. This only applies for OS/2 programs, and only for the first call to this function since the program started. Otherwise, a NULL entry name is invalid.

Leading and trailing blanks are removed from the title, which, if necessary, is also truncated to 60 characters.

If the field of the SWCNTRL structure is NULLHANDLE, the value used by the system when the program was loaded (if it has been loaded) is substituted.

If the field of the SWCNTRL structure is 0, the current process ID is used.

If the field of the SWCNTRL structure is 0, the current session ID is used.

Returns

hswitchSwitch (HSWITCH) - returns

Handle to the newly created Window List entry.

There is a system limit to the number of Window List entries. However, this is a large number (several hundred) and is unlikely to be reached in practice since other system limits, such as memory size, are likely to be reached first.

NULLHANDLE

Error occurred

Other

Handle to the newly created Window List entry.

Errors

Possible returns from WinGetLastError

PMERR_NO_SPACE (0x1201)

The limit on the number of Window List entries has been reached with WinAddSwitchEntry.

PMERR_INVALID_WINDOW (0x1206)

The window specified with a Window List call is not a valid frame window.

PMERR_INVALID_SESSION_ID (0x120B)

The specified session identifier is invalid. Either zero (for the application's own session) or a valid identifier must be specified.

Remarks

Both this function and the WinRemoveSwitchEntry function are not required if the main window is created with the frame creation flags FCF_TASKLIST or FCF_STANDARD, as these styles automatically update the Window List when the main window is created or destroyed, or when its title changes (see also WinAddSwitchEntry).

Example Code

This example creates a task-list entry for program name "Generic: NEW.APP".

#define INCL_WINSWITCHLIST      /* Window Switch List Functions */
#define INCL_WINWINDOWMGR       /* Window Manager Functions     */

#include <os2.h>

HSWITCH hswitch;        /* task-list entry handle               */
SWCNTRL swctl;          /* switch-control data                  */
PID pid;                /* process id                           */
HAB hab;                /* anchor-block handle                  */
HWND hwndFrame;         /* frame handle                         */

hab = WinQueryAnchorBlock(hwndFrame);      /* gets anchor block */
WinQueryWindowProcess(hwndFrame, &pid, NULL);/* gets process id */

/* initialize switch structure */
swctl.hwnd = hwndFrame;                   /* window handle      */
swctl.hwndIcon = NULLHANDLE;              /* icon handle        */
swctl.hprog = NULLHANDLE;                 /* program handle     */
swctl.idProcess = pid;                    /* process identifier */
swctl.idSession = 0;                      /* session identifier */
swctl.uchVisibility = SWL_VISIBLE;        /* visibility         */
swctl.fbJump = SWL_JUMPABLE;              /* jump indicator     */
strcpy(swctl.szSwtitle,"Generic: NEW.APP"); /* program name     */

hswitch = WinCreateSwitchEntry(hab, &swctl);

Definition:

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

HAB         hab;               /*  Anchor-block handle. */
PSWCNTRL    pswctlSwitchData;  /*  Switch data. */
HSWITCH     hswitchSwitch;     /*  Handle to the newly created Window List entry. */

hswitchSwitch = WinCreateSwitchEntry(hab, pswctlSwitchData);

Related Functions

• WinAddSwitchEntry
• WinChangeSwitchEntry
• WinQuerySessionTitle
• WinQuerySwitchEntry
• WinQuerySwitchHandle
• WinQuerySwitchList
• WinQueryTaskSizePos
• WinQueryTaskTitle
• WinRemoveSwitchEntry
• WinSwitchToProgram