Programming Guide

IBM OpenDoc
Programming Guide

Version 1.1

11 Nov 1996

Table of Contents

About Component Integration Laboratories

About This Book

Who Should Read This Book

How This Book Is Organized

Documentation Conventions

Note on Code Presentation

Related Publications

Introduction

Overview of OpenDoc

Documents, Parts, and Embedding

Parts and the User

Other Software Components

Frames and Embedding

Part Data Types

Embedding Compared to Incorporating

Changing Part Editors

Displaying Parts

Drawing Structures

Document Windows and Part Windows

Frame Negotiation

The Document Shell and the Dispatcher

Handling User Commands

Activation and Selection

Storage and Data Transfer

Document Drafts

Scripting Support

Settings Extension

Other Extensions

Cross-Platform Consistency and CI Labs

Development Overview

The OpenDoc Class Library

A Set of Classes, Not a Framework

Classes You Must Subclass

Classes for Extending OpenDoc

Classes You Can Use

Abstract Superclasses

Implemented Classes

Service Classes

Writing OpenDoc Software

Developing with SOM and IDL

OpenDoc Protocols

Participatation in Protocols

Overriding the Methods of ODPart

Development Scenarios

Writing an Editor for NonContainer Parts

Writing an Editor for Container Parts

Converting a Conventional Application to a Part Editor

Writing Other Types of Component Software

Frames and Facets

Frame and Facet Hierarchies

Frames and Parts

Working with Your Display Frames and Facets

Responding to Reconnected and Closed Display Frames

Responding to Added or Removed Facets

Resizing a Display Frame

Requesting an Additional Display Frame

Responding to an Added Display Frame

Removing a Display Frame

Responding to a Removed Display Frame

Grouping Display Frames

Synchronizing Display Frames

Adopting Container Properties

Frame Negotiation

Working with Embedded Frames and Facets

Providing an Embedded-Frames Iterator

Creating a New Embedded Frame

Adding an Embedded Frame on Request

Resizing an Embedded Frame

Removing an Embedded Frame

Reconnecting and Releasing Embedded Frames

Removing a Facet

Creating Frame Groups

Synchronizing Embedded Frames

Transmitting Your Container Properties to Embedded Parts

Platform Canvases

Canvas Features

Adding and Removing Canvases

Transforms and Shapes

Transforms and Coordinate Spaces

Frame Coordinate Space

Content Coordinate Space

Converting to the Coordinates of a Containing Part

Canvas Coordinates and Window Coordinates

Coordinate Bias and Platform-Normal Coordinates

Using Transforms

Scrolling Your Part in a Frame

Transforming the Image of Your Part

Positioning an Embedded Frame

Transforming the Image of an Embedded Part

Using Drawing-Related Shapes

Managing Facet Clip Shapes

Maintaining a List of Embedded Facets

Calculating the Clip Shapes

Embedded-Part Responsibilities

Managing the Active Frame Border

Defining General Display Characteristics

Part Info Data Field

Draw Method of Your Part Editor

Invalidating and Validating your Content

Drawing on Opening a Window

Drawing When a Window Is Scrolled

Redrawing a Frame When It Changes

Drawing When a Part Is Scrolled

Drawing Selections

Drawing with Scroll Bars

Placing Scroll Bars within Your Frame

Placing Scroll Bars in a Separate Frame

Drawing Directly to the Window

Asynchronous Drawing

Offscreen Drawing

Drawing to an Offscreen Canvas

Updating an Offscreen Canvas

Drawing with Multiple Frames or Facets

Using Multiple Frames

Using Multiple Facets

Root-Part Responsibilities

Choosing a Frame for Printing

Printing the Document

Embedded-Part Responsibilities

Engaging in Frame Negotiation

Responding to GetPrintResolution

Issues for All Parts

User Events

User Event Handling

Types of User Events

Mouse Events in Embedded Frames

Keystroke Events

Activate Events

Propagating Events

HandleEvent Method of Your Part Editor

