0ct0pu5/wesnoth
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix documentation errors/typos and grammar.

Browse source 
Errors found by zaroth while reading the document. (patch #2613).
This commit is contained in:
Mark de Wever 2011-04-09 16:00:26 +00:00
parent 634051f7e2
commit 7fbfe57b36
5 changed files with 119 additions and 121 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

126
doc/design/gui2/creating_widgets_and_dialogs.tex
View file

@ -1,12 +1,12 @@
\chapter{Creating new widgets and dialogues}
This chapter dives into the area of creating your own widgets or dialogues. For
this example we use a real widget and dialogue under development. The widget
this example we use a real widget and a dialogue under development. The widget
being developed is the progress bar and the screen the initial load screen.
First we make the widget then the screen in order to test the widget, this
happens often when you need to add a new widget that you need it for a new
dialogue so you need to create both for testing. Another option is to add the
First we make the widget, then the screen in order to test the widget. It
happens often that, when you need to add a new widget, you need it for a new
dialogue - so you need to create both for testing. Another option is to add the
widget as dummy item to another existing dialogue. When adding a dialogue for
which all widgets already exist this doesn't matter and you can directly dive
into generating the dialogue.
@ -16,13 +16,13 @@ into generating the dialogue.
The widget is normally split in 7 different files. Three .cpp/.hpp files and one
WML file. Usually I start to create the new files by simply copy pasting the old
files and pick a rather small class like timage or something. Then I start to
files and pick a rather small class like timage or something. Then, I start to
update the build system files, followed by creating the code for the
classes\footnote{Obviously I already thought about the design of the class
before that, but that's of less importance in this tutorial}.
before that, but that's of less importance in this tutorial.}.
Now we start to explain what the various files do, first a general overview of
the files after which I dive more into the implementation of the file.
Now, we start to explain what the various files do. First, I do a general overview of
the files after which I dive more into the implementation of each file.
\begin{description}
@ -80,16 +80,16 @@ the files after which I dive more into the implementation of the file.
is inside the ``wesnoth-lib'' text domain.
\item[\Lref{progress_bar.cfg:class}]
Beginning of the progress bar, this part is much better documented in
the wiki %TODO ref
since this part is aimed at WML authors, duplicating that effort here
Beginning of the progress bar. This part is much better documented in
the wiki\footnote{\url{http://wiki.wesnoth.org/GUIWidgetDefinitionWML}}.
Since this part is aimed at WML authors, duplicating that effort here
makes no sense so just visit the wiki.
\end{description}
\item[src/gui/auxiliary/window\_builder/progress\_bar.*]
These files contain the code to build a widget from the definition described
above and a config object as defined in the window. This file contains the
above and a config object as defined in the window. These files contain also the
\emph{dynamic} properties of the progress bar. Since the progress bar has no
dynamic content this file is also rather short.
@ -113,11 +113,11 @@ the files after which I dive more into the implementation of the file.
\item[\Lref{window_builder.cpp:constructor}] The constructor used is
pretty typical for all widgets.
If the constructor initialize custom members it may add some validation.
If the constructor initializes custom members it may also add some validation.
This is also true when the widget has a grid, like the listbox or
multi\_page.
\item[\Lref{window_builder.cpp:build}]
This build() is semi-typical, it creates the widget initializes the
This build() is semi-typical, it creates the widget, initializes the
default fields and returns the created object.
Widgets with their own members initialize them after initializing the
@ -133,11 +133,11 @@ the files after which I dive more into the implementation of the file.
\item[src/gui/widgets/progress\_bar.*]
These files contain the interaction the widget has with the outer world and
how it reacts to events. Again the progress bar is rather boring. The
interesting part is the setter of the percentage, here the value of the
percentage use in the drawing routines is set\footnote{Other classes have a
how it reacts to events. Again, the progress bar is rather boring. The
interesting part is the setter of the percentage. The value of the
percentage used in the drawing routines is set here\footnote{Other classes have a
separate update canvas, but that's because the canvas in those classes is
invalidated in several functions.}
invalidated in several functions.}.
\begin{description}
\item[hpp] \Liref{progress_bar.hpp} contains the sample code.
@ -149,17 +149,17 @@ the files after which I dive more into the implementation of the file.
\item[\Lref{progress_bar.hpp:constructor}]
The class calls the control constructor with the number of states, which
is the number of canvases used. Other then that it does the
is the number of canvases used. Other then that, it does the
initialization of its members. Some constructors do a bit more
processing but where a lot needs to be done, it's often deferred to a
finalize function.
processing, but where a lot needs to be done it's often deferred to a
finalize() function.
\item[\Lref{progress_bar.hpp:inherited}]
This section implements or overrides member functions of the base class.
Some functions are pure virtual and need to be overridden others to
change behaviour.\footnote{Of course a list of which functions are
common the add here would be nice, however the library is still too
volatile to do so, no need to create a soon out of date list.}
Some functions are purely virtual and need to be overridden by others to
change the behaviour.\footnote{Of course, adding here a list of functions which are
common would be nice. However, the library is still too
volatile to do so - no need to create a soon out of date list.}
\item[\Lref{progress_bar.hpp:settersgetters}]
This section contains the setters and getters for the class. The
@ -211,18 +211,18 @@ the files after which I dive more into the implementation of the file.
\item[\Lref{progress_bar.cpp:register}]
Registers a widget, this part is really volatile and still has some
hoops and rings to jump through. Normally it works if not too bad and
look through the other widgets to see how to fix it.
hoops and rings to jump through. Normally, it works. If not, too bad -
try to look through the other widgets to see how to fix it.
\textbf{Caveat emptor} just when all compiles fine you get a runtime
\textbf{Caveat emptor} Just when all compiles fine and you suddenly get a runtime
error about your new nice class, the builder claims your widget doesn't
exist. \emph{Don't panic} probably you did nothing wrong grep TRY in
exist. \emph{Don't panic}, probably you did nothing wrong. Grep TRY in
src/gui/auxiliary/window\_builder.cpp (at the moment of writing line 96)
and read the comment above, dully add your class to the list and be
and read the comment above, duly add your class to the list and be
happy.
\item[\Lref{progress_bar.cpp:get_control_type}]
Simple helper to get the human readable name of the class. The first
A simple helper to get the human readable name of the class. The first
version was inlined in the header, but that seems to be an ODR
violation. At least at some point a compiler or linker complained, can't
really remember which one. % TODO git pick-axe
@ -239,20 +239,20 @@ new .cpp files listed, these are:
\item src/CmakeLists.txt
\end{itemize}
The next step has become optional now that most build systems can glob the files
The next step has become optional now, when most of build systems can glob the files
needed for translation, but I still add them manually as well. The file is
po/wesnoth-lib/POTFILES.IN which holds the files for the wesnoth-lib text
po/wesnoth-lib/POTFILES.IN. It holds the files for the wesnoth-lib text
domain.
The last file to be edited is src/gui/widgets/settings.cpp here a wiki comment
for the new class needs to be added, this might change. The reason is that
before automatically registering widgets this file needed more modification so
The last file to be edited is src/gui/widgets/settings.cpp. Here, a wiki comment
for the new class needs to be added, this might change later. The reason is that
before automatically registering widgets this file needed more modification, so
it was done in one fell swoop.
\end{description}
This completes the simple progress bar widget. Of course we haven't tested it
yet since there's no dialogue to test it in. So let's implement a dialogue.
This concludes the simple progress bar widget. Of course, we haven't tested it
yet, since there's no dialogue to test it in. So let's implement a dialogue.
\section{Creating the window}
@ -261,9 +261,9 @@ yet since there's no dialogue to test it in. So let's implement a dialogue.
The window is normally split in 3 files. One .cpp/.hpp file and one WML file.
The dialogue used is the unit attack dialogue, at least an initial version. This
version barely does what it needs to do, and the in game version will be more
polished. This simple version is nice as example here since it's not too large.
polished. This simple version is nice as an example here since it's not too large.
Now we start to explain what the various files do, first a general overview of
Now, let's explain what the various files do. First, a general overview of
the files after which I dive more into the implementation of the file.
\begin{description}
@ -279,39 +279,38 @@ the files after which I dive more into the implementation of the file.
\begin{description}
\item[\Lref{unit_attack.hpp:class}]
Defines the class itself, which normally inherits from tdialog.
Sometimes a class inherits from another class, but that class then
derives from tdialog, for example the wml\_dialogs have a common base and
Sometimes a class inherits from another class, but this other class then
derives from tdialog; for example the wml\_dialogs have a common base and
separate classes for left and right.
\item[\Lref{unit_attack.hpp:constructor}]
Dialogues are often created and then shown once before being destroyed,
therefore the constructor often takes all parameters needed. Since the show
function shouldn't be overloaded the only other alternative would be member
functions to set the members. Note when keeping `references' to widgets these
member must be pointers and set to NULL in the constructor, this due to the
simple fact that the widgets aren't created at this point. Also keep in mind
when
the dialogue is shown twice (using the \emph{same} object) the widgets won't be
therefore the constructor often takes all the parameters needed. Since the show()
function shouldn't be overloaded, the only other alternative would be member
functions to set the members. Note that when keeping `references' to widgets these
members must be pointers and set to NULL in the constructor, this due to the
simple fact that the widgets aren't yet created at this point. Also keep in mind that
when the dialogue is shown twice (using the \emph{same} object) the widgets won't be
the same. The window owning the widgets is destroyed after being shown and
a new one created upon the next call to show.
a new one created upon the next call to show().
\item[\Lref{unit_attack.hpp:settersgetters}]
As said before there are often no setters, since all is set in the
contructor. Most members also remain hidden since the caller has the
As said before, there are often no setters, since all is set in the
contructor. Most members also remain hidden, since the caller has the
information. Only members that change are `exported'. The most common example in
a class with a listbox, the last selected item is made public, since this is
often used as choice the user made.
often used as the choice the user made.
\item[\Lref{unit_attack.hpp:window_id}]
This function is part of the window registration and only needs to be
This function is a part of the window registration and only needs to be
declared in the header, the definition will be provided by a macro.
\item[\Lref{unit_attack.hpp:pre_show}]
This function is called after the window is created but before being
This function is called after the window is created, but before being
shown. This is the point to set the members that point to a widget. As said
before every time the dialogue is shown a newly created window is shown, so
before, every time the dialogue is shown a newly created window is shown as well, so
setting the pointers can be unconditional. This is also the place to fill the
widgets with the proper content, if needed. Eg filling the languages in the
widgets with the proper content, if needed. E.g. filling the languages in the
language selection dialogue.
\item[\Lref{unit_attack.hpp:post_show}]
@ -326,7 +325,7 @@ and let the caller test the status.
\end{description}
\item[cpp] \Liref{unit_attack.cpp} contains the sample code. Note some
parts are already described more verbose in the header and thus not mentioned
parts are already described more verbosely in the header and thus not mentioned
here.
\begin{description}
\item[\Lref{unit_attack.cpp:textdomain}]
@ -337,7 +336,6 @@ domain.
Directly after the includes (inside the gui2 namespace) the wiki
documentation starts.
\item[\Lref{unit_attack.cpp:register}]
After the wiki documentation the registration code follows, it defines
the window\_id function and does some other registration parts.
@ -363,24 +361,24 @@ information on the subject. Still some parts are worth mentioning.
Every file in the library is inside the ``wesnoth-lib'' text domain.
\item[\Lref{unit_attack.cfg:defines}]
With larger dialogs I often design them on paper and then divide the
With larger dialogs, I often first design them on paper and then divide the
dialog in several sections. These sections often are turned into defines in
order to keep the main dialog rather simple. WML tends to be verbose and deeply
nested, and the GUI's also tend to have a lot of nested items, these powers
combined result in deeply nested structure, where one can easily lose the way.
Also not that all local macros are prefixed with \_GUI, this to avoid clashes
Also note that all local macros are prefixed with \_GUI, this is to avoid clashes
with other macros. The BIG in the names are just because I want to make a
different definition of high resolution screens (this will be the first screen
using that feature, but that will be added later).
\item[\Lref{unit_attack.cfg:window}]
Not much to tell about this part, since it's all documented in the wiki.
But do note that due to the defines above the grid in the window itself is
Not much to tell about this part, since it's all documented in the wiki. %TODO add ref?
But do note that due to the defines above, the grid in the window itself is
rather simple.
\item[\Lref{unit_attack.cfg:undefines}]
The local macros are no longer needed so undefine them, I normally
undefine them in the oposite order of the definitions, I'm quite sure that's not
undefine them in the oposite order of the definitions. I'm quite sure that's not
actually needed, but it feels the right way\texttrademark.
\end{description}

46
doc/design/gui2/design_details.tex
View file

@ -1,7 +1,7 @@
\chapter{Design details}
Now that the big picture regarding the library is known, I dive into parts of
the code that can use more explanation. A part not explained here, doesn't mean
the code that can use more explanation. If a part is not explained here, it doesn't mean
the code is obvious or simple, lack of time to document it properly is more
likely the excuse.
@ -13,7 +13,7 @@ The registering is done by some small static classes that do the registering
of the item\footnote{Widget or Window.} in its constructor. Since this
involves some redundant typing there are REGISTER\_XXX macros written.
After all items are register the library can be started, which is simply
After all items are registered the library can be started, which is simply
done by \textsc{gui2::init()}. This function does all required steps to get
the library up and running.
@ -21,7 +21,7 @@ the library up and running.
An important part of the gui engine is to properly layout the widgets in the
available space. The documentation of that algorithm is written in
doxygen\footnote{\url{http://devdocs.wesnoth.org/layout\_algorihm.html}}.
doxygen\footnote{\url{http://devdocs.wesnoth.org/layout\_algorithm.html}}.
\section{Event handling and dispatching}
\label{event_handling}
@ -33,10 +33,10 @@ doxygen\footnote{\url{http://devdocs.wesnoth.org/event_dispatching.html}}
\section{Iterator}
The iterator class is written\footnote{The code hasn't been written yet only
The iterator class is written\footnote{The code hasn't been written yet, only
designed how it should look. Still I feel the design is rather finished and I
can update this paper if details change too much.} to alleviate certain
problems. The scrollbar containers have their own grid and a grid for it's
problems. The scrollbar containers have their own grid and a grid for its
content. The implantation makes the looping over all children tricky. This has
been solved, but the design of the solution is rather awkward. Obviously fixing
the design is the right thing to do, but that breaks the iteration.
@ -47,42 +47,42 @@ cleaner and the classes can easily be refactored.
\subsection{Design}
There are two basic kind of iterators in the design, the simple ones that can
only travel themselves and their direct children. This type will be referred to
only travel to themselves and their direct children. This type will be referred to
as basic iterator hereafter.
This basic iterator is a superclass for several specific subclasses. The
superclass is a concrete class, which can be instantiated. This class acts as a
sentinel iterator, signalling the end of a list.
Every widget has it's own creation function returning a pointer to a subclass
Every widget has its own creation function returning a pointer to a subclass
object, allowing the main iterator to keep pointers to basic iterators, which it
uses for travelling.
\paragraph{}
The other kind is called the main iterator. This iterator is the type the user
The other kind is called the main iterator. This iterator is of the type which the user
normally creates and uses. The class is a template class, where a policy designs
how the travelling should go\footnote{For now only one policy is planned, but I
can think of more kinds}.
When the main iterator is created it's possible to add a predicate to the
When the main iterator is created, it's possible to add a predicate to the
constructor. The predicate determines what the travelling routine does with a
candidate widget.
Now that we know the players in the game look further about the implementation
Now that we know the players in the game, let's look further into the implementation
details and the decisions made.
\subsubsection{Travelling}
A widget can have several ``layers'' namely:
A widget can have several ``layers'', namely:
\begin{description}
\item[self] The widget itself.
\item[grid] Container widget have a grid which is another layer, note that for a
\item[grid] Container widget has a grid which is another layer, note that for a
grid widget, its grid and self layer are the same.
\item[content] Scrollbar containers have a grid, containing their scrollbars and
a dummy content spacer. Their real content is stored in a separate internal
node, which is used as content layer.
node, which is used as the content layer.
\end{description}
The travel policy decides in which order these layers are visited, and when a
@ -102,10 +102,10 @@ values:
This doesn't mean the algorithm gives up. This layer is cancelled but the
travelling path might have more options, which are used. At the moment there's
no way to tell that the candidate has failed and that the searching should stop
altogether, a ``exit'' result might be added for that case.
altogether, an ``exit'' result might be added for that case.
\end{description}
Obviously these names are inspired by the C++ keywords.
Obviously, these names are inspired by the C++ keywords.
\subsubsection{Copying}
@ -114,7 +114,7 @@ The basic iterators are copyable since their state can easily be copied.
\paragraph{}
The main iterator can't be copied, it would involve copying the state
and copying the iterator is deemed not to be needed.
and copying the main iterator is deemed not to be needed.
\subsubsection{Operator++(int) (postfix increment)}
@ -130,7 +130,7 @@ returned object instead of binding it to a reference.
\paragraph{}
The main iterator has no postfix increment operator since it's not copyable.
This of course is a bit the chicken and the egg problem, since I wanted to
This of course is a bit like the chicken and the egg problem: since I wanted to
prevent the postfix increment operator I made the class not copyable.
For most (standard) iterator classes the overhead of copying isn't too high
@ -144,7 +144,7 @@ increment operator.
\section{Callbacks}
\Cref{event_handling} describes the generic event handling for the widgets but
\Cref{event_handling} describes the generic event handling for the widgets, but
in some cases a widget wants to notify other widgets of a state change. Parts of
gui2 use simple C-style callbacks for that purpose, but using boost::function
makes better replacement. Therefore the code was analysed closer and another
@ -159,24 +159,24 @@ In order to fix the problem two classes are defined:
\item[tnotifiee] The class to manage the lifetime of the connection.
\end{description}
The tnotifiee is a small class that holds a pointer to the receiver its
The tnotifiee is a small class that holds a pointer to the receiver it's
connected to, upon destruction it uses this pointer to deregister itself by the
receiver. There after the callback function will no longer be called.
receiver. After that the callback function will no longer be called.
The class should be used as member of a class so it can manage the lifetime of
the connection with the tnotifier.
\paragraph{}
The tnotifier is the main class, when a callback is registered it stores the
The tnotifier is the main class. When a callback is registered it stores the
callbacks in an internal list and updates the pointer in the tnotifiee to
itself.
Upon destruction it clears the pointer in all tnotifiees that point to use, that
Upon destruction it clears the pointer in all tnotifiees that point to use. This
way upon destruction of the tnotifiee it won't try to deregister itself with
this destroyed object.
Subclasses of the tnotifier should add an notification function so the notifier
Subclasses of the tnotifier should add an notification function, so the notifier
can call all callbacks in the list. The notifier should take care of this
calling.

12
doc/design/gui2/introduction.tex
View file

@ -69,12 +69,12 @@ This let to the following design goals:
\end{enumerate}
At the time of this writing the project is still work in progress\footnote{It
was never expected to be a short during project.} and will still take while to
finish. This initial goals were pretty clear, and still are. On the other hand
how to implement certain parts provided to be less clear.
was never expected to be a short during project.} and will still take a while to
finish. The initial goals were pretty clear, and still are. On the other hand
how to implement certain parts turned out to be less clear.
The library is the first time I designed a gui toolkit and like with all larger
projects, you need to learn from mistakes; preferably of others, but your doomed
projects, you need to learn from mistakes; preferably of others, but you're doomed
to make your own as well. The design process is an iterative one, causing some
parts of the design to be changed several times. At the time of
writing\footnote{Shortly before the 1.8 release.} a lot of areas feel stable,
@ -98,8 +98,8 @@ the 1.9 development series and for the iterator class I needed a new kind of
document. I decided that was the final straw and started to work on writing this
document while travelling.
Since you read this document it's uploaded in the Wesnoth source tree, this
doesn't mean the document is complete. In fact it more means the opposite, the
Since you read this document, it's uploaded in the Wesnoth source tree. However, this
doesn't mean the document is complete. In fact it means more of the opposite, the
draft is uploaded and I can start to work on finishing the document by adding
the missing information.

54
doc/design/gui2/overall_design.tex
View file

@ -21,22 +21,22 @@ there are three resolution groups:
\item[PC] For the usage on PC's Wesnoth offers the resolutions $800\times 600$
-- $2560\times 1600$\footnote{And larger once screens that size become
available.}.
\item[Netbooks] When the first netbooks were introduced the normal resolution
was $800\times 480$, which is slightly smaller as the minimum PC resolution.
\item[Netbooks] The first time when netbooks were introduced the normal resolution
was $800\times 480$, which is slightly smaller than the minimum PC resolution.
Therefore a start option \textsc{--smallgui} was added making minimal
modifications to the layout\footnote{Actually this is gui1 only.}.
\end{description}
In order to facilitate this range of resolutions the gui2 code allows several
definitions of a window, tuned for a specific resolution. The reason is twofold;
first to make a difference between the hand-held devices and PCs, second allow
first to make a difference between the hand-held devices and PCs, second to allow
different views for different resolutions.
The main example of this feature\footnote{Not yet implemented, but one of the
main reasons to add this feature.} is the attack dialogue. The dialogue has a
button to show the damage calculation, which shows a new dialogue with the
calculation overview. From an UI point of view I consider that rather ugly and
rather have tabs to switch between the view. But when I have a larger screen the
calculation overview. From the UI point of view I consider that rather ugly and
rather have tabs to switch between the views. But when I have a larger screen the
dialogue only fills a small part and I need to switch between tabs to see the
info, in that case I rather have one dialogue without tabs, which directly shows
all information. When the user changes the resolution the dialogue should switch
@ -45,7 +45,7 @@ between these two views, depending on the current resolution.
\paragraph{}
The gui should be able to adapt to the size actually needed, the current gui
uses fixed sizes at some places. This leads to problems that when the screen
uses fixed sizes at some places. This leads to problems such as when the screen
resolution is reduced widgets end up outside the dialogue or get truncated. The
same for some translated texts, where the translation is much longer as the
English original. Gui2 solves this problem by dynamically determining the size
@ -60,7 +60,7 @@ dialogue fits again, might be a bit ugly but at least everything fits again.
It must be possible for WML designers to change the entire gui of Wesnoth with
their own version. For example Spacenoth\footnote{That project is dead, but
that doesn't matter for this example.} is Wesnoth is a space setting, so the
that doesn't matter for this example.} is Wesnoth in a space setting, so the
project might want to use a more fitting user interface.
Adding a new gui is a lot of work and can't be done in one fell swoop, so the
@ -96,7 +96,7 @@ The definition determines how a widget looks and some basic properties, these
properties are the same for all instances of that widget. For example a button
has a minimum size so the decoration can be drawn. It's possible to make
multiple definitions of a button. These different definitions, can look
different have different minimum sizes and other properties.
different, have different minimum sizes and other properties.
These definitions are written in WML and a small loader class loads and
validates the definition. The definition is then added to the list of known
@ -109,16 +109,16 @@ also be reduced.
\paragraph{The builder}
The builder is started from the C++ code, started while building a window. This
window definition contains a list of widget to build with more instance specific
window definition contains a list of widgets to build with more instance specific
values. For example a label builder has the text to show to the user as
parameter.
These builder ``scripts'' are also written in WML and loaded by as small loader
class that does the validation and build the needed widget.
These builder ``scripts'' are also written in WML and loaded by a small loader
class that does the validation and builds the needed widget.
\paragraph{Widget}
The widget itself is written in a larger C++ class and it defines the behaviour
and provide various hooks to modify the properties of that widget. These hooks
and provides various hooks to modify the properties of that widget. These hooks
are used by the builder, but can also be modified later by the engine.
Other hooks provide bindings to react to events. The bindings are now rather
@ -126,8 +126,8 @@ static, but with the new event handling added late in the 1.8 release series
more things are possible. The plan is to enhance this part during the 1.9
release series and deprecate and remove the current interface.
Of course the question ``why wait until 1.9'' raises. The reason is simple it
was added late in the 1.8 cycle to fix certain issues with the MP lobby at that
Of course the question ``why wait until 1.9'' raises. The reason is simple: it
was added late in the 1.8 cycle to fix certain issues with the MP lobby. At that
time I had no time to convert the rest of the code, since I was working on the
MP lobby instead.
@ -144,21 +144,21 @@ or the window can look completely different.
\subsection{Dialogue}
A dialogue is a pure C++ thing. A dialogue shows a window, but is not a window.
A dialogue is a pure C++ thing. A dialogue shows a window, but is not a window itself.
So what's the difference\footnote{These are the definitions used in the gui2
code and not the definition of other window toolkits.}? A window is a dumb
combination of widgets created depending on the definitions in a WML file. After
the window is created it often needs extra content and react to certain events.
the window is created it often needs extra content and reacts to certain events.
For example the language dialogue after building has an empty list of languages.
This is where the dialogue comes into play. The user asks for the language
selection dialogue. The code creates and shows a dialogue. The dialogue code
builds a window, then fills the language list with the available languages and
builds a window, then fills the language list with the available languages,
selects the current language and then shows it to the user.
In other dialogues the code also needs to wire in event handlers or build other
structures. It searches the wanted widget by id, in some cases it doesn't even
care what kind of widget is used. In other cases it needs to be of a certain
class or ``concept''. This allows a flexible design and let the user select the
class or ``concept''. This allows a flexible design and lets the user select the
kind of widget used in some cases.
So the dialogue is the sugar between the WML window and an interactive dialogue
@ -166,8 +166,8 @@ shown in the game.
\section{Directory structure}
This section describes the directories available, instead of listing them in
alphabetic order I list them in a order that makes explaining them more natural.
This section describes the directories available. Instead of listing them in
alphabetic order, I list them in an order that makes explaining them more natural.
\begin{description}
\item[src/gui] The general source code directory with all parts used for the gui.
@ -180,11 +180,11 @@ alphabetic order I list them in a order that makes explaining them more natural.
\item[widgets] This directory contains all widgets used in the library. Every
file contains one widget. Also base classes or concepts of widgets are
stored in this directory. During the development it also accumulated some
helper files, which don't fit in the aforementioned descriptions, this lead
helper files, which don't fit in the aforementioned descriptions - this led
to the creation of the auxiliary directory. Some files haven't been moved to
this new directory yet.
\item[auxiliary] This directory contains items auxiliary classes. Some helper
parts are so large that they got their own subdirectory.
\item[auxiliary] This directory contains auxiliary classes. Some helper
parts became so large that they got their own subdirectory.
\begin{description}
\item[event] Contains all event handling code, the translation from SDL events
@ -195,7 +195,7 @@ alphabetic order I list them in a order that makes explaining them more natural.
single tasked files over huge files controlling a lot of code\footnote{Some
might remember I started with a single file, which did exactly that, but the
file got too large to maintain efficiently.}.
\item[window\_builder] Contains the code to create a widget object, from the
\item[window\_builder] Contains the code to create a widget object from the
widget definition and the data supplied in the window definition. Again the
name of the file matches the name of widget they build. (These files are
also mostly small.)
@ -216,10 +216,10 @@ alphabetic order I list them in a order that makes explaining them more natural.
\item[macro] This directory contains some helper macros, for default font sizes.
\item[widget] This directory contains the definitions of widgets. Since there
can be multiple definitions of a widget their name is the name of the widget
with a suffix. The suffix for the default widgets is, \textsc{default} for
with a suffix. The suffix for the default widgets is \textsc{default}, for
the others an appropriate name is picked.
\item[window] Contains the definitions of windows, the name of the files is the
name of the dialogue they represent.
\item[window] Contains definitions of windows, the name of the file is the
name of the dialogue it represents.
\end{description}
\end{description}

2
src/gui/widgets/window.cpp
View file

@ -1347,7 +1347,7 @@ void twindow::signal_handler_message_show_helptip(
/**
* @page layout_algorihm Layout algorithm
* @page layout_algorithm Layout algorithm
*
* @section introduction Introduction
*