Paste

To do a paste operation, you get the OpenClip NSDictionary from the pasteboard, run through it to get your objects and then add them to your drawing.

But first you need to learn how to get the objects from the NSDictionary. Start by downloading these files:

OpenClipDefines.h
this is the all-important file that defines all OpenClip tags

NewPasteJob.h/.cp

NewPasteJob is a cut-down version of the PasteJob in the PowerCADD/WildTools OpenClip plug-in, and it is intended as a starting place for you to begin reading objects from the file at the OpenClip path. As with all programming, the hardest part is making the first step.

Follow these steps:

• Download OpenClip Viewer if you haven't already done so.

• Download the OpenClip files if you haven't already done so.

• Create a folder at the OpenClip path:

/Library/Application Support/OpenClip

• Rename one of the OpenClip test files. Let's start with points, so rename 'Three Points' to 'OpenClip' and put it in the OpenClip folder so you have a complete OpenClip path:

/Library/Application Support/OpenClip/OpenClip

• Get the OpenClip Viewer displaying the contents of this file, that is, start the program, or if it is running, click on the Refresh button.

• In your program, create a temporary menu command, say 'Test OpenClip'

• Rework NewPasteJob for your program, then call it:

MyPasteJob TheJob(MyCurrentProgramWindow());
TheJob.ReadOpenClipFile();

PasteJob:ReadOpenClipFile will read in the file from the OpenClip path. It will iterate through the objects in the OpenClip file that was read into memory. This all happens in ParseTheLayers(), ParseTheList() and ParseTheAdvancedList(). At this stage, you really don't want to touch these routines. Maybe later you may want to go back and study them, but it's better that you leave this all alone.

Instead, go direct to the ParsePoint(), ParseLine(), etc routines depending on what types of objects you are getting from the OpenClip file. That's why the OpenClip test files are organized by object types.

If you have a 2D application, these routines will do you just fine, but if you have a 3D application, then you have to go through a familiar drill with each object to deal with the Z height. An example of what is required in shown in PasteJob:ReadPoint3D(). Use this example for all other objects that you want to import into a 3D program.

If you have been developing under Carbon, two things will be new to you.

One is to include

#import <Cocoa/Cocoa.h>

in your code. #import is the equivalent of an #include with a pragma once statement.

And the other is that you will be mixing C++ and Objective C. You can do this in Xcode in several ways. One is to use the .m extension on your files. The other is to set the Target's GCC 4.0 Language to Compile Sources As Objective C++. Objective C++ is not actually a programming language, just a setting that lets you use C, C++ and Objective C all in the same document.

• Since you have renamed 'Three Points' to 'OpenClip'. Change the ParsePoint() routine to add these objects to your drawing.

• Repeat this process for all object types: lines, rectangles, rotated rectangles, circles, ellipses, arcs, polygons, beziers, etc. Change each routine to get the geometry out of each object and into your drawing.

Rectangles, ellipses, arcs and their cousins are typically 2D objects and in a 3D program, they would have a Z height for the object but not for each point in the corners of the enclosing rectangles—which would be impossible since the rectangles are defined by two points.

It will be up to you to 'rectify' the points for a rectangle and to make sure the left is really the minimum value of the two x values, and the same for the y values.

The CorrectPoint routines are commented out in NewPasteJob, but you will have to put the equivalent back in so the points will be correctly scaled for your program.

Once you can successfully read all of the sample files, it's time to get the NSDictionary from the pasteboard. For an example of how to do this, download:

PasteStuff.h/.cp

This is the routine that is used in the PowerCADD/WildTools OpenClip plug-in. It is called by an event handler put on the Paste command in PowerCADD.

As you can see, it checks to see if there are any pasteboard conflicts. Obviously, we don't want to override the default behavior of the base program, so we don't want to do an OpenClip paste until we are certain that there are no pasteboard flavors that PowerCADD uses.

In this case, as you can see, the NSDictionary comes from the pasteboard, not the OpenClip file so we just call ReadTheDictionary, not ReadOpenClipFile.

Once you have that working, now you need an actual NSDictionary on the pasteboard. This is simple, just use the OpenClip Viewer, click the Copy button, and then use the Paste command in your program. As before, you can go through all of the OpenClip test files to check all this.

When you are finished, you'll want to check that the geometry of rotated rectangles and ellipses really matches the samples that you see in the OpenClip Viewer.

You'll also want to check that everything is repeatable and things fall reliably in place. In a 2D program the user might draw a rectangle, paste it in the 3D modeling program, and then realize he left out a line. The user should be able to draw a diagonal line across the rectangle snapping to the corners, and then copy and paste into the 3D modeling program and have the line perfectly positioned with the rectangle. It works this way when copying from PowerCADD to Bonzai3D.

Some 3D modeling programs have a 'normal' for each object which defines which way is up or down. Typically you can't see this, but it will be obvious when you extrude an object and type the 'up' extrusion distance. Sounds obvious, but this can be problematic when dealing with OpenClip.

Some 3D modeling programs have the concept of a current plane, and you'll want to decide if the proper behavior in your application is to paste the objects in the current plane or always at a horizontal plane. Probably most users will expect it to be at the current plane, but it's your program.... And if the current tool is working on a face, then you'll want to think about whether it should paste on that plane.

As you can see, all this is a fairly simple thing to accomplish. It took the programmer at AutoDesSys 12 hours to get an OpenClip paste working in Bonzai3D 2.0. We will be interested to hear how others do using these examples.

We hope you can now see why everyone involved with OpenClip is so excited about it. It's such a simple thing to accomplish. Users love it and often use huge to describe the significance.

For many 3D modeling program, a Paste operation may be all you will need to do, at least initially. Typically, users have created their floor plans and want to bring them into the 3D modeling program to start extruding things and building their models.

Congratulations on making it through the first step of this process!

When you get this done in your program, please send us a note so we can include your program in the OpenClip 'consortium'.

When you're ready, then move on to Copy.