The Enhanced Workplace Shell Programming Interface in OS/2 Warp Version 3

by Cathy Bloomfield

In OS/2 Warp Version 3, tremendous improvements have been made to the programming interface of the Workplace Shell. For developers who want to implement their applications as part of the Workplace Shell, additional classes and methods are now available. And, for those of you who want to create a customized desktop configuration, we have published many new Win APIs, REXX APIs, and setup string keynames.

SOM Background Information

We used the IBM System Object Model (SOM) 2 when developing the OS/2 Warp Version 3 Workplace Shell. What this means to you is that all Workplace Shell objects are SOM objects and are instances of a class. You can think of an object as a data structure. The elements of that data structure define the object's state; they are known as instance variables. The set of functions that modify the elements of that data structure are called methods. The class defines the object's instance variables and the methods that the object supports.

SOM provides a language-neutral methodology for defining classes and methods. With previous versions of SOM, classes were defined using .CSC files. With SOM 2, Workplace Shell uses Interface Definition Language (.IDL) files to define its classes. Because SOM supports binary compatibility, applications written using previous versions of SOM will run on OS/2 Warp Version 3 without having to be recompiled. However, to take advantage of the new Workplace Shell methods, you will need to convert your class definition (.CSC) files to the new IDL format. The Developer's Toolkit for OS/2 Warp Version 3 (which is on your accompanying Developer Connection for OS/2 CD-ROM) provides the CTOI tool to help you convert .CSC files to .IDL files. Read "Using the SOM CTOI Tool" in The Developer Connection News, Volume 5 for more information.

Exciting News for Application Developers

By implementing your application as part of the Common User Access (CUA) conforming Workplace Shell, default characteristics (settings notebooks, context menus, drag and drop, and so forth) are inherited from ancestor classes. This means you end up writing less code. If you want to modify existing behaviors, you can override Workplace Shell methods or replace entire classes. Additionally, you can create new classes and methods to represent new behaviors for descendants of your class.

Class Hierarchy

Figure 1 shows you the new Workplace Shell class hierarchy for OS/2 Warp.

SOMObject

SOMClass

SOMClassMgr

SOMDServer

WPDServer

WPObject

WPFileSystem

WPDataFile

WPBitmap

WPIcon

WPMet

WPProgramFile

WPCommandFile

WPPif

WPPointer

WPFolder

WPDesktop

WPDrives

WPMinWinViewer

WPNetgrp

WPNetwork

WPServer

WPSharedDir

WPStartup

WPTemplates

WPAbstract

WPClock

WPCountry

WPDisk

WPKeyboard

WPLaunchPad

WPMouse

WPPalette

WPColorPalette

WPFontPalette

WPSchemePalette

WPPower

WPPrinter

WPRPrinter

WPProgram

WPShadow

WPNetLink

WPShredder

WPSound

WPSpecialNeeds

WPSystem

WPWinConfig

WPSpool

WPTransient

WPJob

WPPdr

WPPort

WPQdr

Figure 1. New class hierarchy

New Methods

We have published almost 200 additional methods for OS/2 Warp. The following describes a few of the new methods; see the Workplace Shell Programming Reference on your accompanying Developer Connection for OS/2 CD-ROM for details.

New Settings Notebook Methods

For each new settings notebook page, we created a method. This way you can decide whether or not you want to display that page. For example, overriding the wpAddServerPage method and returning SETTINGS_PAGE_REMOVED removes the Network Status page from the Settings notebook of all servers.

New Save/Restore State Methods

The Workplace Shell creates a new object by calling wpclsNew, and initializes that object by calling wpSetup and wpRestoreState. You can override the wpSetup and wpRestoreState methods to initialize your own object's settings. However, the wpclsMakeAwake method wakes up a dormant object and invokes your wpSetup override. So, to perform initialization only when an object is created, you can override the new wpSetupOnce method, which calls wpSetup. To receive notification when the object is completely initialized, you can override the new method wpObjectReady. You also can query the state of an object at any time to see if it's initialized by calling wpIsObjectInitialized.

New Object Usage Methods

