#include <lomse_doorway.h>

Detailed Description

LomseDoorway is the main interface with the Lomse library. This class represent the gate between Lomse and your application:

For your application it is entry point for interacting with the library: the way for configuring Lomse, for accessing Lomse version information and for creating/opening documents and scores, which in turn provides accessors for managing the open documents.
For the Lomse library, it is the way to access platform dependent information and methods, by using callbacks initialized by the user during Lomse configuration.

Public Member Functions
	LomseDoorway (std::ostream logStream=nullptr, std::ostream forensicLogStream=nullptr)

Library initialization and configuration
void	init_library (int pixel_format, int ppi, std::ostream &reporter=std::cout)

void	set_notify_callback (void pThis, void(pt2Func)(void *, SpEventInfo))

void	set_request_callback (void pThis, void(pt2Func)(void , Request ))

void	set_default_fonts_path (const std::string &fontsPath)

double	get_screen_ppi ()

int	get_pixel_format ()

Document creation methods
Presenter *	new_document (int viewType, Drawer screenDrawer=nullptr, Drawer printDrawer=nullptr)

Presenter *	new_document (int viewType, const std::string &source, int format, std::ostream &reporter=std::cout, Drawer screenDrawer=nullptr, Drawer printDrawer=nullptr)

Presenter *	open_document (int viewType, const std::string &filename, std::ostream &reporter=std::cout, Drawer screenDrawer=nullptr, Drawer printDrawer=nullptr)

Presenter *	open_document (int viewType, LdpReader &reader, std::ostream &reporter=std::cout, Drawer screenDrawer=nullptr, Drawer printDrawer=nullptr)

Playback related methods
void	set_global_metronome_and_replace_local (Metronome *pMtr)

Library information
std::string	get_version_string ()

std::string	get_version_long_string ()

std::string	get_build_date ()

int	get_version_major ()

int	get_version_minor ()

int	get_version_patch ()

Other methods
MusicXmlOptions *	get_musicxml_options ()

LibraryScope *	get_library_scope ()

Constructor & Destructor Documentation

◆ LomseDoorway()

LomseDoorway::LomseDoorway	(	std::ostream *	logStream = `nullptr`,
		std::ostream *	forensicLogStream = `nullptr`
	)

explicit

Constructor. Your application should create only one instance of LomseDoorway and its life scope should be as long as your application need to use Lomse.

Member Function Documentation

◆ get_build_date()

std::string LomseDoorway::get_build_date ( )

Returns the build date and time of the Lomse library. The string is twenty characters long and looks like "12-Feb-2016 17:54:03". Date and time are separated by one space. Date is in format dd-mm-yyyy and time in format hh:mm:ss. Day, hour, minutes and seconds are always padded with zero if only one digit e.g., "02-Mar-2016 07:54:03"

◆ get_library_scope()

LibraryScope* LomseDoorway::get_library_scope ( )

inline

Get the pointer to an object of class LibraryScope. This object gives access to all Lomse global functions and information.

◆ get_musicxml_options()

MusicXmlOptions* LomseDoorway::get_musicxml_options ( )

Returns the current options object with the settings to use for dealing and fixing errors and malformed MusicXML files. The import options can be changed multiple times, whenever it is needed. For example:

LomseDoorway* pLomse = ...
MusicXmlOptions* opt = pLomse->get_musicxml_options();
opt->fix_beams(true);
Presenter* pPresenter = pLomse->open_document(k_view_vertical_book,
                                              "my_score.xml");
...
opt->fix_beams(false);
Presenter* pPresenter = pLomse->open_document(k_view_vertical_book,
                                              "other_score.xml");

See also: class MusicXmlOptions

◆ get_pixel_format()

int LomseDoorway::get_pixel_format ( )

inline

Returns settings for rendering bitmap format. This is the value set when method init_library() was called. The meaning of the returned value is given by enum EPixelFormat.

◆ get_screen_ppi()

double LomseDoorway::get_screen_ppi ( )