Mouse Events, Activation, and Dragging

How Part Activation Occurs

Handling Mouse Events

Handling Activate Events

Arbitrating Focus Transfers

Requesting Focuses

Relinquishing Focuses

Transferring Focus without Negotiation

Recording Focus Transfers

Frame Activation

Window Activation

On Closing and Reopening Documents

Display-Related Events

Invalidating and Updating

Event-Handling in Scroll Bars within Your Frame

Event Handling in Scroll Bars in Separate Frames

Mouse-Down Tracking and Selection

Mouse-Up Tracking

Mouse-Up Feedback while Drawing

Windows and Menus

Creating and Using Windows

Window State Object

Creating and Registering a Window

Opening a Window

Closing a Window

Storing and Retrieving Window Characteristics

Open Method of Your Part Editor

Handling Window Events

Modal Dialog Boxes

Acquiring and Relinquishing the Modal Focus

Handling a Simple Modal Dialog Box

Handling a Movable Modal Dialog Box

Modeless Dialog Boxes

Showing the Dialog Box

Closing the Dialog Box

Hiding a Dialog Box when Deactivating a Frame

Design Issues for Controls

Handling Events in Controls

Sharing Palettes and Utility Windows

Using a Tool Palette to Embed Parts

Setting Up Menus

Base Pop-Up Menu

Adding Part Menus to the Base Menu Bar

Obtaining the Menu Focus

Enabling and Disabling Menus and Commands

Menus and Read-Only Documents

Menus and the Root Part

Page Setup and Print document

Cut, Copy, and Paste

Delete selection

Selection properties

OpenDoc information

Help Menu with Part Help

MyPart help index

MyPart information

Accelerator Table Sharing

Multilevel, Cross-Document Capability

Implementing Undo

WriteActionState and ReadActionState

Adding an Action to the Undo History

Adding Multistage Actions

Menu Strings and Two-Stage Actions

Creating an Action Subhistory

Undoing an Action

Redoing an Action

Clearing the Action History

Undo and Embedded Frames

OpenDoc Storage System

Storage Units, Properties, and Values

Storage-Unit Organization

Standard Properties

Creating Properties and Values

Focusing a Storage Unit

Manipulating the Data in a Value

Iterating through a Storage Unit

Removing Properties and Values

Storage-Unit IDs

Persistent References

Main and Auxiliary Storage Units

Prefocused Access with Storage-Unit Views

Documents, Drafts, and Parts

Storage Model for Parts

What a Draft Contains

Info Properties

Container Properties

Creating a New Document

Reading and Writing Your Part

Initializing and Reading a Part from Storage

The somInit Method

The InitPart Method

The InitPartFromStorage Method

Writing a Part to Storage

The Externalize Method

The ExternalizeKinds Method

Creating Additional Storage Units

Storing and Retrieving Display Frames

Storing and Retrieving Embedded Frames

Reading and Writing Part Info Data

Changing Your Part's Content

Adding an Embedded Part

Removing an Embedded Part

Making Content Changes Known

Closing Your Part

The ReleaseAll Method

The somUninit Method

Data Transfer

Storage Issues for Data Transfer

Data Configuration

Link Specification

Frame Shape or Frame Annotation

Cloning-Kind Annotation

Mouse-Down Offset Annotation

Drag and Drop Annotations (For OS/2)

Clonable Data Annotation Prefix

Cloning Sequence

Scope of a Clone Operation

CloneInto Method of Your Part Editor

ClonePartInfo Method of Your Part Editor

Writing a Promise

Getting Data from a Value Containing a Promise

Fulfilling a Promise

Handling Cut Data

Handling Pasted or Dropped Data

Default Conventions

Handling the Paste As Dialog Box

Writing to a Data-Transfer Object

Writing Intrinsic Content

Writing a Single Embedded Frame

Reading from a Data-Transfer Object

Incorporating Intrinsic Content

Embedding a Single Part

Clipboard Transfer

Clipboard Concepts

