TweetFollow Us on Twitter

OD Contain Yourself
Volume Number:12
Issue Number:1
Column Tag:New Apple Technology

OpenDoc: Contain Yourself ...

Updating applications to work with OpenDoc

By Eric Soldan, Apple Developer Technical Support

It’s time to be an OpenDoc™ container application. It’s not too soon, and it’s not too late. So how do you decide if your application should be an OpenDoc container application or not? Here’s an easy test:

• Will your application benefit from Internet access?

If the answer is yes, then being an OpenDoc container application is probably the right thing to do. By becoming an OpenDoc container application, you automatically get the benefits of everything that is OpenDoc, including CyberDog, which will provide component oriented Internet clients and other Internet services. Now is not the time to ignore the Internet bandwagon. It’s worth jumping on. The only question remaining is how to jump. Do you learn Open Transport and MacTCP and recode your entire application to support the Internet? Or do you look for alternatives, like OpenDoc?

A logical question therefore would be: “Is OpenDoc really the fastest way to add Internet to your application?” Adding Internet support with OpenDoc boils down to adding basic OpenDoc support; in this article we will evaluate the difficulty of adding OpenDoc to an existing application. Then you can decide.

The Container Application Library: Your Friend.

CALib, the Container Application Library, has been evolving for a while. It’s looking really good right now. Joshua Susser, of OpenDoc engineering, and I have been adding CALib support to an application I originally developed in Developer Tech Support called DTS.Draw. I wrote DTS.Draw years ago, without ever considering the possibility of adding something like OpenDoc later. DTS.Draw’s document model, while flexible, is a closed model, so adding OpenDoc support is therefore a very interesting test case for CALib.

It turns out that the amount of additional coding necessary is minimal. However, due to CALib’s flexibility, there were many development issues that had to be discussed for quite a while. If these discussions were not held, the implementation would not have been as robust. I will present what we’ve learned from these discussions.

First, let’s talk about DTS.Draw for a while. When adding OpenDoc, it’s important to understand how the existing application works. Since you are probably not familiar with DTS.Draw, I’ll give you a quick overview.

DTS.Draw is an AppsToGo framework based application. AppsToGo is an object-oriented C framework written by DTS. DTS.Draw is also all C code. DTS.Draw is a “standard” drawing application. It has a tool palette of a variety of drawing objects. It has a hierarchical document architecture which allows for grouping and ungrouping of draw objects. It supports infinite undo. It supports drag and drop.

When a document is saved, the object hierarchy is flattened and streamed to the file. When a drag-out occurs, the selected objects are streamed into a handle; this stream represents a sub-hierarchy of the document. This sub-hierarchy is then just a flavor for the clippings file. When a file is opened (or a drag-in occurs), the hierarchy is reconstructed. Very standard stuff.

Here’s a diagram of a representative DTS.Draw document:

For a save, the objects in the hierarchy are streamed in simple tree-walk order, as indicated by the numbering. The drag objects 2, 4, 5, and 6 can be any supported object. The current implementation of DTS.Draw allows for line, rect, round rect, oval, and pie objects. More can be added of course, and this exactly is how we added OpenDoc support to DTS.Draw; we just added a new OpenDoc Part object into the application. The difference with this object is that the content isn’t anything specifically manipulated by DTS.Draw. It is simply a part the user adds to the document. The DTS.Draw object just serves as a “container” for the OpenDoc part. If a user were to add two OpenDoc parts to the above DTS.Draw document, the document hierarchy might end up looking something like:

The implementation in DTS.Draw is relatively simple. The Part object inherits from DTS.Draw’s native rect object. The difference is that it has a much more complex content that the rect object in the standard DTS.Draw application. The content of the Part object can be any OpenDoc part, of course. The content of the Part object is managed using CALib. Given this information, look at this diagram and see exactly what the relationship between the Part objects and CALib :

As shown above, there’s a lot more to the DTS.Draw document now. Fortunately, most of the new stuff is managed by CALib and OpenDoc. CALib uses a “proxy part” to contain the parts that are placed into the document content. Normally, OpenDoc expects there to be a root part that is an OpenDoc container, but since other parts are “embedded” into your application’s non-OpenDoc document, a proxy container part is created and the “embedded” parts are stored in there. The proxy part, as far as OpenDoc is concerned, is what actually contains the other parts that are referenced from the DTS.Draw native content.

The difficulty here is that the proxy part isn’t “real.” It has no geometry information, and OpenDoc doesn’t automatically bind the proxy part to any code, as is the normal case with OpenDoc parts. Thus, OpenDoc is unable to offer the full range of services for the embedded parts. But this is okay. The proxy part isn’t all that smart, nor should it be. It is simply a part that is used by CALib to have somewhere to put the other parts.

So it’s up to DTS.Draw to control the layout and presentation for the OpenDoc parts. Only the application knows the geometry information for the embedded parts, which is stored in DTS.Draw Part objects. The DTS.Draw Part object also has a persistent reference to the corresponding object embedded in the proxy part. Fortunately, CALib offers API calls to help manage these and other OpenDoc interactions, so the above and other OpenDoc related tasks are relatively simple to implement.

For example, to perform screen updates and such, DTS.Draw simply tells CALib to tell the part to draw itself. All that is needed is the Part Ref value, which indicates to CALib which embedded part to draw. The application doesn’t have to care what it references. It references something, and that thing knows how to draw itself.

Streaming Your Objects

Given that the proxy part can’t really deal with containing parts by itself, (i.e., without your application doing the geometry), the proxy part and its embedded parts do not constitute a valid OpenDoc document. This is important when we decide what type of document you want to create when you save it to disk.

The choices are:

1. A Bento stream placed inside your document.

2. Your document stream placed inside a Bento document.

The right choice will of course depend on your application. For DTS.Draw, we chose 1. Choice 1 is closer to existing Macintosh applications. Choice 2 is closer to regular OpenDoc parts. If you were to consider the development choices, from application to OpenDoc part, with CALib applications somewhere in between, your choices look something like this:

Application:

Standard document architecture.

CALib-friendly application:

Standard document architecture with embedded Bento stream.

CALib-savvy application:

Bento document with application data streamed into an OpenDoc storage unit
value.

OpenDoc part editor:

Bento document with part editor data residing in an OpenDoc storage unit.

When considering drag and drop, the above categories are very important. When applications drag something to the desktop, a clippings file is created. When OpenDoc parts are dragged to the desktop, an OpenDoc document is created, instead of a clippings file. This is an important distinction between applications and OpenDoc. Applications create clippings files because they are a standard and flexible intermediate format. OpenDoc parts create OpenDoc documents on a drag-out because an OpenDoc document is already a universal format. There’s no reason to resort to creating a clippings file.

If you are a CALib application, the choice is no longer so clear. Our suggestion is to base your drag-out decision on whether your document format is still “native,” or if you use a Bento file with your native content embedded.

So, if you are a CALib application, what is one to do on a drag-out? The answer lies in the document type. If the document type is an OpenDoc document (CALib-savvy), then the drag-out type is OpenDoc document. If the document type is a standard document (CALib-friendly), then the drag-out type is a clippings file.

DTS.Draw’s native content is simply streamed out. After adding CALib support, this is still the case. The Bento document is streamed out, as well. Here’s the new document format:

Byte offset Description

0 to 3: length of Bento stream

4 to nativeContent - 1: Bento stream

nativeContent to EOF: native content stream, i.e.,
DTS.Draw old format

There was much discussion as to whether or not the Bento stream should be at the front of the file or the end. It turns out that you can do some interesting things if it is at the front of the file. Try out this situation:

1. Your machine has CALib. You add some OpenDoc parts to your DTS.Draw document.

2. You then send the document to some poor individual who doesn’t have CALib or OpenDoc.

Guess what? If the Bento stream is in the front of the file, the unfortunate individual can still use the file with your CALib-friendly application. The user without CALib can actually edit the native content and save it out. The native content changes size, but hey, it’s on the end of the file.

On machines that don’t have CALib but need to display Part objects in their content, the standard look for “NoPart” should be used. This is what OpenDoc displays when an editor for a particular part isn’t available. In the case of CALib applications, it works for when CALib isn’t available, as well.

Making your CALib-based documents work on machines with or without CALib takes a bit of extra coding, but from a version control standpoint, it is well worth it. Documents can go anywhere. A CALib document can be given to someone without CALib. That this person can actually edit the native content of the document, and then give the document back to you, is pretty nifty.

On machines where CALib isn’t available, users obviously won’t be able to add any new parts to the document. They will be restricted to editing the native content. However, this may include moving part objects around that someone else was nice enough to put in the document. This works. Remember that the geometry information is stored in the native objects, which all users can edit. The proxy part doesn’t handle the geometry. In addition, the user can delete the Part objects (which are displayed using the “No Part” look). This of course means that there is data orphaned in the Bento stream. (Since the user doesn’t have CALib, there is no way their machine can modify the Bento stream.) Fortunately, the stream will be compacted the next time the document is saved on a machine with CALib.

