Lomse library. API documentation  0.30.0
GraphicModel Class Reference

#include <lomse_graphical_model.h>

Detailed Description

The GraphicModel represents the visual representation of the document. It is a tree of objects representing the graphical elements (lines, arcs, shapes, etc.) that describe the final appearance of the document from a purely geometric point of view. The graphical model objects (GmoShape and GmoBox derived objects) behave as vertex sources, providing the coordinates for the polygons that define the visual representation of the document.

The GraphicModel is a representation of what in computer graphics theory is named the real world, a virtual rendition of the full document at real size (e.g. millimeters). It is a virtual image of the full document organized as expected by the chosen View type.

The Graphic Model subdivides the document layout in regions or boxes, represented by objects derived from GmoBox. The boxes are organized in a tree so that each box is also a container for other boxes. For instance, the main boxes for an score are depicted in following picture:

graphical-model-boxes.png
Image: Some boxes in the Graphical Model
  • GmoBoxSystem - Represents a line of music in the printed score and encloses all its content.
  • GmoBoxSlice - Systems are vertically split in columns or vertical slices. Normally, for music with time signature, a slice corresponds to a measure. GmoBoxSlice is a container for all boxes and shapes in that system column.
  • GmoBoxSliceInstr - GmoBoxSlice is horizontally subdivided in regions for each instrument in the system. GmoBoxSliceInstr represents a column of an instrument. It is a container for GmoBoxSliceStaff objects that contain the shapes for the slice.

The GraphicModel is built from the Internal Model by the layout process. Once it is built, it will be re-built only if the document or the View type change. Other changes, such as resolution, window size, allocation of a new rendering bitmap, do not affect the Graphic Model.

Rendering the document is done using the Graphic Model. At high level, rendering is a simple operation. It is just traversing the graphical model tree and invoking the GmoObj::on_draw() method on each object. The on_draw() method will issue drawing commands that will be processed by a Drawer object for generating the rendition.

The GraphicModel also provides access to global information (e.g. number of pages) as well as to the most relevant objects.

The Graphic Model can be accessed by invoking method Interactor::get_graphic_model().

Public Member Functions

Access to some information
int get_num_pages ()
 
int get_num_systems (ImoId scoreId)
 
int get_page_number_containing (GmoObj *pGmo)
 
GmMeasuresTable * get_measures_table (ImoId scoreId)
 
Access to main boxes
GmoBoxDocumentget_root ()
 
GmoBoxDocPageget_page (int i)
 
GmoBoxSystemget_system_for (ImoId scoreId, TimeUnits timepos)
 
GmoBoxSystemget_system_box (int iSystem, ImoId scoreId)
 
GmoBoxSystemget_system_for (ImoScore *pScore, const MeasureLocator &ml)
 
GmoBoxSystemget_system_for_staffobj (ImoId id)
 
GmoShapeStaffget_shape_for_first_staff_in_first_system (ImoId scoreId)
 
Access to shapes and boxes related to an ImoObj
GmoShapeget_shape_for_imo (ImoId imoId, ShapeId shapeId)
 
GmoShapeget_main_shape_for_imo (ImoId id)
 
GmoShapefind_shape_for_object (ImoStaffObj *pSO)
 
GmoShapeget_shape_for_noterest (ImoNoteRest *pNR)
 
GmoBoxget_box_for_imo (ImoId id)
 
Information for clicked point
GmoShapefind_shape_at (int iPage, LUnits x, LUnits y)
 
GmoBoxfind_inner_box_at (int iPage, LUnits x, LUnits y)
 
AreaInfoget_info_for_point (int iPage, LUnits x, LUnits y)
 

Member Function Documentation

◆ find_inner_box_at()

GmoBox* GraphicModel::find_inner_box_at ( int  iPage,
LUnits  x,
LUnits  y 
)

Returns pointer to the innermost GmoBox located in the given cordinates of a document page.

Parameters
iPageThe number of the page (0..n-1).
x,yThe relative coordinates for the point (logical units referred to the top-left corner of the page).

◆ find_shape_at()

GmoShape* GraphicModel::find_shape_at ( int  iPage,
LUnits  x,
LUnits  y 
)

Returns pointer to the shape (if any) located in the given cordinates of a document page. If no shape there, returns nullptr.

Parameters
iPageThe number of the page (0..n-1).
x,yThe relative coordinates for the point (logical units referred to the top-left corner of the page).

◆ find_shape_for_object()

GmoShape* GraphicModel::find_shape_for_object ( ImoStaffObj *  pSO)

Returns pointer to the main GmoShape generated by an ImoStaffObj.

Parameters
pSOPointer to the ImoStaffObj to which the request is referring.

◆ get_box_for_imo()

GmoBox* GraphicModel::get_box_for_imo ( ImoId  id)

Returns pointer to the innermost GmoBox in which the shape for an ImoObj is contained.

