[wxWidgets.git] / utils / ogl / docs / topics.tex

\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}.
Commit	Line	Data
0fc1a713 JS	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
0fc1a713 JS	46	\section{wxDividedShape overview}\label{dividedshapeoverview}
	47
	48	Classes: \helpref{wxDividedShape}{wxdividedshape}
	49
	50	A wxDividedShape is a rectangle with a number of vertical divisions. Each
	51	division may have its text formatted with independent characteristics, and
	52	the size of each division relative to the whole image may be specified.
	53
	54	Once a wxDividedShape has been created, the user may move the divisions with the
	55	mouse. By pressing Ctrl while right-clicking, the region attributes can be edited.
	56
	57	Here are examples of creating wxDividedShape objects:
	58
	59	{\small
	60	\begin{verbatim}
	61	/*
	62	* Divided rectangle with 3 regions
	63	*
	64	*/
	65
	66	wxDividedShape *dividedRect = new wxDividedShape(50, 60);
	67
	68	wxShapeRegion *region = new wxShapeRegion;
	69	region->SetProportions(0.0, 0.25);
	70	dividedRect->AddRegion(region);
	71
	72	region = new wxShapeRegion;
	73	region->SetProportions(0.0, 0.5);
	74	dividedRect->AddRegion(region);
	75
	76	region = new wxShapeRegion;
	77	region->SetProportions(0.0, 0.25);
	78	dividedRect->AddRegion(region);
	79
	80	dividedRect->SetSize(50, 60); // Allow it to calculate region sizes
	81	dividedRect->SetPen(wxBLACK_PEN);
	82	dividedRect->SetBrush(wxWHITE_BRUSH);
	83	dividedRect->Show(TRUE);
	84	dividedRect->NameRegions();
	85
	86	/*
	87	* Divided rectangle with 3 regions, rounded
	88	*
	89	*/
	90
	91	wxDividedShape *dividedRect3 = new wxDividedShape(50, 60);
	92	dividedRect3->SetCornerRadius(-0.4);
	93
	94	region = new wxShapeRegion;
	95	region->SetProportions(0.0, 0.25);
	96	dividedRect3->AddRegion(region);
	97
	98	region = new wxShapeRegion;
	99	region->SetProportions(0.0, 0.5);
	100	dividedRect3->AddRegion(region);
	101
	102	region = new wxShapeRegion;
	103	region->SetProportions(0.0, 0.25);
	104	dividedRect3->AddRegion(region);
	105
	106	dividedRect3->SetSize(50, 60); // Allow it to calculate region sizes
	107	dividedRect3->SetPen(wxBLACK_PEN);
	108	dividedRect3->SetBrush(wxWHITE_BRUSH);
	109	dividedRect3->Show(TRUE);
110	dividedRect3->NameRegions();
111	\end{verbatim}
112	}
113
0fc1a713 JS	114	\section{wxCompositeShape overview}\label{compositeshapeoverview}
0fc1a713 JS	115
6f5f3ca0	116	Classes: \helpref{wxCompositeShape}{wxcompositeshape}, \helpref{wxOGLConstraint}{wxoglconstraint}
0fc1a713 JS	117
	118	The wxCompositeShape allows fairly complex shapes to be created, and maintains
	119	a set of constraints which specify the layout and proportions of child shapes.
	120
	121	Add child shapes to a wxCompositeShape using \helpref{AddChild}{wxcompositeshapeaddchild}, and
	122	add constraints using \helpref{AddConstraint}{wxcompositeshapeaddconstraint}.
	123
	124	After children and shapes have been added, call \helpref{Recompute}{wxcompositeshaperecompute} which
	125	will return TRUE is the constraints could be satisfied, FALSE otherwise. If
	126	constraints have been correctly and consistently specified, this call will succeed.
	127
	128	If there is more than one child, constraints must be specified: OGL cannot calculate
	129	the size and position of children otherwise. Don't assume that children will simply
	130	move relative to the parent without the use of constraints.
	131
	132	To specify a constraint, you need three things:
	133
	134	\begin{enumerate}\itemsep=0pt
	135	\item a constraint type, such as gyCONSTRAINT\_CENTRED\_VERTICALLY;
	136	\item a reference shape, with respect to which other shapes are going to be positioned - the\rtfsp
	137	{\it constraining} shape;
	138	\item a list of one or more shapes to be constrained: the {\it constrained} shapes.
	139	\end{enumerate}
	140
	141	The constraining shape can be either the parent of the constrained shapes, or a sibling. The
	142	constrained shapes must all be siblings of each other.
	143
6f5f3ca0	144	For an exhaustive list and description of the available constraint types, see the \helpref{wxOGLConstraint constructor}{wxoglconstraintconstr}.
0fc1a713 JS	145	Note that most constraints operate in one dimension only (vertically or horizontally), so you will
	146	usually need to specify constraints in pairs.
	147
	148	You can set the spacing between constraining and constrained shapes by
6f5f3ca0	149	calling \helpref{wxOGLConstraint::SetSpacing}{wxoglconstraintsetspacing}.
0fc1a713 JS	150
	151	Finally, a wxCompositeShape can have {\it divisions}, which are special child shapes of class
	152	wxDivisionShape (not to be confused with wxDividedShape). The purpose of this is to allow
	153	the composite to be divided into user-adjustable regions (divisions) into which other shapes
	154	can be dropped dynamically, given suitable application code. Divisons allow the child
	155	shapes to have an identity of their own - they can be manipulated independently of their container -
	156	but to behave as if they are contained with the division, moving with the parent shape.
	157	Divisions boundaries can themselves be moved using the mouse.
	158
	159	To create an initial division, call \helpref{wxCompositeShape::MakeContainer}{wxcompositeshapemakecontainer}.
	160	Make further divisions by calling \helpref{wxDivisionShape::Divide}{wxdivisionshapedivide}.
	161