Instrument marks
================

Instrument marks appear as markup in the left margin of your score.

Creating instrument marks
-------------------------

Use context tools to create instrument marks:

<abjad>
instrument_mark = contexttools.InstrumentMark('Violin ', 'Vn. ')
</abjad>

<abjad>
instrument_mark
print repr(instrument_mark) <hide
</abjad>

Attaching instrument marks
--------------------------

Use ``attach_mark()`` to attach any mark to a component:

<abjad>
staff = Staff("c'4 d'4 e'4 f'4")
</abjad>

<abjad>
instrument_mark.attach_mark(staff)
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'instrument-marks-1') <hide
</abjad>


Getting the instrument mark attached to a component
---------------------------------------------------

Use context tools to get the instrument mark attached to a component:

<abjad>
contexttools.get_instrument_mark_attached_to_component(staff)
print repr(contexttools.get_instrument_mark_attached_to_component(staff)) <hide
</abjad>


Getting the instrument in effect for a component
------------------------------------------------

Or to get the instrument currently in effect for a component:

<abjad>
contexttools.get_effective_instrument(staff[1])
print repr(contexttools.get_effective_instrument(staff[1])) <hide
</abjad>


Detaching instrument marks by hand
----------------------------------

Detach instrument marks by hand:

<abjad>
instrument_mark.detach_mark()
</abjad>

<abjad>
instrument_mark
print repr(instrument_mark) <hide
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'instrument-marks-2')
</abjad>


Detaching instrument marks automatically
----------------------------------------

Or use context tools to detach instrument marks all at once:

<abjad>
instrument_mark = contexttools.InstrumentMark('Violin ', 'Vn. ')
instrument_mark.attach_mark(staff)
</abjad>

<abjad>
instrument_mark
print repr(instrument_mark) <hide
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'instrument-marks-3')
</abjad>

<abjad>
contexttools.detach_instrument_mark_attached_to_component(staff)
</abjad>

<abjad>
instrument_mark
print repr(instrument_mark) <hide
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'instrument-marks-4')
</abjad>


Inspecting attachment
---------------------

Use ``start_component`` to inspect attachment:

<abjad>
instrument_mark = contexttools.InstrumentMark('Flute ', 'Fl. ')
instrument_mark.attach_mark(staff)
</abjad>

<abjad>
show(staff)
iotools.write_expr_to_ly(staff, 'instrument-marks-5')
</abjad>

<abjad>
instrument_mark.start_component
print repr(instrument_mark.start_component) <hide
</abjad>


Inspecting instrument name
--------------------------

Use ``instrument_name`` to get the instrument name of any instrument mark:

<abjad>
instrument_mark.instrument_name
print repr(instrument_mark.instrument_name) <hide
</abjad>


Inspecting short instrument name
--------------------------------

And use ``short_instrument_name`` to get the short instrument name of any instrument mark:

<abjad>
instrument_mark.short_instrument_name
print repr(instrument_mark.short_instrument_name) <hide
</abjad>
