Technical documentation

Overview

The main modules

  • The motor of PYNWC is the main script Pythonnwc.

    For the Noteworthy Software application (NWC), Pythonnwc is just one user tool, but when started, you see a window where you have the choise between several tools. So PYNWC is a tool environment within the user tool environment of NWC.

  • The NWC file that’s opened in NWC when you start Pythonnwc is read from the standard input (stdin).

  • The module NWC classes is used to create a ‘score object<NwcFile>’ from the input file.

  • The module NWC terms contains:.

    • literals

    • dictionaries to validate NWC-objects.

    • type_field_lists: valid fields per object type

    • type_field_value_lists: valid values per type_field (special case: type_field_value_lists[“ObjType”] contains the valid object types). “””

  • The module NWC types contains the definition of the types used in PYNWC.

  • The module NWC object gui shows and processes edit windows for NWC object properties.

  • The module NWC xlsx writer writes a workbook from a dictionary.

Tool structure

Present in every tool:

  • A docstring with a short one line description, followed by a blank line, followed by a full description of the tool.

    The first line will be shown in the reporting frame when a tool is selected. The lines after the blank line are used as help information when the button ‘Help’ is pressed.

  • The descriptive ‘name’ of the tool, which is shown in the selection frame of the main window.

  • A list ‘report’: each action taken by the tool is registered in this list and shown in the reporting frame of the main window.

  • A list ‘summary’: a summary overview of the actions.

  • A dictionary of ‘features’:

    • mode: ‘edit’ or ‘report’

    • needs selection: ‘Yes’ or ‘No’

    • has parameters: ‘Yes’ or ‘No’

    • output file types: NWCtext Files (.nwctxt), Text Files (.txt) or XLSX Files (.xls)

  • An instance ‘G’ of a DictClass, containing the global variables:

    • the score

    • if the tool has parameters:

      • the layout for the tool parameter window

      • the parameter_values

      • a function to get the parameters from the tool parameter window

    • variables, specific for the tool itself

  • A function init(score: NWCFile, config: ParmDict). The function is called when a tool is selected and contains following actions:

    • restore the global variables to their original values; this is necessary because a tool can be selected more than once in the same session of PYNWC

    • store the argument ‘score’ in the global variables

    • if the tool has parameters:

      • initialise the parameter values: use the values from config if present or default values.

      • set global variables from the parameter values

      • create a layout for the tool parameter window

      • store a reference in the global variable to the function that gets the parameter values from the tool parameter window

  • Functions if the tool has parameters:

    • create_parameter_layout()

    • get_parameter_values(values)

    • process_parameters(parameter_values)

    • update_parameter_window(window, event, values)

  • A function run().

    This function is called when the button ‘Run Tool’ on the main window is pressed.

  • A function finish() that restores the global variables.

    This function is called when a tool has been run and the main script has done the reporting.

Scenario

  • Upon start:

    • the input file is read from stdin and a NwcFile object is created

    • the configuration file is read into a dictionary (with the tool name as key)

    • the main window is constructed

    • some information about the score is shown in the reporting window

    • if the command line contains arguments (see ‘Installation for a specific tool’ in Installing PYNWC), they are processsed

    • user interaction is awaited

  • actions after a user interaction:
    • Tool selection:

      • The tool name and its features are shown in the reporting frame.

      • The init() function of the tool is called.

    • Button ‘HELP’ is pressed: a help window is opened.

      • If no tool was selected, the general help text is shown.

      • If a tool is selected, the help text of that tool is shown. Via a radio button the user can get the general help text.

    • Button ‘Show Score Info’ is pressed:

      Some info about the score is shown in the reporting frame.

    • Button ‘Tool Parameters’ is pressed (only enabled when a tool with parameters is selected):

      • A parameter window is shown; the layout is determined by the specific tool function create_parameter_layout.

      • When the user exits this window, the values of that window are processed by the selected tool function get_parameter_values and stored in the global variables of the tool.

      • The parameter values for the tool are updated in the configuration dictionary.

    • Button ‘Run Tool’ is pressed:

      • The run() function of the selected tool is called.

      • The resulted report and summary lines are shown in the reporting frame.

      • A list of output lines is formed with:

        • If the tool has mode ‘edit’ and changes to the score are made: the new file representation.

        • If the tool had mode ‘report’: the report lines.

      • The finish() function of the selected tool is called.

    • Button ‘Show Output’ is pressed:

      the output lines are shown in the reporting frame.

    • Button ‘Save Changes’ is pressed:

      • A popup ‘Save changes?’ appears.

      • If the user confirms, the output lines with the representation of the changed score is written to stdout.

    • Button ‘Save as’ is pressed:
      • The output file path is set:

        • The folder must be specified by the user.

        • If the tool returned a value for ‘output_filename’, this is used as the default base file name, otherwise the input file name.

        • The extension is set on the basis of the tool feature ‘output file types’.

        • The user has still the opportunity to change the file name.

      • The file is saved, after confirmation by the user.

    • Button ‘EXIT’ is pressed:

      • If the score was changed and has’nt been saved, a popup ‘Save changes?’ will appear and, if the user confirms, the output lines with the representation of the changed score is written to stdout.

      • The main window is closed.

      • The configuratioen dictionary with the tool parameters is saved in the configuration file.

Main script

Pythonnwc

Environment to run Python tools in NWC (NoteWorthy Composer).

command line arguments
-t <tool name>, --tool <tool name>: select the tool
-p, --parameters: show the tool parameters
-r, --run: run the tool
-s, --save: save changes
-e, --exit: exit
events

Selection of a tool

Button ‘HELP’ pressed

Button ‘Show Score Info’ pressed

Button ‘Tool Parameters’ pressed

Button ‘Run Tool’ pressed

Button ‘Show Output’ pressed

Button ‘Save Changes’ pressed

Button ‘Save as’ pressed

Button ‘EXIT’ pressed

VERSION HISTORY:

Version 1.0: initial release

Version 1.0.1: bug fix: intercept Bank Select not present

Version 1.0.11: bug fix fixed

Version 1.0.2: bug fix in ‘add rest measures’: handling dots and triplets

Version 1.1: tool ‘construct medley’ added

Version 1.2:

  • Tool ‘audit score’ added

  • Redesign of the tool parameter handling (Existing configuration files become obsolete).

    • New option in the ‘tool parameters’ window: ‘Always show this window when selecting this tool.’

    • New directory for the configuration file: ‘%LOCALAPPDATA%PYNWC’ (previously in the same directory as the input score).

    • New name for the configuration file: ‘pynwc.cfg’ (previously: ‘config.txt’).