Object Usage methods exist to keep track of an object's resources, including open views of an object. For example, you can specify OPEN_RUNNING when calling wpFindViewItem to find out if a program object is running. If an object does not exist in any open views, and its lock count is 0, it can go into the dormant state and the Workplace Shell calls wpFree on the object. The wpFree method can be overridden to clean up any resources you many have allocated when then object was initialized. If you do not want your object to be made dormant, you can increase its lock count by calling the new method wpLockObject. To query if an object is locked, wpIsLocked can be called.

New Pop-up Menu Methods

Pop-up menus consist of menu items which describe actions that can be performed on an object. New CTXT_ flags have been added so that menu items can be removed by overriding the wpFilterPopupMenu method. And, the Workplace shell calls the new wpDisplayMenu method to display every object's pop-up menu.

New Set and Query Methods

We've added new methods to set and query object information, such as the attributes of a file and the ID of an object. You can get a pointer to the object's MINIRECORDCORE structure to find the object's icon position and handle by calling the wpQueryRecordCore method. There are even set and query methods to customize your LaunchPad and your printer.

Customizing Your Desktop

A Presentation Manager (PM) program creates an object by calling WinCreateObject. To change an existing object, WinSetObjectData is called. Or, you can create a REXX command file and call the SysCreateObject or SysSetObjectData APIs. A Workplace Shell/SOM-enabled application can invoke the wpclsNew method to create an object, and the wpSetup method to update an object. In all of these cases, the Workplace Shell calls the wpSetup method, which accepts a setup string as a parameter. The setup string consists of keyname=value strings, each separated by a semicolon. For example, you can change an object's open behavior and default open view by specifying a setup string of CCVIEW=YES;DEFAULTVIEW=DETAILS. Then, double-clicking mouse button one on that object will display a concurrent details view, instead of displaying an existing view. Many new setup string keynames in OS/2 Warp are available that help you customize your desktop.

The following is an example REXX command file (MYTOYS.CMD) that creates a folder called Toys in the Productivity folder. Toys always maintains its sort order and is opened in icon view at a specified location after it's created. The background of Toys is the tiled OS/2 logo image.

Another REXX command file (ADDTOLP.CMD) will add this folder to the LaunchPad. When creating an object, it's a good idea to assign your object an ID. You can always update the object later if you know its ID. For an example of system-supplied objects and their corresponding IDs, see the \OS2\INI.RC file.

MYTOYS.CMD

/* */
call RxFuncAdd 'SysLoadFuncs','RexxUtil','SysLoadFuncs'
call SysLoadFuncs

classname = "WPFolder"
location = "<WP_TOOLS>"
title = "Toys"

setup = "OBJECTID=<MY_TOYS>;",
        !! "ALWAYSSORT=YES;",
        !! "ICONVIEWPOS=5 20 75 20;",
        !! "OPEN=ICON;",
        !! "BACKGROUND=C:\OS2\BITMAP\OS2LOGO.BMP,T,,I"

result = SysCreateObject(classname, title, location, setup)

return

ADDTOLP.CMD

/* */
call RxFuncAdd 'SysLoadFuncs','RexxUtil','SysLoadFuncs'
call SysLoadFuncs

result = SysSetObjectData("<WP_LAUNCHPAD>","FPOBJECTS=<MY_TOYS>")

return

In addition, new Workplace Shell-related Win APIs and equivalent REXX APIs are available as the following table shows:

New WIN APIs in OS/2 Warp Version 3	The equivalent REXX APIs
WinCopyObject	SysCopyObject
WinCreateShadow	SysCreateShadow
WinIsSOMDDReady
WinIsWPDServerReady
WinMoveObject	SysMoveObject
WinOpenObject	SysOpenObject
WinQueryActiveDesktopPathname
WinQueryObjectPath
WinRestartSOMDD
WinRestartWPDServer
WinSaveObject	SysSaveObject

The following CONFIG.SYS settings are also new:

Start the Workplace Shell DSOM Server:

SET WPDSERVERSTART=ON

Display the SOMDD window:

SET SOMDD.DISPLAY=ON

And That's Not All

As you have seen, the Workplace Shell's programming interface for OS/2 Warp Version 3 has been greatly enhanced. But this article just mentioned a few of these enhancements. Check out the Workplace Shell Programming Reference (on your accompanying Developer Connection for OS/2 CD-ROM) for all the details. Now is the time to program to the Workplace Shell. Imagine the possibilities!

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation