Alto
dev

Developer guide

Application launch

For a code walkthrough, start with Application launch. It follows alto/__main__.py from the terminal command to the first click on an exercise tile.

Run python -m alto from the repository with the project environment active. The installed alto command and the packaged desktop launcher also call main() in alto/__main__.py.

On a normal launch, main() creates the Qt QApplication, applies the saved theme, and opens Alto’s SQLite database. The next window depends on the profiles in that database. Select a numbered region in any screenshot, or use the links beneath it, to open the API reference for the class that owns or draws that component.

First launch

An empty database opens the welcome dialog. Create profile passes the name to Database.add_profile(). A valid name closes the dialog with the new profile selected. Closing this dialog without creating a profile exits Alto before it opens the main window. Database API

Welcome to Alto with a name field and a Create profile button. Welcome to Alto with a name field and a Create profile button.
  1. Name field and Create profile button · ProfileDialog

Returning profiles

startup_profile() first looks for the last-used profile. If it finds one, Alto opens it directly. If there is no remembered match, Alto uses the only profile in the database or, when there are several, opens the chooser shown below. Both the welcome screen and the chooser come from ProfileDialog. Profile selection code

The profile chooser lists Ada and Sam and offers a field for a new profile. The profile chooser lists Ada and Sam and offers a field for a new profile.
  1. Saved profile list · ProfileDialog

The main window

Once a profile is selected, main() constructs a Learner for it, passes the learner to MainWindow, calls window.show(), and enters Qt’s event loop with app.exec(). From here a click on a tile or toolbar button determines what code runs next. Learner API

On the first launch, the main window opens to the exercise tiles. The toolbar and search field belong to MainWindow. The catalog beneath them is a HomePage, which lays out the tiles and emits exercise_chosen when a learner picks one. Alto remembers whether the catalog last showed exercises or lessons.

Alto’s main window with the navigation toolbar, search field, and exercise tiles. Alto’s main window with the navigation toolbar, search field, and exercise tiles.
  1. Exercise and lesson switch · SegmentedControl
  2. Search field · MainWindow
  3. Note Identification tile · ExerciseCard
  4. Exercise catalog · HomePage

Screens reached from the main window

Exercise workspace

Choosing Note Identification calls MainWindow.open_exercise(). It opens an ExerciseView for the exercise and connects it to the active learner. The staff is a separate widget. When tracing a misplaced note, start with StaffWidget. For a click on an answer button, start with ExerciseView.

Note Identification with the exercise list on the left, a treble staff, and letter answers. Note Identification with the exercise list on the left, a treble staff, and letter answers.
  1. Exercise list · MainWindow
  2. Notated question · StaffWidget
  3. Answer buttons · ExerciseView

Lesson catalog and reader

The graduation-cap button switches the catalog to lessons. HomePage uses a TileCard for each lesson and emits the lesson’s key when the learner selects it.

The lesson catalog with Pitches and Notes, Clef Basics, Intervals, and other lesson tiles. The lesson catalog with Pitches and Notes, Clef Basics, Intervals, and other lesson tiles.
  1. Lesson search · MainWindow
  2. Pitches and Notes tile · TileCard
  3. Lesson catalog · HomePage

Opening Pitches and Notes puts the lesson outline on the left. On the right, LessonsPage supplies Leave lesson and Start over. Inside it, LessonView tracks the current step and StepView displays that step’s text, example, and question.

Pitches and Notes open to its first step, with the outline, sound example, and knowledge check. Pitches and Notes open to its first step, with the outline, sound example, and knowledge check.
  1. Lesson outline · LessonNav
  2. Leave lesson and Start over · LessonsPage
  3. Step title and progress · LessonView
  4. Example and knowledge check · StepView

Glossary

The glossary button opens a searchable term list. Selecting harmonic minor scale updates the definition, the example on the staff, and the links to related practice. The example uses the same staff class as Note Identification.

The harmonic minor scale glossary entry with a term list, a staff example, and related exercise tiles. The harmonic minor scale glossary entry with a term list, a staff example, and related exercise tiles.
  1. Term search and list · GlossaryPage
  2. Harmonic minor scale example · StaffWidget
  3. Related exercise tiles · ExerciseCard

Statistics

The chart button opens StatsPage for the active learner. Changing the exercise or date filter updates both the totals and the graphs. Each chart paints its own data. For example, the stacked bars group questions by the period selected under Granularity, while the line beside them shows daily accuracy.

Statistics with filters, six summary tiles, and charts for question volume, accuracy, and speed. Statistics with filters, six summary tiles, and charts for question volume, accuracy, and speed.
  1. Profile and filters · StatsPage
  2. Summary tiles · Tile
  3. Weekly question counts · StackedBarChart
  4. Daily accuracy · LineChart
  5. Accuracy by exercise · HBarChart

Database and answer details

The database button opens the history browser. DatabasePage handles the table choice and search field. To trace where a displayed cell gets its value, follow RowsModel, the model behind the table.

The Database chapter diagrams the relationships between profiles, submitted answers, and question summaries, and documents every stored column.

The database browser with Answers selected, a search field, and rows of recorded attempts. The database browser with Answers selected, a search field, and rows of recorded attempts.
  1. Table selection and search · DatabasePage
  2. Table data · RowsModel

Double-clicking an answer opens a separate QuestionPreview dialog. It recreates the question from the saved record. This chord example has a StaffWidget above the answer and timing details.

A saved Chord Quality question with its staff, correct answer, and recorded response time. A saved Chord Quality question with its staff, correct answer, and recorded response time.
  1. Saved notation · StaffWidget
  2. Answer and timing details · QuestionPreview

Application settings

Menu → Settings opens AppSettingsDialog. Under Appearance → Notation style, each font sample is a StyleCard. The dialog manages the selection, and each card contains its own staff preview.

Application settings showing the category list and the notation font cards. Application settings showing the category list and the notation font cards.
  1. Settings categories · AppSettingsDialog
  2. Notation font cards · StyleCard