win12.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
WinCreateSwitchEntry (1.2)
Overview                                            Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WINSWITCHLIST
 
HSWITCH WinCreateSwitchEntry(hab, pswctl)
HAB hab;            /* anchor-block handle                             */
PSWCNTRL pswctl;    /* pointer to structure with new entry information */
 
The WinCreateSwitchEntry function creates an entry in the switch list (the
list of running programs displayed in the Task List).
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hab        Identifies the anchor block.
 
pswctl     Points to the SWCNTRL structure that contains information about
           the new switch-list entry. If the szSwtitle field in the SWCNTRL
           structure is NULL, the system uses the name under which the
           application was started.
 
           This applies only to the first call to this function for that
           program (since the program was started). Otherwise, a null entry
           name is invalid.
 
Return Value
 
The return value is a handle to the new switch-list entry, or NULL if an
error occurs.
 
Comments
 
The WinCreateSwitchEntry and WinAddSwitchEntry functions are similar. The
only difference between them is that WinCreateSwitchEntry takes an
anchor-block handle as the first parameter.
 
Leading and trailing blanks are removed from the title. The title is
truncated to 60 characters.
 
Example
 
This example calls WinQueryWindowProcess to get the current process
identifier (needed for the SWCNTRL structure). It then sets up the swctl
structure and calls WinCreateSwitchEntry to add the program's name to the
Task List.
 
The returned handle can be used in subsequent calls to WinChangeSwitchEntry
if the title needs to be changed.
 
The variables swctl, hswitch, and pid should be global if your application
will be calling the WinChangeSwitchEntry function to avoid having to set up
the structure again.
 
SWCNTRL swctl;
HSWITCH hswitch;
PID pid;
HAB hab;
 
hab = WinQueryAnchorBlock(hwndFrame);                /* gets anchor block */
WinQueryWindowProcess(hwndFrame, &pid, (PTID) NULL); /* gets process id   */
 
swctl.hwnd = hwndFrame;                        /* window handle      */
swctl.hwndIcon = (HWND) NULL;                  /* icon handle        */
swctl.hprog = (HPROGRAM) NULL;                 /* program handle     */
swctl.idProcess = pid;                         /* process identifier */
swctl.idSession = o;                           /* session identifier */
swctl.uchVisibility = SWL_VISIBLE;             /* visibility         */
swctl.fbJump = SWL_JUMPABLE;                   /* jump indicator     */
swctl.szSwtitle[0] = '\0';                     /* program name       */
 
hswitch = WinCreateSwitchEntry(hab, &swctl);
 
See Also
 
WinAddSwitchEntry, WinChangeSwitchEntry, WinRemoveSwitchEntry, SWCNTRL