Type specific messages

Some of the messages are accepted only by specific components. This section describes the messages associated to specific objects types.

Brush control

Brush styles

brushStyle message is accepted by the following components: rect ellipse polygon curve layer.

• brushStyle controls the brush style (see figure brushstyle).

The brush style default value is solid. For the layer object, the brush style default value is none.

Example Setting a rectangle style :

/ITL/scene/rect set rect 0.5 0.5 ;
/ITL/scene/rect brushStyle dense4; 

Width and height control

width and height messages are accepted by the almost all components except textual components (see section textscore).

• 1: a single float value express the dimension in the inscore coordinate system.
• 2: a float value suffixed with sw or sh express a dimension relative to the actual scene dimension. sw stands for 'scene width' and sh for 'scene height'. Such dimension dynamically adjusted to any change in the scene dimension.

Example

/ITL/scene/myObject width 1;   #  using the inscore coordinate system 
/ITL/scene/myObject width 0.9sw;       #  using the scene width 

Note: Querying the width and height of any object is always supported, provided that the object has been graphically rendered.

Symbolic score

The following messages are accepted by the components types gmn | gmnstream | gmnf.

• page: set the score current page
• dpage: moves the score current page
• pageFormat: set the page format. The parameters are the page width and height. Note that the message has no effect when the score already includes a \pageformat tag.
• columns: for multi pages display: set the number of columns.
• rows: for multi pages display: set the number of rows.
• pageCount: a read only attribute, gives the score pages count.
• systemCount: a read only attribute, gives the number of systems on each of the score pages. The result is given as a list systems count ordered by page number (index 0 is page 1, etc.).

Example Displaying a multi-pages score on two pages starting at page 3:

/ITL/scene/myScore columns 2 ;
/ITL/scene/myScore page 3 ;

• write: add the gmn code to the current gmn stream
• clear: reinitialize the stream

Example Writing a score in 3 steps:

/ITL/scene/myScore set gmnstream "[ c"; 
/ITL/scene/myScore write " d e";
/ITL/scene/myScore write " f]";

Piano roll

The following messages are accepted by the components types pianoroll | pianorollstream | pianorollf.

• keyboard: display the keyboard on left of piano roll. Default value to 0.
• autoVoicesColoration: enable voices automatic coloration. If voiceColor is used for a voice, automatic voices coloration do nothing for it. Default value to 0.
• measureBars: Display measure bars on piano roll. Default value to 0.
• voiceColor: set a color to a voice. The parameters are voice number (start to 1), and RGBA color (See section colormsg). If not color is present, voice color is reset to default color. If voice number and color are not present, reset all voices to default color.
• pitchLines: Display pitch lines on pianoroll. Parameters are a note list in english notation (A A# B ...) with case insensitive. Default to all lines. An 'empty' note (i.e. the litteral 'empty' string) can be used to hide all lines.
• clipTime: set time limits for piano roll (See section time to set a time). The two times have to be wrote in the same format. If no time is present, time limits are reset to default.
• clipPitch: Set pitch limits to piano roll. The pitch is in midi format. If no value is present, pitch limits are reset to default.

Example Set a color on voice 2 with transparency and display C and F pitch lines:

/ITL/scene/myPianoroll voiceColor 2 154 234 45 100;
/ITL/scene/myPianoroll pitchLines 'C' 'F';

Removes the pitch lines:

/ITL/scene/myPianoroll pitchLines empty;

Piano roll streams support the same messages than Guido streams:

• write: add the gmn code to the current gmn stream
• clear: reinitialize the stream

Example Writing a pianoroll in 3 steps:

/ITL/scene/myPianoroll set pianorollstream "[ c"; 
/ITL/scene/myPianoroll write " d e";
/ITL/scene/myPianoroll write " f]";

Audio and Video

Media objects (audio video) have their own internal time and duration that is independent from the INScore time and duration. This time is controlled using specific messages.

• play start or stop playing the media. Default value is 0.
• volume sets the audio volume. Default and maximum value is 1.
• rate sets the media playing rate. Default value is 1.

• vdate sets the current video frame or audio position. Default value is 0. Arguments are the following:

• 1) : a value in milliseconds.

• 2) : a musical time expressed as a rational. Note that musical time is converted to milliseconds using a tempo value of 60.
• 3) : a musical time expressed as a float.

A media position may be updated while the media is playing.

