Represents a page graphic assignment with positioning and page-range properties. More...

#include <Graphics.h>

Inheritance diagram for musx::dom::others::PageGraphicAssign:

Public Types
enum class	PageAssignType { AllPages , Even , Odd , One }
	Which pages a multipage assignment appears on.

enum class	PositionFrom { Margins , PageEdge }
	Reference frame for positioning. More...

using	HorizontalAlignment = options::TextOptions::HorizontalAlignment
	Horizontal alignment options.

using	VerticalAlignment = options::TextOptions::VerticalAlignment
	Vertical alignment options.

Public Types inherited from musx::dom::Base
enum class	ShareMode { All , Partial , None }
	Describes how this instance is shared between part and score. More...

using	SharedNodes = std::set< std::string >
	The container type for shared nodes.

Public Member Functions
	PageGraphicAssign (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, Cmper cmper, Inci inci)
	Constructor.

std::optional< PageCmper >	calcStartPageNumber (Cmper forPartId) const
	Return the starting page number, taking into account leading blank pages in all parts. This calculation mimics observed behavior in Finale.

std::optional< PageCmper >	calcEndPageNumber (Cmper forPartId) const
	Return the ending page number, taking into account leading blank pages in all parts This calculation mimics observed behavior in Finale.

bool	isMultiPage () const
	Returns true if this is a multi-page assignment.

bool	isMultiAssignedThruLastPage () const
	Returns true if this is a multi-page assignment that is assigned to through last page, no matter how many.

void	integrityCheck (const std::shared_ptr< Base > &ptrToThis) override
	Allows a class to determine if it has been properly contructed by the factory and fix issues that it can, such as creating default instances of contained classes.

Public Member Functions inherited from musx::dom::OthersBase
	OthersBase (const OthersBase &)=default
	explicit default copy constructor

	OthersBase (OthersBase &&) noexcept=default
	explicit default move constructor

Cmper	getCmper () const
	Gets the `cmper` key value.

std::optional< Inci >	getInci () const
	Gets the optional array index (`inci`).

Cmper	getRequestedPartId () const
	If this instance was retrieved from an object pool, it contains the part ID that was used to retrieve it. If this value is different than getSourcePartId, then this instance is a copy of the pool instance.

Public Member Functions inherited from musx::dom::Base
virtual	~Base () noexcept(false)=default
	Virtual destructor for polymorphic behavior.

DocumentPtr	getDocument () const
	Gets a reference to the Document.

Cmper	getSourcePartId () const
	Gets the source partId for this instance. If an instance is fully shared with the score, the source is SCORE_PARTID. If an instance is partially shared or non shared, the source is the ID of the part that sourced it.

ShareMode	getShareMode () const
	Gets the sharing mode for this instance.

const SharedNodes &	getUnlinkedNodes () const
	Gets the unlinked nodes for this instance. (Only populated for `ShareMode::Partial`)

void	addUnlinkedNode (const std::string &nodeName)
	Adds a shared node for this instance.

virtual bool	requireAllFields () const
	Specifies if the parser should alert (print or throw) when an unknown xml tag is found for this class.

Static Public Member Functions
static MusxInstance< others::PageGraphicAssign >	getForPageId (const DocumentPtr &document, Cmper partId, PageCmper pageId, Inci inci)
	Returns a specific page graphic assignment for a given page number in a given part. This allows the caller not to have to know the conversion to page assignment IDs.

static MusxInstanceList< others::PageGraphicAssign >	getArrayForPageId (const DocumentPtr &document, Cmper partId, PageCmper pageId)
	Returns all the page graphic assignments for a given page number in a given part. This allows the caller not to have to know the conversion to page assignment IDs.

static const xml::XmlElementArray< PageGraphicAssign > &	xmlMappingArray ()
	Required for musx::factory::FieldPopulator.

Public Attributes
uint32_t	version {}
	Always 0x100, meaning perhaps "v1.0". (This was intended for tracking changes to the data format, but it was never used.)

Evpu	left {}
	Horizontal position from reference frame.

Evpu	bottom {}
	Vertical position from reference frame.

Evpu	width {}
	Display width of the placed graphic.

Evpu	height {}
	Display height of the placed graphic.

Cmper	fDescId {}
	The Cmper of the assigned FileDescription. (xml tag is `<fDescID>`)

PageAssignType	displayType {}
	Whether the assignment appears on all/even/odd pages.

bool	hidden {}
	If true, the graphic does not display: inverse of "Show" context menu option. (xml tag is `<displayHidden>`)

HorizontalAlignment	hAlign {}
	Horizontal alignment for left/all pages. (xml tag is `<halign>`)

VerticalAlignment	vAlign {}
	Vertical alignment for left/all pages. (xml tag is `<valign>`)

PositionFrom	posFrom {}
	Position reference for left/all pages.

bool	fixedPerc {}
	If true, preserve aspect ratio. This is a UI setting. Use width/origWidth and height/origHeight for actual scaling.

PageCmper	startPage {}
	First page assignment ID where the graphic appears when cmper==0.

PageCmper	endPage {}
	Last page assignment ID where the graphic appears when cmper==0.

bool	savedRecord {}
	Indicates a stored/saved record. (Used internally by Finale when a graphic is created.)

Evpu	origWidth {}
	Intrinsic/original width of the graphic.

Evpu	origHeight {}
	Intrinsic/original height of the graphic.

HorizontalAlignment	rightPgHAlign {}
	Horizontal alignment on right pages.

VerticalAlignment	rightPgVAlign {}
	Vertical alignment on right pages.

PositionFrom	rightPgPosFrom {}