inline

Returns settings for rendering bitmap resolution. This is the value set when method init_library() was called.

◆ get_version_long_string()

std::string LomseDoorway::get_version_long_string ( )

Returns Lomse version and build information as string. e.g., "0.17.20+aaf5e23"

◆ get_version_major()

int LomseDoorway::get_version_major ( )

Returns Lomse major version as integer number. For instance, if version string is "0.17.20" this method will return 0.

◆ get_version_minor()

int LomseDoorway::get_version_minor ( )

Returns Lomse minor version as integer number. For instance, if version string is "0.17.20" this method will return 17.

◆ get_version_patch()

int LomseDoorway::get_version_patch ( )

Returns Lomse patch version as integer number. For instance, if version string is "0.17.20" this method will return 20.

◆ get_version_string()

std::string LomseDoorway::get_version_string ( )

Returns Lomse version as string "major.minor.patch" e.g., "0.17.20"

◆ init_library()

void LomseDoorway::init_library	(	int	pixel_format,
		int	ppi,
		std::ostream &	reporter = `std::cout`
	)

Before using the library, method init_library() should be invoked for initializing the library and providing the necessary information. As Lomse renders scores and documents on a bitmap it is necessary to inform Lomse about the required bitmap properties. Also, you can set an ostream to be used by Lomse for reporting errors.

Initialization is not required if your application will not use Lomse to render scores in bitmaps, e.g.: uses it only for playback or only renders SVG code. In these cases any values for pixel format and resolution will be valid and so, default values are enough and you will not have to invoke this method.

Parameters

pixel_format	A value from the global enumeration type EPixelFormat
ppi	The display resolution in pixels per inch (e.g. 96). Lomse uses vectorial graphics for all, typography included and, thus, screen resolution is no required and your application can always scale the image to as much resolution as you like. The real resolution is determined by the provided bitmap size (pixels) to be used as rendering buffer. Nevertheless, Lomse requires a screen resolution value to adjust internal scaling factors so that when the user scale is set to 1.0 (100%) the document get displayed on the screen at real size. If this is not a requirement for your application, any value can be used (e.g. 72 or 96).
reporter	The ostream to be used by Lomse for reporting errors. By default, all errors will be send to cout.

For instance, assume we are writing an application for Linux to display scores on screen:

LomseDoorway m_lomse;                   //the only instance, representing the lomse library
int pixel_format = k_pix_format_rgb24;  //pixel format: RGB 24bits
int resolution = 96;                    //typical resolution
//initialize the library with these values
m_lomse.init_library(pixel_format, resolution);

◆ new_document() [1/2]

Presenter* LomseDoorway::new_document	(	int	viewType,
		Drawer *	screenDrawer = `nullptr`,
		Drawer *	printDrawer = `nullptr`
	)

Create a new empty document, as well as a View for rendering it and all additional components (Interactor, Presenter, etc.) necessary for managing this document and interacting with it. Optionally, default BitmapDrawer objects used by Lomse can be replaced by any Drawer objects created by your application.

Parameters

viewType	The view type that will be used for rendering this document.
screenDrawer	The Drawer to use as main drawer. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.
printDrawer	The Drawer to use for printing. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.

Returns: A pointer to the Presenter to be used for interacting with this document.

Attention: As Presenter ownership is transferred to user application, you have to take care of deleting the Presenter when no longer needed. Deleting the Presenter will automatically cause deletion of all MVC involved objects: the Document, all existing Views and Interactors, etc., as well as any passed Drawer objects.

See also: Rendering documents overview

◆ new_document() [2/2]

Presenter* LomseDoorway::new_document	(	int	viewType,
		const std::string &	source,
		int	format,
		std::ostream &	reporter = `std::cout`,
		Drawer *	screenDrawer = `nullptr`,
		Drawer *	printDrawer = `nullptr`
	)