With some extra work, you can even allow the user to resize the Part objects without CALib. When this occurs, the information in the Bento stream for that part is no longer up to date. The native content object will need to be flagged as having been resized. When the document is opened on a machine with CALib, these objects will need to have their frame information renegotiated and resolved to reflect their new size.

We’ve been discussing types of editing that can still occur to a CALib document Part object when CALib isn’t available. There are, of course, edits that can’t be performed. Here are two:

1. Dragging that includes a Part object. Streaming the drag data must include streaming the Bento information into the flavor. This can’t be done without CALib. All that’s in the native object is a persistent reference to somewhere inside the Bento stream. You can’t resolve the reference without CALib.

2. Copying the object. At first, it would seem that you would just copy the native content object. It has a persistent reference. Both copies of the object would then point to the same Bento information, i.e., the part. This is a bad thing. When opened again on a CALib machine, each copy of the part should be independent of the other. (You could flag the copy as an unresolved copy, and then clone the object when the document is next opened on a CALib machine.)

As you can see from this discussion, CALib can be used to add OpenDoc capability to your existing applications without radically changing the way they work. The actual amount of code added to an application isn’t all that bad, either. Of course, this will vary, depending on architecture and document content, but most likely, it’s not a complete recode with major modifications throughout your application. Look for the latest CALib and CASample sample code on the OpenDoc DR4 release.

Have fun out there!

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Final Cut Pro 10.6.4 - Professional vide...
Redesigned from the ground up, Final Cut Pro combines revolutionary video editing with a powerful media organization and incredible performance to let you create at the speed of thought.... Read more
iMovie 10.3.4 - Edit personal videos and...
With a streamlined design and intuitive editing features, iMovie lets you create Hollywood-style trailers and beautiful movies like never before. Browse your video library, share favorite moments,... Read more
Motion 5.6.2 - Create and customize Fina...
Motion is designed for video editors, Motion 5 lets you customize Final Cut Pro titles, transitions, and effects. Or create your own dazzling animations in 2D or 3D space, with real-time feedback as... Read more
iMazing 2.15.8 - Complete iOS device man...
iMazing is the world’s favourite iOS device manager for Mac and PC. Millions of users every year leverage its powerful capabilities to make the most of their personal or business iPhone and iPad.... Read more
VueScan 9.7.90 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Compressor 4.6.2 - Adds power and flexib...
Compressor adds power and flexibility to Final Cut Pro X export. Customize output settings, work faster with distributed encoding, and tap into a comprehensive set of delivery features. Features:... Read more
Capture One 15.3.2.11 - RAW workflow sof...
Capture One is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 400 high-end cameras - straight out of the box. It offers... Read more
Vivaldi 5.4.2753.28 - An advanced browse...
Vivaldi is a browser for our friends. We live in our browsers. Choose one that has the features you need, a style that fits and values you can stand by. From the look and feel, to how you interact... Read more
Parallels Desktop 18.0.0 - Run Windows a...
Parallels allows you to run Windows and Mac applications side by side. Choose your view to make Windows invisible while still using its applications, or keep the familiar Windows background and... Read more
TechTool Pro 16.0.1 - Hard drive and sys...
TechTool Pro has long been one of the foremost utilities for keeping your Mac running smoothly and efficiently. With the release of this version, it has become more proficient than ever. Main... Read more

Latest Forum Discussions

See All

