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: @@
+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''.
-This function obtains the title under which a specified application is started, or is added to the Window List.
+== Syntax ==
-==Syntax==
+<pre>
- WinQuerySessionTitle(hab, ulSession, pszTitle, ulTitlelen);
+#define INCL_WINWORKPLACE
+#include <os2.h>
-==Parameters==
+PSZ     pAppName;  /*  Pointer to application name. */
-;hab (HAB) - input
+PSZ     pKeyName;  /*  Pointer to key name. */
-:Anchor-block handle.
+HWND    hwnd;      /*  Window handle of the window to restore. */
+BOOL    rc;        /*  Success indicator. */
-;ulSession (ULONG) - input
+rc = WinRestoreWindowPos(pAppName, pKeyName,
-:Session identity of application whose title is requested.
+       hwnd);
-:Use the session identity of the caller Other
+</pre>
-:Use the specified session identity.
-;pszTitle (PSZ) - output
+== Parameters ==
-:Window List title.
+;''pAppName'' ([[PSZ]]) - input: Pointer to application name.
-:This is the title of the application with a process identity, if the application is present in the Window List.
+:A pointer to a zero-terminated string which contains the application name.
-;ulTitlelen (ULONG) - input
+;''pKeyName'' ([[PSZ]]) - input: Pointer to key name.
-:Maximum length of data returnable, in bytes.
+:A pointer to a zero-terminated string which contains the key name.
-: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 (ULONG) - returns
-:Return code.
-:;Successful completion
-:;Other
-::Error occurred.
-==Remarks==
-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.
-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.)
+;''hwnd'' ([[HWND]]) - input: Window handle of the window to restore.
-==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.
-<pre>
-#define INCL_WINMESSAGEMGR
-#define INCL_WINWINDOWMGR
-#include <OS2.H>
-HAB  hab;
+== Returns ==
-HWND hwndFrame, hwndClient;
+;''rc'' ([[BOOL]]) - returns: Success indicator.
-CHAR szTitle[MAXNAMEL + 1];
+:TRUE: Successful completion.
+:FALSE: Error occurred.
-WinQuerySessionTitle(hab,
+== Remarks ==
-,
+This function will also restore presentation parameters which were saved by a previous call to [[WinStoreWindowPos]].
-                     szTitle,
-                     sizeof(szTitle));
-hwndFrame = WinQueryWindow(hwndClient,
+==Example Code==
-                           QW_PARENT); /* get handle of parent, */
+Declaration:
-                                          /* which is frame window. */
+<PRE>
-WinSetWindowText(hwndFrame, szTitle);
+#define INCL_WINWORKPLACE
-</pre>
-Definition
-<pre>
-#define INCL_WINSWITCHLIST /* Or use INCL_WIN, INCL_PM, */
 #include <os2.h>
-HAB      hab;         /*  Anchor-block handle. */
+PSZ     pAppName;  /*  Pointer to application name. */
-ULONG    ulSession;   /*  Session identity of application whose title is requested. */
+PSZ     pKeyName;  /*  Pointer to key name. */
-PSZ      pszTitle;    /*  Window List title. */
+HWND    hwnd;      /*  Window handle of the window to restore. */
-ULONG    ulTitlelen;  /*  Maximum length of data returnable, in bytes. */
+BOOL    rc;        /*  Success indicator. */
-ULONG    rc;          /*  Return code. */
-rc = WinQuerySessionTitle(hab, ulSession,
+rc = WinRestoreWindowPos(pAppName, pKeyName, hwnd);
-       pszTitle, ulTitlelen);
+</PRE>
-</pre>
-==Related Functions==
+== Related Functions ==
-* [[WinAddSwitchEntry]]
+* [[WinStoreWindowPos]]
-* [[WinChangeSwitchEntry]]
-* [[WinCreateSwitchEntry]]
-* [[WinQuerySessionTitle]]
-* [[WinQuerySwitchEntry]]
-* [[WinQuerySwitchHandle]]
-* [[WinQuerySwitchList]]
-* [[WinQueryTaskSizePos]]
-* [[WinQueryTaskTitle]]
-* [[WinRemoveSwitchEntry]]
-* [[WinSwitchToProgram]]
 [[Category:Win]]