Added revamped Object Graphics Library (for node/arc diagrams).

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@305 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

utils/ogl/docs/bugs.tex

@@ -0,0 +1,11 @@
+\chapter{Bugs}\label{bugs}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}
+
+These are the known bugs.
+
+\begin{itemize}\itemsep=0pt
+\item In the OGLEdit sample, .dia files are output double-spaced
+due to an unidentified bug in the way a stream is converted to a file.
+\end{itemize}
+

utils/ogl/docs/changes.tex

@@ -0,0 +1,9 @@
+\chapter{Change log}
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}
+
+Version 2.0, June 1st 1996
+
+\begin{itemize}\itemsep=0pt
+\item First publically released version.
+\end{itemize}

utils/ogl/docs/intro.tex

@@ -0,0 +1,45 @@
+\chapter{Introduction}
+\pagenumbering{arabic}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}
+
+Object Graphics Library (\ogl) is a C++ library supporting the creation and
+manipulation of simple and complex graphic images on a canvas.
+
+It can be found in the directory {\tt utils/ogl/src} in the
+wxWindows distribution. The file {\tt ogl.h} must be included to make use
+of the library.
+
+Please see \helpref{OGL overview}{ogloverview} for a general description how the object library works. For details,
+please see the \helpref{class reference}{classref}.
+
+\section{File structure}
+
+These are the files that comprise the \ogl\ library.
+
+\begin{description}\itemsep=0pt
+\item[basic.h] Header for basic objects such as wxShape and wxRectangleShape.
+\item[basic.cpp] Basic objects implementation (1).
+\item[basic2.cpp] Basic objects implementation (2).
+\item[bitmap.cpp] wxBitmapShape class header.
+\item[bitmap.cpp] wxBitmapShape implementation.
+\item[canvas.h] wxShapeCanvas class header.
+\item[canvas.cpp] wxShapeCanvas class implementation.
+\item[composit.h] Composite object class header.
+\item[composit.cpp] Composite object class implementation.
+\item[constrnt.h] Constraint classes header.
+\item[constrnt.cpp] Constraint classes implementation.
+\item[divided.h] Divided object class header.
+\item[divided.cpp] Divided object class implementation.
+\item[drawn.h] Drawn (metafile) object class header.
+\item[drawn.cpp] Drawn (metafile) object class implementation.
+\item[graphics.h] Main include file.
+\item[lines.h] wxLineShape class header.
+\item[lines.cpp] wxLineShape class implementation.
+\item[misc.h] Miscellaneous graphics functions header.
+\item[misc.cpp] Miscellaneous graphics functions implementation.
+\item[ogldiag.h] wxDiagram class header.
+\item[ogldiag.cpp] wxDiagram implementation.
+\end{description}
+
+

utils/ogl/docs/ogl.hpj

@@ -0,0 +1,17 @@
+[OPTIONS]
+BMROOT=d:\wx2\wxwind~1\utils\ogl\docs ; Assume that bitmaps are where the source is
+TITLE=OGL Manual
+CONTENTS=Contents
+COMPRESS=HIGH
+
+[FILES]
+ogl.rtf
+
+[CONFIG]
+CreateButton("Up", "&Up", "JumpId(`ogl.hlp', `Contents')")
+BrowseButtons()
+
+[MAP]
+
+[BITMAPS]
+

utils/ogl/docs/ogl.tex

@@ -0,0 +1,38 @@
+\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}
+\newcommand{\ogl}[0]{{OGL}}
+\input psbox.tex
+\parindent 0pt
+\parskip 11pt
+\title{Manual for Object Graphics Library 3.0}
+\author{Julian Smart}
+\date{July 1998}
+
+\makeindex
+\begin{document}
+\maketitle
+
+\pagestyle{fancyplain}
+\bibliographystyle{plain}
+\pagenumbering{roman}
+\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}
+\setfooter{\thepage}{}{}{}{}{\thepage}
+\tableofcontents%
+
+\input{intro.tex}
+%
+\input{sample.tex}
+%
+\input{classes.tex}
+%
+\input{topics.tex}
+%
+\input{bugs.tex}
+%
+\input{changes.tex}
+
+%
+\addcontentsline{toc}{chapter}{Index}
+\setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+\printindex
+\end{document}

utils/ogl/docs/sample.tex

