Detailed Description

The ADocument class is the API root object that contains, basically, the Internal Model, a model similar to the DOM in HTML. And the children of this root element represent the basic blocks for building a document: headers, paragraphs, music scores, lists, tables, images, etc.

You can consider a lomse document similar to an HTML document but it can include also music scores. Another difference is that the document objects support styles, but not CSS. Therefore, you can consider the lomse document as a generic rich text document that also can contain full-fledged music scores. It is mainly oriented to display music scores and to have them inserted in an interactive text document, such as a music theory book with chapters, texts, music scores and interactive music exercises.

The lomse document supports the most common objects for textual content, such as headings, paragraphs, lists, tables and images, plus specific objects for music scores. But for music scores the DOM model analogy is not truly feasible as many music notation markings (like a slur or beam) represent links between objects in the tree. Therefore, lomse or any other program have to maintain self-consistency when there are 'paired elements' representing the starts and ends of things like beams, crescendo markings, slurs, and so on. Therefore, the Internal Model contains additional structures for correctly representing a music score.

Of course, the document can contain just one full-score, and this will be the case when importing music scores in other formats, such as a MusicXML score file.

See ADocument content

Warning: This documentation is incomplete. The user API for the document internal model is currently being defined and, thus, for this class, only some methods have been defined.

Public Member Functions
bool	is_valid () const

ImoId	object_id () const

std::string &	lmd_version () const

AObject	create_object (EDocObject type)

bool	append_child (const AObject &detachedObj)

void	end_of_changes ()

Document *	internal_object ()

Page size and margins
Margings, in lomse, documents, are strips of white space around the edge of the paper. The wider the left and right margins, the narrower the page content. The wider the top and bottom margins, the shorter the page content. In most cases, it is not necessary to change the default page margins. However, you can change the margins with these methods.
void	set_page_left_margin_odd (LUnits value)

void	set_page_right_margin_odd (LUnits value)

void	set_page_top_margin_odd (LUnits value)

void	set_page_bottom_margin_odd (LUnits value)

void	set_page_left_margin_even (LUnits value)

void	set_page_right_margin_even (LUnits value)

void	set_page_top_margin_even (LUnits value)

void	set_page_bottom_margin_even (LUnits value)

void	set_page_size (USize uPageSize)

void	set_page_width (LUnits value)

void	set_page_height (LUnits value)

LUnits	page_left_margin_odd () const

LUnits	page_right_margin_odd () const

LUnits	page_top_margin_odd () const

LUnits	page_bottom_margin_odd () const

LUnits	page_left_margin_even () const

LUnits	page_right_margin_even () const

LUnits	page_top_margin_even () const

LUnits	page_bottom_margin_even () const

USize	page_size () const

LUnits	page_width () const

LUnits	page_height () const

Page content scale
float	page_content_scale () const

void	set_page_content_scale (float scale)

Content traversal
int	num_children () const

AObject	child_at (int iItem) const

AObject	first_child () const

AObject	last_child () const

AScore	first_score () const

Member Function Documentation

◆ append_child()

bool append_child ( const AObject & detachedObj )

Appends a detached AObject to document content. The object to append must be a blocks contained object. Otherwise, nothing will be done. Returns true is the object has been successfully attached. Otherwise, the objects will continue existing as a detached object.

Parameters

detachedObj The detached object to append to document content.

See also: ADocument::create_object()

◆ child_at()

AObject child_at ( int iItem ) const

Returns the specified child object.

Parameters

iItem Is the index to the requested child (0 ... num.children - 1)

◆ create_object()

AObject create_object ( EDocObject type )

Creates a new detached AObject of the type specified by parameter type.

Parameters

type	A value from enum EDocObject that specifies the type of object to be created.

The created object is detached. This means that although it is part of the document, this object is not attached as content. It exists in memory and the document knows about it, but it is not part of the visible content. It is 'waiting' to be inserted at some place in the content. To attach to the document a detached object it is necessary to use specific methods, such as ADocument::append_child().

◆ end_of_changes()

void end_of_changes ( )

When you modify the content of a document it is necessary to update some structures associated to music scores. For this it is mandatory to invoke this method. Alternatively, you can invoke AScore::end_of_changes(), on the modified scores.

◆ first_child()

AObject first_child ( ) const

Returns the first child object.

◆ first_score()

AScore first_score ( ) const

Returns the first child object of type 'music score'.

◆ internal_object()

Document * internal_object ( )

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.

◆ is_valid()

bool is_valid ( ) const

Returns true if the object represents a valid document.

◆ last_child()

AObject last_child ( ) const

Returns the last child object.

◆ lmd_version()

std::string & lmd_version ( ) const

For documents created from sources in LMD format this method will return the LMD version used in the source. For other document creation methods and formats it will return version "0.0".

◆ num_children()

