Programming Reference: ODwps

# Programming Reference

## ODwps

Class definition file | ODWPS.idl
Class C++ Binding | ODWPS.xh

Class hierarchy

    SOMObject
       WPObject
          WPFileSystem
             WPDataFile
                ODwps

Description

This class allows OpenDoc documents to operate as Workplace Shell objects. These actions include double-clicking to open a document.

For OpenDoc class objects not created from the Workplace Shell, the Workplace Shell needs a way to recognize the file as an OpenDoc file. The following methods can be used:

- If a file has an extended attribute type of "OpenDoc Document", the Workplace Shell recognizes it as an OpenDoc file and creates an object of OpenDoc class when needed.

- A file with an extension of .OD is recognized as an OpenDoc file.

Methods | There are no methods defined by the ODwps class.

Overridden methods

The following lists show the methods overridden by the ODwps class.

- WPObject methods

  The following list shows the methods that override the corresponding method from the WPObject class. These methods are overridden to modify the behavior defined by the ancestor class.

  - wpFormatDragItem (OS/2)
  - wpInitData (OS/2)
  - wpMenuItemSelected (OS/2)
  - wpModifyPopupMenu (OS/2)
  - wpOpen (OS/2)
  - wpSetupOnce (OS/2)
  - wpUnInitData (OS/2)
  - wpclsCreateDefaultTemplates (OS/2)
  - wpclsInitData (OS/2)
  - wpclsQueryDefaultHelp (OS/2)
  - wpclsQueryDefaultView (OS/2)
  - wpclsQueryIconData (OS/2)
  - wpclsQueryStyle (OS/2)
  - wpclsQueryTitle (OS/2)

- WPFileSystem methods

  The following list shows the methods that override the corresponding method from the WPFileSystem class. These methods are overridden to modify the behavior defined by the ancestor class.

  - wpclsQueryInstanceFilter (OS/2)
  - wpclsQueryInstanceType (OS/2)

- WPDataFile methods

  The following list shows the methods that override the corresponding method from the WPDataFile class. These methods are overridden to modify the behavior defined by the ancestor class.

  - wpAddFileTypePage (OS/2)

### wpAddFileTypePage (OS/2)

This instance method is called to remove the Type page from ODwps objects Settings Notebook. This method is an override of the corresponding method from the WPDataFile ancestor class.

Syntax

    ULONG wpAddFileTypePage (ODwps *somSelf,
                             HWND hwndNotebook)

Parameters

somSelf (ODwps *) - input

  Pointer to the object on which the method is being invoked. Points to an object of class ODwps.

hwndNotebook (HWND) - input

  Settings notebook handle.

Returns

rv (ULONG) - returns

  Page identifier.

  0 | Error occurred.
  PageId | Identifier for the inserted page.

Remarks

The TYPE of ODwps files is "OpenDoc Document" and cannot be changed by the end user.

Usage This method must be called only from within an override of the wpAddSettingsPages method.

### wpFormatDragItem (OS/2)

This instance method is called to allow the object to format its drag information when the user starts to drag it. This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    BOOL wpFormatDragItem (ODwps *somSelf,
                           PDRAGITEM pDragItem)

Parameters

somSelf (ODwps *) - input

  Pointer to the object on which the method is being invoked. Points to an object of class ODwps.

pDragItem (PDRAGITEM) - input

  Address of the drag item.

  This method adds the DRF_OPENDOCDOCUMENT constant to the valid formats for the hstrRMF field of the DRAGITEM structure.

Returns

rv (BOOL) - returns

  Success indicator.

  TRUE | Successful completion.
  FALSE | Error occurred.

Remarks

This method enables the direct manipulation of this object by initializing the DRAGITEM structure.

Usage

This method is called by the system when the user starts to drag the object.

How to Override

This method is generally overridden by classes that require special processing to initiate a drag or drop operation.

### wpInitData (OS/2)