Acquiring and Relinquishing the Clipboard Focus

Clipboard Update ID

Removing a Link Specification from the Clipboard

Undo for Clipboard

Copying or Cutting to the Clipboard

Pasting from the Clipboard

Drag and Drop Concepts

User Interaction

Droppable Frames

Undo for Drag and Drop

Initiating a Drag

Operations While a Drag Is in Progress

Entering a Part's Facet

Within a Part's Facet

Leaving a Part's Facet

Drag Attributes and the Drop Method

Accepting Non-OpenDoc Data

Completion of StartDrag

Automatic and Manual Propagation of Updates

Automatic and Manual Updating of Link Source Content

Frame Link Status

Content Changes in Embedded Frames

Linking and Undo

Manipulating Links

Creating a Link at the Destination

Creating a Link at the Source

Updating a Link at the Destination

Updating a Link at the Source

Writing Linked Content to Storage

Reading Linked Content from Storage

Revealing the Source of a Link

Editing a Link Destination

Breaking and Cutting Links

Transfer Rules for Links and Link Sources

Direct Scripting

Direct Scripting

Considerations for the Application Developer

Lotus Script Scripting

Creating OpenDoc References

Initializing and Terminating Events

Programming Considerations

Supported Event Return Types

SOM IDL Conversion to Lotus Script

Object Lifecycle

Inheritance Considerations

Runtime Considerations

Modifications to the Lotus Script IDE

Visual Basic Scripting

Embedding an OpenDoc Part into a Visual Basic Form

Writing a Visual Basic Program to Access the Part.

Perform Event Handling

Scriptable Part Development

Script Extension Implementation

InitScriptExtension

Modifications for Part Coding

HasExtension and AcquireExtension

InitPartFromStorage

Part Specific Routines

Menu Management

Part Registration

IDL Modifications

Script Component

Annotating the IDL

IDL Modifiers for OpenDoc

ODdefault (A O)

ODhelpcontext (I A O)

ODhelpfile (I A O)

ODhelpstring (I A O)

OpenDoc Event Notification

Making a Part Connectable

ScriptableSimplePartInterface Code Segment

ScriptableSimplePartEvents IDL Segment

Constructor for Event Notification

Part Availability

Component Manager

Component Registry

Component Access Interface

Extending OpenDoc

OpenDoc Extension Interface

Extension Objects

Using an Extension

Implementing Extensions

The Settings Extension

Custom Event Types

Creating a Dispatch Module

Using a Dispatch Module as a Monitor

Custom Focus Types

Creating a Focus Module

Focus Modules for NonExclusive Focuses

Custom Transform Objects

Patching OpenDoc

Writing a Patch

Installing a Patch

Potential Patch Conflicts

OpenDoc Run-Time Features

Run-Time Environment

OpenDoc Run-Time Process

Dynamic Linking and System Object Model

Dynamic Linking

SOM and Distributed Dispatching

SOM Exception Handling

Part-Wrapper Object

Creating and Releasing Objects

Factory Methods

Reference-Counted Objects

Handling Byte Arrays and Other Parameters

Lazy Instantiation

Accessing Objects through Iterators

Information Used for Binding

Part Kinds Supported by an Editor

Part Kinds Stored in a Part

Part Categories Supported by an Editor

Binding Process

When Binding Occurs

Binding to Preferred Editor

Binding to Default Editor for Kind

Binding to Default Editor for Category

Binding to Any Available Editor

Binding to Editor of Last Resort

Consequences of Changing Part Editors

Run-Time Object Relationships

Session-Level Objects

Drawing-Related Objects

Window State and Windows

Layout and Imaging

User-Interface Objects

Storage Objects

Document Storage

Extension Objects and Scripting

The Document Shell

Document Shell Operations

Opening a Document

Saving and Reverting a Document

Closing a Document

Handling User Events

The Document Shell and the Document Menu

Appendix A. Embedding Checklist

Content Model and Storage

Embedded Frame Management

Scripting Support

