═══ 1. Overview ═══ THIS IS A LIVING, WORKING DOCUMENT, AND WILL CHANGE OVER TIME AS DESIGN AND DEVELOPMENT PROGRESSES. IT DESCRIBES FUNCTIONS WHICH HAVE NOT YET BEEN IMPLEMENTED AS WELL AS FUNCTIONS WHICH HAVE. SEE THE ACCOMPANYING ONLINE REFERENCE AND READ.ME FOR A BETTER UNDERSTANDING OF WHAT HAS BEEN IMPLEMENTED IN A GIVEN DRIVER. CONTACT THE DEVELOPMENT GROUP IF YOU HAVE SPECIFIC REQUIREMENTS FOR ANY OF THIS FUNCTION, SO THAT YOUR REQUIREMENTS CAN BE CONSIDERED. INTERNAL TO IBM, CONTACT PHOLMES AT CARVM3. EXTERNAL TO IBM, APPEND TO THE OPENDOC FORUMS ON EITHER COMPUSERVE (GO OPENDOC) OR INTERNET (opendoc-interest on cilabs.org). THIS DOCUMENT CONTAINS NO SCHEDULES. FOR AVAILABILITY DATES OF PARTICULAR FUNCTIONS (FUNCTION MAY BE STAGED), CONTACT THE AUTHOR. NOTE TO EXTERNAL CUSTOMERS: I'LL NEED TO GET YOU ON A CONFIDENTIAL DISCLOSURE AGREEMENT INDIVIDUALLY IF YOU NEED ANY EXCEPT THE MOST NEAR-TERM SOLID DATES. Arthur Jolin OpenDoc Frameworks C++ UI Tools Development, IBM jolin@vnet.ibm.com ═══ 1.1. Goals ═══ The primary goal of the IBM OpenDoc Forms Framework (OD Framework for short) is to make it as simple as possible for C++ developers to create forms-style OpenDoc parts. "Forms-style" means that the visual interface to the part consists primarily of GUI controls (e..g, buttons, text entry fields, bitmap-display controls), with perhaps some simple 2D drawing and rendering. This Framework is not appropriate for all OpenDoc parts, but it makes the above kinds of parts easier to implement. The OD Framework will consist both of classes for creating and testing your parts and sample fully-implemented parts that use the OD Framework. These sample parts will have their source code made available, to help guide new part developers. The OD Framework will include function designed specifically to work in conjunction with the IBM VisualAge C++ OpenClass class libraries; specifically, OpenClass classes can be used to implement the interior/contents of OD Framework parts in a way familiar to current users of OpenClass. The OD Framework is not the same thing as the OpenDoc base toolkit and runtime (the underlying OS support for OpenDoc). OpenDoc toolkit is being produced by IBM's system groups (OS/2, AIX), WordPerfect (Windows), Sun, etc. It contains basic C++/SOM support, as defined in the Apple design documents for OpenDoc. By definition, as stated in the Apple document, it's goal is not to make it easy to create parts, but only to make it possible. Lastly, the OpenDoc toolkit is intended to be part of the operating system, or made freely available. The OD Framework, on the other hand, is being produced by IBM's SWS, the home of VisualAge C++ (VA C++) and it's OpenClass class libraries (formerly known as IBMCLASS). It's goal is to make it easy to create parts written in C++. The OD Framework is intended to be shipped as part of VA C++. It may be made available in additional ways if conditions (e.g., schedules) demand it. During development, drivers will be made available periodically. ═══ 1.2. Environments ═══ The OpenDoc Forms Framework depends on the base OpenDoc support in each environment, as well as VA C++ class libraries in each environment. Based on current plans, we intend to support the following environments: o OS/2 Warp o OS/2 Warp for the PowerPC o Windows 32bit (i.e., Windows95, a.k.a.Chicago, WindowsNT) o Win32S. Because certain controls (e.g., container) are not available to Win32S applications (and thus there can be no OpenClass classes for them), OD Framework content will be limited here. o AIX o AIX for the PowerPC o Solaris (not sure when OpenDoc support will be completed) o Potentially, other UNIXes, such as HPUX (depends on the VA C++ and OpenDoc products being supported on these UNIX variants) We are working with Apple toward achieving common or very similar frameworks on the MacOS as are available on the other platforms. This may include an OS/2 version of Apple's OpenDoc Developer Framework (ODF) and/or a MacOS version of the VA C++ OpenDoc Forms Framework. ═══ 1.3. Target Users ═══ Target users of the OpenDoc Forms Framework include developers with the following skills and needs: o C++ and general OO programming skills o Little to moderate knowledge of OpenDoc Library o Skills in their own domain (e.g., financial, insurance) o need to convert existing GUI application(s) to a compound document style UI (app becomes a set of semi-independent parts) o need to write OpenDoc parts for the first time o need to write OpenDoc parts which use GUI controls or VA C++ UI Class Library objects, and/or moderately detailed drawn images (via GDI, GPI or VA C++'s portable drawing classes) ═══ 1.4. Summary of Content and its Value to Users ═══ The OpenDoc Forms Framework consists of three major sections: o A forms part framework o A set of already-implemented sample parts and their source code o Test & support stuff Also included in the OD Framework, for purposes of planning & funding, are enhancements to VA C++ class libraries (e.g., OpenClass) in support of OpenDoc. Sub-frameworks have been defined for some part domains, however we welcome and depend on feedback from part developers for additional frameworks. We are actively working with existing part developers, obtaining their code and using it as a guide for where and how new frameworks can help significant numbers of future developers. Naturally, we will concentrate on part domains where significant numbers of parts are expected to be written, and where a framework can have significant value add. Please contact the author directly if you are developing an OpenDoc part and would be interested in working with the IBM OD Framework team. ═══ 1.4.1. Integration with other Products ═══ The OpenDoc Forms Framework is specifically designed to integrate with the VA C++ OpenClass. OpenClass is a primary vehicle for creating the interior of OpenDoc parts created with the OD Framework. You will be able to use the VA C++ visual builder to construct OpenDoc parts by combining classes from the OD Framework and OpenClass, similar to how you combine non-visual "builder-parts" (i.e., model content objects) and visual "builder-parts" (i.e., views) today. This capability will be available at the same time as the OpenDoc Framework GA. ═══ 1.4.2. Usability ═══ See OpenClass usability plan. ═══ 1.4.3. Documentation ═══ Eventual documentation will consist of a users guide and a reference. We are investigating whether this is best done as additions to the existing OpenClass books or as separate books. Assumption is separate books. The material from this document will form the core of the users guide text, to be reviewed by ID for content approximately 3 months before code freeze, and edited to final content format approximately 2 months before code freeze. Content adjustments will occur up until the last minute (let's get real, folks). The reference will be produced using the Odyssey tool, and will adhere to the same format as the OpenClass by using the same Odyssey template. Format of the refrerence is roughly the same as the reference shipped with this driver. ═══ 1.4.4. Install Plan ═══ See OpenClass install plan. ═══ 1.4.5. Development Dependencies ═══ The OD Framework depends on the OpenDoc Library, both toolkit and runtime, for each of its environments. It also depends on the VA C++ R3 (specifically, user interface and collection classes) for each of its environments. ═══ 1.4.6. Performance Objectives ═══ TBD in detail. Basically, the same as for OpenDoc and the VA C++ OpenClass. ═══ 1.4.7. DBCS/NLS Enablement ═══ The OD Framework depends on the DBCS/NLS support in the OpenDoc Library and in the VA C++ OpenClass. To date, there are no unique places in the OpenDoc Framework requiring DBCS/NLS support. ═══ 1.4.8. Forms Part Frameworks ═══ The focus of the forms part framework is to: o help part developers that don't render their own parts but wish to use OpenClass controls to create their part interiors. This is done by giving them model and view classes, where the models derive from an ODPart and the views derive from some existing OpenClass classes. Built-in behaviors between the model, view and related classes make them a framework for part development. Such parts are generically refered to as "form parts" o help part developers that do render their own parts but who have somewhat simple needs. This is done by giving them a view class to derive from that has large amounts of built-in behavior that will be appropriate for at least 50% (guestimate) of anticipated parts, but which does not assume the view uses controls (or system windows of any kind). This puts much more of a burden on the part developer, as the rendering of visuals takes substantial effort. As such specific visuals are unique to each part, the OD Framework can not help you much here (tho the OpenClass graphics and text-drawing classes can help somewhat). The same model class as above, together with a different base view class, is expected to serve this role. o help part developers manage menus (which includes menu bar items, pop-up menus, accelerator keys, etc.) o help part developers manage persistance (in the broadest sense, which includes transfer of data via drag/drop, clipboard and links) o help part developers handle semantic events and being driven by a script, including help for undo/redo of these operations o build other classes into the framework where we have clear value-add over the OD Library classes themselves. This is the same criterion used in the creation of OpenClass, and was well-received by its customers. The model and form view classes will be especially useful to those creating OpenDoc parts for most LOB needs (esp. converting current applications to parts), as well as ISV parts whose views are based primarily on the use of GUI controls. The use of separate model and view classes allows logic for data manipulation, query logic, etc. to be kept discreet from logic for presenting the data. It allows a variety of different views of the same model data. It allows various views of the same model to be kept in synch when the data is changed on one view; this synchronization can be handled mostly by OD Framework code, once the model and view classes are configured. The focus on "form" views comes from examining current UI guides and standards. Due to the guidance of CUA, Motif and other style guides, the majority of views can be grouped into one of several basic varieties. These varieties are: o panel/dialog view - a window (whether present for a long time or only briefly popped-up as needed) which contains entry fields, list boxes, buttons, etc. This is often used to create online forms. Tabular views are (for the time being) included under panel-based views, since today they are typically constructed from a series of entry fields. o notebook-based - a window which represents a set of related panel-based views, each appearing on a separate page of a notebook-like visual o the standard OpenDoc "static" views of icon, mini-icon and thumbnail o container-based - a window which contains a representation (e.g., icon view, a one-line-summary details view) of a large number of objects. Typically, each of these objects can be clicked on and opened into a panel view Note that text/wordprocessor views, graphic/bitmap/drawing views, etc. are not included in this list. Even though MLE and bitmap controls can be used in panel views to achieve something like such views, these are best handled by going beyond the simple text and bitmap controls available today; users demand more functionality in a part than these controls can provide (e.g., rich text, interactive shape drawing & special effects) and this usually means they must render themselves. The "container-based view" deserves special mention. In the OpenDoc UI paradigm, the distinction between container-based views and other views fades away. This is because OpenDoc defines how a part may simultaniously have its own content (be it entry fields and buttons, or drawn images) and have other OpenDoc parts embedded in it. Unlike the CUA paradigm of containment as defined in the container control or "folder", the types of objects can be totally heterogeneous (which, it should be noted, is often a mixed blessing). In recognition of this OpenDoc UI paradigm, the ODFramework views will be able to (optionally) have other OpenDoc parts embedded in them; a combination of OD Framework code and part-specific code will manage how this is done. The idea of multiple views is also based in real scenarios of use. For example, a form part could be loaded with an IMS record representing the complete account information for a bank customer. A loan application review document might include a panel view showing only a summary of balances in various accounts (the data for which came from portions of the form part's IMS record). On the other hand, a deposit/withdrawl document might include a panel view showing details of one particular account. The two views sharing the same form part as model would be kept in synch. Periodically, the form part could be resynchronized with the original IMS database (making updates to the database on behalf of all views, automatically). Parts which do not use the client/server aspects of the OpenDoc Framework can, of course, also be constructed. A part could deal with data strictly on the local user's machine without incurring any additional overhead. ═══ 1.4.9. Test & support ═══ The focus of test & support is to insure a part developer does not have to build a scaffold shell simply to test a part. This will also include sample code. This is not any sort of COMPLIANCE test bed, nor a complete, exhaustive FVT test bed for OpenDoc parts. ═══ 1.5. Strategic Positioning ═══ The OpenDoc Forms Framework has been welcomed by the OpenDoc toolkit development teams for OS/2, AIX, Win32 (i.e., WordPerfect) and Apple. Of course, these folks welcome all OpenDoc-related development. ;-) . Apple and we are working together with the goal of achieving similar or identical support on all platforms. OpenDoc (and, by extension the OD Framework) are part of the IBM Open Blueprint, as are the VA C++ OpenClass class libraries. ═══ 1.5.1. Positioning with Taligent ═══ OpenDoc, the OpenDoc Forms Framework and VA C++ OpenClass are all based on the assumption that standard operating system facilities (e.g., PM, GPI, Motif) should be used. On the other hand, the Taligent UI Frameworks are based on the assumption of new system facilities from low-level drawing on up through controls to the CHER compound document framework. There are advantages and disadvantages to either choice. Use of standard system facilities usually results in smaller size. Creating new facilities can allow new functionality to be added. There are users who desire each choice to be available. Outside of the UI area, many of the classes in TalAE and in VA C++ are complementary to each other. TalAE, for example, has file and licensing frameworks which VA C++ does not. VA C++ has more robust collection classes the those currently in TalAE and which can be used instead. In recognition of these facts, IBM is organizing a unified set of class libraries and frameworks which allow developers to work in either "native" or "TalAE" look and feel for current UI constructs, while continuing to enhance both with new user interface capabilities. The "native" and "TalAE" classes will not be identical. Along with the UI support, it will include a rich set of general application programming frameworks. Existing work from both VA C++ (UI classes, collection classes, OD Framework, etc.) and TalAE (Albert, UI Framework, File, etc.) will be incorporated. ═══ 1.6. Key Design Assumptions ═══ The OpenDoc Forms Framework will be designed as a C++ framework. This choice is based on the fact that C++ is the most widely-used OO language among our target customers (and application developers as a whole), that C++ is the best ANSI-standard language match (today) to underlying SOM/DSOM IDL and functions, and that use of C++ will insure smooth interoperability with the rest of VA C++. For those environments which support it (which should be all of them), key classes within the OD Framework will also have IDL interfaces. The OpenClass support within the OD Framework is dependent on the OpenDoc toolkit supporting ODFacets which are true HWNDs, at least as an option which any part developer can choose to use. The this support is currently available in the SOM version of the OpenDoc Toolkit for OS/2. Similar support exists or is planned for the Windows and *IX versions of OpenDoc. This support is not required on the Mac platform, due to window system differences. Within this document, "?"s indicate the idea, function, etc. is not yet well understood. The number of "?"s roughly indicates the degree of uncertainty; this is also roughly the uncertainty of this function making it into the final OD Framework. Also, please mentally add one "?" to anything in this document which has not been implemented yet. ═══ 2. Design Notes ═══ These design notes explain the overall intent of the various portions of the OpenDoc Framework. This information can be thought of as "User's Guide" type information, and will be one source of info for the eventual User's Guide. ═══ 2.1. Part Framework ═══ This framework is used to create OpenDoc parts whose needs with respect to the data they contain and how they handle that data can be described by one of several "recipies". The first such recipe is for parts who directly or indirectly contain data in the form of records, files or byte streams with a known format, or C/C++ data structures; the parts should also wish to portray that data on the screen by using GUI controls (e.g., entry fields, buttons), simple to medium-complexity drawn images, or a combination of the two. ═══ 2.1.1. ODFFormView ═══ This class is designed to help in writing parts which serve the same purpose that panels and dialogs do in today's applications. You can think of, and programatically use, an ODFFormView in roughly the same way you use an ICanvas client of an IFrameWindow today. In OpenDoc, the document as a whole is your "frame window"; ODFFormView is your piece of that document. You do not control the presence/absence of most frame window decorations (system menu, min/max buttons, menu, titlebar); you can interact with both title bar and menu (within limits) as if they were your own BUT ONLY when OpenDoc permits you to - typically when you are active. ODFFormView assumes it owns one ODFrame and one (for now) ODFacet, and hides the functionality of these two in a single class for simplicity. We have investigated an additional alternative as well; a separate ODFormViewFrame and ODFormViewFacet, to allow one-to-many flexibility. However, it appears today that this would not fit with current window system design, would complicate things for most application developers, and we don't plan to do it at this time. Standard OpenDoc views types of icon, mini-icon and thumbnail are not (normally) handled via this class. They by default are data members of your model class (see ODFFormPart), and we will manage and display them for you (once you give us an icon or bitmap) automatically. We may be able to create a thumbnail for you automatically (at your option, of course). Significant features include: o Existing IHandlers for HI events can be attached to an ODFFormView in the same way you attach them to IFrameWindows in today's OpenClass applications. o ODMouse events will be mapped to/from OpenClass IMouse*Handler functions o The OD document menu can be manipulated via classes similar to OpenClass IMenuBar, IMenuItem (we could move this function to the model object. Any comments? isn't there a need for unique menu items for each view of a model?) o Assistance to help the part save & restore the ODFFormView state (so a part can keep it's view(s) in the same state across sessions). This assistance will likely take the form of methods to streamout ODFFormView state data in a form suitable for storage in an OpenDoc PartData structure. The PartInfo data is data that a part can associate with a frame. It should be used to save frame specific information such as the activation state of the frame, not part content (which is saved elsewhere by the part). Methods identified so far are described in the reference section. Also, all methods inherited from ICanvas and IWindow are supported with the exception of: o window-positioning methods will be limited by the part's containing part o setParent may be restricted or may not be supported o messageQueue won't work, as OpenDoc may support multiple message queues o sendEvent and postEvent may change, to add support for OpenDoc events o not sure what isPrimaryWindow method should return, will work with users to determine o styles clipToParent and synchPaint ═══ 2.1.2. ODFModel ═══ This is the part class most likely to be used in conjunction with an ODFFormView; ODFModel can act as the model and ODFFormView can act as the view in a classic "model/view" structure. ODFModel manages interactions with OpenDoc and contains much function, but it does not itself contain your part-specific model data. An ODFModel has (typically as data members, with corresponding accessors) one or more model content objects derived from IStandardNotifier (called IPart in the VA C++ BETA2 driver, not to be confused with ODPart - it has nothing to do with it). The model content objects are always implemented by part developers (there are no standard ones supplied by the OD Framework, as they are unique to the part). The model content objects may be reused from other parts that you have access to, or may be written specifically for this part. Model content objects are classes containing purely data (no UI) and methods to manipulate that data. These are like the classic objects often discussed in introductory OO texts. The actual data "attributes" owned by or contained in a model content object typically come from some outside source. They might be fields within a stream of bytes which originated as a VSAM record, a CICS or IMS database record, etc. They could be individual variables (or parts of a structure) fetched from a relational database. They could be fields within a workstation file with some kind of standard format known to your model content object. Model content objects could also be produced by DAX relation database access support in VA C++. The attributes may be stored back into the outside source after modification; they could also be stored and retrieved directly in the OpenDoc document as ODStorageUnit values. Or you may use a combination of these two. Besides the framework-supplied behavior built into ODFModel and the model content objects, there is often part-specific behavior which applies to the part as a whole (and is therefore not a method on a model content object). In pre-OpenDoc OpenClass applications, ICommandHandlers are often the classes which implement such methods. In the OpenDoc world, many (tho not all) of these ICommandEvents are better handled by ODFModel, in keeping with the model/view separation of OpenDoc. This is because they are conceptually similar to Apple semantic events, which are also handled by the part. However, ICommandEvents such as the standard "OK", "CANCEL", etc. should probably still be handled at the view level, as they typically signal that some view data is ready to be processed or should be discarded, etc. We are working on the best way to unify these two concepts, and assist you to migrate your work with user-defined ICommandEvents to OpenDoc semantic events where appropriate. See "Semantic IHandlers" for more information. See the reference section for further details on this class. ═══ 2.1.3. ODFNotebook - an alternative view for ODFModels ═══ An earlier version of this document mentioned a separate class for a notebook-based view. In our current design, you can now make an INotebook object the client-child of an ODFFormView. You can then make connections between controls on any page of the notebook and data in your model. This yields the same functionality as we planned for the ODFNotebook class; therefore, this class is dropped from the design. ═══ 2.1.4. Container support in the OpenDoc Framework ═══ (this section replaces ODFContainerView and ODFCollectionPart) Since the basic capability to contain parts within parts is integral to OpenDoc, the ODFrk will enhance and extend that capability to move it more toward the level of functionality in the current CUA control and OpenClass IContainerControl et al framework. The major areas of extension include: o layout - built-in functions (virtual) which lay out the objects within a container. Layouts will either be on demand (i.e., like WPShell's "arrange" folder function), or will be automatic. "Automatic" means that the contained parts can be dragged in/out of the container, and an override will be available to allow part-specific logic to determine what cell/location the dropped part should go into. The drag/drop ability can be disabled if desired, of course, in which case only programmatic insertion of new parts will use the override. Additional details TBD as the work progresses. The design goal is to be able to use any of the standard layout canvases (i.e., ISetCanvas or IMultiCellCanvas), or any user-written layout canvases which are compatible with these. o scrolling - built-in functions (virtual) which assist in scrolling the contents of a container. Not sure yet what will happen when parts (i.e., their facets) scroll out of view and possibly get deleted. This will have to be integrated with OpenDoc transforms, which are the OpenDoc-y way to move parts; this may be a non-trivial design problem. As you can tell, there are many unknowns in scrolling support. o inserting/deleting items in a container - questions TBD o details view - this is even more of an unknown topic. The OpenDoc UI Guidelines has not settled yet on whether there should be a details view in an OpenDoc container. The main problem is that OpenDoc containers can hold heterogeneous parts, and CUA container details view was designed assuming homogenous objects. One possibility which is being at least thought of, tho not within current resources, is establishing a protocol whereby OpenDoc parts can act homogeneous by responding to a homogeneous set of functions (analogous to a semantic event suite, but purely for data access). If a part did not respond to a given function, the corresponding column for that part would be empty and non-editable. Again, this design and development work is not within current plan. Those who require a details view should contact us to levy requirements, so we can prioritize our work. ═══ 2.1.5. ODFContainerEditView (a.k.a. Tony's View) ═══ This was mentioned in prior versions of this document. We have determined that this function is specific to non-OpenDoc UIs (including the interior of an OpenDoc part, of course). It has been converted to a proposed feature of OpenClass itself and has been removed from the OpenDoc Framework-specific feature list. ═══ 2.1.6. Semantic IHandlers for use with ODF parts ═══ The semantic events supported by OpenDoc will (according to current specs) be modeled after AppleEvents, and will be grouped into event suites. Current design of OpenDoc will require that part developers code up a "case statement from hell" (as one programmer called it) to look for and process all the events in the suite. Based on our experience with OpenClass, developers prefer to stick with the C++ model of overriding methods if and as necessary. That was one of the reasons for the IHandler classes in OpenClass. The semantic IHandler classes will be specialized subclasses of IHandler (see OpenClass documentation), tailored to each of the OD semantic event suites. Each semantic IHandler will include as much default behavior as is possible, with all methods being virtual so derived classes can override them if necessary. We expect that many methods will be pure virtual because there is no reasonable default behavior. Exactly how this works out must wait until the OD Library supports semantic events and we can see exactly how the underlying support works. These IHandler classes can be attached to OD Framework parts in the same way the current OpenClass IHandlers can be attached to IWindows today. If a part developer has created a part which should respond to a particular semantic event suite, s/he can attach the appropriate semantic IHandler (after deriving to add its part-specific processing for methods) in the part ctor. As in OpenClass, semantic IHandlers can be shared by any number of parts. Additional details TBD as these classes are developed. ═══ 2.1.7. Storage Framework (to assist in using ODStorageUnit & related classes) ═══ The ODFrk storage framework has three main goals: o to simplify the programmer's job in storing and retrieving the persistant data of a part. If the programmer's needs are complex, this framework may not suffice and s/he will have to drop back to OpenDoc classes. The OpenDoc classes are well designed, albeit with some awkward syntax checking. o to allow each class in the ancestry of an object to contribute its own persistant data, and retrieve it as necessary. o to eliminate the awkward syntax checking, which (according to some OD part developers) can easily lead to unexpected and erroneous results. The goal is to do this without actually eliminating any function; we would simply do more thorough cross-checking of parameters prior to calling the underlying OpenDoc storage functions. There are two basic flavors of persistance that we anticipate supporting. The first is the traditional "stream-in/stream-out" paradigm of persistance. This will use the de facto standard of ">>" and "<<" operators. The ODFramework will manage storing the resulting stream for a given part into the document (using ODStorageUnits under the covers) and retrieving it as necessary. The second is similar but will use the OpenDoc storage unit paradigm. Current design thoughts are that this paradigm can be abstracted into a three-part key plus value. Each piece of data can be uniquely identified by: o what class is contributing it. This insures that each class in the ancestry of a part can contribute data and retrieve it. This key could be of type IString or perhaps an ODType (which is a char*). o the value name. This uniquely identified the item of data within the scope of this class. This key would be of type ODType. o the value type. This identifies one of perhaps several formats (e.g, ASCII text vs. rich text) in which the value is stored. This key would be of type ODValueType. The value itself is in the form of a length (ODULong or just unsigned long) and an ODValue (which is a void*). The major design decisions in this form of persistance support relate to performance overhead versus flexibility of data storage. The more elaborate the set of C++ objects used to store the data (e.g., many nested ODStorageUnits), the worse the performance. How good or bad it is remains TBD. ═══ 2.2. Enhancements to OpenClass in support of OD Framework ═══ o Non-rectangular IMultiCell canvas class ??? The goal here is to help with dynamic layout within a non-rectangular area. This assumes the OpenDoc Library achieves some form of non-rectangular HWND, o asStream method, stream ctor (may use <<, >> operators) Selected OpenClass classes will have a method asStream which returns all necessary data to reconstruct the object later. The returned data will be in an IString (which can be used as if it were an ODValue), ready to stuff into an ODStorageUnit. These OpenClass classes will also have a new ctor which takes the output of asStream() and reconstructs the object. The goal here is to help a part save away the state of it's associated view; the assumption is that the view (frame/facet) does the work, using the proposed new OpenClass methods of asStream as an aid. It then passes the stream of data to the part, who saves it along with the part-specific data in its storage unit(s). The reverse is done when a part is initialized or opened, using the new OpenClass stream ctors as an aid. Since, in OpenDoc, the part is the key to persistance (not frames or facets), this data passing between part and frame/facet must be coded by the part developer. Also, whether or not it makes sense to restore the state of a view (e.g., the current scroll position of an MLE) depends on whether the model data portrayed in that MLE has changed since it was last displayed. This also will ultimately need to be part-specific logic, done with the assistance of the OD Framework. Note that it is up to the part to swizzle any references to OpenClass objects as needed ("swizzle" is the act of finding a reference to an object which was formerly at one memory location and is now at another - i.e., you reconstructed it from an ODStorageUnit value stream - and changing the reference to point to the new location). The ctor does no content validity checking, so the caller must insure that the proper string is passed in. The ctor will check for a signature substring which was placed in the stream when it was returned by asStream (e.g., "IBM OpenClass IEntryField"). Classes will be selected based on how they would contribute to a part saving the state of its view(s), so that same part can reconstruct the view later. o Possible extensions to asStream - declare asStream a standard method, implemented uniquely for every class, which recursively runs imbedded and/or composed objects of the receiver, returning a concatinated stream. Reverse also, which implies a method which takes a stream and parses it to set data in existing objects (similar to the stream ctor on an individual OpenClass class above). This method would only be needed when the receiver contains imbedded or composed (imbedded reference to) objects. The implementation of this method is of course the responsibility of the part developer. - add support in OpenClass implementations of asStream to recursively run children of receiver IWindow, returning a concatinated stream. Reverse also, which calls stream ctors to recreate children. This method could probably be implemented completely by OpenClass, since we know how to find all children of an IWindow. It is not yet clear whether an entire panel or container can be recreated this way, nor whether it is really of any usefulness if it can be done (i.e., only the particular view may know what to do). o Drag/drop - ????mappable onto OpenDoc d/d classes???? o Addition of ODStorageUnit structure to the general drag/drop and clipboard support, so it can be used in data transfer even outside of OpenDoc parts. ═══ 2.3. Test Stuff ═══ This will include a shell, a containing part and a non-containing part. The purpose of the shell and the containing part is to allow a unit-test-level validation of customer-written parts, with emphasis on their relation to the shell or part which contains them. The purpose of the containing part and non-containing part is to allow a unit-test-level validation of customer-written shells and containing parts, with emphasis on their relation to the parts they contain. The parts will not only read their state from a storage unit, but will write back to it as well (this has been shown to exercise different code in containing parts). If the OpenDoc toolkit includes a generic shell as planned, then we will not include one. The source code for these test classes will be included, to make it easier to trace into and thru them. It is likely that the test stuff can also serve the role of sample source code (see below). Further details after we have done some part and shell testing ourselves, and probably after we get some user feedback. ═══ 2.4. Sample Source Code ═══ Samples of at least one non-containing part, one containing part and one shell will be included. Samples will use OD Framework classes as applicable. Samples will be well commented. Samples will attempt to actually apply to a real-world situation. The "already-implemented parts" will be considered as a source for these samples. Further details after most of the OD Framework is completed.