OpenDoc 202

Writing a Part using PartMeister

by Rollin White

In prior newsletters we have explored the design and architecture of OpenDoc. Now it's time to get down and dirty; we will begin building our first part. There are some concepts that may popup in the course of this article that will not be covered in any detail. Many of them such as SOM and IDL would take several articles to explain fully.

For this article we will use the Beta 6 version of PartMeister from IBM. As you may recall, you rarely want or need to build an OpenDoc part from scratch. Instead, parts are built using either skeletons, templates, or subclasses of other parts. And PartMeister is one of a growing number of tools to help us do this. Download it from:

After installing PartMeister, we can use it to generate the code for our component. When we start PartMeister for the first time, we must configure the basic settings for the parts we'll be building in the Part -> Settings menu dialog.

Using PartMeister

That done, we are ready to begin defining our first component. On the Template page, we will accept the default of Base Non-Container. Note that in the drop down list, there are other templates for Base Non-Container that provide support for clipboard, drag and drop, and linking. But, this being our first part, we'll start simply.

Once we have chosen the template, we can move to the Part section. On this page we must define several characteristics of our part:

The Class Name will be used to name all classes for the SOM interface and in our .IDL file. Essentially this is the name OpenDoc and OS/2 use internally to distinguish our part from all other parts.

The Short Name attribute is used to name the files. This name should be similar to the Class Name, but must be less than 8 characters.

The Desktop Display Name should be more descriptive. This is the name that users will see and use to identify parts of this class.

The Category field is an identifier internal to OpenDoc to indicate what type of data it is that our component will handle. For now we will stick with the default of kODCategoryPlainText. You may want to browse the list so that you are aware of what other options are available.

The Category Display Name is automatically filled-in based on our choice for category. While we could edit the text, it is wise to leave it alone.

The Kind field is an identifier to more specifically identify what type of data our part contains. The format for this string is

CompanyName:Kind:Classname.

In our example we will use SCOUG:Kind:Test.

The Kind Display Name field is the human readable version of the Kind field. This should be descriptive, such as "SCOUG Sample."

Once we've have filled-in all of the fields, we are ready to generate a template for our part. Select the Part -> Generate menu option. If we neglected to fill out any of the required fields, including those in the Settings dialog, we'll be given a descriptive error message. After correcting the error, select Part -> Generate again.

The Results

The result of the PartMeister generation process is the creation of three files. A fairly typical MAKEFILE is created to build our part. An .IDL file is generated to define the SOM level interfaces of the part. Finally, a .CPP file is generated that contains the bare bones implementation of our new part, as a subclass of the Base Non-Container part.

What next?

To ensure that we configured PartMeister correctly, we should compile the bare-bones part before making any changes to it. For this we will need IBM's VisualAge C++ Compiler as well as either the Warp 4 or OpenDoc toolkit. Assuming that it compiles correctly, the MAKEFILE will copy the resulting DLL into our OpenDoc directory. If it doesn't compile correctly, it is probably because one of the paths defined in PartMeister's Settings dialog is incorrect.

Now that the template provided by PartMeister has been compiled, how does that become a part in the OpenDoc environment? The result of the compilation process was a DLL named SCOUG.DLL. This DLL contains all of the code necessary to implement our part. To introduce it into the OpenDoc environment we will use a program named ODINST (for OpenDoc Install).

From the command line run:

Where the text following the -c is the name of our part class. The text following the -d is the DLL name. Note that the .DLL extension is omitted. The ODINST program will register our class with OpenDoc. If there are any errors, it will report them, otherwise it will indicate that the part registration was successful.

Once the part is successfully registered, there should be a new template in our OpenDoc Templates folder. We can now use our sample part just like any of the other parts that come with OpenDoc.

Adding Functionality

Right now our part doesn't really do anything. To make it real, we should add some sort of purpose to it - and I'm leaving that to you. When you add functionality, be sure to update your .IDL file, if it is appropriate. Also, since the template generated by PartMeister does not include any event handling, you'll have to take care of it. If you recall, in OpenDoc events are used to communicate an outside action, usually by a user.

For example, if you wanted to respond to a double click on the background of your component, you would add a SCOUGHandleEvent() method to your class. Handling events is very similar to a standard PM Message Loop. So, to check for a double click you would watch for a WM_BUTTON1DBLCLK and respond appropriately. Once you have made changes to your part, you will need to recompile and perhaps reregister your part handler.

The process is to make a change; recompile; reregister. Try it out, then repeat the process until your part has all the functionality you want. Not glamorous, but it gets the job done!

Still have questions?

This concludes our series of articles on OpenDoc. If you have questions about OpenDoc - either as a user or developer - please send me e-mail or talk to me at the meeting.

Also in this series on OpenDoc for OS/2

OpenDoc 101, A Technology Frontier

OpenDoc 102

OpenDoc 201

Copyright 1996 the Southern California OS/2 User Group. Reproduced with permission from the November 1996 edition of the group's newsletter, OS/2 For You.
All trademarks remain the property of their respective owners.