WinSwitchToProgram: Difference between revisions
m →Returns |
No edit summary |
||
| Line 1: | Line 1: | ||
This function makes a specific program the active program. | |||
==Syntax== | |||
WinSwitchToProgram(hswitchSwHandle); | |||
=== Parameters === | === Parameters === | ||
; | |||
; hswitchSwHandle ([[HSWITCH]]) - input | |||
: Window List entry handle of program to be activated. | |||
:Task List handle returned by: | |||
:* [[WinAddSwitchEntry]] | :* [[WinAddSwitchEntry]] | ||
:* [[WinCreateSwitchEntry]] | :* [[WinCreateSwitchEntry]] | ||
| Line 9: | Line 15: | ||
=== Returns === | === 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++) === | === Define (C/C++) === | ||
| Line 23: | Line 42: | ||
=== Example Code === | === Example Code === | ||
Declaration: | |||
<pre> | |||
#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); | |||
</pre> | |||
Example: | |||
<pre> | |||
HSWITCH taskListHndl; | HSWITCH taskListHndl; | ||
ULONG rc; | ULONG rc; | ||
| Line 28: | Line 59: | ||
rc = WinSwitchToProgram(taskListHndl); | rc = WinSwitchToProgram(taskListHndl); | ||
... | ... | ||
</pre> | |||
This example calls WinSwitchToProgram to make a window the foreground process. | |||
<pre> | |||
#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); | |||
</pre> | |||
=== Related Functions === | === Related Functions === | ||
| Line 34: | Line 80: | ||
*[[WinQuerySwitchList]] | *[[WinQuerySwitchList]] | ||
*[[WinQuerySwitchEntry]] | *[[WinQuerySwitchEntry]] | ||
[[Category:Win]] | [[Category:Win]] | ||
Revision as of 19:03, 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
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);
Example:
HSWITCH taskListHndl; ULONG rc; ... rc = WinSwitchToProgram(taskListHndl); ...
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);