Turn-Based RPG ‘Avatar: Generations’ Sof...
Square Enix London Mobile, Navigator Games, and Paramount Consumer Products just announced that the turn-based RPG Avatar: Generations based on Nickelodeon’s Avatar: The Last Airbender is soft launching this month for mobile. Avatar: Generations is... | Read more »
Tower of Fantasy launches today and brin...
Level Infinite and Hotta Studio have announced the release of their very ambitious looking shared open world MMORPG Tower of Fantasy. With its cross-platform functionality between PC and mobile, it looks to be one to roll the dice on and enjoy at... | Read more »
‘Genshin Impact’ Version 3.0 Gets a New...
After HoYoverse released Genshin Impact (Free) version 2.8 on all platforms, the company has slowly been teasing the major upcoming 3.0 update. This update features the Sumeru region with many characters. While details on the update including a... | Read more »
Out Now: ‘Tower of Fantasy’, ‘Tightrope...
Each and every day new mobile games are hitting the App Store, and so each week we put together a big old list of all the best new releases of the past seven days. Back in the day the App Store would showcase the same games for a week, and then... | Read more »
SwitchArcade Round-Up: ‘Book Quest’, ‘Cl...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for August 10th, 2022. In today’s article, we’ve got a little news about an update to a game I really like, a few new releases to summarize, and some sales to look at. A bit of a quiet... | Read more »
‘Pine Tar Poker’ is an Otherworldly Poke...
Developer BJ Malicoat, who put out the well-received and former Apple Game of the Day pick Downwordly in June of last year, is back working on another mobile game project called Pine Tar Poker, and it has caught my attention. Why? Because it’s a... | Read more »
Darkness Rises celebrates four years of...
Four years of uptime for a mobile game is akin to eternity, and this is exactly the milestone that Darkness Rises has reached. It is important for developers to keep updating to keep the game fresh, and NEXON has announced a massive anniversary... | Read more »
Keep Your Smatphone’s Case On When Using...
The original Gamevice was born as a sort of offshoot of the weird Wikipad gaming tablet/controller/hybrid thing way back in 2014. Interestingly, the first Gamevice controller for iOS only supported the iPad mini and launched in 2015, with versions... | Read more »
SwitchArcade Round-Up: A ‘Splatoon 3’ Ni...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for August 9th, 2022. In today’s article, we’ve got some news about a Splatoon 3 Nintendo Direct, a review of QUByte’s Thunderbolt Collection, a single new release summary, and the usual... | Read more »
Orangepixel’s Pacifist Survival Game ‘Re...
Back in June we learned that long-time mobile developer Orangepixel, who also makes games for PC and consoles (including the Atari VCS!), would be bringing the unique survival game Residual to mobile devices sometime this year. Originally launched... | Read more »

Price Scanner via MacPrices.net

Apple has 24-inch M1 iMacs available starting...
Apple has 24-inch M1 iMacs with M1 CPUs (8-core CPU/7-core GPU) available today in their Certified Refurbished store for $1099 shipped. Their price is $200 off standard MSRP. Each iMac is in like-new... Read more
13″ M1 MacBook Airs in stock today for $799,...
QuickShip Electronics has open-box return 13″ M1 MacBook Airs in stock and on sale for $200 off MSRP on their eBay store right now, each with free express delivery. According to QuickShip, “The item... Read more
In stock today: Mac Studio models for up to $...
Apple retailer Expercom has Mac Studio models in stock today and on sale for up to $400 off Apple’s MSRP, depending on configuration. Their prices are the lowest price available for a Mac Studio from... Read more
Mac mini with M1 CPU and 512GB of storage on...
Amazon has the M1 Mac mini with a 512GB SSD in stock today on sale for $749.99 including free shipping. Their price is $150 off Apple’s MSRP, and it’s the lowest price available for this... Read more
Need a Mac or iPad for school? Get a free App...
Apple’s Back to School promotion for 2022 continues to run through September 26, 2022. As part of this promotion, Apple will include a free $150 Apple Gift Card with the purchase of any MacBook Air,... Read more
Apple Watch SE on sale for $50 off MSRP
Amazon has Apple Watch SE GPS models on sale for $50 off MSRP for a limited time, each including free shipping. Their prices are the lowest currently available for SE Watches: – 40mm Apple Watch SE... Read more
Save $310 on a 14″ 24-core GPU M1 Max MacBook...
Save $310 on 14″ MacBook Pros with 24-core M1 Max processors at Apple (32GB RAM/1TB SSD) with these Certified Refurbished models in stock today for $2789 in Space Gray or Silver colors. Regular price... Read more
14″ M1 Pro MacBook Pros available today at Ap...
Apple has Certified Refurbished standard-configuration 14″ MacBook Pros with M1 Pro CPUs available today for up to $250 off original MSRP, starting at $1799. Each model features a new outer case,... Read more
13″ MacBook Air with M2 CPU, in Starlight, on...
Apple retailer Expercom has the new Starlight 13″ MacBook Air with an M2 CPU (8GB RAM/256GB SSD) on sale for $1135.05, shipped, through August 12, 2022. Their price is $64 off Apple’s MSRP, and it’s... Read more
14″ M1 Pro MacBook Pro with 1TB SSD on sale f...
Expercom is offering a $200 instant discount on the 14″ M1 Pro MacBook Pro with a 1TB SSD through August 12, 2022. Their discount reduces the price of this configuration to $1999 shipped — the lowest... Read more

Jobs Board

Solutions Engineering Manager - *Apple* - S...
…in our Hardware and Advanced Solutions group leading and developing our Apple technical practice to increase revenue and profitability. The ideal candidate would Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Sephora Beauty Advisor - *Apple* Blossom Ma...
Sephora Beauty Advisor - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.