From 7fbfe57b3670c7b731106fdd5aefab83f5fc3100 Mon Sep 17 00:00:00 2001 From: Mark de Wever Date: Sat, 9 Apr 2011 16:00:26 +0000 Subject: [PATCH] Fix documentation errors/typos and grammar. Errors found by zaroth while reading the document. (patch #2613). --- .../gui2/creating_widgets_and_dialogs.tex | 126 +++++++++--------- doc/design/gui2/design_details.tex | 46 +++---- doc/design/gui2/introduction.tex | 12 +- doc/design/gui2/overall_design.tex | 54 ++++---- src/gui/widgets/window.cpp | 2 +- 5 files changed, 119 insertions(+), 121 deletions(-) diff --git a/doc/design/gui2/creating_widgets_and_dialogs.tex b/doc/design/gui2/creating_widgets_and_dialogs.tex index 809ea00b486..2249785087e 100644 --- a/doc/design/gui2/creating_widgets_and_dialogs.tex +++ b/doc/design/gui2/creating_widgets_and_dialogs.tex @@ -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} diff --git a/doc/design/gui2/design_details.tex b/doc/design/gui2/design_details.tex index cd957fbc53e..f21104d928e 100644 --- a/doc/design/gui2/design_details.tex +++ b/doc/design/gui2/design_details.tex @@ -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. diff --git a/doc/design/gui2/introduction.tex b/doc/design/gui2/introduction.tex index 6ba6f4832dd..8d6dc0c4845 100644 --- a/doc/design/gui2/introduction.tex +++ b/doc/design/gui2/introduction.tex @@ -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. diff --git a/doc/design/gui2/overall_design.tex b/doc/design/gui2/overall_design.tex index 1c95431a929..96beacfd999 100644 --- a/doc/design/gui2/overall_design.tex +++ b/doc/design/gui2/overall_design.tex @@ -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} diff --git a/src/gui/widgets/window.cpp b/src/gui/widgets/window.cpp index 828e05bc6b4..abc0336a3e3 100644 --- a/src/gui/widgets/window.cpp +++ b/src/gui/widgets/window.cpp @@ -1347,7 +1347,7 @@ void twindow::signal_handler_message_show_helptip( /** - * @page layout_algorihm Layout algorithm + * @page layout_algorithm Layout algorithm * * @section introduction Introduction *