Version 1.3:

Version 1.4: Tool Search & Modify added

class pythonnwc.G

Global variables.

exception pythonnwc.TimeOutException
pythonnwc.close(values=None) → None

Invoked after event ‘EXIT’.

pythonnwc.help(*args)

invoked after event ‘HELP’.

pythonnwc.run_tool(values=None) → None

Invoked after event ‘Run Tool’.

pythonnwc.save(values=None, close: bool = False) → None

Invoked after event ‘Save Changes’.

Shows a confirmation screen and, if confirmed, saves the changes in the score.

pythonnwc.save_output_file(values) → None

Invoked after event ‘Save as’.

pythonnwc.select_tool(values=None, index: int = None) → None

Invoked by the event ‘Select a tool’.

  • Shows the selected tool name, its features and the actual parameter values (if any) in the reporting frame.

  • Gets the output file types.

  • Calls the init function of the tool.

pythonnwc.show_output(values) → None

Invoked after event ‘Show Output’, if the tool edited the score of produced a text file.

pythonnwc.show_score_info(values=None) → None

Invoked at opening of the environment window and after event ‘Show Score Info’.

Shows info:

  • File path

  • Last modified

  • Song title

  • For each staff:

    • muted and/or hidden

    • name[(hidden)]

    • number of measures

  • Active staff

  • Selection from … to …

General modules

NWC classes

Definition of the classes.

Structure of the classes and subclasses:

A score consists of the following classes:

class nwc_classes.Chord(line, score, staff_index=None)
class nwc_classes.Clef(line, score, staff_index=None)
class nwc_classes.Editor(line, score, staff_index=None)
class nwc_classes.Font(line, score, staff_index=None)
class nwc_classes.General(line, score, staff_index=None)
class nwc_classes.Instrument(line, score, staff_index=None)
exception nwc_classes.InvalidChordError
class nwc_classes.Key(line, score, staff_index=None)
class nwc_classes.LyricLine(line, score, staff_index=None)
class nwc_classes.Lyrics(line, score, staff_index=None)
class nwc_classes.Note(line, score, staff_index=None)
class nwc_classes.NwcFile(nwc_file)
Parameters

nwc_file (list[str]) – the input file, read from stdin

Main attributes

For each input line (except header and trailer) a NwcObject is created.

report(classes=None, score_headers: bool = True, staff_headers: bool = True, staff_instrument: bool = True, staff_lyrics: bool = True, staff_objects: bool = True) → List

Shows ‘translation’ of the file into the internal representation that’s used by the tools.

repr_file() → List[Union[Literal[|], str]]

Creates nwctxt lines that can be stored as a file.

:return:List[NWCline]

class nwc_classes.NwcObject(line: str, score: nwc_classes.NwcFile, staff_index=None)

Basic object, the building block for the score.

Parameters

  • line (str) – input line from stdin or nwctxt file

  • score (NwcFile) – the NwcFile object from the input file

  • staff_index(optional) (int) – the index of the staff the object belongs to

get(key: str, default=None) → Any

Gets the value from self.fields or self.opts.

has_duration() → bool
has_notes() → bool
is_score_header() → bool
is_staff_header() → bool
is_type(object_type: str) → bool
set(key: str, value: Any, dur_index: int = 0, pos_index: int = 0)

Sets a value in self.dur_features, self.pos_feature, self.fields or self.opts(depending on the key).

class nwc_classes.PageMargins(line, score, staff_index=None)
class nwc_classes.PageSetup(line, score, staff_index=None)
class nwc_classes.Playable(line, score, staff_index=None)
property accidentals

derived from pos_features

can_have_lyric() → bool
property dots

derived from dur_features

property dur_features

features related to the duration(s) of the object: Duration, Tics (a whole note = 768 tics), Dotted, DblDotted, Triplet, Slur, Grace, Marcato, Staccato, Staccatissimo, Accent, Tenuto.

  • Duration and Tics are always present, the other features only when they apply.

  • the structure is a list of 1 or 2 dictionaries(see also: derived properties).

    • e.g.: [{‘Duration’: ‘8th’, ‘Staccato’: True, ‘Tics’: 96}, {‘Duration’: ‘4th’, ‘Tics’: 192}]

    • derived properties: durations: [‘8th’, ‘4th’], Tics: [96, 192]

property duration

derived from dur_features (not for chords and restchords, see also: durations)

property durations

derived from dur_features

has_position() → bool
has_position2() → bool
has_slur() → bool
is_beamed() → bool
is_tripled() → bool
property noteheadcolors

derived from pos_features (refers to the color of individual notes of a chord or restchord, dont confuse with opts[‘Color’])

property noteheads

derived from pos_features

property pos_courtesy_accs

derived from pos_features

property pos_features

features related to the position(s) of the object: position, color, tied, accidental, courtesyacc, notehead.

  • the position is always present, the other features only when they apply.

  • the structure is a list of 1 or 2 lists of dictionaries(see also: derived properties).

  • for each value of the position, pos_features contains a dictionary with the feature names as key.

  • for each value of the duration, the feature dictionaries are put together in a list

  • the simplest case is an object that has no duration:

    • e.g.: pos_features: [[{‘position’: -4.0}]]

    • derived property: ‘position’: -4.0

  • for a single note, we can have e.g.: pos_features: [[{‘accidental’: ‘sharp’, ‘tied’: True, ‘position’: 0.0}]]

    • derived properties: positions: [0.0], pos_acidentals: [‘sharp’], ties: [True]

  • the most general case is a chord consisting of notes of different duration,

    • e.g.: [[{‘accidental’: ‘flat’, ‘position’: -4.0}, {‘position’: -2.0}], [{‘position’: -1.0}, {‘position’: 2.0}]]

    • the order is acsending duration / ascending position

    • derived properties: positions: [-4.0, -2.0, -1.0, 2.0], pos_acidentals: [‘flat’, None, None, None]

property position

derived from pos_features (not for chords and restchords, see also: positions)

property positions

derived from pos_features (only for chords and restchords, see also: position)

property tics

derived from dur_features

property ties

derived from pos_features

