Technical Overview
Find out more about:
- Languages and toolkits; why wxWidgets and why C/C++?
- Architecture; the modules and how they are connected
- Status of files; what's finished, what's not and what needs optimizing?
There is also a to-do list in the docs directory of the trunk.
Languages and Toolkits
The project is a hybrid of straight-C and C++. The C components include:
- Compiler, parser
- Virtual machine
- Execution environment
- Fields and buttons
- File format
The C++ components include:
- Application startup/termination
- GUI windows, menus, palettes and event capture
- Paint tools
- Graphics compression, card and background artwork
The C++ components are larely based upon the wxWidgets cross-platform GUI toolkit.
The reasons for this split include:
- A personal dislike of C++:
- There are too many ways to do the same thing (such as pointers and references, new and malloc); it promotes the development of incompatible, incomprehensible, complex and inconsistent APIs.
- Compilation times for simple C++ files on my current hardware are often 5-20x that of the equivalent C source file; during a massive debug/refactoring session I just can't be bothered.
- The language seems to have taken a long time to mature with what appear to be major changes along the development (STL ?). Compiler support for various language features has at times appeared unpredictable/inconsistent.
- Partial-independence from the GUI toolkit; this may or may not be considered a good thing. Since it increases the disconnect between several components (environment, virtual machine, Application and StackWindow) I'm not sure it was worth it. Like most things I thought it was a good idea when I started.
I thought perhaps I might find time one day to write a native Cocoa version of the application for MacOS X, or even a cut-down version for iPhone. I also wanted to keep my text field completely separate from the UI so I can more easily borrow the code in other projects. - My recent experience was in C and wxWidgets was written in C++
WxWidgets Toolkit
I stumbled upon wxWidgets on several occasions in the past while looking for a cross-platform GUI toolkit. I'm not really sure why I chose it but it seemed to have a good following (many applications listed and bindings for popular languages; Python and ?)
Cross-platform software is a key requirement for me. I work on Windows at work, have always tended to use Mac at home and desire the freedom to be able to move between platforms and take my work with me. Ironically a project which should have started out on the Mac has ended up with the first release on Windows due to my current computing situation and expenses.
Architecture
Everything from the Application layer up is implemented using C++ and wxWidgets. Everything else is C and the standard library.
Architecture block diagram: showing layers from user (top) to system (bottom)
Perhaps an interesting ramification of this structure is the possibility of building a console (text-mode) version of the application; with access to buttons and fields but without the graphics obviously. Why you would want to do this I have no idea.
The diagram below illustrates the relationships between source file modules and again the heirarchy from user to operating system. C++ modules are highlighted in a different colour.
Architecture files diagram: shows connections between source files
Note that the environment module (env) acts as an interface between the user interface, and program behaviours and implementation.
CinsScript Influence
The scripting language, CinsScript, has had a significant impact on the design of certain inter-module APIs. Specifically, the access and mutation of button and field properties by the user interface uses the same mechanism as the virtual machine uses. The pathway is therefore implemented only once, but used both by the interface and the scripting language environment. The downside to this is the format the properties are accessed tends to be biased towards the virtual machine and is quite verbose.
File Status
Quality Legend
| 1 | Incomplete, likely unreliable, API changes likely |
| 2 | Partially implemented, some changes likely, API unlikely to change |
| 3 | Mostly implemented, minor changes only |
| 4 | Implemented, considered stable, optimization(s) possible |
| 5 | Implemented, considered stable, optimal |
File Descriptions
| AboutDialog | C++ | About box, copyright notices | 5 |
| Application | C++ | Application startup/termination, menu event handlers, C callback interface | 1 |
| button | C | Buttons; behaviour and appearance | 2 |
| common | C | Shared structures, error handling and convenience/utility routines | 3 |
| env | C | Environment; command and event behaviour, current tool and edit modes, current card | 1 |
| field | C | Fields; behaviour and appearance | 3 |
| gdi | C | Management of fields and buttons within the card window, event distribution and wrappers for wx graphics routines | 2 |
| stack | C | Stack file format | 3 |
| gen | C | Script language byte-code generator | 2 |
| parse | C | Script language parser | 3 |
| vm | C | Script language virtual machine | 2 |
| MessageBox | C++ | Small utility window to type language instructions and expressions, and see the results | 5 |
| PropertiesPalette | C++ | Editor for button, field, card, background and stack properties | 5 |
| ScriptDialog | C++ | Script language editor | 3 |
| StackWindow | C++ | Main window, menubar layout, event capture, paint tools, card artwork and visual effects | 1 |
| ToolsPalette | C++ | Utility palette to select current tool with a grid of icon buttons | 3 |
Table Updated: January 31, 2010.
Occasionally there may be other source files present that are not in any documented list. These are usually placeholders for modules that may be written in the future, or just old files that will eventually be removed.