This instance method is creates an object window for notifications.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    VOID wpInitData (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the object on which the method is being invoked. Points to an object of class ODwps.

Returns

None.

Remarks

This routine is called by the system when the object is created or when it is awakened from the dormant state so that it can initialize all of its instance variables to a known state. By default, memory allocated to instance variables is zero-filled. This method is called before the object's state is known, so it is important that the object does not try to process any other method while processing this method. If an object needs extra initialization that requires it to invoke other methods, this must be done from wpRestoreState.

When the object is first created, wpSetupOnce must be overridden to perform initialization that is required only once.

The parent method must be called before any processing is done by your overriding method.

Usage

This method is generally called only by the system when the object is awakened.

How to Override

Subclasses that override this method must call the parent method before any special processing.

### wpMenuItemSelected (OS/2)

This instance method processes an OpenDoc specific pop-up menu selection.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    wpMenuItemSelected (ODwps *somSelf,
                        HWND hwndFrame,
                        ULONG ulMenuId)

Parameters

somSelf (ODwps *) - input

  Pointer to the object on which the method is being invoked. Points to an object of class ODwps.

hwndFrame (HWND) - input

  Handle to the frame window.

ulMenuId (ULONG) - input

  ID of the selected pop-up menu.

  For a listing of WPMENUIDs, see the individual object classes.

Remarks

Class-specific menu IDs must be above WPMENUID_USER.

Usage

This method is generally called only by the system when a pop-up menu item is selected.

How to Override

This method must be overridden to process class-specific menu-item actions or to modify the behavior of a menu-item action provided by an ancestor class.

Related Methods

- wpFilterPopupMenu
- wpInsertPopupMenuItems
- wpMenuItemHelpSelected
- wpModifyPopupMenu

### wpModifyPopupMenu (OS/2)

This overridden instance method adds the OpenDoc views available for this object to the "Open" pop-up menu. This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    BOOL wpModifyPopupMenu (ODwps *somSelf,
                            HWND hwndMenu,
                            HWND hwndCnr,
                            ULONG ulPosition)

Parameters

somSelf (ODwps *) - input

  Pointer to the object on which the method is being invoked. Points to an object of class ODwps.

hwndMenu (HWND) - input

  Menu handle.

hwndCnr (HWND) - input

  Handle to container control window.

ulPosition (ULONG) - input

  Position to insert menu items.

Returns

rv (BOOL) - returns

  Success indicator.

  TRUE | Successful completion.
  FALSE | Error occurred.

Remarks

Class-specific menu IDs must be above WPMENUID_USER. This method must be called if the pop-up menu applies to objects of the same class.

Usage

This method is generally called by the system when a request to display the object's pop-up menu is made. This method is called following a call to the wpFilterPopupMenu method.

How to Override

his method must be overridden to add class-specific actions to the object's pop-up menu. Descendant classes can remove these actions by processing the wpFilterPopupMenu method.

Related Methods

- wpFilterPopupMenu
- wpInsertPopupMenuItems
- wpMenuItemHelpSelected
- wpMenuItemSelected

### wpOpen (OS/2)

This method invokes the DocShell program to open a document.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    HWND wpOpen (ODwps *somSelf,
                 HWND hwndCnr,
                 ULONG ulView,
                 ULONG ulparam)

Parameters

somSelf (ODwps *) - input

  Pointer to the object on which the method is being invoked. Points to an object of class ODwps.

hwndCnr (HWND) - input

  Handle of the container window.

  Handle of the container window from which the object is opened. This value can be set to NULLHANDLE.

ulView (ULONG) - input

  Specifies which view to open.

  OPEN_CONTENTS | Open contents view.
  OPEN_DEFAULT | Open default view (same as double-click).
  OPEN_DETAILS | Open details view.
  OPEN_HELP | Display HelpPanel.
  OPEN_PALETTE | Open palette object.
  OPEN_RUNNING | Execute object.
  OPEN_SETTINGS | Open Settings notebook.
  OPEN_TREE | Open tree view.
  OPEN_USER | Class-specific views have a greater value than this.

ulparam (ULONG) - input

  Open view parameter.

  This value is (reserved=NULL) for views supported by the WPObject class.

Returns

rv (HWND) - returns

  Success indicator.

  NULLHANDLE | Error occurred.
  Other | Handle to the window created or program executed.

Remarks

This method invokes `docshell.exe` against the name of the file containing the object.

Usage

This method can be called at any time to open a view of an object.

How to Override

This method must be overridden to process class-specific open views. This method can be overridden to modify the behavior defined by an ancestor class. When wpOpen is overridden to implement a user-defined view, it must call wpAddToObjUseList and wpRegisterView to ensure that the new view is registered by the Workplace Shell as a view of the object.

Related Methods

- wpClose

### wpSetupOnce (OS/2)

This instance method allows the newly created object to self-initialize.

This method is an override of the corresponding method from the WPObject ancestor class. Subclasses that override this method must call the parent before any special processing.

Syntax

    BOOL wpSetupOnce (ODwps *somSelf,
                      ISOString setupString)

Parameters

somSelf (ODwps *) - input

  A pointer to the object on which the method is being invoked. It points to an object of class ODwps.

setupString (ISOString) - input

  Class specific setup parameters for an object. This parameter contains a series of "keyname=value" pairs that change the behavior of the object. Multiple "keyname=value" pairs are separated by semicolons.

Returns

rv (BOOL) - returns

  Success indicator.

  TRUE | Successful completion.
  FALSE | Error occurred. If wpSetupOnce returns FALSE, the creation of the object is terminated.

Remarks

Each object class documents the keynames and the parameters it expects to see immediately following. All parameters have safe defaults. It is never required to pass parameters to an object.

For a listing of setup strings, see the individual object classes. This method adds the SENDER setup string. SEEDER is a fully-qualified file name. This allows an object to be created (for example, using the WinCreateObject function) with initial content. The content of the specified file name are written to the new object to "seed" it.

Note:

> This only has an effect when an ODwps class object is initially created, and only when it has no initial content; if an ODwps object is created by copying an existing one, this setup string has no effect.

This method is generally only called by the system during the processing of wpclsNew and WinCreateObject. For more information about WinCreateObject, see the Workplace Shell Programming Reference.

Related Methods

- wpSetup

### wpUnInitData (OS/2)

This instance method is called to allow the object to free allocated resources.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    VOID wpUnInitData (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the object on which the method is being invoked. Points to an object of class ODwps.

Returns

None.

Remarks

Subclasses that override this method must call the parent method after any special processing.

Usage

This method is generally called only by the system when the object is made dormant. The object is made dormant when it is destroyed or when there are no open views and the folder containing the object are not open.

How to Override

This method is overridden to de-allocate resources allocated during the processing of wpInitData.

The parent method must be called after you have completed your own processing.

Related Methods

- wpInitData

### wpclsCreateDefaultTemplates (OS/2)

This method is called to allow the specified class to create default stationery document instances of its class.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    BOOL wpclsCreateDefaultTemplates (ODwps *somSelf,
                                      WPFolder *Folder)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

Folder (WPFolder *) - input

  Pointer to the folder in which to create the stationery documents. Points to an object of class wpFolder.

Returns

rv (BOOL) - returns

  Flag indicating whether the class creates the stationery documents. This method does not create any default stationery documents in the OS/2 stationery document folder; therefore, this flag returns FALSE. Stationery documents can be made of ODwps objects that contain parts.

Usage

This method is called by the system when the class is registered. A class is registered by a call to the WinRegisterObjectClass function.

When the system calls this method, "Folder" is a pointer to the Stationery folder.

How to Override

This method must be overridden by classes that need to create default stationery document instances of their class.

### wpclsInitData (OS/2)

This method is called to allow the class object to initialize its instance data.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    VOID wpclsInitData (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

Returns

None.

Remarks

This method is called immediately after the class object is first awakened, and then sets the type and title strings from the MRI resource.

Usage

This method is generally called only by the system when the class object is awakened. The class object is awakened when the first instance of this class is awakened or newly created. It is made dormant again when the last instance of this class is made dormant.

How to Override

Any class that has metaclass instance variables must override this method so that those variables are all initially in a known state. It is essential to pass this method onto the parent class object before performing any override processing.

### wpclsQueryDefaultHelp (OS/2)

This method is called to allow the class object to specify its default help panel for its instances.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    ULONG wpclsQueryDefaultHelp (ODwps *somSelf,
                                 ODULong HelpPanelId,
                                 ISOString HelpLibrary)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

HelpPanelId (ODULong) - output

  Pointer to the help panel which provides help for this class.

HelpLibrary (ISOString) - output

  Pointer to the buffer in which to place the name of the Help library. This buffer must be at least the length of CCHMAXPATH bytes.

Returns

rv (ULONG) - returns

  Success indicator.

  TRUE | Successful completion.
  FALSE | Error occurred.

Remarks

This class method is called during the processing of wpQueryDefaultHelp.

Usage

This method can be called at any time to determine the default help panel for this object class.

How to Override

The default WPObject class does not process this method other than returning FALSE.

Related Methods

- wpDisplayHelp
- wpMenuItemHelpSelected
- wpQueryDefaultHelp
- wpSetDefaultHelp
- wpclsQueryDefaultHelp

### wpclsQueryDefaultView (OS/2)

This method is called to allow the class object to specify the default open view for its instance.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    ULONG wpclsQueryDefaultView (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

Returns

rv (ULONG) - returns

  Default open view.

  OPEN_DOCSHELL | Open document shell view.

Usage

This method can be called at any time to query the default open view for instances of this class.

How to Override

All classes must override this method, so that new objects in their class always has a sensible default view (device objects typically have a default view of OPEN_SETTINGS). The default view is used for both the conditional Open cascade menu and double-clicking on the object.

Related Methods

- wpQueryDefaultView
- wpclsQueryDefaultView
- wpSetDefaultView

### wpclsQueryIconData (OS/2)

This class method allows the system to build the class default icon for a given class.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    ULONG wpclsQueryIconData (ODwps *somSelf,
                              PICONINFO pIconInfo)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

pIconInfo (PICONINFO) - in/out

  Pointer to the default icon for OpenDoc objects.

  If this parameter is NULLHANDLE, the size must be returned correctly.

Returns

ulReturn (ULONG) - returns

  Buffer size or number of bytes required to hold the output data. Depending of the contents of the pIconInfo parameter, ulReturn contains one of the following:

  pIconInfo | ulReturn
  NULL | Number of bytes required to hold the output data for this class.
  Not NULL | Number of bytes written into the buffer.

  If ulReturn is 0, an error occurred.

Remarks

If NULL is passed for the pIconInfo parameter, the caller is asking for the size of the ICONINFO buffer needed for this class (usually for memory allocation purposes). Otherwise, the pIconInfo parameter can always be assumed to be large enough to accommodate the ICONINFO and the variable data for this class.

The ICONINFO structure allows default icon specification as:

- Block of binary data
- Icon file name
- Module name and resource identifier

However, only one mechanism need be supported by any given class. For example, a caller cannot request one of the formats by prefilling the ICONINFO structure.

Usage

This method can be called at any time. Typically, it would not be useful for another object class to make calls to this method.

How to Override

Workplace classes that wish to have a unique class default icon must override this method and fill out the appropriate fields within the ICONINFO structure. In addition, the correct size for the ICONINFO must always be returned.

Related Methods

- wpQueryIcon
- wpQueryIconData
- wpSetIcon
- wpSetIconData
- wpclsQueryIcon

### wpclsQueryInstanceFilter (OS/2)

This method is called to allow the class object to specify the file title filters for instances of its class.

This method is an override of the corresponding method from the WPFileSystem ancestor class.

Syntax

    ISOString wpclsQueryInstanceFilter (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

Returns

psuccess (ISOString) - returns

  Success indicator.

  NULL | Error occurred.
  Other | A pointer to a string containing the "*.OD" file title filter to support the recognition of &per.OD files as OpenDoc files.

Remarks

It is important that the values returned by this class method are restricted to class-specific filters. For example, returning a filter of "*.*" effectively makes the system unstable.

Usage

This method can be called at any time to determine which file title filters are used to determine instances of this class.

How to Override

This method must be overridden to designate file objects as instances of this class. The value returned by the override method replaces the current title filter string which is used to designate instances. If the parent method is called, it must be called first.

Related Methods

- wpclsQueryInstanceType

### wpclsQueryInstanceType (OS/2)

This method is called to allow the class object to specify the file types for instances of its class.

This method is an override of the corresponding method from the WPFileSystem ancestor class.

Syntax

    ISOString wpclsQueryInstanceType (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

Returns

psuccess (ISOString) - returns

  Success indicator.

  NULL | Error occurred.
  Other | A pointer to a string containing "OpenDoc Document" to support the recognition of files with this .TYPE extended attribute (EA) as OpenDoc files.

Remarks

Object classes should define their own special type strings.

Usage

This method can be called at any time to determine which file types are used to determine instances of this class.

How to Override

This method must be overridden to designate file objects as instances of this class. The value returned by the override method replaces the current type string which is used to designate instances. If the parent method is called, it must be called first.

Related Methods

- wpclsQueryInstanceFilter

### wpclsQueryStyle (OS/2)

This method is called to allow the class object to specify the default object class style for its instances.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    ULONG wpclsQueryStyle (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

Returns

ulReturn (ULONG) - returns

  Class style for this object.

  CLSSTYLE_DONTTEMPLATE | Do not allow a create-template operation on objects of this class.
  CLSSTYLE_NEVERCOPY | Do not allow a copy operation on objects of this class.
  CLSSTYLE_NEVERDELETE | Do not allow a delete operation on objects of this class.
  CLSSTYLE_NEVERDRAG | Do not allow a drag operation on objects of this class.
  CLSSTYLE_NEVERDROPON | Do not allow a drop operation on objects of this class.
  CLSSTYLE_NEVERLINK | Do not allow a create-shadow operation on objects of this class.
  CLSSTYLE_NEVERMOVE | Do not allow a move operation on objects of this class.
  CLSSTYLE_NEVERPRINT | Do not allow a print of this object.
  CLSSTYLE_NEVERRENAME | Do not allow the renaming of objects of this class.
  CLSSTYLE_NEVERSETTINGS | Do not allow a settings operation on objects of this class.
  CLSSTYLE_NEVERVISIBLE | Make instances of this class invisible.
  CLSSTYLE_NEVERPRINT | Make instance of this class never print.

Remarks

When an instance is initially created, it has the same object style (OBJSTYLE_xxx) flags as its class style (CLSSTYLE_xxx).

Usage

This method can be called at any time to determine the default style for instances of this class.

How to Override

This method must be overridden to modify the default object style for instances of this class.

### wpclsQueryTitle (OS/2)

This method is called to allow the class object to specify the default title for its instances.

This method is an override of the corresponding method from the WPObject ancestor class.

Syntax

    ISOString wpclsQueryTitle (ODwps *somSelf)

Parameters

somSelf (ODwps *) - input

  Pointer to the ODwps class object.

Returns

rv (ISOString) - returns

  Pointer to the national language version of the string "OpenDoc Document".

Remarks

The title is used for stationery documents and the default for new instances of this class.

Usage

This method can be called at any time to determine the default title for instances of this class.

How to Override

All classes must override this method, so that new objects and their classes must have a sensible default title.

Related Methods

- wpQueryTitle
- wpclsQueryTitle
- wpSetTitle

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]