Create a new document initialized with the passed content. Also creates a View for rendering it as well as all additional components (Interactor, Presenter, etc.) necessary for managing this document and interacting with it. Optionally, default BitmapDrawer objects used by Lomse can be replaced by any Drawer objects created by your application.

Parameters

viewType	The view type that will be used for rendering this document.
source	A string with the content for the document to create.
format	A value specifying the format for the source content. Valid values are defined in Document class. Valid values are: Document::k_format_ldp = 0, for LenMus documents in LDP syntax. Document::k_format_lmd = 1, for LenMus documents in XML syntax (LMD format). Document::k_format_mxl = 2, for MusicXML documents
reporter	The ostream to be used for reporting any errors. By default, all errors will be send to cout.
screenDrawer	The Drawer to use as main drawer. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.
printDrawer	The Drawer to use for printing. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.

Returns: A pointer to the Presenter to be used for interacting with this document.

Attention: As Presenter ownership is transferred to user application, you have to take care of deleting the Presenter when no longer needed. Deleting the Presenter will automatically cause deletion of all MVC involved objects: the Document, all existing Views and Interactors, etc., as well as any passed Drawer objects.

See also: Rendering documents overview

◆ open_document() [1/2]

Presenter* LomseDoorway::open_document	(	int	viewType,
		const std::string &	filename,
		std::ostream &	reporter = `std::cout`,
		Drawer *	screenDrawer = `nullptr`,
		Drawer *	printDrawer = `nullptr`
	)

Open a document. Its content is read from a file. Also creates a View for rendering it as well as all additional components (Interactor, Presenter, etc.) necessary for managing this document and interacting with it. Optionally, default BitmapDrawer objects used by Lomse can be replaced by any Drawer objects created by your application. Optionally, default BitmapDrawer objects used by Lomse can be replaced by any Drawer objects created by your application.

Parameters

viewType	The view type that will be used for rendering this document.
filename	A string with the absolute path to the file containing the document.
reporter	The ostream to be used for reporting any errors. By default, all errors will be send to cout.
screenDrawer	The Drawer to use as main drawer. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.
printDrawer	The Drawer to use for printing. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.

Returns: A pointer to the Presenter to be used for interacting with this document.

Attention: As Presenter ownership is transferred to user application, you have to take care of deleting the Presenter when no longer needed. Deleting the Presenter will automatically cause deletion of all MVC involved objects: the Document, all existing Views and Interactors, etc., as well as any passed Drawer objects.

See also: Rendering documents overview

◆ open_document() [2/2]

Presenter* LomseDoorway::open_document	(	int	viewType,
		LdpReader &	reader,
		std::ostream &	reporter = `std::cout`,
		Drawer *	screenDrawer = `nullptr`,
		Drawer *	printDrawer = `nullptr`
	)

Open a document. Its content is provided by an LdpReader object. Also creates a View for rendering it as well as all additional components (Interactor, Presenter, etc.) necessary for managing this document and interacting with it. Optionally, default BitmapDrawer objects used by Lomse can be replaced by any Drawer objects created by your application.

Parameters

viewType	The view type that will be used for rendering this document.
reader	An object of class LdpReader that will be used for reading the content of the document.
reporter	The ostream to be used for reporting any errors. By default, all errors will be send to cout.
screenDrawer	The Drawer to use as main drawer. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.
printDrawer	The Drawer to use for printing. Ownership of this Drawer is transferred to the View. You must not delete it. If not specified or nullptr a BitmapDrawer will be used.

Returns: A pointer to the Presenter to be used for interacting with this document.

Attention: As Presenter ownership is transferred to user application, you have to take care of deleting the Presenter when no longer needed. Deleting the Presenter will automatically cause deletion of all MVC involved objects: the Document, all existing Views and Interactors, etc., as well as any passed Drawer objects.

See also: Rendering documents overview

◆ set_default_fonts_path()

void LomseDoorway::set_default_fonts_path ( const std::string & fontsPath )