class nwc_classes.Properties(line, score, staff_index=None)
class nwc_classes.Qualifier(line, score, staff_index=None)
class nwc_classes.Rest(line, score, staff_index=None)
class nwc_classes.RestChord(line, score, staff_index=None)
class nwc_classes.RestMultiBar(line, score, staff_index=None)
class nwc_classes.ScoreHeader(line, score, staff_index=None)
class nwc_classes.SongInfo(line, score, staff_index=None)
class nwc_classes.Staff(object: nwc_classes.NwcObject, score: nwc_classes.NwcFile)
Parameters

  • object (General) – object that gives rise to creating a staff

  • score – the NwcFile object from the input file

refresh(ind: int = 0, log: bool = False)

Recalculates the locative attributes of the staff objects.

Parameters

ind (int) – the index of the first staff object to refresh.

Returns

class nwc_classes.StaffHeader(line, score, staff_index=None)
class nwc_classes.StaffObject(line, score, staff_index=None)
class nwc_classes.Tempo(line, score, staff_index=None)
class nwc_classes.TimeSignature(line, score, staff_index=None)

NWC terms

Contains: - dictionaries to validate NWC-objects.

  • type_field_lists: valid fields per object type

  • type_field_value_lists: valid values per type_field (special case: type_field_value_lists[“ObjType”] contains the valid object types).

NWC Types

Definition of types used in PYNWC and some basic functions.

exception nwc_types.CanceledByUser
class nwc_types.DictClass(**kwargs)

Dict-like class with attributes instead of keys. The initial values are remembered and can be restored.

restore(*attributes)

Restores the initial value (default: all attributes).

class nwc_types.MagicDict

NWC Object gui

Shows and processes edit property windows for NWC objects.

Xlsx module

my_xlsxwriter.write_workbook_from_dict(workbook_name: str, xlsx_dict: Dict[str, Union[List[str], Dict[str, List[Any]]]]) → None

Adds apropriate format and stores the xlsx file from the dictionary with sheet information.

Parameters

  • workbook_name – path name of the xlsx file to be saved

  • xlsx_dict – dictionary with sheets

Returns

None

Tool modules

Add rest measures

Adds ‘rest measures’ to the staves that have less measures then the active staff.

This tool completes the staves that have less measures than the active staff with ‘rest measures’(*).

The tool parameters determine whether or not the hidden staves are processed.

(*)A ‘rest measure’ is constructed from a copy of the corresponding measure in the active staff, replacing notes, chords and restchords with rests of the same duration and leaving the other objects as they are.

class add_rest_measures.Parameters(values: Dict = <factory>)
add_rest_measures.create_parameter_layout() → List[List[Callable]]

Creates a layout for the variable part of the ‘Tool Parameters’ window:

add_rest_measures.finish()

Restoring static state of global variables. This function is called after running tool.run

add_rest_measures.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

add_rest_measures.process_parameters(values: Dict[str, Any]) → None

Sets the global variables that depend on the parameters

add_rest_measures.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]

Add ‘rest measures’ to staves that have less measures than the active staff.

Returns

A dictionary:

  • ”Report”: a list of report lines.

  • ”Summary”: a list of summary lines.

  • ”Edited”: True if there has been some editing of the score.

Side effects

Rest measures are inserted in global variable G.score.

Analyse score

Creates an analysis report of the score.

The analysis of the score is divided into several analysis groups. You can see these groups in the ‘Tool Parameters’ window.

There are 2 categories of groups:

  • The ‘Staff Properties’ groups: they report several staff properties.

  • The ‘Object Type’ groups contain the measure numbers for each particular value of the main property for a certain object type.

    For some object types, extra properties can be reported (e.g. velocity and volume for dynamics).

In the ‘Tool Parameters’ window, you can uncheck the groups and/or properties that you want to exclude from the analysis.

The results are presented on a window with one tab per group.

When the ‘OK’ button of this window is pressed, the report can be saved into a xlsx file by pressing ‘Save as’ on the main window. In this file, the results are presented in one sheet per group.

class analyse_score.Parameters(values: Dict = <factory>)
analyse_score.create_parameter_layout() → List[List[Callable]]

Creates a layout with the rows for the ‘Tool Parameters’ window.

analyse_score.create_xlsx_dict(score: nwc_classes.NwcFile) → Dict[str, Union[List[str], Dict[str, List[Any]]]]

Creates a dictionary with sheet names and result sheets. Used as parameter for write_workbook_from_dict

Parameters

score (NwcFile) –

Returns

Dictionary with sheet names and result sheets.

analyse_score.finish()

Restoring static state of global variables. This function is called after running tool.run

analyse_score.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. Runs when the tool is selected.

analyse_score.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]

Creates an analysis report of the score.

Returns

A dictionary:

  • ”Report”: a list of report lines.

  • ”Summary”: a list of summary lines.

  • ”Xlsx”: a dictionary with sheet names and result sheets.

Side effects

A window with the analysis results is shown.

analyse_score.show_window(score: nwc_classes.NwcFile) → None

Creates a window with the results of the analysis.

:param score :type score: ´NwcFile´ :return: None

Audit score

Audit score

