This is the specification for the major architectural changes implemented 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.
This page has been copied and adapted from the draft.
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 is 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 alters the
StoreCursor in the
StoreController that specifies which units are usable in the currently selected mode. This cursor is used by the
MainController object serves as proxy for communications where no “official” channel is available. For example the
StoreController gets its reference to the
UnitController instance via the
Extensions can be done in one of three ways:
Currently there is not any plug-in support Virtaal yet, so this section will be completed as plug-in support is finished.
This section contains some notes about specific components.
UndoControllerthat contains 5 lines of Gtk+ code. Yes, it should actually be in a view object, but creating a whole new class for only those 5 lines seem to be a bit too extreme.
unselected()methods do not take any parameters, because we don't want to make any assumptions about what the mode does. If a mode needs any information, it can collect that via its connection to
ModeControllerand then to
BaseMode, and so also all other modes, do not inherit from
GObjectWrapper, because, as “dynamic” pieces of code, it is not condsidered safe (or necessary) to connect to a mode's event(s). This can, of course, easily be changed later.
ModeView.mode_boxMUST be contained in the mode's
self.widgetslist to make sure that it can be removed when the mode is unselected.
Contains some minor bugs:
StoreModel._get_valid_units()adjusts all stats to be relative to
stats['total']. That is,
stats['total']is accepted as a list of valid unit indexes. Thus all stats are changed to be relative to the list of valid units. This is potentially a bad thing to do, although I can't of a reason at the moment.
gtk.Eventboxitself, in stead of a factory for such an object, might have been a bit overkill.
StoreCursormore a part of
The following files are currently either unused or are still being integrated into Virtaal:
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.
All implementation reuses as much code as possible from Virtaal 0.2 in order to save development time.
ModeCursors and using them for navigation.
gettargetlanguage()in stead of the store-level equivalent.