Crate narthex_engine_trait[−][src]
Expand description
This system enables building portable apps that run on both PCs and Android mobile phones.
There is an example repository that implements an example app (the classic Wumpus game) for both the PC and for Android mobile. The two platform implementations share a common back end (‘engine’) and otherwise use boilerplate code that differs little across applications.
Overall
The system contains the following parts, each of which is in a GitHub repository. This section describes which of these parts need to be changed to implement a different app. Some parts do not require any change, some parts are examples that should not require much change, and the the engine crate will need to be written to provide the functionality of the new app.
- narthex-engine-trait defines EngineTrait; this should not require any change to implement a new app.
- narthex-wumpus is an example of the use of this framework. See the GitHub page for narthex-wumpus for this. The narthex-wumpus repository contains:
- engine crate contains the code to implement the wumpus game, this implements EngineTrait.
- wumpus crate is the front-end for the PC implementation of the game; this should require little change to implement a new app.
- wumpus-c crate is C bindings for the engine crate; this should require little change to implement a new app.
- Wumpus is the Android code (Java etc) for the Android implementation of the game; this should require little change to implement a new app.
- narthex-web-app is some code that makes it easier to put together the PC implementation of the app; this should not require any change to implement a new app. See the narthex-web-app documentation for more information.
This page describes the EngineTrait interface between an Engine and a user interface. This crate should not require any change to implement a new app.
Creating an engine (overall architecture)
To create an app, you need to create the following types in your application. The engine (satisfies EngineTrait) does the application-specific functions.
- At the start, the user interface will create a web view (a browser) for the engine.
- The engine, at initialisation, is passed a
Config(satisfies ConfigTrait) by the main program. - The user interface will call
engine.initial_html()and the engine must return an HTML string. - Then, for each user input, the user interface passes an Action (satisfies ActionTrait) to the engine using
engine.execute(action)and the engine must return a Response (satisfies ResponseTrait) back to the user interface. - Also, for application event, the user interface passes an Event to the engine using
engine.execute(action)and the engine must return a Response (satisfies ResponseTrait) back to the user interface. - At the end, the engine will return a response with
response.shutdown_required()and the user interface will terminate the application.
Enums
Events are requirements for an event (generated by the execution environment and passed to the engine), for example app shutdown. Events are like actions but generated by the app not the user interface. There is a fixed list of Events as they are based on the architecture of the platforms (PC, Android), but it may be necessary to add to the list e.g. to support other Android Activity events.
type of execution environment e.g. PC, Android. This is passed to the engine to handle platform-specific functions.
An ResponseKind describes the broad category of response.
Traits
ActionTrait is the requirements for an action (command sent from the user interface to the engine)
ConfigTrait is the requirements for the engine configuration (passed to the engine when it it created).
The EngineTrait defines what an engine must be able to do. The associated types will need to be set by the application author in accordance with the specific needs of the application. See the wumpus example.
ResponseTrait is the requirements for a response (sent from the engine to the user interface). One possible response is that shutdown is required