utils/ogl/docs/topics.tex

   1 \chapter{Topic overviews}
   2 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
   3 \setfooter{\thepage}{}{}{}{}{\thepage}
   4
   5 The following sections describe particular topics.
   6
   7 \section{OGL overview}\label{ogloverview}
   8
   9 \helpref{wxShapeCanvas}{wxshapecanvas}, derived from {\bf wxCanvas}, is the drawing area
  10 for a number of \helpref{wxShape}{wxshape} instances. Everything drawn on a
  11 wxShapeCanvas is derived from wxShape, which provides virtual
  12 member functions for redrawing, creating and destroying
  13 resize/selection `handles', movement and erasing behaviour, mouse
  14 click behaviour, calculating the bounding box of the shape, linking
  15 nodes with arcs, and so on.
  16
  17 The way a client application copes with `damage' to the canvas is to
  18 erase (white out) anything should no longer be displayed, redraw the shape,
  19 and then redraw everything on the canvas to repair any damage. If quick edit
  20 mode is on for the canvas, the complete should be omitted by OGL and the
  21 application.
  22
  23 Selection handles (called control points in the code) are implemented as
  24 wxRectangleShapes.
  25
  26 Events are passed to shapes by the canvas in a high-level form, for example {\bf OnLeftClick},
  27 {\bf OnBeginDragLeft}, {\bf OnDragLeft}, {\bf OnEndDragLeft}. The canvas decides
  28 what is a click and what is a drag, whether it is on a shape or the canvas itself,
  29 and (by interrogating the shape) which attachment point the click is associated with.
  30
  31 In order to provide event-handling flexibility, each shapes has an `event handler' associated with it,
  32 which by default is the shape itself (all shapes derive from wxShapeEvtHandler).
  33 An application can modify the event-handling behaviour simply by plugging a new
  34 event handler into the shape. This can avoid the need for multiple inheritance when
  35 new properties and behaviour are required for a number of different shape classes: instead
  36 of overriding each class, one new event handler class can be defined and used for all
  37 existing shape classes.
  38
  39 A range of shapes have been predefined in the library, including rectangles, ellipses,
  40 polygons. A client application can derive from these shapes and/or derive entirely
  41 new shapes from wxShape.
  42
  43 Instances of a class called \helpref{wxDiagram}{wxdiagram} organise collections of
  44 shapes, providing default file input and output behaviour.
  45
  46
  47 \section{wxDividedShape overview}\label{dividedshapeoverview}
  48
  49 Classes: \helpref{wxDividedShape}{wxdividedshape}
  50
  51 A wxDividedShape is a rectangle with a number of vertical divisions. Each
  52 division may have its text formatted with independent characteristics, and
  53 the size of each division relative to the whole image may be specified.
  54
  55 Once a wxDividedShape has been created, the user may move the divisions with the
  56 mouse. By pressing Ctrl while right-clicking, the region attributes can be edited.
  57
  58 Here are examples of creating wxDividedShape objects:
  59
  60 {\small
  61 \begin{verbatim}
  62   /*
  63    * Divided rectangle with 3 regions
  64    *
  65    */
  66
  67   wxDividedShape *dividedRect = new wxDividedShape(50, 60);
  68
  69   wxShapeRegion *region = new wxShapeRegion;
  70   region->SetProportions(0.0, 0.25);
  71   dividedRect->AddRegion(region);
  72
  73   region = new wxShapeRegion;
  74   region->SetProportions(0.0, 0.5);
  75   dividedRect->AddRegion(region);
  76
  77   region = new wxShapeRegion;
  78   region->SetProportions(0.0, 0.25);
  79   dividedRect->AddRegion(region);
  80
  81   dividedRect->SetSize(50, 60); // Allow it to calculate region sizes
  82   dividedRect->SetPen(wxBLACK_PEN);
  83   dividedRect->SetBrush(wxWHITE_BRUSH);
  84   dividedRect->Show(TRUE);
  85   dividedRect->NameRegions();
  86
  87   /*
  88    * Divided rectangle with 3 regions, rounded
  89    *
  90    */
  91
  92   wxDividedShape *dividedRect3 = new wxDividedShape(50, 60);
  93   dividedRect3->SetCornerRadius(-0.4);
  94
  95   region = new wxShapeRegion;
  96   region->SetProportions(0.0, 0.25);
  97   dividedRect3->AddRegion(region);
  98
  99   region = new wxShapeRegion;
 100   region->SetProportions(0.0, 0.5);
 101   dividedRect3->AddRegion(region);
 102
 103   region = new wxShapeRegion;
 104   region->SetProportions(0.0, 0.25);
 105   dividedRect3->AddRegion(region);
 106
 107   dividedRect3->SetSize(50, 60); // Allow it to calculate region sizes
 108   dividedRect3->SetPen(wxBLACK_PEN);
 109   dividedRect3->SetBrush(wxWHITE_BRUSH);
 110   dividedRect3->Show(TRUE);
 111   dividedRect3->NameRegions();
 112 \end{verbatim}
 113 }
 114
 115
 116 \section{wxCompositeShape overview}\label{compositeshapeoverview}
 117
 118 Classes: \helpref{wxCompositeShape}{wxcompositeshape}, \helpref{OGLConstraint}{oglconstraint}
 119
 120 The wxCompositeShape allows fairly complex shapes to be created, and maintains
 121 a set of constraints which specify the layout and proportions of child shapes.
 122
 123 Add child shapes to a wxCompositeShape using \helpref{AddChild}{wxcompositeshapeaddchild}, and
 124 add constraints using \helpref{AddConstraint}{wxcompositeshapeaddconstraint}.
 125
 126 After children and shapes have been added, call \helpref{Recompute}{wxcompositeshaperecompute} which
 127 will return TRUE is the constraints could be satisfied, FALSE otherwise. If
 128 constraints have been correctly and consistently specified, this call will succeed.
 129
 130 If there is more than one child, constraints must be specified: OGL cannot calculate
 131 the size and position of children otherwise. Don't assume that children will simply
 132 move relative to the parent without the use of constraints.
 133
 134 To specify a constraint, you need three things:
 135
 136 \begin{enumerate}\itemsep=0pt
 137 \item a constraint type, such as gyCONSTRAINT\_CENTRED\_VERTICALLY;
 138 \item a reference shape, with respect to which other shapes are going to be positioned - the\rtfsp
 139 {\it constraining} shape;
 140 \item a list of one or more shapes to be constrained: the {\it constrained} shapes.
 141 \end{enumerate}
 142
 143 The constraining shape can be either the parent of the constrained shapes, or a sibling. The
 144 constrained shapes must all be siblings of each other.
 145
 146 For an exhaustive list and description of the available constraint types, see the \helpref{OGLConstraint constructor}{oglconstraintconstr}.
 147 Note that most constraints operate in one dimension only (vertically or horizontally), so you will
 148 usually need to specify constraints in pairs.
 149
 150 You can set the spacing between constraining and constrained shapes by
 151 calling \helpref{OGLConstraint::SetSpacing}{oglconstraintsetspacing}.
 152
 153 Finally, a wxCompositeShape can have {\it divisions}, which are special child shapes of class
 154 wxDivisionShape (not to be confused with wxDividedShape). The purpose of this is to allow
 155 the composite to be divided into user-adjustable regions (divisions) into which other shapes
 156 can be dropped dynamically, given suitable application code. Divisons allow the child
 157 shapes to have an identity of their own - they can be manipulated independently of their container -
 158 but to behave as if they are contained with the division, moving with the parent shape.
 159 Divisions boundaries can themselves be moved using the mouse.
 160
 161 To create an initial division, call \helpref{wxCompositeShape::MakeContainer}{wxcompositeshapemakecontainer}.
 162 Make further divisions by calling \helpref{wxDivisionShape::Divide}{wxdivisionshapedivide}.
 163