 |
Lomse library. API documentation
0.30.0
|
|
Lomse library. API documentation
0.30.0
|
AInstrument represents an instrument on the score. For lomse, an instrument refers to a physical musical instrument, such as a violin, a flute, or a piano. It is represented by one or more staves and is modeled as the collection of all aspects pertaining to the visual display of the staff/staves as they appear on the printed page (name, transposition, musical content, etc) as well as the required information for audio playback (e.g. MIDI channel, MIDI program, etc.).
But there are cases in which the staves for an instrument contain the music for more than one real instrument. For instance the bass and tenor voices in a choral can be placed in a single staff, or the different percussion instruments can share an staff.
In theory, sharing the same staff between several instruments should be forbidden, and each instrument should be modeled in its own staff. And for presentation, the user should be able to decide which instruments are going to form an score part, and how that part should be displayed: all instruments merged in a single staff or other layout. But for compatibility with MusicXML, lomse allows that several instruments share the same staves. As a consequence, a lomse instrument could represent several real instruments and, thus, could have several sound information objects (ASoundInfo objects) each of them containing the sound information for each real physical instrument that is sharing the staff.
Public Member Functions | |
| ImoInstrument * | internal_object () const |
Name and abbreviation | |
| std::string & | name_string () const |
| std::string & | abbreviation_string () const |
| void | set_name_string (const string &name) |
| void | set_abbreviation_string (const string &abbrev) |
Sound information | |
| int | num_sounds () const |
| ASoundInfo | sound_info_at (int iSound) const |
 Public Member Functions inherited from AObject | |
| AObject () | |
| bool | is_valid () const |
| ImoObj * | internal_object () const |
| ImoId | object_id () const |
| const std::string & | object_name () const |
| ADocument | owner_document () const |
| ADynamic | downcast_to_dynamic () const |
| AInstrument | downcast_to_instrument () const |
| AInstrGroup | downcast_to_instr_group () const |
| ALink | downcast_to_link () const |
| AList | downcast_to_list () const |
| AParagraph | downcast_to_paragraph () const |
| AScore | downcast_to_score () const |
| ATextItem | downcast_to_text_item () const |
| bool | is_anonymous_block () const |
| bool | is_button () const |
| bool | is_content () const |
| bool | is_control () const |
| bool | is_dynamic () const |
| bool | is_heading () const |
| bool | is_image () const |
| bool | is_inline_wrapper () const |
| bool | is_instrument () const |
| bool | is_instr_group () const |
| bool | is_link () const |
| bool | is_list () const |
| bool | is_list_item () const |
| bool | is_midi_info () const |
| bool | is_multicolumn () const |
| bool | is_music_data () const |
| bool | is_paragraph () const |
| bool | is_score () const |
| bool | is_sound_info () const |
| bool | is_table () const |
| bool | is_table_cell () const |
| bool | is_table_body () const |
| bool | is_table_head () const |
| bool | is_table_row () const |
| bool | is_text_item () const |
| std::string & abbreviation_string | ( | ) | const |
Returns the short, abbreviated name that appears on every system other than the first system.
| ImoInstrument * internal_object | ( | ) | const |
Transitional, to facilitate migration to the new public API. Notice that this method will be removed in future so, please, if you need to use this method open an issue at https://github.com/lenmus/lomse/issues explaining the need, so that the public API could be fixed and your app. would not be affected in future when this method is removed.
| std::string & name_string | ( | ) | const |
Returns the name of the instrument, that is the string that is placed at the start of the first system in the score.
| int num_sounds | ( | ) | const |
Returns the number of ASoundInfo elements contained in this instrument, at least one.
An AInstruments always have at least one sound, represented by an ASoundInfo object. But there are cases in which the staves for an instrument contain the music for more than one real instrument. For instance the bass and tenor voices in a choral can be placed in a single staff, or the different percussion instruments can share an staff. In these cases in which a lomse instrument represents several real instruments there is aISoundInfo object for each real physical instrument that is sharing the staff.
Method AInstrument::num_sounds() informs about the number of ASoundInfo objects that this instrument contains. Always at least one.
| void set_abbreviation_string | ( | const string & | abbrev | ) |
Sets the short, abbreviated name that appears on every system other than the first system.
| void set_name_string | ( | const string & | name | ) |
Sets the name of the instrument, that is the string that is placed at the start of the first system in the score.
It’s important to note that changing the name of an instrument doesn’t actually change any other instrument properties, such as transposition information or number of staves. For example, renaming "Flute" to "Piano" does not creates a second staff for the instrument. Or renaming “Trumpets in Bb” to “Trumpets in C” does not change the transposition information.
| ASoundInfo sound_info_at | ( | int | iSound | ) | const |
Returns the ASoundInfo object at a given position in the collection of sounds for this instrument.
In cases in which a lomse instrument represents several real instruments there is a collection of ASoundInfo objects, one for each real physical instrument that is sharing the staff.
AInstrument::sound_info_at(0) is always valid and returns the only ASoundInfo object for normal cases and the first ASoundInfo object when several real instruments are represented by a single AInstrument object.
| iSound | The index (0..n-1) to the requested sound info object. |
1.8.13