Parameters
idThe Id of the ImoObj to which the request is referring.

◆ get_info_for_point()

AreaInfo* GraphicModel::get_info_for_point ( int  iPage,
LUnits  x,
LUnits  y 
)

Returns pointer to an AreaInfo object containing the classification information and pointers to shape and boxes related to the given cordinates of a document page.

Parameters
iPageThe number of the page (0..n-1).
x,yThe relative coordinates for the point (logical units referred to the top-left corner of the page).

◆ get_main_shape_for_imo()

GmoShape* GraphicModel::get_main_shape_for_imo ( ImoId  id)

Returns pointer to the main GmoShape generated by an ImoObj. It is equivalent to get_shape_for_imo(imoId, 0).

Parameters
idThe Id of the ImoObj to which the request is referring.

◆ get_measures_table()

GmMeasuresTable* GraphicModel::get_measures_table ( ImoId  scoreId)

Returns the GmMeasuresTable for the given score. The GmMeasuresTable object manages the table with the graphical information about the measures in the score and provides information such as the number of measures in the score, or their coordinates.

Parameters
scoreIdThe Id of the score to which the request is referring.

◆ get_num_pages()

int GraphicModel::get_num_pages ( )

Returns the number of pages of the rendered document. This value can also be obtained by invoking Interactor::get_num_pages().

◆ get_num_systems()

int GraphicModel::get_num_systems ( ImoId  scoreId)

Returns the number of systems in the rendered score.

Parameters
scoreIdThe Id of the score to which the request is referring.

◆ get_page()

GmoBoxDocPage* GraphicModel::get_page ( int  i)

Returns the GmoBoxDocPage for the given page number.

Parameters
iThe number of the page (0..n-1) for which the GmoBoxDocPage is requested.

◆ get_page_number_containing()

int GraphicModel::get_page_number_containing ( GmoObj pGmo)

Returns the number of the page (0..n-1) that contains the given GmoObj.

Parameters
pGmoPointer to the GmoObj to which the request is referring.

◆ get_root()

GmoBoxDocument* GraphicModel::get_root ( )
inline

Returns the root object of the Graphical Model. It is always a GmoBoxDocument object.

◆ get_shape_for_first_staff_in_first_system()

GmoShapeStaff* GraphicModel::get_shape_for_first_staff_in_first_system ( ImoId  scoreId)

Returns pointer to the GmoShapeStaff for the first staff in first system.

Parameters
scoreIdThe Id of the score to which the request is referring.

◆ get_shape_for_imo()

GmoShape* GraphicModel::get_shape_for_imo ( ImoId  imoId,
ShapeId  shapeId 
)

Returns pointer to the GmoShape generated by an ImoObj.

Parameters
imoIdThe Id of the ImoObj to which the request is referring.
shapeIdAs any ImoObj can generate several shapes it is necessary to provide the shape index. The first generated shape has index 0, the next one index 1, and so on.

◆ get_shape_for_noterest()

GmoShape* GraphicModel::get_shape_for_noterest ( ImoNoteRest *  pNR)

Returns pointer to the main GmoShape generated by an ImoNoteRest.

Parameters
pNRPointer to the ImoNoteRest to which the request is referring.

◆ get_system_box()

GmoBoxSystem* GraphicModel::get_system_box ( int  iSystem,
ImoId  scoreId 
)

Returns pointer to the GmoBoxSystem for the given system number.

Parameters
iSystemThe number of the system (0..n-1) for which the GmoBoxSystem is requested.
scoreIdThe Id of the score to which the request is referring.

◆ get_system_for() [1/2]

GmoBoxSystem* GraphicModel::get_system_for ( ImoId  scoreId,
TimeUnits  timepos 
)

Returns pointer to the GmoBoxSystem that contains the specified timepos. If there is no system for the given timepos, returns nullptr.

This method gives preference to finding a system containing a note/rest at the given tiempos instead of non-timed staff objects. For example, the last barline in one system has the same timepos than the first note/rest in next system. Therefore, this method will return the second system not the one containing the barline.

Parameters
scoreIdThe Id of the score to which the request is referring.
timeposThe time position (absolute time units) for the requested system.

◆ get_system_for() [2/2]

GmoBoxSystem* GraphicModel::get_system_for ( ImoScore *  pScore,
const MeasureLocator &  ml 
)

Returns pointer to the GmoBoxSystem that contains the specified MeasureLocator. If there is no system for the given location, returns nullptr.

Parameters
pScoreThe score to which the request is referring.
mlThe MeasureLocator for which the GmoBoxSystem is requested.

◆ get_system_for_staffobj()

GmoBoxSystem* GraphicModel::get_system_for_staffobj ( ImoId  id)

Returns pointer to the GmoBoxSystem that contains the specified ImoStaffObj.

Parameters
idThe Id of the ImoStaffObj to which the request is referring.