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/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}.
+