WinSwitchToProgram: Difference between revisions

Latest revision as of 19:04, 14 May 2025

This function makes a specific program the active program.

Syntax

WinSwitchToProgram(hswitchSwHandle);

Parameters

hswitchSwHandle (HSWITCH) - input

Window List entry handle of program to be activated.

Task List handle returned by:

Returns

rc (ULONG) - returns: Return code.; Successful completion.

INV_SWITCH_LIST_ENTRY_HANDLE: Invalid Window List entry handle of the program to be activated.
NOT_PERMITTED_TO_CAUSE_SWITCH: Requesting program is not the current foreground process.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_SWITCH_HANDLE (0x1202): An invalid Window List entry handle was specified.

Remarks

Use of this function causes another window (and its related windows) of a PM session to appear on the front of the screen, or a switch to another session in the case of a non-PM program. In either case, the keyboard (and mouse for the non-PM case) input is directed to the new program.

Notes

Use this function, from a foreground session, to force another session to the foreground. A nonforeground session cannot make itself a foreground session.

Define (C/C++)

INCL_WINSWITCHLIST or INCL_PM or INCL_WIN

Calling Convention

Cdecl32

Example Code

Declaration:

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

HSWITCH    hswitchSwHandle;  /*  Window List entry handle of program to be activated. */
ULONG      rc;               /*  Return code. */

rc = WinSwitchToProgram(hswitchSwHandle);

This example calls WinSwitchToProgram to make a window the foreground process.

#define INCL_WINSWITCHLIST
#include <OS2.H>

HAB     hab;
HWND    hwndFrame;
HSWITCH hswitch;

hswitch = WinQuerySwitchHandle(hwndFrame, 0);

/* Switch to the window defined by hwndFrame */
WinSwitchToProgram(hswitch);

Related Functions

@@ Line 1: / Line 1: @@
-== WinSwitchToProgram ==
+This function makes a specific program the active program.
-; WinSwitchToProgram(taskListHndl) : Changes active task.
+==Syntax==
+ WinSwitchToProgram(hswitchSwHandle);
 === Parameters ===
-; taskListHndl - [[OS2_API:DataType:HSWITCH|HSWITCH]] - input : Task List handle returned by:
-* [[OS2_API:WinAddSwitchEntry|WinAddSwitchEntry]]
-* [[OS2_API:WinCreateSwitchEntry|WinCreateSwitchEntry]]
-* [[OS2_API:WinQuerySwitchList|WinQuerySwitchList]]
-* [[OS2_API:WinQuerySwitchEntry|WinQuerySwitchEntry]]
-=== Constants ===
+; hswitchSwHandle ([[HSWITCH]]) - input
+: Window List entry handle of program to be activated.
+:Task List handle returned by:
+:* [[WinAddSwitchEntry]]
+:* [[WinCreateSwitchEntry]]
+:* [[WinQuerySwitchList]]
+:* [[WinQuerySwitchEntry]]
 === Returns ===
-Returns [[OS2_API:DataType:ULONG|ULONG]]:
+;rc (ULONG) - returns
-* 0 Successful.
+:Return code.
-* Anything else - unsuccessful.
+:Successful completion.
+:;INV_SWITCH_LIST_ENTRY_HANDLE
+::Invalid Window List entry handle of the program to be activated.
+:;NOT_PERMITTED_TO_CAUSE_SWITCH
+::Requesting program is not the current foreground process.
+== Errors==
+Possible returns from WinGetLastError
+;PMERR_INVALID_SWITCH_HANDLE (0x1202)
+:An invalid Window List entry handle was specified.
-Possible returns from [[OS2_API:WinGetLastError|WinGetLastError]]:
+==Remarks==
-* [[OS2_API:PMI:error#PMERR_INVALID_SWITCH_HANDLE|PMERR_INVALID_SWITCH_HANDLE]]
+Use of this function causes another window (and its related windows) of a PM session to appear on the front of the screen, or a switch to another session in the case of a non-PM program. In either case, the keyboard (and mouse for the non-PM case) input is directed to the new program.
-=== Module ===
+=== Notes ===
+Use this function, from a foreground session, to force another session to the foreground. A nonforeground session cannot make itself a foreground session.
 === Define (C/C++) ===
 INCL_WINSWITCHLIST or INCL_PM or INCL_WIN
-=== Export name/Ordinal ===
+=== Calling Convention ===
-=== Calling conversion ===
 [[Cdecl32]]
 === Example Code ===
- [[OS2 API:DataType:HSWITCH|HSWITCH]] taskListHndl;
+Declaration:
- [[OS2 API:DataType:ULONG|ULONG]]     rc;
+<pre>
- ...
+#define INCL_WINSWITCHLIST /* Or use INCL_WIN, INCL_PM, */
- rc = WinSwitchToProgram(taskListHndl);
+#include <os2.h>
- ...
-=== Related Functions ===
+HSWITCH    hswitchSwHandle;  /*  Window List entry handle of program to be activated. */
-[[OS2 API:WinAddSwitchEntry|WinAddSwitchEntry]] [[OS2_API:WinCreateSwitchEntry|WinCreateSwitchEntry]] [[OS2_API:WinQuerySwitchList|WinQuerySwitchList]]
+ULONG      rc;               /*  Return code. */
-[[OS2_API:WinQuerySwitchEntry|WinQuerySwitchEntry]]
-=== Notes ===
+rc = WinSwitchToProgram(hswitchSwHandle);
-Use this function, from a foreground session, to force another session to the foreground.  A nonforeground session cannot make itself a foreground session.
+</pre>
+This example calls WinSwitchToProgram to make a window the foreground process.
+<pre>
+#define INCL_WINSWITCHLIST
+#include <OS2.H>
-=== OS Version Introduced ===
+HAB     hab;
+HWND    hwndFrame;
+HSWITCH hswitch;
+hswitch = WinQuerySwitchHandle(hwndFrame, 0);
-[[OS2_API | Back to OS/2 API]]
+/* Switch to the window defined by hwndFrame */
+WinSwitchToProgram(hswitch);
+</pre>
+=== Related Functions ===
+*[[WinAddSwitchEntry]]
+*[[WinCreateSwitchEntry]]
+*[[WinQuerySwitchList]]
+*[[WinQuerySwitchEntry]]
-[[Category:The OS/2 API Project]]
+[[Category:Win]]