Appendix B. Part Developer's Checklist

Part Properties

Resizing Frames

Changing Display Forms

Multiple Selection

Sequenced Frames

Appendix C. OpenDoc Recipes

Making Parent Method Calls

Object Equality

Parameters and Memory in OpenDoc

Part Properties

Standard Properties

Non-Container Part Protocol

Container Protocol

Additional Note for Root Containers

Notes on Background Transparency Handling

Cloning Mechanism

Recipe for Clients

Recipe for Parts

Scoping for Cloning

Destination Frame for Cloning

Persistent Object Annotations

Reference Counting

Why Use ODRefCntObject?

What Is ODRefCntObject?

What Are the ODRefCntObjects in OpenDoc?

How Does It Work?

What Are the Implications on ODPersistentObjects?

Persistent References

ODStorageUnitRef

Strong and Weak ODStorageUnitRef

Storage Unit Manipulation Recipes/Examples

Persistent Objects Removal

Alternate Container Suite Use

Creating a Container

Acquiring a Container

Default Container Type

Bento Container Suite

How to Create a BCS File Container?

How to Create a BCS In-Memory Container?

How to Get the FSSpec from a BCS File Container?

Garbage Collection

Data Interchange

Data Interchange Basics

About Coding Examples

Data Interchange Mechanisms

Promising Intrinsic Content

Writing an Embedded Frame

Implementing CloneInto

Incorporating from a Content Storage Unit

Embedding a Content Storage Unit

Clipboard Recipes

About Coding Examples

When Parts May Access the Clipboard

Determining that a Draft Can Be Modified

Clipboard Focus

Acquiring the Clipboard Focus

Relinquishing the Clipboard Focus

Cloning to the Clipboard

Clipboard Update IDs

Undoing Clipboard Operations

Undoing the Cut or Paste of Embedded Frames

Cleanup in ReleaseAll

Writing Intrinsic Content to the Clipboard

Copying Intrinsic Content to the Clipboard

Cutting Intrinsic Content to the Clipboard

Copying a Single Embedded Frame to the Clipboard

Cutting a Single Embedded Frame to the Clipboard

Incorporating Content from the Clipboard

Embedding a Part from the Clipboard

Container Application Requirements

Preparing for a Drop

Detecting a Drag (Handling Mouse-Down Events)

Initiating a Drag

Tracking a Drag

Receiving a Drop

Incorporating Data from a Non-OpenDoc Document

Embedding Data from a Non-OpenDoc Document

Putting Out a Promise

Getting Data from a Value with a Promise

Fulfilling a Promise

Forcing Promise Fulfillment

Drag and Drop - Promising Non-OpenDoc File

Initiating a Drag

Fulfilling the Promise/Creating the Non-OpenDoc File

Linking Recipes

Utility Functions Used in Code Samples

Associating Links with Content

Persistent Representation of Links

Implementing InitPartFromStorage

Implementing Externalize

About Cloning Linked Content

Incorporating Linked Content from the Clipboard

Incorporating Linked Content the Easy Way

Incorporating Linked Content the Efficient Way

Copying a Single Embedded Frame at the Source or Destination of a Link

Posting a Link Specification to the Clipboard or Drag and Drop Object

When Not To Post a Link Specification

Removing a Link Specification from the Clipboard

Specifying Kinds Supported via nmap Resources

Implementing Paste with Link (Incorporating Content)

Implementing Paste with Link (Embedding Content)

Drop Result when Pasting a Link

Registering for Update Notification

Undoable Actions and Linking

Undoing the Paste or Drop of Linked Content

Accessing a Link

Basic Recipe for Writing to a Link

Implementing CreateLink

Better Undo Recipe for CreateLink

When CreateLink Is Called To Get an Existing Link

Updating a Link

Creating or Updating a Link Consisting of a Single Embedded Frame

Notes on Implementing FulfillPromise

Updating the Destination of a Link

Link Source Moved Across Parts

Links Containing Embedded Frames

Frame Link Status

