Jump to content

WpRestoreState: Difference between revisions

From EDM2
Created page with "{{DISPLAYTITLE:wpRestoreState}} This instance method **restores the state of the object**, which was saved during the processing of the `wpSaveState` method . ==Syntax== _wpRestoreState(somSelf, ulReserved) ==Parameters== ;''somSelf'' (WPObject *) - input :Pointer to the object on which the method is being invoked . :Points to an object of class WPObject . ;''ulReserved'' (ULONG) - input :Reserved value; **must be 0** . ==Returns== ;''rc'' (BOOL) -..."
 
No edit summary
 
Line 1: Line 1:
{{DISPLAYTITLE:wpRestoreState}}
{{DISPLAYTITLE:wpRestoreState}}
This instance method **restores the state of the object**, which was saved during the processing of the `wpSaveState` method .
This method restores the state of the object which was saved during the processing of the [[wpSaveState]] method.


==Syntax==
==Syntax==
_wpRestoreState(somSelf, ulReserved)  
 
<PRE>
_wpRestoreState(somSelf, ulReserved);
</PRE>


==Parameters==
==Parameters==
;''somSelf'' ([[WPObject]] *) - input  
;''somSelf'' ([[WPObject]] *) - input
:Pointer to the object on which the method is being invoked .
:Pointer to the object on which the method is being invoked.
:Points to an object of class [[WPObject]] .
:Points to an object of class [[WPObject]].


;''ulReserved'' ([[ULONG]]) - input  
;''ulReserved'' ([[ULONG]]) - input
:Reserved value; **must be 0** .
:Reserved value; must be 0.


==Returns==
==Returns==
;''rc'' ([[BOOL]]) - returns  
;''rc'' ([[BOOL]]) - returns
:Success indicator .
:Success indicator.
::**TRUE: Successful completion** .
::TRUE: Successful completion.
::**FALSE: Error occurred** .
::FALSE: Error occurred.


==Remarks==
==Remarks==
This method restores the object's state that was saved during the processing of the `wpSaveState` method . When an object needs extra initialization that requires invoking other methods, this should be done from `wpRestoreState`. The `wpRestoreData`, `wpRestoreLong`, and `wpRestoreString` methods can only be called during the processing of `wpRestoreState` . Conversely, `wpSaveDeferred` cannot be called from within `wpRestoreState` .
This method restores the state of the object that was saved during the processing of the [[wpSaveState]] method.


==Usage==
==Usage==
This method is **generally called only by the system** while it is processing the `wpInitData` method .
This method is generally called only by the system while it is processing the [[wpInitData]] method.


==How to Override==
==How to Override==
This method **should be overridden by all classes that provide settings that can be saved** . Overriding the `wpSaveState` method is a **prerequisite** if persistent instance data is desired .
This method should be overridden by all classes that provide settings that can be saved. An override of the [[wpSaveState]] method is a prerequisite if persistent instance data is desired. Override processing of this method typically includes a series of calls to any combination of the restore state methods: [[wpRestoreData]], [[wpRestoreLong]], [[wpRestoreString]].
 
Override processing of `wpRestoreState` typically includes a series of calls to any combination of the following restore state methods :
*  `wpRestoreData`
*  `wpRestoreLong`
*  `wpRestoreString`


==Example Code==
==Example Code==
Declaration:
Declaration:
```
 
<PRE>
#define INCL_WINWORKPLACE
#define INCL_WINWORKPLACE
#include <os2.h>
#include <os2.h>


WPObject     *somSelf;     /* Pointer to the object on which the method is being invoked. */
WPObject     somSelf;     / Pointer to the object on which the method is being invoked. /
ULONG       ulReserved; /* Reserved value; must be 0. */
ULONG         ulReserved; / Reserved value; must be 0. /
BOOL         rc;         /* Success indicator. */
BOOL         rc;         / Success indicator. */


rc = _wpRestoreState(somSelf, ulReserved);
rc = _wpRestoreState(somSelf, ulReserved);
```
</PRE>
The following example demonstrates an override of `wpRestoreState` to restore data from the `OS2.INI` file. If restoration fails, it initializes a string to NULL and saves it .
 
In this example, wpRestoreState is overridden to restore data from the OS2.INI file.


