105 lines
5.2 KiB
TeX
105 lines
5.2 KiB
TeX
\chapter{Introduction}
|
|
|
|
This paper describes the general design of the gui2 project. The paper is
|
|
divided in several chapters:
|
|
\begin{description}
|
|
\item[Chapter 1] Explains why yet another document is added instead of using the
|
|
doxygen and a short history of the gui2 project.
|
|
\item[Chapter 2] Goes into the general design and structure of the gui2 project.
|
|
\item[Chapter 3] Dives deeper into certain parts of the design of certain
|
|
classes and algorithms.
|
|
\end{description}
|
|
|
|
A omission in this paper is the simple story of how to add your own widgets in
|
|
the C++ code\footnote{The WML part is described in the wiki.}. I have a slightly
|
|
outdated paper on the subject, but decided not to add it; the paper needs
|
|
polishing and updates, but I've some design changes planned for the 1.9
|
|
development series. These changes will also change the way of adding new
|
|
widgets, so that paper needs to be rewritten and added after the rewrite is
|
|
complete.
|
|
|
|
\section{Why why why?}
|
|
|
|
Why is this document written in \LaTeX{} instead of doxygen? The reason is
|
|
simple; during the development of the iterator class I felt I had to write a
|
|
lot. Writing much documentation in doxygen feels awkward. A lot of time is spend
|
|
on formatting, the number of subsections is limited (too low in my opinion).
|
|
Also it's not possible to document why certain functions aren't implemented, a
|
|
solution would be to make the function private and declared only, but that feels
|
|
like an ugly hack.
|
|
|
|
Why is the document needed? In my opinion most manuals written in doxygen are
|
|
great as reference manuals but fail to explain how to do certain things with the
|
|
library and fail to explain why certain things are implemented in the way it is.
|
|
Writing a separate document separated from the code has the disadvantage of
|
|
getting earlier out of sync when an implementation details differs, but this can
|
|
be used as an advantage as well. Since it's hard to keep the details in sync,
|
|
it's a good reason not to dive into these details. This makes a natural
|
|
separation between which part should be in doxygen and which part in this
|
|
manual.
|
|
|
|
Why after the above, are some parts of gui2 documented in separate pages in
|
|
doxygen? This indeed seems a contradiction, but it's not. Remember the first
|
|
paragraph stating it's annoying to write this kind of documentation in doxygen?
|
|
These parts are where I realized it's annoying to do it in doxygen and haven't
|
|
been incorporated in this document\footnote{These parts are still mentioned in
|
|
this paper, but they refer to the doxygen documentation.}.
|
|
|
|
\section{History}
|
|
|
|
The gui2 project was started late in 2007 to fix several problems I had with the
|
|
current gui at that time. The problems I had were:
|
|
\begin{enumerate}
|
|
\item When using small resolutions the gui started to look bad, since widgets
|
|
simply left their container and were drawn outside it.
|
|
\item Most of the gui was hard-coded in the C++ code and thus not configurable
|
|
for normal users.
|
|
\item ThemeWML, the part that allows the user to configure the layout, is not
|
|
well understood by the current developers.
|
|
\end{enumerate}
|
|
|
|
This let to the following design goals:
|
|
|
|
\begin{enumerate}
|
|
\item The gui should look well at every possible resolution and automatically
|
|
fit well.
|
|
\item Everything, or at least as much as possible should be configurable by WML.
|
|
\item The project needed more documentation as the current ThemeWML, and explain
|
|
how to create your own guis.
|
|
\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 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 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,
|
|
but others are still planned to be rewritten. Mainly the handling of scrollbar
|
|
widgets feels awkward and hacky and are slated for a redesign.
|
|
|
|
Other parts of the gui are still in the planning stage and not implemented yet,
|
|
but the project moves along at a steady pace and more features will be added in
|
|
the future.
|
|
|
|
\paragraph{}
|
|
|
|
The history of this document also goes back a long time, it's mostly build from
|
|
various scraps of notes I have on my system. The plan was to change these notes
|
|
to doxygen format some day put it in the source. The problem was to find a nice
|
|
place in the source to do so.
|
|
|
|
This lead to the fact the notes just stayed on my system and the number of
|
|
notes accumulated. During travelling to work I started to design some things for
|
|
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. 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.
|
|
|