Implementing LinkStatusChanged

Content Change Protocol

Implementing EmbeddedFrameUpdated

Calling ODFrame::ContentUpdated

Displaying Link Info Dialogs

Displaying Link Borders

Implementing RevealLink

Editing in a Link Destination

Implementing Linking Dialogs

Imaging and Layout Recipes

Adding a Display Frame

Adding and Removing Facets

Removing a Facet

Adjusting the Active Border

Adjusting the Border Shape

About Reference Counts

Clipping Obscured Content and Parts

Clipping Embedded Facets

Responsibilities

Content Update Notification

Calling ODFrame::ContentUpdated

Implementing EmbeddedFrameUpdated

Creating an Embedded Frames Iterator

Creating the Iterator

Determining Print Resolution

Embedding a Frame

Frame Groups and Sequencing

Containing Part Perspective

Embedded Part Perspective

Frame Link Status

Implementing LinkStatusChanged

Internalizing an Embedded Frame

Embedding a Frame

Making a Frame Visible

Creating and Using Offscreen Canvases

Creating an Offscreen Canvas

Imaging on an Offscreen Canvas

Updating an Offscreen Canvas

Managing the Print Job and Page Layout

Imaging Onto a Printing Canvas

Removing an Embedded Frame

RequestEmbeddedFrame

Coordinate Systems

Simple Scrolling

Partial Scrolling

User Interface Interaction

Embedding Support

View Types and Presentations

Connecting Frames to Parts

Requesting a Focus or Focus Set

Transferring a Focus or Focus Set

Basic Frame Activation

Window Activation and Frame Activation

Basic Event Handling

Standard Events

Special Considerations

Movable Modal Dialogs

Modeless Dialogs

Closing a Dialog

When Activating or Deactivating a Frame

Getting the Menu Bar

Adding Part Menus and Menu Items to the Base Menu Bar

Displaying the Menu Bar

Adjusting the Menu Bar

Handling Menu Events

Adding Accelerators

Getting the Pop-Up

Adding to the Pop-Up Menu

Displaying the Pop-Up Menu

Adjusting the Pop-Up Menu

Opening and Closing Windows

Creating a Window

Registering a Window

Opening a Window

Closing Windows

Opening a Part into a Window

Properties Notebook

Displaying the Properties Notebook

ODSettingsExtension Programming

Creating ODSettingsExtension

Presentation Page

Stationery Support for the OS/2 Platform

Creating the Icon File

Updating Part Editor Source Code

Creating A Part's Desktop Stationery

Using Resources in OpenDoc

Querying the Facet Window Handle

Specifying the PS for a Facet Window

Using Embedded PM Controls within a Facet (OS/2)

Managing Clipping

Handling Mouse Events on OS/2

Implementing a Dispatch Module

Defining a Dispatch Module

Implementing a Focus Module

Defining a Focus Module

Installing a Focus Module

Part Persistency

Multiple Kind Support

Coding Required

Resources Required

Multiple Kinds User Interface Description

Part Storage Model

Rules and Requirements

Details of the Part Storage Model

Questions and Answers

Part Init and Externalizing

Proper Treatment of Permissions

Sample Code for Initialization

Sample Code for Externalization

Part Info 'Ternalization

Persistent Format

'Ternalizing Part Info

Display Frame 'Ternalization

Methods Affected

Lazy Frame Internalization

Getting Laziness to Work for You

Dynamic Binding

Installation of OpenDoc Software

The Standard File Directory Structure

The Runtime File Directory

The Part Handler File Directory

The Source Sandbox File Directory

The OpenDoc Desktop File Directory

Packaging Your OpenDoc Part Handler

The Part Handler Package File Format

Registering a Part Handler

Appendix D. Sample Parts

Creating a Part from SimplePart

SimplePart Attributes

Overrides from ODPart for SimplePart

Methods Defined in SimplePart Class

AdjustViewTypeShapes

CreateFramePartInfo

DeleteFramePartInfo