Media objects support also specific queries:

• mls gives the media absolute duration in milliseconds.
• vduration gives the media duration in musical time. The returned value is a rational computed using the current rate, according to a tempo value of 60.

A media object supports specific events (see section typespecevents for more details).

Example Playing a video at half speed:

/ITL/scene/video set video "Video.mp4"; 
/ITL/scene/video rate 0.5;
/ITL/scene/video play 1";

Note: Depending on the video encoding and on the platform renderer, setting the video current position using the vdate message may be aligned to key frames.

Supported audio and video formats are highly dependent on the platform, as well as media specific features (e.g. setting the playing rate that may or may not be supported, or may behave differently).

SVG Objects

The following message is accepted by the SVG components (types svg | svgf).

• animate: start or stop the svg animation (provided the SVG is animated). The parameter is a boolean value (default is 0).
• animated: a get parameter only: returns whether the svg is animated or not.

Note: SVG objects are rendered using the Qt SVG Renderer and suffer the Qt limitations. For example and with Qt 5.5, xlinks are not supported.

Rectangles

Rectangles (type rect) accept a radius message that can be used to draw rounded rectangles.

• radius: followed by 2 values that specify the radius on the x and y axis (default is 0 0). The values express a percentage of the object dimensions, thus the value's range is [0, 100].

Arcs

Arcs are portions of ellipses. Although an arc is specified by it's set message, it supports additional messages to control the start angles and the arc extension individually. An additional close message affects the drawing of the arc.

• start: set the start angle of the arc.
• range: set the arc extension in degrees counter-clockwise.
• dstart: move the start angle of the arc from the value given as parameter.
• drange: move the arc range from the value given as parameter.
• close: by default, only the curve of an arc is drawn. When the close attribute is set, lines from the arc borders to the center of the ellipse are also drawn. The close parameter is read as a boolean value.

Angles are in degrees and express counter-clockwise directions.

The 'grid' object

The grid object provides a pre-defined time to graphic mapping organized in columns and row. By default, it is not visible (white, transparent) but supports all the attributes of rectangles (color, pen, effects, etc.). Each element of a grid has a duration that is computed as the grid duration divided by the total number of elements ( columns x rows) and is placed in the time space from the date 0 to the end of the grid duration.

• columns set the number of columns of the grid,
• rows set the number of rows of the grid,
• xborder set the horizontal spacing between the elements of the grid (default is 0.),
• yborder set the vertical spacing between the elements of the grid (default is 0.),
• order defines the time order of the elements. By default, elements are organized from left to right first and from top to bottom next (leftright). The topbottom parameter changes this order from top to bottom first and from left to right next.

Example Creating a 10 x 10 grid organized from top to bottom with a border:

/ITL/scene/grid set grid 10 10 ;
/ITL/scene/grid xborder 3. ;
/ITL/scene/grid yborder 3. ;
/ITL/scene/grid order topbottom ;

Arrows

Specific arrows message is accepted by the component type line. It add capability to draw arrow heads to the begining and the end of a line object.

• arrowStyleBegin Set the arrow head of the begining of the line.
• arrowStyleEnd Set the arrow head of the end of the line.

The arrow style default value is none.

Textual objects

Font control

Specific font messages are accepted by txt html txtf and htmlf components.

• fontSize controls the font size in pixel. The default value is 13px.
• fontFamily controls the font family. The default value is 'Arial'. If a non existing value is used, system default font is used.
• fontStyle controls the pen style. The font style default value is normal.
• weightValue controls the font weight. The font weight default value is normal.

Example Setting a text object with a font family Times and bold weight:

/ITL/scene/text set txt "text sample";
/ITL/scene/text fontFamily Times;
/ITL/scene/text fontWeight bold;  

Writing

Textual objects support writing in a stream-like way.

• write: append the arg list formatted as a string to the textual content.

Example

/ITL/scene/text set txt "Hello";
/ITL/scene/text write "world!";

Getting the text

A specific text query is provided to get the textual content.

Example

/ITL/scene/text get text;

The 'debug' nodes

Each component includes a static debug nodes provided to give information about components.

• map is used to display the time to graphic mapping. The parameter is a int value: 0 prevents mapping display, 1 displays only the bounding boxes and 2 displays also the dates along with the boxes. Default is 0 (no map).
• name is used to display both the object name and bounding box. The parameter is a boolean value. Default is 0.