Before running this tool, be sure to select in the tool parameter window the audit you want to be performed. Also specify the process mode: all staves, visible staves, active staff or the selection. Depending on the audit you choose, additional options will be shown. See below for details per audit.

  • Audit accidentals:

    Via the tool parameters you can select one of this options for handling natural accidentals:

    • Leave naturals unchanged

    • Make courtesy accidentals

    • Remove accidentals

    This audit acts on any unnecessary accidentals assigned to notes. It compares a note with an accidental with the ‘running’ key signature, which is determined by the previous key signature + the preceding accidentals in the measure. If the accidental matches the running signature, and it’s not a courtesy accidental, it will be removed if it’s not a natural. For naturals the action taken depends on the option in the tool parameters.

  • Audit bar lines:

    Audits the bar line alignment. In the tool parameters you can indicate whether you want to admit a short first measure (anacrusis). If the audit finds a standard bar line that is not aligned properly, it is removed and a new bar line is added in the proper place. As a result, notes and chords can be split and tied.

    • Measures with a special ending that is not at the beginning of the measure, are not audited.

  • Audit enharmonic spelling:

    Replaces notes with their enharmonic equivalents. There are several options you can choose from (see below), via the tool parameters. If your process mode = ‘Process selection’, and an enharmonic change is to be done on a note, the following notes in the same measure or which are tied to the changed note, are investigated to determine if they need to be changed also. If affirmative, they will be added to the selection.

    Available options:

    • ‘No sharps’: All sharps are replaced.

    • ‘No flats’: All flats are replaced.

    • ‘Reverse sharps/flats’.

    • ‘No doubles’: All double sharps and double flats are replaced.

    • ‘Preferably naturals’: If a enharmonic equivalent without accidental is possible, it’s used.

    • ‘No forced naturals’:

      If a natural accidental is caused by an preceding note with an accidental, this preceding note is replaced by its enharmonic equivalent.

    • ‘Common preferred accidentals’: A# -> Bb, Db -> C#, D# -> Eb, Gb -> F#, Ab -> G#.

    • ‘Sharps up, flats down’:

      If the next note is a tone or a semitone higher, a sharp is used; if it is a tone or a semitone lower, a flat is used (not applicable to chords and restchords).

    • ‘Custom changes’: You can choose one or more items from a list of all possible enharmonic changes.

  • Audit note length and beaming:

    Splits notes and group beamings, according to the time signatures. Upon start, a window is shown with the default groupings for note length and beaming, for each found time signature. You can accept or modify them. The specifications mainly come from @hmmueler (see https://forum.noteworthycomposer.com/?topic=10050.msg72212#msg72212).

    • Note, chord and rest lengths are distributed in each measure according to standard rules(see e.g. Elaine Gould, Behind Bars, pp. 160-164, 166-169, 171).

      • Rest chords, chords with different durations, triplets, or notes with a ‘Staccato’, ‘Staccatissimo’, ‘Accent’ or ‘Marcato’ articulations will not be split.

    • Beams connect notes and chords according to standard rules (see e.g. Elaine Gould, Behind Bars, pp. 153-155).

    • The main and secondary beat patterns are derived from the currently active time signature.

    • It ‘s possible to specify alternative beat patterns for a time signature, both for the note lengths and beams.

    • A long note that starts at a beat and spans over several beats, will not be split.

    • If the first measure of the score or selection is a short measure, it is treated as the right part of the full beat pattern.

    • When a special ending is found that’s not at the beginning of the measure, the remaining of the measure is not audited.

    • A measure that is longer than the current time signature indicates causes an error message.

  • Audit note stems:

    Removes unnecessary stem up or down attributes and resets stem directions for note beams and triplets.

class audit_score.Parameters(values: Dict = <factory>)
audit_score.add_fake_rest_in_anacrusis(staff: nwc_classes.Staff) → bool

Updates: - G.score.selected_objects - staff

audit_score.add_report(message: str, object: nwc_classes.NwcObject = None) → None

Updates list report.

audit_score.audit_accidentals(object: nwc_classes.StaffObject) → None

Updates: - G.removed_accidentals - list report Calls: change_nwctxt_line

audit_score.audit_bar_lines(object: nwc_classes.StaffObject) → None

Updates: - G.time_signature - G.current_measure_tics - G.to_remove_objects - G.first_measure - G.removed_bars Calls: split_playable

audit_score.audit_enharmonic_spelling(object: nwc_classes.StaffObject) → None

updates: - G.actual_key Calls: - process_enharmonic

audit_score.audit_note_length_beaming(object: nwc_classes.StaffObject) → None

updates: - G.time_signature - G.measure_tics - G.current_measure_tics - G.current_beat_tics - G.beat_idx - G.measure_beats, - G.to_beam Calls: - init_beat_tics - split_playable - beam

audit_score.audit_note_stems(object: nwc_classes.StaffObject) → None

Updates: - the input object - G.audited_stems - G.edited

audit_score.beam() → None

Updates: G.edited list report

audit_score.change_name_acc(object: Union[nwc_classes.Note, nwc_classes.Chord, nwc_classes.RestChord], idx: int, name_acc: str, new_name_acc=<class 'str'>) → str

Updates: list report, G.enharmonic_changes. Returns the updated nwctxt_line of the object.

audit_score.change_nwctxt_line(object: nwc_classes.NwcObject, new_line: str) → None

Updates nwctxt_line in the input object. Updates G.edited

audit_score.check_parameter_values(values: Dict[str, Any]) → None

Checks parameter value dependencies, after event ‘OK’ or ‘Apply’.

audit_score.create_explicit_accidentals(staff: nwc_classes.Staff) → None

Updates: - G.edited Calls: - set_or_remove_explicit_accidental

audit_score.create_parameter_layout() → List[List[Callable]]

Create a layout with the rows of the ‘Tool Parameters’ window.

audit_score.enharmonic_change(object: Union[nwc_classes.Note, nwc_classes.Chord, nwc_classes.RestChord], get_new_name_acc: Callable) → None

Calls: - preprocess_next_notes - change_nwctxt_line

audit_score.finish()

Restoring static state of global variables. This function is called after running tool.run

audit_score.finish_staff_audit(staff: nwc_classes.Staff) → None

Updates: - G.edited - removes objects - refreshes staff Calls: - remove_explicit_accidentals

audit_score.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

audit_score.init_audit() → None

updates: - G.score.selected_objects - G.time_signatures

audit_score.init_beat_tics() → None

Returns: - beat_tics, - current_beat_tics - cumulated_beat_tics

audit_score.init_staff_audit(staff: nwc_classes.Staff) → None

Updates: G.time_signature, G.measure_tics, G.measure_beats, G.current_measure_tics, G.to_remove_objects, G.to_beam Calls: create_explicit_accidentals, init_beat_tics

audit_score.preprocess_next_notes(object: Union[nwc_classes.Note, nwc_classes.Chord, nwc_classes.RestChord], idx: int, position: float, stage: str, name_acc: str) → None

Calls: set_or_remove_explicit_accidental

audit_score.process_enharmonic(object: Union[nwc_classes.Note, nwc_classes.Chord, nwc_classes.RestChord]) → None

Updates: - G.actual_key Calls: enharmonic_change

audit_score.process_object(object: nwc_classes.StaffObject) → None

Updates: - G.actual_key Calls: - audit_enharmonic_spelling - audit_accidentals - audit_note_length_beaming - audit_bar_lines - audit_note_stems

audit_score.process_parameters(values: Dict[str, Any]) → None

Sets the global variables that depend on the parameters.

audit_score.remove_explicit_accidentals(staff: nwc_classes.Staff) → None

Updates: - G.edited Calls: - set_or_remove_explicit_accidental

audit_score.remove_fake_rests_in_anacrusis(staff: nwc_classes.Staff) → bool

Updates: - G.score.selected_objects - staff

audit_score.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]

