Added OGL to contrib

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

contrib/docs/latex/ogl/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}
+

contrib/docs/latex/ogl/changes.tex

@@ -0,0 +1,19 @@
+\chapter{Change log}
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}
+
+Version 3.0, September 8th 1998
+
+\begin{itemize}\itemsep=0pt
+\item Version for wxWindows 2.0.
+\item Various enhancements especially to wxDrawnShape
+(multiple metafiles, for different orientations).
+\item More ability to override functions e.g. OnSizeDragLeft, so events can be
+intercepted for Do/Undo.
+\end{itemize}
+
+Version 2.0, June 1st 1996
+
+\begin{itemize}\itemsep=0pt
+\item First publicly released version.
+\end{itemize}

contrib/docs/latex/ogl/intro.tex

@@ -0,0 +1,47 @@
+\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[bmpshape.h] wxBitmapShape class header.
+\item[bmpshape.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.
+\item[mfutils.h] Metafile utilities header.
+\item[mfutils.cpp] Metafile utilities implementation.
+\end{description}
+
+

contrib/docs/latex/ogl/ogl.hpj

@@ -0,0 +1,17 @@
+[OPTIONS]
+BMROOT=d:\wx2\wxwind~1\docs\latex\ogl ; 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]
+

contrib/docs/latex/ogl/ogl.tex

@@ -0,0 +1,46 @@
+\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}
+\newcommand{\ogl}[0]{{OGL}}%
+\definecolour{black}{0}{0}{0}%
+\definecolour{cyan}{0}{255}{255}%
+\definecolour{green}{0}{255}{0}%
+\definecolour{magenta}{255}{0}{255}%
+\definecolour{red}{255}{0}{0}%
+\definecolour{blue}{0}{0}{200}%
+\definecolour{yellow}{255}{255}{0}%
+\definecolour{white}{255}{255}{255}%
+\input psbox.tex
+\parindent 0pt
+\parskip 11pt
+\title{Object Graphics Library 3.0}
+\author{Julian Smart}
+\date{September 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}

contrib/docs/latex/ogl/sample.tex

@@ -0,0 +1,87 @@
+\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.
+
+\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.

contrib/docs/latex/ogl/tex2rtf.ini

