README for OpenDoc® GrafPart

README for
OpenDoc® Graphics Editor Sample Part


Contents

  • Files and their Uses in this Part
  • Functional Description of the GrafPart Sample
  • Compiling the GrafPart Sample
  • Executing the GrafPart Sample
  • Platform Dependance Issues
  • GrafPart Known Bugs and Limitations

  • Files in this part

    Files shipped as Source in the Package

    The following files are shipped in the OpenDoc distribution as source, and are required to rebuild the GrafPart sample (without modification). All of the following files are platform-independent, except as noted.

    src/grafpart/makefile
    makefile for the Graphics editor and its content classes (for use with Nmake)
    src/grafpart/README.htm
    HTML document containing directions for use of the GrafPart sample part (hypertext version of this file)
    src/grafpart/README.txt
    Text file containing directions for use of the GrafPart sample part (flat text version of this file)
    src/grafpart/iodgraph.gif
    Image file of the GrafPart editor icon
    src/grafpart/iodgraph.rc
    Resource script file
    src/grafpart/iodgradc.ico
    Source icon for "document" use (platform-specific)
    src/grafpart/iodgraed.ico
    Source icon for "editor" use (platform-specific)
    src/grafpart/iodgrast.ico
    Source icon for "stationery" use (platform-specific)
    src/grafpart/iodgraph.hpp
    Global constants and defines
    src/grafpart/iodgcomm.cpp
    Global common includes and preprocessor instructions
    src/grafpart/iodgraph.def
    Object export definitions (platform-specific)
    src/grafpart/iodgraph.idl
    SOM interface definition for the Graphics editor class
    src/grafpart/iodgraph.cpp
    C++ implementation for the Graphics editor class
    src/grafpart/iodgfigr.idl
    SOM interface definition for a "virtual" class which generically describes 2D figures.
    src/grafpart/iodgfigr.cpp
    C++ implementation of the 'figure' class
    src/grafpart/iodgpoin.idl
    SOM interface definition of a point figure class, which derives from the 'figure' class.
    src/grafpart/iodgpoin.cpp
    C++ implementation of the point class
    src/grafpart/iodgline.idl
    SOM interface definition of a line figure class, which derives from the 'figure' class
    src/grafpart/iodgline.cpp
    C++ implementation of the line class
    src/grafpart/iodgrect.idl
    SOM interface definition of a rectangle figure class, which derives from the 'line' class.
    src/grafpart/iodgrect.cpp
    C++ implementation of the rect class
    src/grafpart/iodgtext.idl
    SOM interface definition of a text figure class, which derives from the 'rect' class.
    src/grafpart/iodgtext.cpp
    C++ implementation of the text class
    src/grafpart/en_US/iodgraph.msg
    NLS message source for the Graphics editor in English for United States
    src/grafpart/ja_JP/iodgraph.msg
    NLS message source for the Graphics editor in Japanese for Japan

    Files shipped as Binary, or Built

    The following files are shipped in the OpenDoc distribution as prebuilt binaries, and will be overlayed (or ignored) when the GrafPart sample is rebuilt (without modification). These binaries were built with the IBM VisualAge for C++ product.

    src/grafpart/iodgraph.RES
    Binary resource object for the Graphics editor class
    src/grafpart/iodgraph.xih
    Private C++ language bindings for the Graphics editor class
    src/grafpart/iodgraph.obj
    Binary object for the Graphics editor class
    src/grafpart/iodgraph.odt
    Table of contents for the package file (platform-specific)
    src/grafpart/iodgfigr.xih
    Private C++ language bindings for the 'figure' virtual class
    src/grafpart/iodgfigr.obj
    Binary object for the 'figure' virtual class
    src/grafpart/iodgpoin.xih
    Private C++ language bindings for the 'point' figure class
    src/grafpart/iodgpoin.obj
    Binary object for the 'point' figure class
    src/grafpart/iodgline.xih
    Private C++ language bindings for the 'line' figure class
    src/grafpart/iodgline.obj
    Binary object for the 'line' figure class
    src/grafpart/iodgrect.xih
    Private C++ language bindings for the 'rectangle' figure class
    src/grafpart/iodgrect.obj
    Binary object for the 'rectangle' figure class
    src/grafpart/iodgtext.xih
    Private C++ language bindings for the 'text' figure class
    src/grafpart/iodgtext.obj
    Binary object for the 'text' figure class
    dll/iodgraph.dll
    Dynamic Linked Library for the Graphics editor
    include/iodgraph.idl
    Exported copy of the Graphics editor SOM class definition
    include/iodgfigr.idl
    Exported copy of the 'figure' virtual SOM class definition
    include/iodgpoin.idl
    Exported copy of the 'point' figure SOM class definition
    include/iodgline.idl
    Exported copy of the 'line' figure SOM class definition
    include/iodgrect.idl
    Exported copy of the 'rectangle' figure SOM class definition
    include/iodgtext.idl
    Exported copy of the 'text' figure SOM class definition
    include/iodgraph.hpp
    Exported copy of the global constants and defines
    include/iodgraph.xh
    Public C++ language bindings for the Graphic editor class
    include/iodgfigr.xh
    Public C++ language bindings for the 'figure' virtual class
    include/iodgpoin.xh
    Public C++ language bindings for the 'point' figure class
    include/iodgline.xh
    Public C++ language bindings for the 'line' figure class
    include/iodgrect.xh
    Public C++ language bindings for the 'rectangle' figure class
    lib/iodgraph.def
    Exported copy of the object export definitions (platform-specific)
    lib/iodgraph.lib
    Linked object archive of all class objects
    lib/iodgraph.exp
    Binary export list
    src/grafpart/en_US/iodgraph.cat
    Compiled NLS message catalog for the Graphics editor in English for United States
    pkg/iodgraph.odz
    Install-ready compressed binary-only part install file

    Back to the Table of Contents.


    Function Description

    GrafPart is a sample of OpenDoc component software (part), which provides basic two-dimensional vector graphics capabilities. It is provided to serve as a model which OpenDoc part developers can use as a basis in designing more sophisticated graphics-related parts, as well as to provide an embeddable basic graphic function to the shipped set of GrafPart sample parts.

    Inherited Behaviors

    The GrafPart is subclassed from the BaseContainer, which in turn, is subclassed from ODPart, and thus inherits all part behaviors, such as

    Due to GrafPart's inheritance from BaseContainer, it provides a set of container part behaviors, such as

    Inherited Content types

    GrafPart will display in its Embed menu all the part kinds currently registered in the system, and allow the user to embed them as in the BaseContainer

    Intrinsic Behaviors

    The intrinsic content is selectable and can be manipulated once selected via keyboard/mouse input or clipboard functions. Specific manipulations vary by figure type.

    Intrinsic Content types

    In addition to being able to imbed other OpenDoc part kinds, GrafPart may also embed intrinsic content types and manipulate them as peers of full OpenDoc part kinds. Intrinsic contents are instances of a set of classes called "figures", which implement basic two-dimensional vector graphic primitives, and include:

    With provisions for the user to implement these additional types:

    * - "Text" is not fully supported first-class implementation at this time, that is, the class may be instantiated programmatically (ie., though the scripting interface), but is not supported by GrafPart GUI, and thus cannot created interactively.

    Back to the Table of Contents.


    Compiling the GrafPart Sample

    The GrafPart binaries are shipped as compiled with IBM's VisualAge for C++ compilers on Windows and OS/2 platforms, with the nmake macro 'ODDebug' turned on. The GrafPart source code also uses a local CPP symbol, 'GPDebug', to control various debugging functions. Specifically, if GrafPart is compiled with the GPDebug CPP symbol defined, the following will occur:

    Trace messages are activated
    Each method of the GrafPart sample source code contains a message that is printed upon invocation, and another upon exit. In addition, many methods output various additional messages indicating status and parameter content. The output of these messages may be viewed by starting a receiver application, such as the MsgDisp.exe utility (on Windows platforms), or the PMPrintf.exe utility (on OS/2 platforms). With the appropriate message receiver application running, the performance of the GrafPart will be impacted, more severely with greater volume of embedded content. However, normal OpenDoc part performance can be regained simply by closing the receiver application. With the GPDebug CPP symbol not defined, no messages will be sent, regardless of the presence of a receiver application.
    NLS catalog function is asserted
    If NLS catalog function fails, then default string values are used. If the GrafPart was compiled with the GPDebug CPP symbol defined, then those default string values will be in ALL UPPERCASE TEXT, to allow the developer to distinguish the default strings from strings obtained from an NLS catalog in the same language ("en_US"). The strings specifically affect by this feature are the menu items which GrafPart defines, which are:
  • the intrinsic content types in the "Embed" menu, and
  • the "Refresh screen" item in the "Options" menu.
    With the GPDebug CPP symbol not defined, The default strings will appear in mixed case, indistinguishable from the catalog strings for the locale, en_US. In most cases, failure of NLS catalog function is a result of bad or missing definition of the LOCALE and NLSPATH environment variables.
  • If you wish to recompile the GrafPart sample with these functions enabled, you must first clear the system of any of the existing GrafPart binaries. From the %ODBASE%/samples/src/grafpart directory, issue the following:

    Nmake clean The GPDebug CPP symbol may be defined in two ways:
  • By uncommenting the line (remove the leading "#") in the makefile which currently reads: #ExtraCompileOptions = -DGPDebug
  • By invoking Nmake with an explicit command-line macro definition: Nmake "ExtraCompileOptions = -DGPDebug"

    Back to the Table of Contents.


    Executing the GrafPart Sample

    The GrafPart editor may be started in any of the manners an OpenDoc part may usually be run.

    Adds to two of BaseContainer's main menubar items, Embed and Options. In its Embed menu, GrafPart shows all the currently registered OpenDoc part kinds, and then below a menu separator line all of the currently implemented intrinsic content types.

    Unlike embedding OpenDoc part kinds, GrafPart intrinsic content types are embedded with a drag operation, as follows:

    1. Select "Embed" from the main menu.
    2. Select the desired intrinsic type in the pull-down menu, from amongst the items listed below the menu separator line.
    3. Press mouse button 1 in the GrafPart content area at the first point of the figure.
    4. Keeping MB1 depressed, drag the mouse to the second point in the desired figure. A representation of the figure will appear interactively, "rubberbanding" as you drag the mouse.
    5. Release MB1 at the second point.

    For the "Point" type, you may use the above described method, or simply place the cursor where the point is desired and click MB1.

    As an aid to performance tuning and a demonstration vehicle, the method of updating the screen during the "rubberbanding" process is user-selectable at run-time. In the environment from which DocShell will be started, set an environment variable 'GP_REFRESH' to a value between '1' and '3', with the following meanings:

    GP_REFRESH=1
    The whole current frame will be invalidated with each pixel of mouse movement. This is the most time- and resource-intensive method, but is smoothest performing method on systems with the speed to handle it. This is the default if the GP_REFRESH environment variable is not set.
    GP_REFRESH=2
    Only the shape of the current figure in the current facet will be invalidated with each pixel of mouse movement. This is less resource- and computation-intensive, but is still a synchronous process.
    GP_REFRESH=3
    The shape of the current figure in the current facet will be updated with each pixel of mouse movement. This is the least resource- and computation-intensive, as it is an asynchronous process, but may produce 'jumpy' feedback performance on slower systems.

    In the Options main menubar, GrafPart implements a "Refresh Screen" menu item, which, when selected, will immediately perform a invalidation on all frames belonging to that GrafPart instance, synchronizing them and causing them to redraw their contents. This useful if more than one frame exists, or if the content area has become polluted due to a drag operation.

    Back to the Table of Contents.


    Platform Dependance Issues

    GrafPart is written to utilize National Language Support for catalogs. Its proper operation for the display of its implemented menu items is dependant on settings of the LANG and NLSPATH environment variables.

    Back to the Table of Contents.


    GrafPart Known Bugs and Limitations

    Back to the Table of Contents.


    ©. 1996 IBM Corporation. All rights reserved.

    Last updated: 2/7/97 17:42:28