User manual

Overview

This page is the one SPPAS opens when it starts. It is the entrance hall: nothing is done here, everything starts from here.

The window is divided into four spaces, and you will find the same four in every other page of SPPAS.

The header, at the top: it says which page you are reading.
The menu, along the left edge: a column of buttons, the same wherever you are. It is how you go from one place to another.
The body, in the middle: what the page is for. Here, the list of what you can start.
The footer, at the bottom: the SPPAS picture, who wrote the software, and a button to climb back to the top of the page.

The menu, on the left

The menu shows only the drawings when it is narrow. Move the mouse over it and it widens, and each drawing is given its name. Here is what each button does.

Pin menu. Click it and the menu stays wide open, without having to move the mouse over it. Click it again and it goes back to its narrow shape.

Theme. Changes the colors of the whole software. Click it several times: each click tries the next set of colors, and the last one brings you back to the colors of SPPAS.

Contrast. Click it and the writing becomes bigger, more spaced out and drawn with a font made to be read easily. Click it again to come back.

Color. Switches between a light page, black writing on white, and a dark page, white writing on black. A dark page is often more comfortable in a room with little light.

Dashboard. Brings you back to this page, wherever you are. When you are lost, this is the button to click.

Help. Opens the document explaining the page you are reading -- the one you have under your eyes right now. A button drawn in a duller color, which the mouse refuses to click, means that this page has no document yet.

Journal. Opens a page where SPPAS writes what it is doing, and why. Read it while an annotation is running to follow where it is, afterwards to see what was produced and what was left aside, and the day something goes wrong to understand what happened -- and to say it precisely when reporting a problem.

Exit. Stops SPPAS. It is the only way of leaving properly: see Stopping SPPAS.

Keyboard shortcuts

A key does the same thing as the button it names, and the keys are the same in every page of SPPAS.

Going from one place to another
Key	What it does
h, H or ?	Opens the document of the page you are reading. On a page whose document is not written yet, nothing happens.
j or J	Opens the Journal in its tab.
q or Q	Quits the page and goes back to the Dashboard, wherever you are.

Changing how the page looks
Key	What it does
+	Turns the contrast on, and off.
*	Switches between a light page and a dark one.
>	Applies the next set of colors.

A key is never taken from what you are writing: while the cursor is in a text field, in a list or on a button, the letters go to it and to nothing else.

Stopping SPPAS

SPPAS is a software running on your computer, and the pages you are reading are the way you talk to it. Leaving is therefore an action of its own: click the Exit button of the menu, at the bottom on the left. Your settings are written down, then the software stops.

Closing the tab, or closing the browser, does not stop SPPAS. The software keeps running on your computer, and what you changed during the session is not written down. Leave by the Exit button, not by the cross of the window.

Leaving protects what you are working on. If the Desktop window has files you changed without saving them, SPPAS does not stop: it asks you there, and this page turns grey and waits, with a box telling you where to answer. Answer in the Desktop window -- save, or leave without saving -- and SPPAS stops. Say no, and nothing is closed: your work is untouched, and you can go on.

Once SPPAS is stopped, the pages left open in the browser stay readable: they are the last thing SPPAS said, and nothing answers them any more. A button clicked there does nothing.

To work again, start SPPAS from your computer as you did the first time: the page you are reading now opens again, and the software answers.

The body, in the middle

The first time: the licence

At the very first start, the page shows a text and waits for you to accept it. It is the licence: what you are allowed to do with SPPAS, which is free and open-source. Nothing else is shown until you have answered. The question is asked once and never again.

The button to click looks like this one:

The box asking for the Journal

Once the licence is agreed, SPPAS watches whether the tab of the Journal is open. As long as it is not, a box stays at the top of the page:

Please check the Journal tab regularly.

Click that button and the Journal opens in its own tab. The box then goes away by itself, without reloading anything, and it comes back the day that tab is closed. It is not an error message: it says that SPPAS is writing what it does somewhere nobody is reading.

What you can start

Each rectangle is one part of SPPAS: a picture, a name, one line saying what it is for, and a button to start it. Click the button and that part opens. Here is one, drawn as you see it on the page:

The name of the part

One line saying what this part of SPPAS is for.