@@ -0,0 +1,35 @@
+;    Last change:  JS    8 Sep 98    2:54 pm
+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 }\settransparency{on}\sethotspotcolour{off}\sethotspotunderline{on}\winhelponly{\image{}{books.bmp}\settransparency{off}}
+\htmlonly{\image{}{books.gif}}\helpref{#1}{#2}
+\sethotspotcolour{on}\sethotspotunderline{on}}
+\docparam [2]{\parskip{0}{\it #1}\htmlignore{\par}\parskip{10}\indented{1cm}{#2}}
+\wxheading [1]{{\bf \htmlignore{\fcol{blue}{#1}}\htmlonly{\fcol{red}{#1}}}}
+\const [0] {{\bf const}}
+\constfunc [3] {{\bf #1} {\bf #2}(#3) {\bf const}\index{#2}}
+\windowstyle [1] {{\bf #1}\index{#1}}
+
+;;
+;; These two are for generating MS HTML Help project, contents and index files.
+;;
+htmlWorkshopFiles = true
+htmlIndex = true
+\pythonnote [1] {{\bf \fcol{blue}{wxPython note:}} #1}
+%\pythonnote [1] {}
+

contrib/docs/latex/ogl/texhelp.sty

@@ -0,0 +1,298 @@
+% LaTeX style file
+% Name:   texhelp.sty
+% Author: Julian Smart
+%
+% Purpose
+% -------
+% Style file to enable the simultaneous preparation of printed LaTeX and on-line
+% hypertext manuals.
+% Use in conjunction with Tex2RTF (see Tex2RTF documentation).
+%
+% Note that if a non-ASCII character starts a newline and there should be a space
+% between the last word on the previous line and the first word on this line,
+% you need to use \rtfsp to generate a space in Windows Help. \rtfsp is ignored
+% in all other formats.
+%
+% Julian Smart
+% Artificial Intelligence Applications Institute
+%
+%
+% ============== C++/CLIPS Documentation Facilities ==============
+%
+% Each class definition should be typeset with e.g.
+%
+% \section{\class{Name}: Parent}
+%
+% followed by a description of the class.
+% Each member should follow:
+%
+% \membersection{wxName::Member}
+%
+% with a description of what this member does.
+% Then, one (or more if overloaded) member (function) in detail:
+%
+% \func{return type}{name}{args}
+% or
+% \member{type}{name}
+%
+% where args is a list of \param{type}{name}, ...
+
+% Function, e.g.
+% e.g. to typeset
+%
+% void DoIt(char *string);
+%
+% write:
+%
+% \func{void}{DoIt}{\param{char *}{string}}
+%
+
+\newcommand{\func}[3]{\hangafter=1\noindent\hangindent=10mm
+{{\it #1} {\bf #2}\index{#2}}(#3)}
+
+% For function/type definition where the name is a pointer,
+% e.g. to typeset
+%
+% typedef void (*wxFunction)(wxObject&)
+%
+% write:
+%
+% \pfunc{typedef void}{wxFunction}{param{wxObject&}}
+
+\newcommand{\pfunc}[3]{\hangafter=1\noindent\hangindent=10mm
+{{\it #1} ({\bf *#2})\index{#2}}(#3)}
+
+% Use an ordinary \section command for class name definitions.
+
+% This is used for a member, such as wxBitmap: GetDepth
+\newcommand{\membersection}[1]{\subsection*{#1}\index{#1}}
+
+% CLIPS function
+\newcommand{\clipsfunc}[3]{\hangafter=1\noindent\hangindent=10mm
+{{\bf #1} ({\bf #2}\index{#2}}#3)}
+
+\newcommand{\clipssection}[1]{\chapter{#1}}
+
+% This is used for a CLIPS function name
+\newcommand{\functionsection}[1]{\subsection*{#1}}
+
+% Member: a type and a name
+\newcommand{\member}[2]{{\bf #1 \it #2}}
+
+% C++ Parameter: a type and a name (no intervening space)
+\newcommand{\param}[2]{{\it #1}{\bf #2}}
+
+% CLIPS Parameter: a type and a name (one intervening space)
+\newcommand{\cparam}[2]{{\bf #1} {\it #2}}
+
+% Class: puts in index
+\newcommand{\class}[1]{#1\index{#1}}
+
+%\newcommand{\docparam}[2]{\parskip=0pt {\it #1}\par\parskip=10pt\begin{indented}{1cm}{#2}\end{indented}}
+
+% Void type
+\newcommand{\void}{{\it void}}
+
+% Typeset destructor
+\newcommand{\destruct}[1]{{$\sim$}#1}
+
+% Typeset insert/extract operators
+\newcommand{\cinsert}{$<<$}
+\newcommand{\cextract}{$>>$}
+
+
+% =================== Hypertext facilities ===================
+%
+% To insert hyperlinks (or references, in Latex), \label the sections
+% or membersections \label{ref-label} immediately after the section, on the same line,
+% and use \helpref{text-to-show}{ref-label} to make a reference.
+%
+
+% Type text with section reference
+\newcommand{\helpref}[2]{{\it #1} (p.\ \pageref{#2}) }
+
+% Type text with URL in verbatim mode
+\newcommand{\urlref}[2]{#1 (\verb$#2$)}
+
+% Don't typeset section number in LaTeX
+\newcommand{\helprefn}[2]{{\it #1}}
+
+% Like helpref, but popup text in WinHelp instead of hyperlinked
+\newcommand{\popref}[2]{{\it #1}}
+
+% Like footnote, but popup text.
+\newcommand{\footnotepopup}[2]{{\it #1}\footnote{#2}}
+
+% =================== On-line help specific macros ===================
+%
+
+% Global document font size/family, help only.
+\newcommand{\helpfontsize}[1]{}
+\newcommand{\helpfontfamily}[1]{}
+
+% Ignore in all on-line help
+\newcommand{\helpignore}[1]{#1}
+% Only print in all on-line help
+\newcommand{\helponly}[1]{}
+
+% Ignore in LaTeX
+\newcommand{\latexignore}[1]{}
+% Only print in LaTeX
+\newcommand{\latexonly}[1]{#1}
+
+% Ignore in linear RTF
+\newcommand{\rtfignore}[1]{#1}
+% Only print in linear RTF
+\newcommand{\rtfonly}[1]{}
+
+% Ignore in WinHelp RTF
+\newcommand{\winhelpignore}[1]{#1}
+% Only print in WinHelp RTF
+\newcommand{\winhelponly}[1]{}
+
+% Ignore in wxHelp
+\newcommand{\xlpignore}[1]{#1}
+% Only print in wxHelp
+\newcommand{\xlponly}[1]{}
+
+% Ignore in HTML
+\newcommand{\htmlignore}[1]{#1}
+% Only print in HTML
+\newcommand{\htmlonly}[1]{}
+
+% Input a file only for help system (binder thickness is not a limitation
+% in help systems!)
+\newcommand{\helpinput}[1]{}
+
+\newcommand{\rtfsp}{ } % Force a space in RTF, ignore in Latex
+
+% =================== Miscellaneous macros ===================
+%
+% Headings consistent with generated ones
+\newcommand{\myheading}[1]{\vspace*{25pt}
+\begin{flushleft}
+{\LARGE \bf #1}
+\end{flushleft}
+\vskip 20pt
+}
+
+% Heading with entry in contents page.
+\newcommand{\chapterheading}[1]{\myheading{#1}
+\addcontentsline{toc}{chapter}{#1}}
+
+\newcommand{\sectionheading}[1]{\myheading{#1}
+\addcontentsline{toc}{section}{#1}}
+
+% Glossary environment
+\newenvironment{helpglossary}{\newpage\chapterheading{Glossary}\begin{description}}{\end{description}}
+
+% Glossary entry
+\newcommand{\gloss}[1]{\item[#1]\index{#1}}
+
+% Image: EPS in Latex, BMP or MF (whatever's available) in RTF. Requires psbox.
+\newcommand{\image}[2]{\psboxto(#1){#2}}
+
+% Image, left aligned (HTML)
+\newcommand{\imager}[2]{\psboxto(#1){#2}}
+
+% Image, right aligned (HTML)
+\newcommand{\imagel}[2]{\psboxto(#1){#2}}
+
+% Imagemap: principally for HTML only. In Latex,
+% acts like \image.
+\newcommand{\imagemap}[3]{\psboxto(#1){#2}}
+
+% Headers and footers
+% \setheader{EvenPageLeft}{EvenPageCentre}{EvenPageRight}
+% {OddPageLeft}{OddPageCentre}{OddPageRight}
+\newcommand{\setheader}[6]{
+\lhead[\fancyplain{}{#1}]{\fancyplain{}{#4}}
+\chead[\fancyplain{}{#2}]{\fancyplain{}{#5}}
+\rhead[\fancyplain{}{#3}]{\fancyplain{}{#6}}
+}
+
+% \setfooter{EvenPageLeft}{EvenPageCentre}{EvenPageRight}
+% {OddPageLeft}{OddPageCentre}{OddPageRight}
+\newcommand{\setfooter}[6]{
+\lfoot[\fancyplain{#1}{#1}]{\fancyplain{#4}{#4}}
+\cfoot[\fancyplain{#2}{#2}]{\fancyplain{#5}{#5}}
+\rfoot[\fancyplain{#3}{#3}]{\fancyplain{#6}{#6}}
+}
+
+% Needed for telling RTF where margin paragraph should go
+% in mirrored margins mode.
+\newcommand{\marginpareven}[1]{\hspace*{0pt}\marginpar{#1}}
+\newcommand{\marginparodd}[1]{\hspace*{0pt}\marginpar{#1}}
+
+% Environment for two-column table popular in WinHelp and manuals.
+\newcommand{\twocolwidtha}[1]{\def\twocolwidthaval{#1}}
+\newcommand{\twocolwidthb}[1]{\def\twocolwidthbval{#1}}
+\newcommand{\twocolspacing}[1]{\def\twocolspacingval{#1}}
+
+\twocolwidtha{3cm}
+\twocolwidthb{8.5cm}
+\twocolspacing{2}
+
+\newcommand{\twocolitem}[2]{#1 & #2\\}
+\newcommand{\twocolitemruled}[2]{#1 & #2\\\hline}
+
+\newenvironment{twocollist}{\renewcommand{\arraystretch}{\twocolspacingval}\begin{tabular}{lp{\twocolwidthbval}}}%
+{\end{tabular}\renewcommand{\arraystretch}{1}}
+
+% Specifying table rows for RTF compatibility
+\newcommand{\row}[1]{#1\\}
+
+% Use for the last ruled row for correct RTF generation.
+\newcommand{\ruledrow}[1]{#1\\\hline}
+
+% Indentation environment. Arg1 is left margin size
+\newenvironment{indented}[1]{\begin{list}{}{\leftmargin=#1}\item[]}%
+{\end{list}}
+
+% Framed box of text, normal formatting.
+\newcommand{\normalbox}[1]{\fbox{\vbox{#1}}}
+% Double-framed box of text.
+\newcommand{\normalboxd}[1]{\fbox{\fbox{\vbox{#1}}}}
+
+% WITHDRAWN -- can't do in RTF, easily.
+% Framed box of text, horizontally centred. Ragged right within box.
+% \newcommand{\centeredbox}[2]{\begin{center}\fbox{\parbox{#1}{\raggedright#2}}\end{center}}
+% Double-framed box of text, horizontally centred. Ragged right within box.
+% \newcommand{\centeredboxd}[2]{\begin{center}\fbox{\fbox{\parbox{#1}{\raggedright#2}}}\end{center}}
+
+% toocomplex environment: simply prints the argument in LaTeX,
+% comes out verbatim in all generated formats.
+\newenvironment{toocomplex}{}{}
+
+% Colour: dummy commands since LaTeX doesn't support colour.
+% \definecolour{name}{red}{blue}{green}
+% \fcol{name}{text} ; Foreground
+% \bcol{name}{text} ; Background
+\newcommand{\definecolour}[4]{}
+\newcommand{\definecolor}[4]{}
+\newcommand{\fcol}[2]{#2}
+\newcommand{\bcol}[2]{#2}
+\newcommand{\sethotspotcolour}[1]{}
+\newcommand{\sethotspotunderline}[1]{}
+\newcommand{\settransparency}[1]{}
+\newcommand{\backslashraw}[0]{}
+\newcommand{\lbraceraw}[0]{}
+\newcommand{\rbraceraw}[0]{}
+\newcommand{\registered}[0]{(r)}
+\newcommand{\background}[1]{}
+\newcommand{\textcolour}[1]{}
+\newcommand{\overview}[2]{See \helpref{#1}{#2}.}
+\newcommand{\docparam}[2]{{\it #1}\begin{list}{}{\leftmargin=1cm}\item[]
+#2%
+\end{list}}
+\newcommand{\wxheading}[1]{{\bf #1}}
+\newcommand{\const}[0]{{\bf const}}
+\newcommand{\constfunc}[3]{{\bf #1} {\bf #2}(#3) {\bf const}\index{#2}}
+\newcommand{\windowstyle}[1]{{\bf #1}\index{#1}}
+
+\addtolength{\textwidth}{1in}
+\addtolength{\oddsidemargin}{-0.5in}
+\addtolength{\topmargin}{-0.5in}
+\addtolength{\textheight}{1in}
+\sloppy
+

contrib/docs/latex/ogl/topics.tex

@@ -0,0 +1,161 @@
+\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{wxOGLConstraint}{wxoglconstraint}
+
+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{wxOGLConstraint constructor}{wxoglconstraintconstr}.
+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{wxOGLConstraint::SetSpacing}{wxoglconstraintsetspacing}.
+
+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}.
+