The initial beginnings on a technical fpGUI manual.

1 files changed, 156 insertions, 0 deletions

diff --git a/docs/fpGUI_tech_ref.tex b/docs/fpGUI_tech_ref.tex
new file mode 100644
index 00000000..eb8105f8
--- /dev/null
+++ b/docs/fpGUI_tech_ref.tex
@@ -0,0 +1,156 @@
+\documentclass[a4paper,11pt]{report}
+
+% Define the title
+\author{Graeme Geldenhuys}
+\title{fpGUI - A technical reference}
+
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}
+
+\begin{document}
+
+% generates the title
+\maketitle
+\newpage
+
+% insert the table of contents
+\tableofcontents
+\newpage
+
+% *******************************************************************
+\chapter{Introduction}
+After developing many cross platform applications with Kylix and Delphi
+I started getting very frustrated with the differences between the look and
+behaviour of the applications under Linux and Windows.  The code was also
+riddled with IFDEF statements.
+
+Then I stumbled across the Free Pascal and Lazarus projects. I thought this 
+is it, the answer to all my cross platform development problems. Unfortunately
+after working with Lazarus for a few months I started finding more and more
+issues with the widget sets, though the IDE was great.
+
+The Lazarus LCL is a wrapper for each platforms native widget set. This 
+brought with it the same issues I experienced with Kylix and Delphi. This got
+me thinking about how I could resolve this issue.
+
+Then it hit me - implement the widget set myself using Free Pascal! Painting
+the widgets myself to get a consistent look and implementing a consistent
+behaviour. Instead of reinventing the wheel, I thought I would do some searching
+to see if there is another project I can contribute to or help by giving me
+a head start.
+
+The first version of my widget set was based around a heavily modified version
+of the Light Pascal Toolkit\footnote{http://sourceforge.net/projects/lptk}. 
+I then discovered the discontinued fpGUI and fpGFX projects. I tried 
+to contact the original author to no avail. The fpGUI code hasn't been 
+touched in four years (since early 2002). After studying the code for a 
+few weeks, I came to the conclusion that fpGUI is much closer to what I strived 
+to accomplish with my modified LPTK. A lot was still missing from fpGUI though.
+
+After thinking long and hard, I decided to start my widget set again, but 
+this time based on the work done in fpGUI and fpGFX. I also added to the 
+mix some good ideas I saw in Qt 4.1. So far I have completed quite a few things 
+missing in fpGUI, but I still need to do a lot to get to the point where I 
+can test drive it in a commercial application. I set myself a list of 
+things outstanding which should get it to a usable level. I also added a 
+lot of documentation as I went as there was no documentation included with 
+the original fpGUI and fpGFX projects. Documentation is important 
+to attract other developers in using the widget set.
+
+
+
+% *******************************************************************
+\chapter{GUI and Events}
+This chapter is currently a copy and paste of an email I wrote explaining
+how the events work. The difference between the GFX events and the GUI events. 
+Soon I will rewrite this chapter and add a lot more detail. Here follows the email
+text for now.
+
+The GFX part gets events from the windowing system, be that X11 or 
+GDI. That means that TFCustomWindow gets all the events from the 
+windowing system.
+
+Now the GUI part. Every widget is \emph{not} a TFCustomWindow, so every 
+widget doesn't have a Handle.  The GUI is implemented with only one 
+handle per Form (TFForm).  All widgets are just painted onto the canvas 
+of the TFForm.
+
+If you look at the TFCustomForm you will see it has a instance of 
+TFCustomWindow stored in FWnd. That instance gets all the events from 
+the windowing system. So to let the widgets also get events we have to 
+implement our own event system. The TFCustomForm will then send those 
+custom events (TEventObj descendants) by translating the windowing 
+events into our custom GUI events.
+
+For example:\\
+Lets say we have a Form with a Button on it. Now we want to handle a 
+OnMouseMove event on the Button.  The flow of events will go as follows:
+
+\begin{itemize}
+	\item TFCustomForm.Wnd  will receive the OnMouseMove from the windowing 
+system and process it in the WndMouseMoved() method.
+
+	\item WndMouseMoved() will translate that windowing system event into 
+whatever GUI events are needed and start sending them.
+
+	\item Any TWidget descendant handles events in the ProcessEvent() method. 
+TWidget being the big one.
+
+	\item Because TFCustomForm is a TFContainerWidget descendant, it means it 
+can contain other widgets. So it starts distributing the GUI events to 
+the children. Distribution is done by the DistributeEvent() method.
+
+	\item If TFCustomButton needed to do any special processing with the GUI 
+event, it would handle it in its ProcessEvent() method. 
+TWidget.ProcessEvent normally does most of the generic work.
+
+	\item As an example of a widget that does custom processing, have a 
+look at the TFMenuItem.ProcessEvent(). In this case it handles the 
+TMouseEnterEventObj and TMouseLeaveEventObj events so it can changes 
+it's look when the mouse enters a menu item or leaves a menu item.
+\end{itemize}
+
+So as a summary:\\
+TFCustomForm contains a instance of a GFX window. Translates all the 
+GFX events (underlying windowing events) to GUI events (TEventObj 
+descendants) and distributes them to the children of the Form.
+
+
+% *******************************************************************
+\chapter{Layout Algorithm}
+
+\section{Initialisation of a window (form)}
+If a window presents itself for the first time, and no standard size was
+ given, then it must compute these.
+ This is a recursive process, with which the event TCalcSizesEventObj is
+ set for all children of the window from top to bottom in the Widget tree
+ (beginning with the window).
+ TWidget reacts to the receipt of this event as follows (in TWidget.EvCalcSizes):
+
+\begin{itemize}
+	\item The event is passed on with TWidget.DistributeEvent to all children.
+	
+	\item The virtual protected method TWidget.DoCalcSizes is called.
+ Again derived Widgets overwrites this method, in order to compute its sizes
+ of (minimum, maximum, optimum).
+ 
+ 	\item The results of DoCalcSizes are if necessary corrected, e.g.
+ the maximum size may not be smaller than the minimum size.
+ 
+ 	\item If the code for the window finished the dispatch of this event, all Widgets
+ in the window has valid statements of size.
+ Now it can do its own, initials size sets (this is the before computed
+ optimum size of the window).
+ This is accomplished by TWidget.SetBounds.
+\end{itemize}
+
+... to be continued ...
+
+
+% *******************************************************************
+\chapter{Database Components}
+
+... to be continued ...
+
+
+\end{document}