Do what has to be done.

Returns

A dictionary:

“Report”: a list of report lines.

“Summary”: a list of summary lines.

“Edited”: True if there has been some editing of the score.

Side effects

  • If ‘Edited’ is True, the score has been changed.

audit_score.set_or_remove_explicit_accidental(object: Union[nwc_classes.Note, nwc_classes.Chord, nwc_classes.RestChord], idx: int, action: str) → None

Updates: - input object - list report - G.score.selected_objects

audit_score.show_grouping_window() → str

Updates: - G.note_length_groupings - G.beam_groupings Returns: event

audit_score.split_playable(object: nwc_classes.Playable, tics_left: int) → None

Updates: - G.split_notes - G.to_remove_objects - the input object - inserts a ¨Playable in the staff - inserts a bar to the staff - list report - G.edited

audit_score.staves_to_process() → Generator[nwc_classes.Staff, None, None]

Updates G.time_signature.

audit_score.update_parameter_window(window, event, values: Dict[str, Any]) → None

Updates the parameter window after each event.

Color beams, slurs and triplets

Colors beams, slurs and triplets in the selection.

When you select notes in a NWC file and change the color, the beams, slurs and triplet bracket still have the old color.

With this tool, the necessary markers and beam objects are created, so that everything will be colored.

It contains an algorithm to determine the position and final stemlength of the beam object and the position of the triplet and slur marker, but maybe you need to change them for an optimal result.

The tool operates on the selection you made on the score. The objects with a default color will get the color of the first selected object.

color_beams_slurs_triplets.beam_object_opts(object: nwc_classes.NwcObject) → Tuple[str, str]

Calculates position and final stemlength of the beam user object to be created.

Parameters

object (NwcObject) – first note or chord in a beamed serie

Returns

beam_pos

Returns

final_stemlength

Return type

Tuple[str, str]

color_beams_slurs_triplets.finish()

Restoring static state of global variables. This function is called after running tool.run

color_beams_slurs_triplets.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

color_beams_slurs_triplets.slur_marker_position(object: nwc_classes.NwcObject) → float

Calculates the position of the marker object to be inserted.

Parameters

object (NwcObject) – object having a slur

Returns

position of the slur marker

Return type

float

color_beams_slurs_triplets.triplet_marker_position(object: nwc_classes.NwcObject, beam_object: nwc_classes.NwcObject) → float

Calculates the position of the triplet marker to be created.

Parameters

  • object (NwcObject) – last object of a triplet serie

  • beam_object – the created beam object or None

Returns

position of the triplet marker

Return type

float

Color flow changes

Colors flow changes.

This tool colors all items that change the direction of the flow:

  • flow direction objects(Coda, Segno, Fine, …, D.S. al Fine)

  • repeat bars

  • special endings

Via ‘Tool Parameters’ you can set:

  • the color for the flow change objects

  • the staves to be processed

class color_flow_changes.Parameters(values: Dict = <factory>)
color_flow_changes.create_parameter_layout() → List[List[Callable]]

Creates a layout for the variable part of the ‘Tool Parameters’ window: a listbox to set the color.

color_flow_changes.finish()

Restoring static state of global variables. This function is called after running tool.run

color_flow_changes.init(score: nwc_classes.NwcFile)

Initialization of the global variables. This function is called when the tool is selected.

color_flow_changes.process_parameters(values: Dict[str, Any]) → None

Sets the global variables that depend on the parameters

color_flow_changes.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]

Colors all items that change the direction of the flow.

Returns

A dictionary:

  • ”Report”: a list of report lines.

  • ”Summary”: a list of summary lines.

  • ”Edited”: True if there has been some editing of the score.

Side effects

Rest measures are inserted in global variable G.score.

Configure new song

Configure a new song file.

Run this tool after you created and saved a new file from a template, and before you start changing staff labels, channels, …, removing some staves, inserting tempo, key and time signatures, dynamics, copying and pasting… All that can be done in one go, with this tool.

On the main dialog window, you see on the left a list of all the staves with attributes name, label, group, channel, volume, stereo pan, muted and visible. Each of these attributes is changeable. In front of each staff line is a checked check box. Unchecking a box will remove the corresponding staff from the file (1).

Via the buttons at the right you can configure the properties of objects you want to be inserted. Clicking one of them will open a dialog window, similar to the correspondent ‘Notation Properties’ window of NWC. They have 4 buttons at the right; ‘Create’, ‘Modify’, ‘Remove’ and ‘Cancel’.

  • With ‘Create you schedule the insertion of the correspondent object.

  • With ‘Modify’ you can change the properties of a scheduled object.

  • With ‘Remove’ you undo a scheduled insertion.

  • With ‘Cancel’ you quit the window without any resulting action.

At the bottom of the main window is indicated which objects are scheduled for insertion.

When clicking the ‘OK’ button at the bottom of the main dialog window (2):

  • the staff changes will be carried out (3);

  • the unchecked staves will be removed;

  • the scheduled objects will be created and inserted in every staff, after the clef;

(1) Hint: You may want to use a template with all the staves that you’ll ever be needing, and uncheck those that you don’t want to be present in the new file.

  1. As in every other tool, the changes will not be saved until after your confirmation.

(3) As a next step you may want to run the tool ‘Set staff properties’ to carry out within one dialog window all other needed staff changes (general, visual, midi, instrument, default dynamic velocities).

new_song.finish()

Restoring static state of global variables. This function is called after running tool.run

new_song.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

new_song.process_event(event: str, values: Dict)

Executed after every event, except ‘None’, ‘Cancel’ and ‘OK’.

new_song.process_staves()

Carries out the staff attribute changes and removes unchecked staves.

new_song.process_values(values: Dict)

Executed after event ‘OK’.

new_song.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]

Shows a window to create the initial key signature and tempo and select the staves to be withheld.

Returns

A dictionary:

“Report”: a list of report lines.

“Summary”: a list of summary lines.

“Edited”: True if there has been some editing of the score.

Side effects

  • If ‘Edited’ is True, the score has been changed.

Construct medley

Combine several song files into 1 medley file.

