README for OpenDoc® GrafPart
README for
OpenDoc® Graphics Editor Sample Part
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
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
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.
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
- drag/drop support,
- persistence,
- properties,
- clipboard operations,
- base menubar,
- drafts,
and
- printing.
Due to GrafPart's inheritance from BaseContainer,
it provides a set of container part behaviors,
such as
- embedding,
- selection,
- activation,
- non-rectangular frames,
and
- content part
- Z-order maintenance,
and
- background color manipulation.
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
The intrinsic content is selectable and can be manipulated
once selected via keyboard/mouse input or clipboard functions.
Specific manipulations vary by figure type.
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:
- Point
- Line
- Rectangle
- Text*
With provisions for the user to implement these additional types:
- Circle
- Ellipse
- Polyline
- Polygon
- Freehand
- Image
* - "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.
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.
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:
- Select "Embed" from the main menu.
- Select the desired intrinsic type in the pull-down menu, from amongst the
items listed below the menu separator line.
- Press mouse button 1 in the GrafPart content area at the
first point of the figure.
- 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.
- 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.
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.
- Due to NLS dependance, GrafPart requires an NLS-compliant compiler. Currently it has only
been tested with IBM's VisualAge for C++ compilers on Windows and OS/2 platforms.
- No keypress handling.
- Limited available implemented intrinsic content types.
- No editing of intrinsic content types, besides move and resize.
- Intrinsic content types have no user-definable or editable attributes.
- Some possible user scenarios may be confusing, such as attempting
to embed within the selection threshold of an intrinsic content item.
- Unnecessary screen refreshes under certain conditions.
Back to the Table of Contents.
©. 1996 IBM Corporation. All rights reserved.
Last updated: 2/7/97 17:42:28