bool	rightPgFixedPerc {}
	If true, preserve aspect ratio on right-pages (UI setting only). The Finale UI appears to sync this with fixedPerc.

Evpu	rightPgLeft {}
	Horizontal position for right pages.

Evpu	rightPgBottom {}
	Vertical position for right pages.

Cmper	graphicCmper {}

Static Public Attributes
static constexpr std::string_view	XmlNodeName = "pageGraphicAssign"
	The XML node name for this type.

Additional Inherited Members
Protected Member Functions inherited from musx::dom::OthersBase
	OthersBase (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode, Cmper cmper, std::optional< Inci > inci=std::nullopt)
	Constructs an OthersBase object.

OthersBase &	operator= (const OthersBase &other)
	Assignment operator delegates to base, preserving OthersBase state.

OthersBase &	operator= (OthersBase &&other) noexcept
	Assignment operator delegates to base, preserving OthersBase state.

Protected Member Functions inherited from musx::dom::Base
	Base (const DocumentWeakPtr &document, Cmper partId, ShareMode shareMode)
	Constructs the base class.

	Base (const Base &)=default
	explicit default copy constructor

	Base (Base &&) noexcept=default
	explicit default move constructor

Base &	operator= (const Base &)
	no-op copy assignment operator allows subclasses to copy their values.

Base &	operator= (Base &&) noexcept
	no-op move assignment operator allows subclasses to move their values.

Detailed Description

Represents a page graphic assignment with positioning and page-range properties.

Instances of PageGraphicAssign use page assignment IDs rather than straightforward page numbers. If the cmper is non-0, startPage is not used and the cmper specifies a page assignment ID that defines which page this graphic is assigned to. If the cmper is 0, startPage specifies the first page assignment ID to which the graphic is assigned (and displayType governs whether it repeats on odd/even/all pages thereafter).

The inci value specifies a particular page graphic when more than one exists for a cmper value.

This class is identified by the XML node name "pageGraphicAssign".

Member Enumeration Documentation

◆ PositionFrom

enum class musx::dom::others::PageGraphicAssign::PositionFrom

strong

Reference frame for positioning.

Enumerator
Margins	Position is relative to page margins.
PageEdge	Position is relative to page edge.

Member Function Documentation

◆ calcEndPageNumber()

std::optional< PageCmper > musx::dom::others::PageGraphicAssign::calcEndPageNumber ( Cmper forPartId ) const

Return the ending page number, taking into account leading blank pages in all parts This calculation mimics observed behavior in Finale.

Returns: The first page in forPartId on which the page graphic appears. If it does not appear on the part, the function returns std::nullopt.

◆ calcStartPageNumber()

std::optional< PageCmper > musx::dom::others::PageGraphicAssign::calcStartPageNumber ( Cmper forPartId ) const

Return the starting page number, taking into account leading blank pages in all parts. This calculation mimics observed behavior in Finale.

Returns: The first page in forPartId on which the page graphic appears. If it does not appear on the part, the function returns std::nullopt.

◆ getArrayForPageId()

MusxInstanceList< PageGraphicAssign > musx::dom::others::PageGraphicAssign::getArrayForPageId	(	const DocumentPtr &	document,
		Cmper	partId,
		PageCmper	pageId
	)

static

Returns all the page graphic assignments for a given page number in a given part. This allows the caller not to have to know the conversion to page assignment IDs.

Parameters

document	The document to search.
partId	The ID of the linked part to search.
pageId	The page number to search for, or zero for all multipage assignments.

◆ getForPageId()

MusxInstance< PageGraphicAssign > musx::dom::others::PageGraphicAssign::getForPageId	(	const DocumentPtr &	document,
		Cmper	partId,
		PageCmper	pageId,
		Inci	inci
	)

static

Returns a specific page graphic assignment for a given page number in a given part. This allows the caller not to have to know the conversion to page assignment IDs.

Parameters

document	The document to search.
partId	The ID of the linked part to search.
pageId	The page number to search for, or zero for multipage assignments.
inci	The inci of the specific page text assignment to retrieve.

◆ integrityCheck()

void musx::dom::others::PageGraphicAssign::integrityCheck ( const std::shared_ptr< Base > & ptrToThis )

inlineoverridevirtual

Allows a class to determine if it has been properly contructed by the factory and fix issues that it can, such as creating default instances of contained classes.

The default implementation should always be called inside an overridden implementation.

Parameters

ptrToThis This instance in a shared_ptr. (Avoids need for shared_from_this.)

Exceptions

musx::dom::integrity_error if there is a problem.

Reimplemented from musx::dom::Base.

Member Data Documentation

◆ graphicCmper

Cmper musx::dom::others::PageGraphicAssign::graphicCmper {}

Graphic instance Cmper. A non-zero value indicates that the graphic is embedded in the musx file. Embedded graphics are stored in the /graphics/ subdirectory of the musx zip archive. This value also identifies the filename within that directory. For example, if the graphicCmper is 3 and the embedded file has extendion .png then the file is called 3.png within the directory.

◆ rightPgPosFrom

PositionFrom musx::dom::others::PageGraphicAssign::rightPgPosFrom {}

Position reference for right pages. This is a UI setting. Use width/origWidth and height/origHeight for actual scaling. The Finale UI appears to sync this with posFrom.

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ PositionFrom

Member Function Documentation

◆ calcEndPageNumber()

◆ calcStartPageNumber()

◆ getArrayForPageId()

◆ getForPageId()

◆ integrityCheck()

Member Data Documentation

◆ graphicCmper

◆ rightPgPosFrom