View source for 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".
<PRE>
#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);
</PRE>

Definition:
<PRE>
#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);
</PRE>
== Related Functions ==
* WinAddSwitchEntry
* WinChangeSwitchEntry
* WinQuerySessionTitle
* WinQuerySwitchEntry
* WinQuerySwitchHandle
* WinQuerySwitchList
* WinQueryTaskSizePos
* WinQueryTaskTitle
* WinRemoveSwitchEntry
* WinSwitchToProgram

[[Category:Win]]