OS/2 Shareware BBS: 10 Tools/10-Tools.zip/ibmodf.zip/ODFRDSGN.INF

OS/2 Help File | 1995-06-14 | 35KB | 731 lines

ΓòÉΓòÉΓòÉ 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
[e-mail]


ΓòÉΓòÉΓòÉ 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.