This is a draft specification for the major architectural changes planned for Virtaal 0.3. The main aim of these changes is to create a stable, robust and easy-to-use platform from which all the future changes can be easily implemented. For this purpose it has been decided to use a MVC architecture.
While this page is in its draft stage all statements made herein should be considered suggestions or opinions. Specific sections, paragraphs or sentences that are not yet decided on will be marked with ”(??)”.
To reach the goals stated in the introduction above we will be implementing a MVC architecture in the code. See the diagram below for the proposed architectural structure.
With a basic understanding of the MVC pattern as well as knowledge of Virtaal's features, the diagram should be reasonably self-explanitory. The following description contains notes about unexpected, unclear or new concepts introduced.
Store group in the diagram represents the model, view and controller that is related to store-level activities. In terms of the GUI, the
StoreView would be the main
gtk.TreeView widget as it is in Virtaal 0.2. The
StoreModel is a basic wrapper for basic translation store which (mainly) handles the loading, saving and parsing of translation files.
Unit group represents the unit-level components. The
UnitView specifically represents the GUI of the unit editor (the selected unit) as it is in Virtaal 0.2.
Mode MVC-triplet produces a
ModeCursor that specifies which units are usable in the currently selected mode. This cursor will be used by the
MainWindow object is responsible for managing the creation of the other main components and may also serve as proxy for communications where no “official” channel is available(??).
Adding features to Virtaal will be much easier once this architecture is in place. The way in which this is done can make the difference between a nice, modular system and a convoluted mountain of messy code. Extensions can be done in one of three ways(??):
This section contains specifications for all source code-related issues. Please add any missing info.
As per PEP 8 class names are written in camel case, starting with a capital letter.
As per PEP 8, as well as existing conventions in the Translate Toolkit and Virtaal, variable names are all-lower case and words should be split with underscores.
Names of variables representing Gtk+ widgets should have a prefix describing the type of widget it represents. Here are some prefixes:
@typedirective) and the return value if not
None, except where these are very obvious.
This is section is only applicable to the
virtaal/ source sub-directory, seeing as the rest of the directory structure is serving us quite well.
Related code should definitely be grouped together into modules and sub-modules. Here are some possibilities:
controllersand put the files containing the relevant classes in each of those directories. Example for unit-related class files:
modesub-directories. Example for unit-related class files:
Note that there is no mention of a plug-ins directory, because it has not been decided if plug-ins will be supported.
API documentation should be generated from the epydoc documentation strings in the source code. Other, more descriptive documentation should be maintained on the wiki.
Seeing as this implementation will affect our planning schedule, the implementation of specific parts of the code should be ordered in such a way that other planned work can be started as soon as possible.
All implementation should reuse as much code as possible from Virtaal 0.2 in order to save development time.
(Note that all time estimations include the writing of tests)
ModeCursors and using them for navigation.
gettargetlanguage()in stead of the store-level equivalent.