Method set_default_fonts_path() is used for informing Lomse about the path in which additional fonts are installed. Default fonts used by Lomse are located in folders known by Lomse, but Lomse has no knowledge about where the additional fonts the user would like to use are located. They are probably in the folder used by the operating system for fonts. But as Lomse is platform independent, currently it has no knowledge about operating system folders for fonts. Therefore, applications using additional fonts other than Lomse default fonts should use this method for informing Lomse about the path for the fonts.

Parameters

fontsPath Absolute path to the fonts folder in which Lomse will look for fonts other than Lomse default fonts. Please note that Lomse will not look into sub-folders in the passed path.

◆ set_global_metronome_and_replace_local()

void LomseDoorway::set_global_metronome_and_replace_local ( Metronome * pMtr )

This method is used for informing Lomse about the metronome control to use to determine tempo in playback. By default, Lomse takes metronome settings from ?. But your application can specify another metronome control, normally a global metronome for the all your application.

Todo:: Clarify the purpose and usage of this method

Parameters

pMtr	Pointer to the Metronome object to be used.

◆ set_notify_callback()

void LomseDoorway::set_notify_callback	(	void *	pThis,
		void()(void , SpEventInfo)	pt2Func
	)

This method is used by for informing Lomse about the callback method that Lomse should invoke when having to communicate an event to your application.

Parameters

pThis	A pointer to the instance of object that will receive the notifications.
pt2Func	A pointer to the method in previous object that Lomse will invoke when an event is generated in Lomse.

See How Lomse callbacks work.

For example, to prepare our application for handling visual tracking events during score playback we could define a callback method:

class MyApp
{
public:
    //callback wrapper
    static void wrapper_for_lomse_event_handler(void* pThis, SpEventInfo pEvent)
    {
        static_cast<MyApp*>(pThis)->on_lomse_event(pEvent);
    }
    ...
protected:
    void on_lomse_event(SpEventInfo pEvent);
    ...
};

And inform lomse about it. We do it at lomse initialization:

void MyApp::initialize_lomse()
{
    //initialize the library
    ...
    m_lomse.init_library(pixel_format, resolution, reverse_y_axis);
    //set callbacks
    m_lomse.set_notify_callback(this, wrapper_for_lomse_event_handler);
    ...
}

◆ set_request_callback()

void LomseDoorway::set_request_callback	(	void *	pThis,
		void()(void , Request *)	pt2Func
	)

This method is used by for informing Lomse about the callback method that Lomse should invoke when having to request information to your application. See Request, RequestDynamic, RequestFont

Parameters

pThis	A pointer to the instance of object that will receive the notifications.
pt2Func	A pointer to the method in previous object that Lomse will invoke when a requests is generated in Lomse.

See How Lomse callbacks work for an explanation of Lomse callbacks and its parameters.

For example:

class MyApp
{
public:
    //requests wrapper
    static void wrapper_for_lomse_requests(void* pThis, Request* pRequests)
    {
        static_cast<MyApp*>(pThis)->on_lomse_request(pRequest);
    }
    ...
protected:
    void on_lomse_request(Request* pRequest);
    ...
};

And inform lomse about it. We do it at lomse initialization:

void MyApp::initialize_lomse()
{
    //initialize the library
    ...
    m_lomse.init_library(pixel_format, resolution, reverse_y_axis);
    //set callbacks
    m_lomse.set_request_callback(this, wrapper_for_lomse_requests);
    ...
}

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ LomseDoorway()

Member Function Documentation

◆ get_build_date()

◆ get_library_scope()

◆ get_musicxml_options()

◆ get_pixel_format()

◆ get_screen_ppi()

◆ get_version_long_string()

◆ get_version_major()

◆ get_version_minor()

◆ get_version_patch()

◆ get_version_string()

◆ init_library()

◆ new_document() [1/2]

◆ new_document() [2/2]

◆ open_document() [1/2]

◆ open_document() [2/2]

◆ set_default_fonts_path()

◆ set_global_metronome_and_replace_local()

◆ set_notify_callback()

◆ set_request_callback()