HandleMenuEvent

LoadIconsFromModule

SetViewTypeRect

Creating a Part from BaseContainer Part

Overrides from ODPart for BaseContainer

Methods Defined in BaseContainer

CompleteMoveOperation

CompleteResizeOperation

DeleteSelection

DrawSelectionBorder

GetBackgroundColor

GetContentObjectFromObjType

GetDisplayFrames

GetEmbeddedObjects

GetSelectedObjects

HandleColorChange

HandleMenuEvent

HandleMouseClick

HandleMouseDown

HandleMouseMotionLBDown

HandleMouseMotionEnd

HandleMouseMotionStart

HandleMouseMove

InstallMenuItems

MoveSelectionToBack

MoveSelectionToFront

PasteSelectionAs

SelectContentObject

SetBackgroundColor

The ContentObject Class

ContentObject Attributes

Methods Defined in ContentObject Class

Creating a Part with PartMeister

Settings Notebook

Creating a Part

PartMeister Templates

Building Sample Parts

The Build Environment

Part Developer's Makefile

Macro Definitions

The Include of Platform.mak

Simplified Inference Rules

Environment Variable Macros

General Use Macros

Default Target and Its Corresponding Rules

Remaining Rules

Appendix E. Sample Utilities

Exception Handling

Guidelines for Coding Exception Handling

Use the New Header Files

Use the Debug Header Files

Define the _NATIVE_EXCEPTIONS_ Macro

Never Throw a C++ Exception out of an OpenDoc Part DLL

Check for SOM Exceptions

Use ODSetSOMException

Clear the SOM Exception Variable

SOM Compiler Flags

Using SOMMalloc and SOMFree

Programming Tools in ODExcept.h

Tools to Raise Exceptions

Tools to Manage the SOM Exception Handling Environment

Tools to Get and Set Exception Values

Obsolete Macros and Methods

Standard Structure for SOM Methods

Basic Try and Catch Model

Automatic Environment Checking

Guidelines for Using the Debugging Tools.

Display Warnings

Exceptions and Warning Based on Conditions

Printing Messages

FocusLib Utility

Temporary References and Objects

Using TempObjs and TempRefs

Adding New Classes

AreByteArraysEqual

CopyByteArrayStruct

CreateByteArray

CreateByteArrayStruct

CreateEmptyByteArray

CreateEmptyByteArrayStruct

DisposeByteArray

DisposeByteArrayStruct

StorageUnitGetValue

StorageUnitSetPromiseValue

StorageUnitSetValue

StorageUnitViewGetValue

StorageUnitViewSetValue

International Text

CopyITextStruct

CreateITextClear

CreateITextCString

CreateITextFromCharPtr

CreateITextPString

DisposeITextStruct

GetCStringFromIText

GetITextScriptCode

GetPStringFromIText

GetITextCString

GetITextLangCode

GetITextPString

GetITextPStringFromIText

GetITextStringLength

SetITextBufferSize

SetITextCString

SetITextScriptCode

SetITextLangCode

SetITextPString

SetITextStringLength

ODFixedMultiply

ODFractMultiply

ODWideSquareRoot

Data Types for Sample Utilities

ODTradITextDataHeader

ODTradITextData

Appendix F. OpenDoc Executables

avsshell Utility

cmgrcmd Utility

ctypelib Utility

docshell Utility

mkcatdef Utility

msgdisp Utility

odDeRgPt Utility

odDumpRg Utility

odmkSampleTree Utility

odRegPrt Utility

odsetenv Utility

odsomxh Utility

oduninst Utility

oleshell Utility

pmeister Utility

pmprintf Utility

prefedit Utility

reg1part Utility

scriptrg Utility

Appendix G. Notices

Appendix H. Glossary

Note
Before using this information and the product it supports, be sure to read the general information under Appendix G. "Notices".

First Edition (November 1996)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative. © Copyright Apple Computer, Inc. 1995. All rights reserved.

[ Top | Next | Index | Documentation Homepage ]