EventVisualTracking Class Reference

#include <lomse_events.h>

Inheritance diagram for EventVisualTracking:

Detailed Description

An event to signal different actions related to visual tracking effects during score playback.

Warning

This event is sent to your application from the Lomse sound thread. For processing it, do not retain control: generate an application event, place it on the application events loop, and return control to Lomse.

The EventVisualTracking event, derived from EventPlayback, signals the need to do several actions related to visual tracking effects during score playback. It contains a list of sub-events and affected objects:

• k_highlight_on. Add highlight to a note/rest.
• k_highlight_off. Remove highlight from a note/rest.
• k_end_of_visual_tracking. End of score playback. Remove all visual tracking effects.
• k_move_tempo_line. Advance visual tempo line to next beat.

For handling all events related to score playback it is very important to return control to Lomse as soon as possible. This is because, currently, Lomse does not implement an event subsystem with its own thread. Instead Lomse sends events to your application by invoking a callback. This implies that your application code for handling the event is processed by the Lomse sound thread. As this thread is dealing with sound generation, your application must return control to Lomse as soon as possible, so that the sound thread can continue processing sound events. Otherwise, sound can be stalled! The suggested way for handling EventVisualTracking events is to generate an application event and to enqueue it in the application events system.

For instance, in an application written using the wxWidgets framework you could have a global method for receiving all Lomse events, convert them in application events, and return control to Lomse:

void MainFrame::on_lomse_event(SpEventInfo pEvent)
{
    DocumentWindow* pCanvas = get_active_document_window();

    switch (pEvent->get_event_type())
    {
        case k_tracking_event:
        {
            if (pCanvas)
            {
                //generate visual tracking event
                SpEventVisualTracking pEv(
                    static_pointer_cast<EventVisualTracking>(pEvent) );
                MyVisualTrackingEvent event(pEv);
                ::wxPostEvent(pCanvas, event);
            }
            break;
        }
    ...

Later, your application will just process the application event as convenient. The recommended action is to use the Interactor for requesting to process the event and update the rendering bitmap. For instance:

void DocumentWindow::on_visual_tracking(MyVisualTrackingEvent& event)
{
    SpEventVisualTracking pEv = event.get_lomse_event();
    WpInteractor wpInteractor = pEv->get_interactor();
    if (SpInteractor sp = wpInteractor.lock())
        sp->on_visual_tracking(pEv);
}

Public Types
enum	ETrackingEvent

Public Member Functions
	EventVisualTracking (WpInteractor wpInteractor, ImoId nScoreID)
	EventVisualTracking (const EventVisualTracking &event)
ImoId	get_score_id ()
int	get_num_items ()
std::list< pair< int, ImoId > > &	get_items ()
TimeUnits	get_timepos ()
Public Member Functions inherited from EventPlayback
virtual	~EventPlayback ()
WpInteractor	get_interactor ()
Public Member Functions inherited from EventInfo
virtual	~EventInfo ()
virtual Observable *	get_source ()
EEventType	get_event_type ()
bool	is_doc_modified_event ()
bool	is_update_window_event ()
bool	is_mouse_in_event ()
bool	is_mouse_out_event ()
bool	is_on_click_event ()
bool	is_link_clicked_event ()
bool	is_show_contextual_menu_event ()
bool	is_control_point_moved_event ()
bool	is_selection_set_change ()
bool	is_pointed_object_change ()
bool	is_do_play_score_event ()
bool	is_pause_score_event ()
bool	is_stop_playback_event ()
bool	is_tracking_event ()
bool	is_update_viewport_event ()
bool	is_end_of_playback_event ()

Member Enumeration Documentation

ETrackingEvent

enum EventVisualTracking::ETrackingEvent

Values for sub-events.

Enumerator
k_highlight_on	add highlight to a note/rest
k_highlight_off	remove highlight from a note/rest
k_end_of_visual_tracking	end of score playback. Remove all visual tracking effects. ///< end of score play back. Remove all highlight.
k_move_tempo_line	advance visual tempo line to next beat

Constructor & Destructor Documentation

EventVisualTracking() [1/2]

EventVisualTracking::EventVisualTracking ( WpInteractor  wpInteractor, ImoId  nScoreID  )

inline

Constructor.

EventVisualTracking() [2/2]

EventVisualTracking::EventVisualTracking ( const EventVisualTracking &  event )

inline

Copy constructor.

Member Function Documentation

get_items()

std::list< pair<int, ImoId> >& EventVisualTracking::get_items ( )

inline

Returns the list of notes & rests affected by the event. Each list item is a pair of two values: the sub-event type (from enum ETrackingEvent), and the ID of the object (note / rest) to highlight or un-highlight.

get_num_items()

int EventVisualTracking::get_num_items ( )

inline

Returns the number of sub-events.

get_score_id()

ImoId EventVisualTracking::get_score_id ( )

inline

Returns ID of the score affected by the event.

get_timepos()

TimeUnits EventVisualTracking::get_timepos ( )

inline

Returns the time position for the tempo line sub-event.