```c
<PRE>
SOM_Scope void SOMLINK UserSetTitle(nbk *somSelf,
SOM_Scope void   SOMLINK UserSetTitle(nbk *somSelf,
PSZ pszNewTitle)
PSZ pszNewTitle)
{
{
nbkData *somThis = nbkGetData(somSelf);
nbkData *somThis = nbkGetData(somSelf);
nbkMethodDebug("nbk","UserSetTitle");
nbkMethodDebug("nbk","UserSetTitle");
strcpy ( _title, pszNewTitle );
strcpy ( _title, pszNewTitle );
}
}
/*
/*
* Override of wpRestoreState method to restore our data
 
* from the OS2.INI file.
    Override of wpRestoreState method to restore our data
*/
 
SOM_Scope BOOL SOMLINK wpRestoreState(nbk *somSelf,
    from the OS2.INI file.
ULONG ulReserved)
    */
{
    SOM_Scope BOOL   SOMLINK wpRestoreState(nbk   *somSelf,
BOOL fSuccess;
    ULONG ulReserved)
ULONG ulCount;
    {
CHAR buf;
    BOOL fSuccess;
nbkData *somThis = nbkGetData(somSelf);
    ULONG ulCount;
nbkMethodDebug("nbk","wpRestoreState");
    CHAR buf[40];
ulCount = 40; /* Length of data buffer */
 
fSuccess = _wpRestoreData ( somSelf /* Our pointer */
    nbkData *somThis = nbkGetData(somSelf);
, (PSZ) "nbk" /* Name of class */
    nbkMethodDebug("nbk","wpRestoreState");
, WPNBK_KEY /* Key of data requested */
 
, (PBYTE) &buf /* Where to put data */
    ulCount = 40;                                     /* Length of data buffer /
, &ulCount ); /* Length of data returned */
    fSuccess = _wpRestoreData ( somSelf                 / Our pointer /
if ( !fSuccess )
    , (PSZ) "nbk"               / Name of class /
{
    , WPNBK_KEY                 / Key of data requested /
/* first time the object is being restored */
    , (PBYTE) &buf             / Where to put data /
/* initialize string to NULL */
    , &ulCount   );             / Length of data returned */
strcpy ( buf, "" );
 
/* Save initial string to OS2.INI file */
    if ( !fSuccess )
_wpSaveData ( somSelf /* Pointer to ourself */
    {
, (PSZ) "nbk" /* Class name */
    /* first time the object is being restored */
, WPNBK_KEY /* Key of data */
 
, (PBYTE) buf /* Pointer to data */
    /* initialize string to NULL */
, 40 ); /* Length of data to write */
    strcpy ( buf, &quot;&quot; );
} /* endif */
 
_UserSetTitle ( somSelf, buf );
    /* Save initial string to OS2.INI file */
return (parent_wpRestoreState(somSelf,ulReserved));
    _wpSaveData ( somSelf                     /* Pointer to ourself */
}
                , (PSZ) &quot;nbk&quot;                  /* Class name */
```
                , WPNBK_KEY                     /* Key of data */
                , (PBYTE) buf                 /* Pointer to data */
                , 40 );                         /* Length of data to write */
 
    } /* endif */
 
    _UserSetTitle ( somSelf, buf );
 
    return (parent_wpRestoreState(somSelf,ulReserved));
    }
    </PRE>


==Related Methods==
==Related Methods==
*   [[wpRestoreData]]  
* [[wpRestoreData]]
*   [[wpRestoreLong]]  
* [[wpRestoreLong]]
*   [[wpRestoreString]]  
* [[wpRestoreState]]
*   [[wpSaveData]]  
* [[wpRestoreString]]
*   [[wpSaveDeferred]]  
* [[wpSaveData]]
*   [[wpSaveImmediate]]  
* [[wpSaveDeferred]]
*   [[wpSaveLong]]  
* [[wpSaveImmediate]]
*   [[wpSaveState]]  
* [[wpSaveLong]]
*   [[wpSaveString]]
* [[wpSaveState]]
*  [[wpInitData]]  
* [[wpSaveString]]


[[Category:Workplace Instance Methods]]
[[Category:Workplace Instance Methods]]

Latest revision as of 00:22, 2 September 2025

This method restores the state of the object which was saved during the processing of the wpSaveState method.

Syntax

_wpRestoreState(somSelf, ulReserved);

Parameters

somSelf (WPObject *) - input
Pointer to the object on which the method is being invoked.
Points to an object of class WPObject.
ulReserved (ULONG) - input
Reserved value; must be 0.

Returns

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

Remarks

This method restores the state of the object that was saved during the processing of the wpSaveState method.

Usage

This method is generally called only by the system while it is processing the wpInitData method.

How to Override

This method should be overridden by all classes that provide settings that can be saved. An override of the wpSaveState method is a prerequisite if persistent instance data is desired. Override processing of this method typically includes a series of calls to any combination of the restore state methods: wpRestoreData, wpRestoreLong, wpRestoreString.

Example Code

Declaration: 

#define INCL_WINWORKPLACE
#include <os2.h>

WPObject      somSelf;      / Pointer to the object on which the method is being invoked. /
ULONG         ulReserved;  / Reserved value; must be 0. /
BOOL          rc;          / Success indicator. */

rc = _wpRestoreState(somSelf, ulReserved);

In this example, wpRestoreState is overridden to restore data from the OS2.INI file. 

SOM_Scope void    SOMLINK UserSetTitle(nbk *somSelf,
PSZ pszNewTitle)
{
nbkData *somThis = nbkGetData(somSelf);
nbkMethodDebug("nbk","UserSetTitle");

strcpy ( _title, pszNewTitle );

}

/*

    Override of  wpRestoreState method to restore our data

    from the OS2.INI file.
    */
    SOM_Scope BOOL    SOMLINK wpRestoreState(nbk   *somSelf,
    ULONG ulReserved)
    {
    BOOL fSuccess;
    ULONG ulCount;
    CHAR buf[40];

    nbkData *somThis = nbkGetData(somSelf);
    nbkMethodDebug("nbk","wpRestoreState");

    ulCount = 40;                                      /* Length of data buffer /
    fSuccess = _wpRestoreData ( somSelf                  / Our pointer /
    , (PSZ) "nbk"                / Name of class /
    , WPNBK_KEY                  / Key of data requested /
    , (PBYTE) &buf             / Where to put data /
    , &ulCount   );             / Length of data returned */

    if ( !fSuccess )
    {
    /* first time the object is being restored */

     /* initialize string to NULL */
     strcpy ( buf, "" );

     /* Save initial string to OS2.INI file */
     _wpSaveData ( somSelf                      /* Pointer to ourself */
                 , (PSZ) "nbk"                   /* Class name */
                 , WPNBK_KEY                      /* Key of data */
                 , (PBYTE) buf                  /* Pointer to data */
                 , 40 );                          /* Length of data to write */

    } /* endif */

    _UserSetTitle ( somSelf, buf );

    return (parent_wpRestoreState(somSelf,ulReserved));
    }

Related Methods

Retrieved from "https://www.edm2.com/index.php?title=WpRestoreState&oldid=88743"