COM Objects > TracksBoard object > Methods > TracksBoard.ControlIconAdd method

Remarks

Adds a new two states control icon to the Tracksboard by taking its bitmaps from two bitmap handles (HBITMAP): once added, each control icon is immediately positioned on the left amplitude vertical ruler for each of the available tracks; for this reason the bVisibleLeft field of the TRACKSBOARD_RULERS_SETTINGS data structure must be set to BOOL_TRUE.

Each control icon can have two bitmaps representing two different situations; on the screenshot below, taken from the TracksBoard sample project available with the installer, two control icons are added, one providing the possibility to mute / unmute the track and the other one providing the possibility to lock / unlock the track; by default each track is in "unmute" status and in "unlock" status (status 1); when in status 1 the tooltip text represents what will happen after clicking the control icon with the mouse: once clicked, the bitmap will show the "mute" status (status 2) and the tooltip text will show that, by clicking the control again, the track will be brought back to the "unmute" status (status 1).

This is obviously a simple usage of control icons, you may decide to use these control icons for any purpose you may have.

When one of the control icons is clicked, the TracksBoardControlPressed event is raised.

The vertical and horizontal alignment of control icons can be modified through the TracksBoard.ControlIconsAlignmentSet method.

For details about the use of the TracksBoard refer to the How to use the TracksBoard to visually compose songs tutorial.

For further details about methods of the TracksBoard refer to the TracksBoard object section.

Syntax

[Visual Basic]

control.TracksBoard.ControlIconAdd (

nUniqueId as Long,

hIconStatus1 as OLE_HANDLE,

strTextStatus1 as String,

hIconStatus2 as OLE_HANDLE,

strTextStatus2 as String,

nReserved as Integer

) as enumErrorCodes

[C++]

short control.TracksBoard.ControlIconAdd (

long *nUniqueId,

OLE_HANDLE hIconStatus1,

LPCTSTR strTextStatus1,

OLE_HANDLE hIconStatus2,

LPCTSTR strTextStatus2,

short nReserved

);

Parameter	Description

nUniqueId	Reference to a value that, on return from the method call, will contain the unique identifier of the newly added control icon: this unique identifier will be passed to the TracksBoardControlPressed event when the control icon is clicked.
hIconStatus1	Handle (HBITMAP) of the picture for status 1: when no more needed this handle will be destroyed by the control.
strTextStatus1	String to display on the tooltip when the mouse is hovering the control icon in its status 1.
hIconStatus2	Handle (HBITMAP) of the picture for the status 2: when no more needed this handle will be destroyed by the control.
strTextStatus2	String to display on the tooltip when the mouse is hovering the control icon in its status 2.
nReserved	Reserved for future uses.

Return value

Value	Meaning

Negative value	An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0)	The method call was successful.