To create a medley file, you have to start this tool from a blank score: Choose ‘File/New’ and select <blank score> from the ‘Song Templates/General’ tab and save it before you go to ‘Tools/User Tools’. This file will be the destination file, in which you add the songs that will make up the medley. You can create the medley file in several steps, so you can also start this tool from an earlier created medley file. (The tool checks the presence of ‘song lines’(1) in the Comments section of the Song Info to decide whether it’s a valid medley file.)

Via the tool parameters you can specify:

  • Include song titles at the start of each song (top staff).

  • Position, scale and font for the Song Title text objects.

  • Type of separation bar between the songs (except when the previous song ends with a Repeat Close): Single, Double or Section Close.

  • Page break, System Break or no break between the songs.

The tool consists of several stages:

  • A popup window ‘Select Songs’.

    • If you press ‘Add a file’, a Windows Explorer window will be opened.

    • Important: Only files in NWC Text format can be processed. So maybe you’ll have to open and ‘save as’ one or more of your songs first.

    • A selected song can be removed from the list by clicking on it.

    • In this stage you can also set or change the Medley Title.

    • ‘Cancel’ will exit the tool without any changes.

    • If you have chosen your files, press ‘Continue >’.

  • A popup window ‘Arrange Staves’. Via this window you can:

    • Reorder the staves

    • Change song titles(2)

    • Change staff names and labels

    • Join staves (by assigning the same name and label)

    • Press ‘?’ to see more detailed help info

    • Press ‘< Back’ to return to the ‘Adding Songs’ window.

  • Review of the staff properties:

    • For each staff that appears in several songs, the properties from the different songs are compared. For each mismatch(except for ‘visibility’ and ‘muted’), a popup window is presented where you can choose which values to retain(2). If there are to many mismatches, you may want to press ‘Cancel’, in which the tool is ended without any change. When there’s a mismatch for ‘visibility’, the part of the song with property invisible will be collapsed. When there’s a mismatch for ‘muted’, the appropriate notes will be muted.

  • Construction of the medley, according the choices in the Tool Parameters:

    • Adding ‘song lines(1)’ to the Comments Section of the Song Info.

    • Adding song titles at the start of each song.

    • Creating delimiter objects: separation bar, new system or new page.

    • Inserting rests measures in staves that aren’t part of every song, surrounded by boundary collapse and end collapse objects (3).

Notes:

  1. A ‘song line’ is of the form “Song:{song title}#{starting measure}-{ending measure}”

  2. Changing the song titles and/or staff properties has only effect in the destination file. The original song files will not be modified.

  3. The inserted boundary changes don’t always give the expected result between the songs, so may be you’ll have to delete or replace some of them.

class construct_medley.MedleyStaffList(staff_keys: List[Tuple[str, str]] = None, staff_headers_list: List[List[nwc_classes.Staff]] = None, staff_objects_list: List[List[List[nwc_classes.StaffObject]]] = None, score_indices_list: List[List[int]] = None)

List of staves that will part of the medley. Each row consists of:

  • a ‘staff key’, formed by the combination of the staff name and staff label

  • a list of staff headers from the songs that have a staff with that key

  • a list of staff objects from the files that have a staff with that key

  • a list of indices that point to the songs that have a staff with that key

class construct_medley.Parameters(values: Dict = <factory>)
construct_medley.create_staff_window(medley_staves: construct_medley.MedleyStaffList)

This window shows:

  • The song titles, with the corresponding file number. You can change the song titles, except those that were already in the destination file.

  • The staves of the medley file. Staves from different files but with the same values for staff name and label are joined together.

You can change staff numbers, staff names and labels. Changing a staff number will reorder the staves. The staff will move to the new number, the other staves are shifted accordingly. You can see the result of your changes after pressing ‘Refresh’. If you want to reorder more than one staff, refresh after each change.

When you’ve changed a staff name and/or label and the new combination name/label matches with one of the other staves, they will be joined together. Press ‘Refresh’ to see the result.

When no more changes or needed, press ‘Continue >’. You can at all times press ‘< Back’ to return to the ‘Adding Songs’ window.

Layer voices

Layer 2 voices and do necessary changes to get a ‘neat’ visual result.

In many song sheets for choirs, each group of two voices is on 1 staff. In NWC, you can do this by entering chords, or by layering each group of two staves.

Entering chords is not very easy + you don’t always have control over the stems of the individual notes of a chord, which is necessary to differentiate between the two voices.

On the other hand, when layering, you not only have to set the stems. In order not to have a messy result after layering, you also have to set the properties ‘Use stem for articulation’, ‘Slur direction’ and ‘Tie direction’.

Furthermore, you have to check the whole staff for situations where you have to set the properties ‘Extra note spacing’ and/or ‘Extra accidental spacing’.

This tool takes care of all this.

In addition:

If both staves have lyrics, the property ‘Placement’ will be set to ‘Top’, resp. ‘Bottom’.

The label of the bottom staff will be changed to the combination of the 2 labels.

Via a popup window you can choose which pair of staves you want to be layered.

REMARK: Because of the many changes, you’ll be asked if a safety copy of the original file is to be created before layering.

class layer_voices.PlayLocation(staff: nwc_classes.Staff, index: int)
layer_voices.finish()

Restoring static state of global variables. This function is called after running tool.run

layer_voices.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

layer_voices.layer_locs(top: nwc_classes.Staff, bottom: nwc_classes.Staff)

Yields the locations of the next layer_pair.

layer_voices.playables(staff: nwc_classes.Staff)

Yields the next object with duration except multibarrests.

layer_voices.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]

Layer 2 voices and do necessary changes to get a ‘neat’ visual result.

Returns

A dictionary:

  • ”Report”: a list of report lines.

  • ”Summary”: a list of summary lines.

  • ”Edited”: True if there has been some editing of the score.

Side effects

  • If ‘Edited’ is True, the score has been changed.

layer_voices.tune_contains_chord(top_object, bottom_object)

Sets extra note space on bottom staff.

layer_voices.tune_contains_rest(top_object, bottom_object)

Sets vertical offset.

layer_voices.tune_notes(top_object: nwc_classes.NwcObject, bottom_object: nwc_classes.NwcObject)

Sets extra note space and extra accidental space.

  1. check accidentals and vertical distance

  2. if distance == 0 : check for white/black notes

  3. if distance between -2 and 2: check for dots

Make rehearsal file

Creates a rehearsal file.

For each staff, you can assign one of three ‘play modes’: background voice, foreground voice or instrument. After you click ‘OK’, the staff volume, stereo pan, color and dynamics will be changed according to the ‘Tool Parameters’.

