[wxWidgets.git] / contrib / docs / latex / ogl / sample.tex

\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.
Commit	Line	Data
2d08140f JS	1	\chapter{OGLEdit: a sample OGL application}\label{ogledit}%
	2	\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
	3	\setfooter{\thepage}{}{}{}{}{\thepage}
	4
	5	OGLEdit is a sample OGL application that allows the user to draw, edit,
	6	save and load a few shapes. It should clarify aspects of OGL usage, and
	7	can act as a template for similar applications. OGLEdit can be found in\rtfsp
	8	{\tt samples/ogledit} in the OGL distribution.
	9
	10	$$\image{10cm;0cm}{ogledit.eps}$$\par
	11
	12	The wxWindows document/view model has been used in OGL, to reduce the amount of
	13	housekeeping logic required to get it up and running. OGLEdit also provides
	14	a demonstration of the Undo/Redo capability supported by the document/view classes,
	15	and how a typical application might implement this feature.
	16
	17	\section{OGLEdit files}
	18
	19	OGLEdit comprises the following source files.
	20
	21	\begin{itemize}\itemsep=0pt
	22	\item doc.h, doc.cpp: MyDiagram, DiagramDocument, DiagramCommand, MyEvtHandler
	23	classes related to diagram functionality and documents.
	24	\item view.h, view.cpp: MyCanvas, DiagramView classes related to visualisation of
	25	the diagram.
	26	\item ogledit.h, ogledit.cpp: MyFrame, MyApp classes related to the overall application.
	27	\item palette.h, palette.cpp: EditorToolPalette implementing the shape palette.
	28	\end{itemize}
	29
	30	\section{How OGLEdit works}
	31
	32	OGLEdit defines a DiagramDocument class, each of instance of which holds a MyDiagram
	33	member which itself contains the shapes.
	34
	35	In order to implement specific mouse behaviour for shapes, a class MyEvtHandler is
	36	defined which is `plugged into' each shape when it is created, instead of overriding each shape class
	37	individually. This event handler class also holds a label string.
	38
	39	The DiagramCommand class is the key to implementing Undo/Redo. Each instance of DiagramCommand
	40	stores enough information about an operation (create, delete, change colour etc.) to allow
	41	it to carry out (or undo) its command. In DiagramView::OnMenuCommand, when the user initiates the
	42	command, a new DiagramCommand instance is created which is then sent to the document's
	43	command processor (see wxWindows manual for more information about doc/view and command
	44	processing).
	45
	46	Apart from menu commands, another way commands are initiated is by the user left-clicking on
	47	the canvas or right-dragging on a node. MyCanvas::OnLeftClick in view.cpp shows how
	48	the appropriate wxClassInfo is passed to a DiagramCommand, to allow DiagramCommand::Do
	49	to create a new shape given the wxClassInfo.
	50
	51	The MyEvtHandler right-drag methods in doc.cpp implement drawing a line between
	52	two shapes, detecting where the right mouse button was released and looking for a second
	53	shape. Again, a new DiagramCommand instance is created and passed to the command
	54	processor to carry out the command.
	55
	56	DiagramCommand::Do and DiagramCommand::Undo embody much of the
	57	interesting interaction with the OGL library. A complication of note
	58	when implementing undo is the problem of deleting a node shape which has
	59	one or more arcs attached to it. If you delete the node, the arc(s)
	60	should be deleted too. But multiple arc deletion represents more information
	61	that can be incorporated in the existing DiagramCommand scheme. OGLEdit
	62	copes with this by treating each arc deletion as a separate command, and
	63	sending Cut commands recursively, providing an undo path. Undoing such a
	64	Cut will only undo one command at a time - not a one to one
65	correspondence with the original command - but it's a reasonable
66	compromise and preserves Do/Undo whilst keeping our DiagramCommand class
67	simple.
68
69	\section{Possible enhancements}
70
71	OGLEdit is very simplistic and does not employ the more advanced features
72	of OGL, such as:
73
74	\begin{itemize}\itemsep=0pt
75	\item attachment points (arcs are drawn to particular points on a shape)
76	\item metafile and bitmaps shapes
77	\item divided rectangles
78	\item composite shapes, and constraints
79	\item creating labels in shape regions
80	\item arc labels (OGL has support for three movable labels per arc)
81	\item spline and multiple-segment line arcs
82	\item adding annotations to node and arc shapes
83	\item line-straightening (supported by OGL) and alignment (not supported directly by OGL)
84	\end{itemize}
85
86	These could be added to OGLEdit, at the risk of making it a less
87	useful example for beginners.