@@ -0,0 +1,128 @@
+\chapter{OGLEdit: a sample OGL application}\label{ogledit}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}
+
+OGLEdit is a sample OGL application that allows the user to draw, edit,
+save and load a few shapes. It should clarify aspects of OGL usage, and
+can act as a template for similar applications. OGLEdit can be found in\rtfsp
+{\tt samples/ogledit} in the OGL distribution.
+
+$$\image{10cm;0cm}{ogledit.eps}$$\par
+
+The wxWindows document/view model has been used in OGL, to reduce the amount of
+housekeeping logic required to get it up and running. OGLEdit also provides
+a demonstration of the Undo/Redo capability supported by the document/view classes,
+and how a typical application might implement this feature.
+
+{\it Note:} A bug in the wxWindows document/view implementation before
+version 1.66C may cause Do/Undo to misbehave and get out of sync. If this is the case,
+please replace wxCommandProcessor::Submit with the following in wx\_doc.cpp.
+
+{\small
+\begin{verbatim}
+  Bool wxCommandProcessor::Submit(wxCommand *command, Bool storeIt)
+  {
+    Bool success = command->Do();
+    if (success && storeIt)
+    {
+      if (commands.Number() == maxNoCommands)
+      {
+        wxNode *firstNode = commands.First();
+        wxCommand *firstCommand = (wxCommand *)firstNode->Data();
+        delete firstCommand;
+        delete firstNode;
+      }
+
+      // Correct a bug: we must chop off the current 'branch'
+      // so that we're at the end of the command list.
+      if (currentCommand)
+      {
+        wxNode *node = currentCommand->Next();
+        while (node)
+        {
+          wxNode *next = node->Next();
+          delete node;
+          node = next;
+        }
+      }
+    
+      commands.Append(command);
+      currentCommand = commands.Last();
+      SetMenuStrings();
+    }
+    return success;
+  }
+\end{verbatim}
+}
+
+\section{OGLEdit files}
+
+OGLEdit comprises the following source files.
+
+\begin{itemize}\itemsep=0pt
+\item doc.h, doc.cpp: MyDiagram, DiagramDocument, DiagramCommand, MyEvtHandler
+classes related to diagram functionality and documents.
+\item view.h, view.cpp: MyCanvas, DiagramView classes related to visualisation of
+the diagram.
+\item ogledit.h, ogledit.cpp: MyFrame, MyApp classes related to the overall application.
+\item palette.h, palette.cpp: EditorToolPalette implementing the shape palette.
+\end{itemize}
+
+\section{How OGLEdit works}
+
+OGLEdit defines a DiagramDocument class, each of instance of which holds a MyDiagram
+member which itself contains the shapes.
+
+In order to implement specific mouse behaviour for shapes, a class MyEvtHandler is
+defined which is `plugged into' each shape when it is created, instead of overriding each shape class
+individually. This event handler class also holds a label string.
+
+The DiagramCommand class is the key to implementing Undo/Redo. Each instance of DiagramCommand
+stores enough information about an operation (create, delete, change colour etc.) to allow
+it to carry out (or undo) its command. In DiagramView::OnMenuCommand, when the user initiates the
+command, a new DiagramCommand instance is created which is then sent to the document's
+command processor (see wxWindows manual for more information about doc/view and command
+processing).
+
+Apart from menu commands, another way commands are initiated is by the user left-clicking on
+the canvas or right-dragging on a node. MyCanvas::OnLeftClick in view.cpp shows how
+the appropriate wxClassInfo is passed to a DiagramCommand, to allow DiagramCommand::Do
+to create a new shape given the wxClassInfo.
+
+The MyEvtHandler right-drag methods in doc.cpp implement drawing a line between
+two shapes, detecting where the right mouse button was released and looking for a second
+shape. Again, a new DiagramCommand instance is created and passed to the command
+processor to carry out the command.
+
+DiagramCommand::Do and DiagramCommand::Undo embody much of the
+interesting interaction with the OGL library. A complication of note
+when implementing undo is the problem of deleting a node shape which has
+one or more arcs attached to it. If you delete the node, the arc(s)
+should be deleted too. But multiple arc deletion represents more information
+that can be incorporated in the existing DiagramCommand scheme. OGLEdit
+copes with this by treating each arc deletion as a separate command, and
+sending Cut commands recursively, providing an undo path. Undoing such a
+Cut will only undo one command at a time - not a one to one
+correspondence with the original command - but it's a reasonable
+compromise and preserves Do/Undo whilst keeping our DiagramCommand class
+simple.
+
+\section{Possible enhancements}
+
+OGLEdit is very simplistic and does not employ the more advanced features
+of OGL, such as:
+
+\begin{itemize}\itemsep=0pt
+\item attachment points (arcs are drawn to particular points on a shape)
+\item metafile and bitmaps shapes
+\item divided rectangles
+\item composite shapes, and constraints
+\item creating labels in shape regions
+\item arc labels (OGL has support for three movable labels per arc)
+\item spline and multiple-segment line arcs
+\item adding annotations to node and arc shapes
+\item line-straightening (supported by OGL) and alignment (not supported directly by OGL)
+\end{itemize}
+
+These could be added to OGLEdit, at the risk of making it a less
+useful example for beginners.

utils/ogl/docs/tex2rtf.ini

@@ -0,0 +1,20 @@
+runTwice = yes
+titleFontSize = 12
+authorFontSize = 10
+chapterFontSize = 12
+sectionFontSize = 12
+subsectionFontSize = 12
+headerRule = yes
+footerRule = yes
+useHeadingStyles = yes
+listItemIndent=40
+generateHPJ = no
+htmlBrowseButtons = bitmap
+winHelpVersion = 3
+winHelpContents = yes
+winHelpTitle = "OGL Manual"
+truncateFilenames = yes
+combineSubSections = yes
+\overview [2] {\rtfonly{See also }\sethotspotcolour{off}\sethotspotunderline{on}\winhelponly{\image{}{books.bmp}}
+\htmlonly{\image{}{books.gif}}\helpref{#1}{#2}
+\sethotspotcolour{on}\sethotspotunderline{on}}

utils/ogl/docs/topics.tex

@@ -0,0 +1,163 @@
+\chapter{Topic overviews}
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}
+
+The following sections describe particular topics.
+
+\section{OGL overview}\label{ogloverview}
+
+\helpref{wxShapeCanvas}{wxshapecanvas}, derived from {\bf wxCanvas}, is the drawing area
+for a number of \helpref{wxShape}{wxshape} instances. Everything drawn on a
+wxShapeCanvas is derived from wxShape, which provides virtual
+member functions for redrawing, creating and destroying
+resize/selection `handles', movement and erasing behaviour, mouse
+click behaviour, calculating the bounding box of the shape, linking
+nodes with arcs, and so on.
+
+The way a client application copes with `damage' to the canvas is to
+erase (white out) anything should no longer be displayed, redraw the shape,
+and then redraw everything on the canvas to repair any damage. If quick edit
+mode is on for the canvas, the complete should be omitted by OGL and the
+application.
+
+Selection handles (called control points in the code) are implemented as
+wxRectangleShapes.
+
+Events are passed to shapes by the canvas in a high-level form, for example {\bf OnLeftClick},
+{\bf OnBeginDragLeft}, {\bf OnDragLeft}, {\bf OnEndDragLeft}. The canvas decides
+what is a click and what is a drag, whether it is on a shape or the canvas itself,
+and (by interrogating the shape) which attachment point the click is associated with.
+
+In order to provide event-handling flexibility, each shapes has an `event handler' associated with it,
+which by default is the shape itself (all shapes derive from wxShapeEvtHandler).
+An application can modify the event-handling behaviour simply by plugging a new
+event handler into the shape. This can avoid the need for multiple inheritance when
+new properties and behaviour are required for a number of different shape classes: instead
+of overriding each class, one new event handler class can be defined and used for all
+existing shape classes.
+
+A range of shapes have been predefined in the library, including rectangles, ellipses,
+polygons. A client application can derive from these shapes and/or derive entirely
+new shapes from wxShape.
+
+Instances of a class called \helpref{wxDiagram}{wxdiagram} organise collections of
+shapes, providing default file input and output behaviour.
+
+
+\section{wxDividedShape overview}\label{dividedshapeoverview}
+
+Classes: \helpref{wxDividedShape}{wxdividedshape}
+
+A wxDividedShape is a rectangle with a number of vertical divisions. Each
+division may have its text formatted with independent characteristics, and
+the size of each division relative to the whole image may be specified.
+
+Once a wxDividedShape has been created, the user may move the divisions with the
+mouse. By pressing Ctrl while right-clicking, the region attributes can be edited.
+
+Here are examples of creating wxDividedShape objects:
+
+{\small
+\begin{verbatim}
+  /*
+   * Divided rectangle with 3 regions
+   *
+   */
+
+  wxDividedShape *dividedRect = new wxDividedShape(50, 60);
+
+  wxShapeRegion *region = new wxShapeRegion;
+  region->SetProportions(0.0, 0.25);
+  dividedRect->AddRegion(region);
+
+  region = new wxShapeRegion;
+  region->SetProportions(0.0, 0.5);
+  dividedRect->AddRegion(region);
+
+  region = new wxShapeRegion;
+  region->SetProportions(0.0, 0.25);
+  dividedRect->AddRegion(region);
+  
+  dividedRect->SetSize(50, 60); // Allow it to calculate region sizes
+  dividedRect->SetPen(wxBLACK_PEN);
+  dividedRect->SetBrush(wxWHITE_BRUSH);
+  dividedRect->Show(TRUE);
+  dividedRect->NameRegions();
+
+  /*
+   * Divided rectangle with 3 regions, rounded
+   *
+   */
+
+  wxDividedShape *dividedRect3 = new wxDividedShape(50, 60);
+  dividedRect3->SetCornerRadius(-0.4);
+
+  region = new wxShapeRegion;
+  region->SetProportions(0.0, 0.25);
+  dividedRect3->AddRegion(region);
+
+  region = new wxShapeRegion;
+  region->SetProportions(0.0, 0.5);
+  dividedRect3->AddRegion(region);
+
+  region = new wxShapeRegion;
+  region->SetProportions(0.0, 0.25);
+  dividedRect3->AddRegion(region);
+  
+  dividedRect3->SetSize(50, 60); // Allow it to calculate region sizes
+  dividedRect3->SetPen(wxBLACK_PEN);
+  dividedRect3->SetBrush(wxWHITE_BRUSH);
+  dividedRect3->Show(TRUE);
+  dividedRect3->NameRegions();
+\end{verbatim}
+}
+
+
+\section{wxCompositeShape overview}\label{compositeshapeoverview}
+
+Classes: \helpref{wxCompositeShape}{wxcompositeshape}, \helpref{OGLConstraint}{oglconstraint}
+
+The wxCompositeShape allows fairly complex shapes to be created, and maintains
+a set of constraints which specify the layout and proportions of child shapes.
+
+Add child shapes to a wxCompositeShape using \helpref{AddChild}{wxcompositeshapeaddchild}, and
+add constraints using \helpref{AddConstraint}{wxcompositeshapeaddconstraint}.
+
+After children and shapes have been added, call \helpref{Recompute}{wxcompositeshaperecompute} which
+will return TRUE is the constraints could be satisfied, FALSE otherwise. If
+constraints have been correctly and consistently specified, this call will succeed.
+
+If there is more than one child, constraints must be specified: OGL cannot calculate
+the size and position of children otherwise. Don't assume that children will simply
+move relative to the parent without the use of constraints.
+
+To specify a constraint, you need three things:
+
+\begin{enumerate}\itemsep=0pt
+\item a constraint type, such as gyCONSTRAINT\_CENTRED\_VERTICALLY;
+\item a reference shape, with respect to which other shapes are going to be positioned - the\rtfsp
+{\it constraining} shape;
+\item a list of one or more shapes to be constrained: the {\it constrained} shapes.
+\end{enumerate}
+
+The constraining shape can be either the parent of the constrained shapes, or a sibling. The
+constrained shapes must all be siblings of each other.
+
+For an exhaustive list and description of the available constraint types, see the \helpref{OGLConstraint constructor}{oglconstraintconstr}.
+Note that most constraints operate in one dimension only (vertically or horizontally), so you will
+usually need to specify constraints in pairs.
+
+You can set the spacing between constraining and constrained shapes by
+calling \helpref{OGLConstraint::SetSpacing}{oglconstraintsetspacing}.
+
+Finally, a wxCompositeShape can have {\it divisions}, which are special child shapes of class
+wxDivisionShape (not to be confused with wxDividedShape). The purpose of this is to allow
+the composite to be divided into user-adjustable regions (divisions) into which other shapes
+can be dropped dynamically, given suitable application code. Divisons allow the child
+shapes to have an identity of their own - they can be manipulated independently of their container -
+but to behave as if they are contained with the division, moving with the parent shape.
+Divisions boundaries can themselves be moved using the mouse.
+
+To create an initial division, call \helpref{wxCompositeShape::MakeContainer}{wxcompositeshapemakecontainer}.
+Make further divisions by calling \helpref{wxDivisionShape::Divide}{wxdivisionshapedivide}.
+