# -*- coding: utf-8 -*-

# ------------------------------------------------------------------------------

# Name: layout.py

# Purpose: Layout objects

#

# Authors: Christopher Ariza

# Michael Scott Asato Cuthbert

#

# Copyright: Copyright © 2010, 2012 Michael Scott Asato Cuthbert

# License: BSD, see license.txt

# ------------------------------------------------------------------------------

'''

The layout.py module contains two types of objects that specify the layout on

page (or screen) for Scores and other Stream objects. There are two main types

of Layout objects: (1) layout describing elements and (2) layout defining Streams.

(1) ScoreLayout, PageLayout, SystemLayout, and StaffLayout objects describe the size of

pages, the geometry of page and system margins, the distance between staves, etc.

The model for these layout objects is taken directly (perhaps too directly?)

from MusicXML. These objects all inherit from a BaseLayout class, primarily

as an aid to finding all of these objects as a group. ScoreLayouts give defaults

for each page, system, and staff. Thus, they contain PageLayout, SystemLayout, and

currently one or more StaffLayout objects (but probably just one. MusicXML allows more than

StaffLayout object because multiple staves can be in a Part. Music21 uses

the concept of a PartStaff for a Part that is played by the same performer as another.

e.g., the left hand of the Piano is a PartStaff paired with the right hand).

PageLayout and SystemLayout objects also have a property, 'isNew',

which, if set to `True`, signifies that a new page

or system should begin here. In theory, one could define new dimensions for a page

or system in the middle of the system or page without setting isNew to True, in

which case these measurements would start applying on the next page. In practice,

there's really one good place to use these Layout objects and that's in the first part

in a score at offset 0 of the first measure on a page or system

(or for ScoreLayout, at the beginning

of a piece outside any parts). But it's not an

error to put them in other places, such as at offset 0 of the first measure of a page

or system in all the other parts. In fact, MusicXML tends to do this, and it ends up

not being a waste if a program extracts a single part from the middle of a score.

These objects are standard :class:`~music21.base.Music21Object` types, but many

properties such as .duration, .beat, will probably not apply.

When exporting to MusicXML (which is currently the only format in which music21 can and

does preserve these markings), many MusicXML readers will ignore these tags (or worse,

add a new page or system when PageLayout and SystemLayout objects are found but also

add theme wherever they want). In Finale, this behavior disappears if the MusicXML

document notes that it <supports> new-page and new-system markings. Music21 will add

the appropriate <supports> tags if the containing Stream has `.definesExplicitPageBreaks`

and `.definesExplicitSystemBreaks` set to True. When importing a score that has the

<supports> tag set, music21 will set `.definesExplicitXXXXBreaks` to True for the

outer score and the inner parts. However, this means that if the score is manipulated

enough that the prior layout information is obsolete, programs will need to set these

properties to False or move the Layout tags accordingly.

(2) The second set of objects are Stream subclasses that can be employed when a program

needs to easily iterate around the systems and pages defined through the layout objects

just described, or to get the exact position on a page (or a graphical representation

of a page) for a particular measure or system. (Individual notes coming soon). Normal

Score streams can be changed into LayoutStreams by calling `divideByPages(s)` on them.

A Score that was organized: Score->Part->Measure would then become:

LayoutScore->Page->System->Staff->Measure.

The new LayoutScore has methods that enable querying what page or system a measure is in, and

specifically where on a page a measure is (or the dimensions

of every measure in the piece). However

do not call .show() on a LayoutScore -- the normal score it's derived from will work just fine.

Nor does calling .show() on a Page or System work yet, but once the LayoutStream has been created,

code like this can be done:

s = stream.Stream(...)

ls = layout.divideByPages(s)

pg2sys3 = ls.pages[1].systems[2] # n.b.! 1, 2

measureStart, measureEnd = pg2sys3.measureStart, pg2sys3.measureEnd

scoreExcerpt = s.measures(measureStart, measureEnd)

scoreExcerpt.show() # will show page 2, system 3

Note that while the coordinates given by music21 for a musicxml score (based on margins,

staff size, etc.)

generally reflect what is actually in a musicxml producer, unfortunately, x-positions are

far less accurately

produced by most editors. For instance, Finale scores with measure sizes that have been

manually adjusted tend to show their

unadjusted measure width and not their actual measure width in the MusicXML.

SmartScore Pro tends to produce very good MusicXML layout data.

'''

from __future__ import annotations

# may need to have an object to convert between size units

import copy

import unittest

from collections import namedtuple

import typing as t

from music21 import base

from music21.common.enums import GatherSpanners

from music21 import environment

from music21 import exceptions21

from music21 import spanner

from music21 import stream

from music21.stream.enums import StaffType

environLocal = environment.Environment('layout')

SystemSize = namedtuple('SystemSize', ['top', 'left', 'right', 'bottom'])

PageSize = namedtuple('PageSize', ['top', 'left', 'right', 'bottom', 'width', 'height'])

class LayoutBase(base.Music21Object):

return ''

# ------------------------------------------------------------------------------

class ScoreLayout(LayoutBase):

return round(millimetersPerTenth * tenths, 6)

# ------------------------------------------------------------------------------

class PageLayout(LayoutBase):

self.isNew = isNew

# ------------------------------------------------------------------------------

class SystemLayout(LayoutBase):

self.isNew = isNew

class StaffLayout(LayoutBase):

f'staffSize {self.staffSize!r}, staffLines {self.staffLines!r}')

# ------------------------------------------------------------------------------

class LayoutException(exceptions21.Music21Exception):

pass

class StaffGroupException(spanner.SpannerException):

pass

# ------------------------------------------------------------------------------

class StaffGroup(spanner.Spanner):

''')

# ---------------------------------------------------------------

# Stream subclasses for layout

def divideByPages(

return scoreLists

def getPageRegionMeasureNumbers(scoreIn):

return getRegionMeasureNumbers(scoreIn, 'Page')

def getSystemRegionMeasureNumbers(scoreIn):

return getRegionMeasureNumbers(scoreIn, 'System')

def getRegionMeasureNumbers(scoreIn, region='Page'):

return measureList

class LayoutScore(stream.Opus):