The first one, Desktop, opens the desktop of SPPAS: the window where all its features are gathered today. The other parts are being moved into the browser one by one.

When a part cannot be started, its drawing is grey and its Launch button does not answer: what this part needs is not installed on your computer. Run Setup to install it.

The name written above the rectangles

Above them, SPPAS writes the name of the current workspace. A workspace is the set of files you are working on -- your recordings and everything SPPAS produces from them.

It is written here for information only: this page does not let you change it.

Below: knowing more, and the web

Two sets of rectangles follow, and they do not behave the same way.

Under Find out more, the rectangles open pages of SPPAS itself: what this software is, how to name it in the bibliography of your report, the Journal, and a form to write to the author. They take the place of this page: to come back, click the Dashboard button of the menu.

Under Learn more on the Web, the rectangles lead to pages of the internet: the site of SPPAS, its book, video tutorials, the questions users ask most often, the source code, the resources for the languages, and a prize the software received. Each of them opens a new tab in your browser: this page stays where it is, and you come back to it by closing the tab that opened.

Here is the first of them, the one leading to the site of SPPAS. This one is only an image of it: clicking it does nothing.

The header and the footer

The header holds the name of the page. Nothing is to be clicked there.

The footer holds the picture of SPPAS, the name of who wrote it, and the year. At its end, the button climbs back to the top of the page, which is handy on a long one -- this document, for instance.

Developer manual

Organisation

The application lives in sppas/ui/swapp/app_dashboard/. It follows the MVC pattern shared by every application of the swapp package.

app_dashboard.py -- DashboardWebData, which parses the JSON configuration and answers which page it can bake.
dashboardmaker.py -- DashboardResponseRecipe, the bakery of dashboard.html: it receives the events and decides whether the page is created again.
dashboard_controller.py -- DashboardController, which holds the answers to the events and fills the view from the model.
dashboard_view.py -- DashboardView, which builds the HTML tree and nothing else.
nodes/ -- the cards of the applications, the buttons of the links, and the dialogs.

What the page is made of

The registries

The cards are not written in the page: they come from two registries. The applications are declared in WEB_APPLICATIONS, the pages in WEB_PAGES, as a list of WebPageInfo(recipe, show). A page declared with show=True gets its link in the section of information. A spin-off adds its own entries through SWAPP_PAGES.

The menu is never fed from a registry: its list is fixed. The Dashboard is where the whole set is shown, the menu is where the daily loop is.

The nodes

AppsNode.create_app_card() builds a card: an article holding the picture, the title, the description and the launching button. The links of the two other sections are built by LinksNode and AboutsNode: an a element carrying the classes card and link-button -- a link, not a button, since it leads somewhere instead of doing something.

The events

_process_events() of the recipe answers four of them, and returns whether the whole page must be created again.

workspace_name -- the periodic request of the JavaScript. It returns the name of the workspace, the path of its file and whether the Journal tab is alive. The page is not baked again: the browser updates what changed.
handle_licence_agreement -- the licence is agreed, the page is built again without the dialog.
handle_start_sppas -- the wx interface is launched. The answer is the error, if any, or the state saying it started.
event_bake=close -- leaving SPPAS. The page answers 410, Gone.

The accessibility parameters of Whakerexa never reach this method: the base recipe removes every wexa_ parameter, and the name of the CSS theme with them. Both belong to the client alone.

The stylesheets

Four sheets are loaded, in this order.

main_swapp.css -- the shape of every page: sizes, spacings, the side menu, the cards. No color is written there.
main_swapp_identity.css -- what identifies SPPAS whatever the theme: the reading font, and the colors naming a destination, a status or a step. It is never swapped.
main_swapp_theme.css -- the theme, carrying the id wexa-theme: the ThemeManager of Whakerexa swaps its href to change the look of the page. It is the default theme, named swapp.
app_dashboard.css -- what belongs to this page alone: the panel of the applications and the seven links.

The scripts

dashboard_manager.js attaches what the page needs: the click on a card of an application, the periodic request refreshing the workspace and the Journal dialog, and the buttons of the dialogs. The links towards the internal pages are not handled there: they are a elements, followed by goToLink() of Whakerexa, which carries the accessibility parameters over to the page.