Configuration
Keywords: developer_docs

Subsections

- - - Reading configuration
    - Writing configuration
    - Song state
    - How to add new items

#
Configuration

Configuration is a bit pesky in MusE in its current state. If you get confused by reading this chapter, that's a sign of a sane mind.

There are three kinds of configuration items:

- (1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings
- (2) Per-Song configuration, like whether to show or hide certain track types in the arranger
- (3) Something in between, like MIDI port settings etc. They obviously actually are global configuration issues (or ought to be), but also obviously must be stored in the song file for portability. (This problem could possibly be solved by the feature proposal in 3.7.

#### Reading configuration

`fterfirstv`v=95 _ `v=58 : `v>64 `v<91 vvv <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>oid MusECore::readConfiguration(Xml&, bool, bool)` in `fterfirstc`c=95 _ `c=58 : `c>64 `c<91 ccc <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>onf.cpp` is the central point of reading configuration. It is called when MusE is started first (by `fterfirstb`b=95 _ `b=58 : `b>64 `b<91 bbb <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>ool MusECore::readConfiguration()`), and also when a song is loaded.
It can be instructed whether to read MIDI ports (3), global configuration and MIDI ports (1+3). Per-Song configuration is always read (2).

When adding new configuration items and thus altering `fterfirstr`r=95 _ `r=58 : `r>64 `r<91 rrr <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>eadConfiguration()`, you must take care to place your item into the correct section. The code is divided into the following sections:

- Global and/or per-song configuration (3)
- Global configuration (1)
- Code for skipping obsolete entries

The sections are divided by comments (they contain `--`, so just search for them). Please do not just remove code for reading obsolete entries, but always add an appropriate entry to the 'skipping' section in order to prevent error messages when reading old configs.

#### Writing configuration

Global configuration is written using the `fterfirstM`M=95 _ `M=58 : `M>64 `M<91 MMM <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>usEGui::MusE::writeGlobalConfiguration()` functions, while per-song-config is written by `fterfirstM`M=95 _ `M=58 : `M>64 `M<91 MMM <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>usEGui::MusE::writeConfiguration()` (notice the missing `fterfirstG`G=95 _ `G=58 : `G>64 `G<91 GGG <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>lobal`; both implemented in `fterfirstc`c=95 _ `c=58 : `c>64 `c<91 ccc <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>onf.cpp`).

`fterfirstw`w=95 _ `w=58 : `w>64 `w<91 www <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>riteConfiguration` is actually just a subset of the code in `fterfirstw`w=95 _ `w=58 : `w>64 `w<91 www <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>riteGlobalConfiguration`. Duplicate code!

#### Song state

Additionally to per-song configuration, there is the song's state. This contains "the song", that is all tracks, parts and note events, together with information about the currently opened windows, their position, size, settings and so on. Adding new items here is actually pretty painless: Configuration is read and written using `fterfirstM`M=95 _ `M=58 : `M>64 `M<91 MMM <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>usECore::Song::read` and `fterfirst:`:=95 _ `:=58 : `:>64 `:<91 ::: <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>:write`, both implemented in `fterfirsts`s=95 _ `s=58 : `s>64 `s<91 sss <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>ongfile.cpp`. There are no caveats.

#### How to add new items

When adding global configuration items, then add them into the second block ("global configuration") in `fterfirstr`r=95 _ `r=58 : `r>64 `r<91 rrr <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>eadConfiguration` and into `fterfirstw`w=95 _ `w=58 : `w>64 `w<91 www <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>riteGlobalConfiguration`.

When adding just-per-song items, better don't bother to touch the "configuration" code and just add it to the song's state (there might be rare exceptions).

When adding global configuration items, make sure you add them into the correct section of `fterfirstr`r=95 _ `r=58 : `r>64 `r<91 rrr <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>eadConfiguration`, and into `fterfirstw`w=95 _ `w=58 : `w>64 `w<91 www <`<=95 _ `<=58 : `<>64 `<<91 <<< c@amelhyph<269>>riteGlobalConfiguration`.