So, before you run this tool for the first time, take a look at the ‘Tool Parameters’ window.

The left frame shows the ‘Play mode Staff Properties’. Here you can set the staff volume, stereo pan and color for the three play modes.

The right frame concerns the ‘Default Dynamic Velocities’. Here you can choose the values for the default dynamic velocities that will be set in the instrument panel for each staff of your score. These values are used to calculate the velocity and volume settings of the dynamics. (For more information: see document ‘Dynamics.pdf’ in <http://nwc-scriptorium.org/helpful.html#Explanations>) You can either choose for the velocities of the active staff (which are shown at the top op the frame, or for the parameter values.

After you pressed ‘Run Tool’, have set the play modes and pressed ‘OK’:

  • The chosen default dynamic velocities are copied in each staff.

  • The staff properties are changed according to the tool parameters.

  • The velocity and volume settings of the dynamics are calculated as follows:

    • for a voice staff :

      ° The ‘custom velocity’ of each dynamic is set equal to the highest value of the default dynamic velocity (‘fff’).

      ° The ‘custom volume’ is set using Tina Billet’s formula : Volume = default velocity for the dynamic * Staff Volume / highest velocity.

    • for an instrument staff: the custom velocity and volume are unchecked.

Tip: Use the button ‘Save as’ to create a rehearsal file and add the label of the foreground voice to the file name. You can do this for each voice as foreground while keeping the original file unchanged by answering ‘No’ the the popup ‘Save changes?’

class rehearsal_file.Parameters(values: Dict = <factory>)
rehearsal_file.Tina_Billets_formula(default_velocity, staff_volume, high_velocity)

Calculate velocity and volume for a dynamic.

rehearsal_file.create_parameter_layout() → List[List[Callable]]

Create a layout with the rows of the ‘Tool Parameters’ window.

rehearsal_file.finish()

Restore the static state of global variables. This function is called after running tool.run

rehearsal_file.init(score: nwc_classes.NwcFile)

Initialise the global variables. This function is called when the tool is selected.

rehearsal_file.process_parameters(values) → None

Set the global variables that depend on the parameters.

rehearsal_file.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]
Returns

A dictionary:

“Report”: a list of report lines.

“Summary”: a list of summary lines.

Side effects

changes the score

rehearsal_file.set_dynamics(staff, play_mode, high_velocity)

Set the velcity and volume for the dynamics in a staff.

rehearsal_file.set_staff_properties(staff, play_mode)

Set the staff_properties according to the play_modes of the staff.

Organize files

Version management for your NWC files.

The purpose of this tool is to provide a sort of ‘version management’. A possible scenario:

  • When you think a draft version of your score is ready to be ‘promoted’ or secured:

    • register the date last modified in the File Info comments section.

    • create a read-only copy in a dedicated folder, with one or more suffixes added to the file name to see at a glance the date last modified, the creation date of the copy and/or a ‘version text’.

  • Then you can safely continue working with the original draft version.

  • If you want to work again with the secured version, you could unlock it, or leave it locked and create a new, writable copy in your ‘working’ folder.

The tool window:

  • The date modified, shown at the top of the window, is extracted from the windows file system.

  • The ‘File Info Comments’ frame shows the comment section of the ‘File Info’ from the input file.

  • The actions lock or unlock input file will be done after you click ‘OK’.

  • The other actions that you select in the ‘Actions’ frame are not accomplished until you click one of the buttons ‘Save changes’ or ‘Save as’ in the main window.