int num_children ( ) const

Returns the number of objects contained, at first level, in this document.

◆ object_id()

ImoId object_id ( ) const

Returns the internal unique identifier (ID) for this document.

◆ page_bottom_margin_even()

LUnits page_bottom_margin_even ( ) const

Returns the bottom margin for even pages. The returned value is in logical units (cents of a millimeter).

◆ page_bottom_margin_odd()

LUnits page_bottom_margin_odd ( ) const

Returns the bottom margin for odd pages. The returned value is in logical units (cents of a millimeter).

◆ page_content_scale()

float page_content_scale ( ) const

Return the scaling factor to apply to the content when rendered divided into pages of the size defined by the paper size. Normally this factor is 1.0.

◆ page_height()

LUnits page_height ( ) const

Returns the paper height intended for rendering this document. The returned value is in logical units (cents of a millimeter).

◆ page_left_margin_even()

LUnits page_left_margin_even ( ) const

Returns the left margin for even pages. The returned value is in logical units (cents of a millimeter).

◆ page_left_margin_odd()

LUnits page_left_margin_odd ( ) const

Returns the left margin for odd pages. The returned value is in logical units (cents of a millimeter).

◆ page_right_margin_even()

LUnits page_right_margin_even ( ) const

Returns the right margin for even pages. The returned value is in logical units (cents of a millimeter).

◆ page_right_margin_odd()

LUnits page_right_margin_odd ( ) const

Returns the right margin for odd pages. The returned value is in logical units (cents of a millimeter).

◆ page_size()

USize page_size ( ) const

Returns the paper size intended for rendering this document. The returned value is in logical units (cents of a millimeter).

◆ page_top_margin_even()

LUnits page_top_margin_even ( ) const

Returns the top margin for even pages. The returned value is in logical units (cents of a millimeter).

◆ page_top_margin_odd()

LUnits page_top_margin_odd ( ) const

Returns the top margin for odd pages. The returned value is in logical units (cents of a millimeter).

◆ page_width()

LUnits page_width ( ) const

Returns the paper width intended for rendering this document. The returned value is in logical units (cents of a millimeter).

◆ set_page_bottom_margin_even()

void set_page_bottom_margin_even ( LUnits value )

Sets the bottom margin in even pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_bottom_margin_odd()

void set_page_bottom_margin_odd ( LUnits value )

Sets the bottom margin in odd pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_content_scale()

void set_page_content_scale ( float scale )

Set the scaling factor to apply to the content when rendered divided into pages of the size defined by the paper size. By default this factor is 1.0.

◆ set_page_height()

void set_page_height ( LUnits value )

Sets the paper height intended for rendering this document. The height value is in logical units (cents of a millimeter).

◆ set_page_left_margin_even()

void set_page_left_margin_even ( LUnits value )

Sets the left margin in even pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_left_margin_odd()

void set_page_left_margin_odd ( LUnits value )

Sets the left margin in odd pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_right_margin_even()

void set_page_right_margin_even ( LUnits value )

Sets the right margin in even pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_right_margin_odd()

void set_page_right_margin_odd ( LUnits value )

Sets the right margin in odd pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_size()

void set_page_size ( USize uPageSize )

Sets the paper size intended for rendering this document. The size values are in logical units (cents of a millimeter).

◆ set_page_top_margin_even()

void set_page_top_margin_even ( LUnits value )

Sets the top margin in even pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_top_margin_odd()

void set_page_top_margin_odd ( LUnits value )

Sets the top margin in odd pages. The new margin value is specified in logical units (cents of a millimeter).

◆ set_page_width()

void set_page_width ( LUnits value )

Sets the paper width intended for rendering this document. The width value is in logical units (cents of a millimeter).

Detailed Description

Public Member Functions

Member Function Documentation

◆ append_child()

◆ child_at()

◆ create_object()

◆ end_of_changes()

◆ first_child()

◆ first_score()

◆ internal_object()

◆ is_valid()

◆ last_child()

◆ lmd_version()

◆ num_children()

◆ object_id()

◆ page_bottom_margin_even()

◆ page_bottom_margin_odd()

◆ page_content_scale()

◆ page_height()

◆ page_left_margin_even()

◆ page_left_margin_odd()

◆ page_right_margin_even()

◆ page_right_margin_odd()

◆ page_size()

◆ page_top_margin_even()

◆ page_top_margin_odd()

◆ page_width()

◆ set_page_bottom_margin_even()

◆ set_page_bottom_margin_odd()

◆ set_page_content_scale()

◆ set_page_height()

◆ set_page_left_margin_even()

◆ set_page_left_margin_odd()

◆ set_page_right_margin_even()

◆ set_page_right_margin_odd()

◆ set_page_size()

◆ set_page_top_margin_even()

◆ set_page_top_margin_odd()

◆ set_page_width()