A new object class in the Workplace Shell is typically created by taking an existing object class and subclassing it, introducing new data and methods, and modifying existing behaviors where required. The new object class is then registered with the Workplace Shell, and is available from that point on.
Registration
Once an object class has been defined, compiled and placed into a dynamic link library, it must be registered with Workplace Shell before it can be used. This may be accomplished in either of two ways:
An example of the WinRegisterObjectClass() function is given in Figure "Registering a Workplace Shell Object Class".
Figure "Registering a Workplace Shell Object Class" provides a very simple example; a useful technique for registering object classes is to build a simple program that reads a set of strings from an ASCII data file and uses these strings as parameters to the WinRegisterObjectClass() function. In this way, a generic object-registraion routine can be built and used for multiple object classes, without the need to modify and recompile source code.
Note that once an object class has been registered with the Workplace Shell, it is permanently available until it is explicitly deleted by deregistering it. See Deregistering an Object Class for information on deregistering an object class.
Class Data
Class data is owned by the object class rather than by an instance of that class. It is therefore available to all instances of the class, and must be initialized prior to instantiating any objects within the class.
For this reason, class data is initialized when the object classes are loaded from their DLLs, either during Workplace Shell initialization or dynamically during execution. Class data initialization is performed by the _wpclsInitData class method, which is called by the system when the class is loaded. If a new object class has class data that must be initialized, it should override the _wpclsInitData method and perform its class-specific processing.
An example of an overridden _wpclsInitData method from the password-protected folder example is shown in Figure "Initializing Class Data".
In the example shown in Figure "Initializing Class Data", a global variable hModule is used to contain the module handle for the DLL, which is required when loading Presentation Manager resources such as strings, pointers or dialogs. Since a global variable is used rather than a class data variable, the first statement in the overridden method, which obtains a handle to the class data, is not required and is therefore commented out.
Any class data items obtained or initialized by an object class from within the _wpclsInitData method should also be freed by the object class, by overriding the _wpclsUnInitData method. This method is invoked by the system when an object class is deregistered (see Deregistering an Object Class), or when the Workplace Shell process is terminated. An example of the _wpclsUnInitData method is shown in Figure "Freeing Class Data Items".
The example shown in Figure "Freeing Class Data Items" assumes that the module handle for the DLL has already been obtained and stored in the global variable hModule, as shown in Figure "Initializing Class Data".
Instantiation
Once an object class has been registered with the Workplace Shell, an instance of that class may be created; this is normally known as instantiation. This may be done in one of two ways. The simplest method is to open the Templates folder and drag the template for the object class to the required location. Alternatively, an object may be created from within an application, using the WinCreateObject() function, an example of which is given in Figure "Creating an Object".
Note that the pszParams parameter shown in Figure "Creating an Object" is used to contain a setup string, which can be used to pass one or more of a number of parameters to the object class. In the example, it is used only to set the icon for the object, but may also be used to specify other parameters for that instance of the class. The keywords and values supported by the WPObject class are documented in the IBM OS/2 Version 2.0 Presentation Manager Reference; other object classes may add their own keywords and values.
The final parameter contains one or more flags which determine the behavior of the WinCreateObject() call if the object being created clashes with an object that already exists with the specified name and in the specified location. Valid actions are for the call to fail, to update the existing object or to replace the existing object. These flags are documented in the IBM OS/2 Version 2.0 Presentation Manager Reference.
The setup string is passed as a parameter to the _wpSetup method, which is invoked when the object is instantiated. This method is defined by the WPObject class, and may be overridden by a new object class in order to check for its own keywords and take appropriate setup action.
The _wpSetup method accepts the setup string as a parameter, and may then parse the setup string, extract any class-specific data and perform appropriate processing on that data. However, since many of the keywords that may be specified in the setup string are defined by the WPObject class and are handled by the default _wpSetup method, the default processing must be carried out. In this particular case, the default processing may be carried out before or after the class-specific processing.
An example of an overridden _wpSetup method is shown in Figure "Object Setup"; this example shows the use of an additional parameter in the setup string (PASSWORD=) to set an initial password for a password-protected folder upon folder creation.
The setup string is parsed from within the object by calling the _wpScanSetupString method. Both of these methods, along with the keywords supported by the WPObject class, are described in the IBM OS/2 Version 2.0 Presentation Manager Reference.
After performing the class-specific processing in the _wpSetup method, an object class should invoke its parent class's _wpSetup method to perform the default processing for any other keywords in the setup string that are defined by the parent class.
Before the _wpSetup method is invoked, the system invokes the object's _wpInitData method, which allows an object to allocate resources and initialize its instance data. See Instance Data below for further details.
Note that unlike a Presentation Manager window, which exists only for the duration of an application's execution, an object remains in existence permanently unless explicitly deleted from the system.
Instance Data
When an object is created or awakened from a dormant state, the _wpInitData method is invoked by the system. This method allows an object to initialize its instance data to a known state. Operating system resources should be allocated at this stage, but Presentation Manager resources should not, since a view of the object is not yet being opened. The allocation of Presentation Manager resources is typically done during processing of the _wpOpen method (see Using an Object (Opening an Object)).
If an object has its own instance data, which must be initialized to a known state before processing may be carried out, the object should override the _wpInitData method in its class definition file, and include the initialization code. However, for any object class other than a base storage class, the default initialization processing must be carried out in addition to the class-specific processing. This allows the correct initialization of any instance data items defined by the parent class, and ensures that the new object class behaves in a manner consistent with its ancestors.
Figure "Initializing Instance Data" shows an overridden _wpInitData method, which initializes the password information for a password-protected folder.
Note that during processing of the _wpInitData method, the instance data of the object is not necessarily in a known state. The programmer must therefore take great care when carrying out any processing during the execution of this method, in order to avoid using data that may not yet have been initialized correctly. Failure to follow this guideline may cause unpredictable results for the object.