Via the Tool Parameters you can change following values:

  • The caption for the date modified text (default = ‘Last Modified’

  • The PageStyle for the print object (default = ‘Modified’)

  • The font and font size (default = StaffItalic, size 1.0)

  • The location of the print object (default = bottom left, X- and Y-offset 0)

If you save a copy of the input file, you can add one or more suffixes:

  • #m, followed by the date modified

  • #c, followed by the creation date of the copy

  • #v, followed by a self chosen text

(Remark: Any suffixes of the input file are not retained in the name of the copy.)

Via a popup window you can choose or create the folder for the copy.

class organize_files.Parameters(values: Dict = <factory>)
organize_files.create_print_objects()

Creates(but doesn’t save it yet) the necessary user object(s) to print the date modified at the bottom of each page on each page.

organize_files.init(score: nwc_classes.NwcFile) → None

Initialisation of the global variables. This function is called when the tool is selected.

organize_files.lock_inputfile()

Locks the input file (after confirmation). Executed after ‘OK’ has been pressed on the tool window and ‘Lock input file’ was checked.

organize_files.process_parameters(parameter_values: Dict[str, Any]) → None

Sets the global variables that depend on the parameters

organize_files.register_lock_input_file()

Registers that ‘Unlock input file’ was checked.

organize_files.register_unlock_input_file()

Registers that ‘Unlock input file’ was checked.

organize_files.run()

Creates and processes a window with the possible actions.

organize_files.store_date_modified() → None

Stores(but doesn’t save it yet) the date modified in the comments section of the ‘File Info’.

organize_files.unlock_inputfile()

Unlocks the input file (after confirmation). Executed after ‘OK’ has been pressen on the tool window and ‘Unlock input file’ was checked.

Search & Modify

Search and Modify.

With this tool you can search a score for all objects of a given type that have some given properties. Next you can:

  • Inspect where the occur (staff, measure number), with their nwctxt presentation.

  • Choose an action: ‘Modify’ or ‘Delete.

  • For the action ‘Modify’:

    • Indicate which property(ies) you want to modify.

    • Fill in the new value(s) in a popup, that resembles the ‘Notation Properties’ window in NWC for the given object type.

Remarks:

  • At every moment you can leave to undo your choices or modifications.

  • On the main window, every input field is a combo box from you can select the appropriate value.

Only those values that are of interest are presented. For instance: If you specified ‘Clef’ as object type and all clefs have the same value for ‘Octave Shift’, that property is not present in the ‘condition’ lines. .

Detailed description:
The main window consists of following parts, from top to bottom:
  • The frame ‘Make your choices’ to specify:

    • Where to search (selection, active staff, all staves or visible staves).

    • The object type to search for.

  • The ‘Conditions’ frame where you can set up to 6 search criteria. If you specify more than 1 condition for the same property, then all the objects are selected that satisfy any of these criteria. Criteria for different properties must be satisfied separately. At the bottom of the conditions frame you can see a verbose description of your selection criteria. It’s updated after every completed condition line.

  • A status line, that indicates:

    • The object type to search for.

    • The number of objects found (dynamically updated).

    • A button ‘Show’.

      When clicked a popup window will show the location and nwctxt presentation of the objects that satisfy the criteria.

  • The ‘Action’ line, with choices ‘Modify’ or ‘Delete’

  • The ‘Modifications’ frame, where (if your action = ‘Modify’) you have to specify at least 1 and at most 4 properties.

    Only those properties can be specified that are present in the ‘Notation Properties’ window for the object type. e.g.: for a note you can’t change the position, duration, accidental, staccato,….

  • Three buttons:
    • The action button. The caption will indicate the action you chose.

      If the action is ‘Modify’, a popup is presented that resembles the ‘Notation Properties’ window of NWC, in which the fields contain the values of the first object found. Only the fields for the properties you selected in the modification frame will be enabled. After you entered your new values, these will be set in each found object. All the other properties of each object remain unchanged.

    • The ‘Reset’ button. When clicked, every input is cleared so you can restart your input.

    • Finally a ‘Cancel’ button to leave without any action taken.

global_mod.finish()

Restoring static state of global variables. This function is called after running tool.run

global_mod.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

global_mod.process_values(values: Dict)

Executed after event ‘OK’.

Set Staff Properties

Set general, visual and midi staff properties for every staves in one window.

The window of this tool contains 5 tabs: ‘General’, Visual’, ‘Midi’,Instrument and ‘Default Dynamic Velocities’. These tabs correspondent with the tabs or the Staff Properties Window of NWC, with following exceptions: - In the ‘Visual’ tab, you can also change ‘Allow layering’ (at the bottom), although it’s not a staff property.

  • The ‘Midi’ tab doesn’t contain the playback device.

  • In the ‘Instrument’ tab, the instrument name, patch and bank are showed but can’t be changed.

  • The default dynamic velocities have their own tab.

In each tab you have a staves column, a selection column, followed by some property columns. If you want to change a certain property for a certain staff, just change the value in the appropriate row/column combination.

But it’s also possible to change a property for more than one staff in one go, via the top row. The cells in the top row are disabled until you tick one of more boxes in the selection column. (Ticking the top most box will check all boxes.) The staff names of the selected rows will appear in green. You can then change a property for the selected staves in one go via the op row.

If needed, you can repeat this for other selections and properties. (Ticking the top most box twice will remove all selections.)

set_staff_properties.finish()

Restoring static state of global variables. This function is called after running tool.run

set_staff_properties.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

Show clip

Shows ‘translation’ of the selected object(s) into the internal representation that’s used by the tools.

This tool shows a translation of the selected object(s) into the internal representation that’s used by the tools.

show_clip.finish()

Restoring static state of global variables. This function is called after running tool.run

show_clip.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

Show collapsible sections

Show collapsible sections.

In NWC you can mark collapsible sections with the boundary objects ‘Start a collapsible section’ and ‘Cancel/forbid collapse from this bar’. But then it’s very hard to see them in the editor, you’ll have to use ‘Print preview’ to see the effect.

This tool is intended to solve that problem by coloring the notes, chords and rests of a collapsible section with a color of your choice. After that it’s easy to locate these sections in the editor.

Remark: You still have to do a print preview to see the real effect, since collapsing will only start and end at system breaks. But at least now you know in what part of your score they occur.

The tool show a window consisting of 4 frames:

  • ‘Collapsible sections’: Shows the staves with collapsible sections and the measures from - to.

  • ‘Choose Collapse Color’

  • ‘Colors in collapsible sections’: Shows which colors are now present in the collapsible sections for the notes, chords and rests.

  • ‘Options’: If there’s both ‘Default’ and at least 1 ‘Highlight’ color in the collapsible sections, you can indicate:

    • Change the color of all notes/chords/rests in the collapsible sections.

    • Keep the non default color(s) unchanged.

You can click ‘OK’ to do the changes, or ‘Cancel’ to leave without changing anything.

show_collapsible.finish()

Restoring static state of global variables. This function is called after running tool.run

show_collapsible.init(score: nwc_classes.NwcFile)

Initialisation. This function is called when the tool is selected.

show_collapsible.process_event(event, values)

Executed after every event, except ‘None’, ‘Cancel’ and ‘OK’.

Show file

Shows ‘translation’ of the file objects into the internal representation that’s used by the tools.

This tool shows a translation of the file objects into the internal representation that’s used by the tools. The tool parameters determine the objects that are shown.

class show_file.Parameters(values: Dict = <factory>)
show_file.finish()

Restoring static state of global variables. This function is called after running tool.run

show_file.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

Transfer selection

Copies the selected objects to the other staves.

The selected objects are copied to the other staves. The tool parameters determine whether or not the hidden staves are processed.

class transfer_selection.Parameters(values: Dict = <factory>)
transfer_selection.finish()

Restore the static state of global variables. This function is called after running tool.run

transfer_selection.init(score: nwc_classes.NwcFile)

Initialise the global variables. This function is called when the tool is selected.

transfer_selection.process_parameters(values: Dict[str, Any]) → None

Set the global variables that depend on the parameters

Tool template

A template for a nwctool module.

Include the description and the help text here.

class tool_template.Parameters(values: Dict = <factory>)
tool_template.create_parameter_layout() → List[List[Callable]]

Create a layout with the rows of the ‘Tool Parameters’ window.

tool_template.finish()

Restoring static state of global variables. This function is called after running tool.run

tool_template.init(score: nwc_classes.NwcFile)

Initialisation of the global variables. This function is called when the tool is selected.

tool_template.process_event(event, values)

Executed after every event, except ‘None’, ‘Cancel’ and ‘OK’.

tool_template.process_parameters(values: Dict[str, Any]) → None

Sets the global variables that depend on the parameters

tool_template.process_values(values)

Executed after event ‘OK’.

tool_template.run() → Dict[str, Union[List[str], Dict[str, Union[List[str], Dict[str, List[Any]]]]]]

Do what has to be done.

Returns

A dictionary:

“Report”: a list of report lines.

“Summary”: a list of summary lines.

# “Output_filename”: a suggested filename when ‘saving as’

# “Edited”: True if there has been some editing of the score.

# “XLSX”: a dictionary that holds the data to save in a XLSX file.

Side effects

  • If ‘Edited’ is True, the score has been changed.

# …