WinRestoreWindowPos: Difference between revisions

Latest revision as of 16:14, 15 May 2025

The WinRestoreWindowPos function will restore the size and position of the window specified by hwnd to the state it was in when WinStoreWindowPos was last called with the same pAppName and pKeyName.

Syntax

#define INCL_WINWORKPLACE
#include <os2.h>

PSZ     pAppName;  /*  Pointer to application name. */
PSZ     pKeyName;  /*  Pointer to key name. */
HWND    hwnd;      /*  Window handle of the window to restore. */
BOOL    rc;        /*  Success indicator. */

rc = WinRestoreWindowPos(pAppName, pKeyName,
       hwnd);

Parameters

pAppName (PSZ) - input: Pointer to application name.; A pointer to a zero-terminated string which contains the application name.

pKeyName (PSZ) - input: Pointer to key name.; A pointer to a zero-terminated string which contains the key name.

hwnd (HWND) - input: Window handle of the window to restore.

Returns

rc (BOOL) - returns: Success indicator.; TRUE: Successful completion.; FALSE: Error occurred.

Remarks

This function will also restore presentation parameters which were saved by a previous call to WinStoreWindowPos.

Example Code

Declaration:

#define INCL_WINWORKPLACE
#include <os2.h>

PSZ     pAppName;  /*  Pointer to application name. */
PSZ     pKeyName;  /*  Pointer to key name. */
HWND    hwnd;      /*  Window handle of the window to restore. */
BOOL    rc;        /*  Success indicator. */

rc = WinRestoreWindowPos(pAppName, pKeyName, hwnd);

Related Functions

WinStoreWindowPos

@@ Line 1: / Line 1: @@
-This function obtains the title under which a specified application is started, or is added to the Window List.
+The WinRestoreWindowPos function will restore the size and position of the window specified by ''hwnd'' to the state it was in when [[WinStoreWindowPos]] was last called with the same ''pAppName'' and ''pKeyName''.
-==Syntax==
+== Syntax ==
- WinQuerySessionTitle(hab, ulSession, pszTitle, ulTitlelen)
+<pre>
+#define INCL_WINWORKPLACE
+#include <os2.h>
-==Parameters==
+PSZ     pAppName;  /*  Pointer to application name. */
-;hab (HAB) - input:Anchor-block handle.
+PSZ     pKeyName;  /*  Pointer to key name. */
-;ulSession (ULONG) - input:Session identity of application whose title is requested.
+HWND    hwnd;      /*  Window handle of the window to restore. */
-:Use the session identity of the caller Other
+BOOL    rc;        /*  Success indicator. */
-:Use the specified session identity.
-;pszTitle (PSZ) - output:Window List title.
-:This is the title of the application with a process identity, if the application is present in the Window List.
-;ulTitlelen (ULONG) - input:Maximum length of data returnable, in bytes.
-:If the pszTitle parameter is longer than this value, the title is truncated. However, the terminating null character is left at the end of the string. The maximum number of title characters copied is (ulTitlelen-1).
-==Returns==
+rc = WinRestoreWindowPos(pAppName, pKeyName,
-;rc (ULONG) - returns:Return code.
+       hwnd);
-:;Successful completion
+</pre>
-:;Other
-::Error occurred.
-==Remarks==
+== Parameters ==
-This function is useful when an application uses the same name in its window title (and in its entry in the Window List) as the end user invokes to start the application. This provides a visual link for the end user.
+;''pAppName'' ([[PSZ]]) - input: Pointer to application name.
+:A pointer to a zero-terminated string which contains the application name.
-If this function is used after a Window List entry is created for the application, the title in the Window List entry is obtained. (See also WinQueryTaskTitle.)
+;''pKeyName'' ([[PSZ]]) - input: Pointer to key name.
+:A pointer to a zero-terminated string which contains the key name.
+;''hwnd'' ([[HWND]]) - input: Window handle of the window to restore.
+== Returns ==
+;''rc'' ([[BOOL]]) - returns: Success indicator.
+:TRUE: Successful completion.
+:FALSE: Error occurred.
+== Remarks ==
+This function will also restore presentation parameters which were saved by a previous call to [[WinStoreWindowPos]].
 ==Example Code==
-This example calls WinQuerySessionTitle to retrieve the application's title, and then sets the title bar of the frame window to that title.
+Declaration:
-<pre>
+<PRE>
-#define INCL_WINMESSAGEMGR
+#define INCL_WINWORKPLACE
-#define INCL_WINWINDOWMGR
 #include <os2.h>
-HAB  hab;
+PSZ     pAppName;  /*  Pointer to application name. */
-HWND hwndFrame, hwndClient;
+PSZ     pKeyName;  /*  Pointer to key name. */
-CHAR szTitle[MAXNAMEL + 1];
+HWND    hwnd;      /*  Window handle of the window to restore. */
+BOOL    rc;        /*  Success indicator. */
-WinQuerySessionTitle(hab,
-,
-                     szTitle,
-                     sizeof(szTitle));
-hwndFrame = WinQueryWindow(hwndClient,
+rc = WinRestoreWindowPos(pAppName, pKeyName, hwnd);
-                           QW_PARENT); /* get handle of parent, */
+</PRE>
-                                          /* which is frame window. */
-WinSetWindowText(hwndFrame, szTitle);
-</pre>
-==Related Functions==
+== Related Functions ==
-* [[WinAddSwitchEntry]]
+* [[WinStoreWindowPos]]
-* [[WinChangeSwitchEntry]]
-* [[WinCreateSwitchEntry]]
-* [[WinQuerySessionTitle]]
-* [[WinQuerySwitchEntry]]
-* [[WinQuerySwitchHandle]]
-* [[WinQuerySwitchList]]
-* [[WinQueryTaskSizePos]]
-* [[WinQueryTaskTitle]]
-* [[WinRemoveSwitchEntry]]
-* [[WinSwitchToProgram]]
 [[Category:Win]]