guitar_prometheus::AppController

Top-level state and orchestration for the running app. More…

#include <AppController.h>

Inherits from juce::ChangeBroadcaster, juce::Timer

Public Functions

	Name
	AppController()
	~AppController() override
std::vector< std::string >	createNewProject(const juce::File & musicXmlPath, const std::string & name) Create a new Project from a MusicXML file.
std::vector< std::string >	openProject(const juce::File & path) Open a `.gpproj` from disk; materializes the Score.
std::vector< std::string >	replaceMusicXml(const juce::File & newSourcePath) Replace the active project’s embedded MusicXML with a freshly-imported source.
std::vector< std::string >	addMusicXmlToProject(const juce::File & sourcePath) Parse a MusicXML file and merge its parts into the active project’s runtime Score via `Util::merge`.
bool	saveProject() Save the active Project to its current path.
bool	saveProjectAs(const juce::File & path) Save the active Project to the given path, updating the tracked current path.
void	closeProject() Drop the active Project and Score.
void	setProfileForPart(const juce::Uuid & partId, const std::optional< juce::Uuid > & profileId) Bind / unbind a profile to a part.
void	setTempoForMeasure(int measureNumber, int bpm) Override the tempo for the downbeat of a specific measure.
void	setTempoOverride(int measureNumber, int tickWithinMeasure, int bpm) Override the tempo at `(measureNumber, tickWithinMeasure)`.
void	clearTempoOverride(int measureNumber, int tickWithinMeasure) Drop the tempo override at `(measureNumber, tickWithinMeasure)`.
void	setProfileOverrideForPart(const std::string & scorePartId, const GuitarPrometheus::Profiles::ProfileFormState & form) Set a per-file profile override for a part keyed by its scorePartId.
void	clearProfileOverrideForPart(const std::string & scorePartId) Drop the per-file profile override for `scorePartId`.
void	setOctaveOffsetForPart(const std::string & scorePartId, int offset) Set the octave offset for a specific part in the project’s export config.
void	setHumanizerForPart(const std::string & scorePartId, std::optional< GuitarPrometheus::Midi::HumanizerConfig > cfg) Set the per-part humanizer config override.
void	setStackPickDirectionForPart(const std::string & scorePartId, bool stack) Set the per-part toggle for stacking pick-direction keyswitches alongside single-resolution technique keyswitches.
juce::Uuid	createNewProfile(const std::string & name) Mint a new empty profile, persist it via the ProfileStore, and broadcast a change so any open editor reloads.
bool	hasProject() const
bool	isDirty() const
const std::optional< juce::File > &	currentPath() const
const std::optional< GuitarPrometheus::Project::Project > &	project() const
const std::optional< GuitarPrometheus::SongStructure::Score > &	score() const
GuitarPrometheus::Profiles::ProfileStore &	profileStore()
const std::vector< std::string > &	parserWarnings() const Parser warnings collected when the active Score was last materialized.
std::vector< juce::File >	recentProjects() const Recently-opened project paths, most-recent-first.
void	clearRecentProjects()
AppPreferences &	prefs() Direct access to the controller’s `[AppPreferences]()`.
void	dismissParserWarnings() Hide the unknown-techniques banner until next file load.
bool	parserWarningsDismissed() const

Detailed Description

class guitar_prometheus::AppController;

Top-level state and orchestration for the running app.

Owns the active Project, the materialized Score, the ProfileStore, and the project-file path. Broadcasts when state changes so panels refresh.

UI panels read state via getters, mutate via typed methods (setProfileForPart, setOctaveOffset, etc.), and listen to addChangeListener for refresh signals.

Public Functions Documentation

function AppController

AppController()

function ~AppController

~AppController() override

function createNewProject

std::vector< std::string > createNewProject(
    const juce::File & musicXmlPath,
    const std::string & name
)

Create a new Project from a MusicXML file.

Parses the XML, builds an embedded gzip Project, and loads it as the active project. The project has no on-disk file yet; the user must Save / Save As to persist it. Returns the parser diagnostics on failure (empty score).

function openProject

std::vector< std::string > openProject(
    const juce::File & path
)

Open a .gpproj from disk; materializes the Score.

function replaceMusicXml

std::vector< std::string > replaceMusicXml(
    const juce::File & newSourcePath
)

Replace the active project’s embedded MusicXML with a freshly-imported source.

Return: Diagnostics vector (errors first, then carry-over warnings). Non-empty errors mean the replacement was rejected.

Profile bindings carry forward by score-part-id; tempo overrides and per-part export config drop entries that no longer apply. The Project’s identity (UUID + salt + name) is preserved.

function addMusicXmlToProject

std::vector< std::string > addMusicXmlToProject(
    const juce::File & sourcePath
)

Parse a MusicXML file and merge its parts into the active project’s runtime Score via Util::merge.

Return: Diagnostics vector (errors first, then warnings). Non-empty errors mean the merge was rejected.

Score-part-id collisions are suffix-deduped and surfaced in the returned diagnostics. New parts get a default (empty) TrackBinding.

The embedded MusicXML in the .gpproj blob stays single-source — F11.6 will add a manifest schema that persists merged-in payloads alongside the primary one. Until then a save/reopen cycle drops the merged delta; document the limitation in the UI.

function saveProject

bool saveProject()

Save the active Project to its current path.

Returns true on success; false if no active project or no path set yet (caller should fall back to Save As).

function saveProjectAs

bool saveProjectAs(
    const juce::File & path
)

Save the active Project to the given path, updating the tracked current path.

function closeProject

void closeProject()

Drop the active Project and Score.

function setProfileForPart

void setProfileForPart(
    const juce::Uuid & partId,
    const std::optional< juce::Uuid > & profileId
)

Bind / unbind a profile to a part.

Updates both the persistent Project (trackBindings, scorePartId-keyed) and the runtime resolution map (partUuid → profileUuid). Pass nullopt to clear.

function setTempoForMeasure

void setTempoForMeasure(
    int measureNumber,
    int bpm
)

Override the tempo for the downbeat of a specific measure.

bpm == 0 (or any value outside [1, 999]) clears the override. Thin wrapper around setTempoOverride with tickWithinMeasure == 0 for compatibility with code paths that haven’t migrated to the F9.6 (measure, tick) API.

function setTempoOverride

void setTempoOverride(
    int measureNumber,
    int tickWithinMeasure,
    int bpm
)

Override the tempo at (measureNumber, tickWithinMeasure).

bpm outside [1, 999] clears the entry. tickWithinMeasure is in PPQN-480 ticks from the measure downbeat (0 = downbeat). Schema v2 stores the (measure, tick) key; v1 projects migrate forward with tickWithinMeasure == 0 for every entry.

function clearTempoOverride

void clearTempoOverride(
    int measureNumber,
    int tickWithinMeasure
)

Drop the tempo override at (measureNumber, tickWithinMeasure).

No-op if no entry exists.

function setProfileOverrideForPart

void setProfileOverrideForPart(
    const std::string & scorePartId,
    const GuitarPrometheus::Profiles::ProfileFormState & form
)

Set a per-file profile override for a part keyed by its scorePartId.

The override is a complete ProfileFormState — at export time the pipeline applies it on top of the part’s bound profile via applyProfileEdits, so every field the override sets replaces the bound profile’s. Use this to tweak a single song’s keyswitch / velocity behaviour without polluting the global profile library.

function clearProfileOverrideForPart

void clearProfileOverrideForPart(
    const std::string & scorePartId
)

Drop the per-file profile override for scorePartId.

The pipeline falls back to the part’s bound profile on next export. No-op if no override exists for that part.

function setOctaveOffsetForPart

void setOctaveOffsetForPart(
    const std::string & scorePartId,
    int offset
)

Set the octave offset for a specific part in the project’s export config.

Broadcasts a change only if the value actually changed.

function setHumanizerForPart

void setHumanizerForPart(
    const std::string & scorePartId,
    std::optional< GuitarPrometheus::Midi::HumanizerConfig > cfg
)

Set the per-part humanizer config override.

std::nullopt clears the override so the bound profile’s settings (if any) apply. Broadcasts a change.

function setStackPickDirectionForPart

void setStackPickDirectionForPart(
    const std::string & scorePartId,
    bool stack
)

Set the per-part toggle for stacking pick-direction keyswitches alongside single-resolution technique keyswitches.

Default (no entry in the map) is true — historic behaviour.

function createNewProfile

juce::Uuid createNewProfile(
    const std::string & name
)

Mint a new empty profile, persist it via the ProfileStore, and broadcast a change so any open editor reloads.

Return: The new profile’s UUID, useful for the editor to auto-select on open.

The new profile is pitched (no drumMap), category “User”, with a default MezzoForte velocity of 80; the caller can flip it to a drum profile via the editor’s drum toggle.

function hasProject

bool hasProject() const

function isDirty

bool isDirty() const

function currentPath

const std::optional< juce::File > & currentPath() const

function project

const std::optional< GuitarPrometheus::Project::Project > & project() const

function score

const std::optional< GuitarPrometheus::SongStructure::Score > & score() const

function profileStore

GuitarPrometheus::Profiles::ProfileStore & profileStore()

function parserWarnings

const std::vector< std::string > & parserWarnings() const

Parser warnings collected when the active Score was last materialized.

function recentProjects

std::vector< juce::File > recentProjects() const

Recently-opened project paths, most-recent-first.

Persisted across launches.

function clearRecentProjects

void clearRecentProjects()

function prefs

AppPreferences & prefs()

Direct access to the controller’s [AppPreferences]().

Used by [MainWindow](/api-reference/classes/classguitar__prometheus_1_1mainwindow/) to plumb the same prefs instance into [Theming::ThemeManager](/api-reference/classes/classguitar__prometheus_1_1theming_1_1thememanager/) — sharing one PropertiesFile-backed object avoids the stale-cache problem that would occur with two parallel preferences instances writing to the same on-disk settings file.

function dismissParserWarnings

void dismissParserWarnings()

Hide the unknown-techniques banner until next file load.

function parserWarningsDismissed

bool parserWarningsDismissed() const

Updated on 2026-05-29 at 07:39:52 +0000