CPeerCtrl Class Reference

Encapsulates an assignment to a single parameter. More...

#include <peerctrl.h>

List of all members.

Public Member Functions
Initialisation
	CPeerCtrl ()
	Constructor suitable for creating instances before mi::Init() (eg as members of your mi class).
	CPeerCtrl (CMachine *pmac, CMachineInterface *pmi)
	Constructor suitable for creating instances within or after mi::Init().
	~CPeerCtrl ()
	Destructor.
void	Init (CMachine *pmac, CMachineInterface *pmi)
	Initialise this instance.
void	SetLabel (const std::string &label)
	Set a human-readable label for this CPeerCtrl instance.
void	SetLabel (const char *label)
	As SetLabel(const std::string&), but takes a null-terminated C string.
void	SetLabelAsTrackNumber (int t)
	Set the label (see SetLabel()) to a string of the form "Track %i", where i is replaced by the integer t.
Song file data
void	ReadFileData (CMachineDataInput *const pi)
	Read settings from the song file.
void	PushFileData (const char *macname, int paramnum, int group)
	Give CPeerCtrl some data to treat as if it was read by ReadFileData().
void	WriteFileData (CMachineDataOutput *const po, bool backwardsCompatible=false)
	Write settings to the song file.
Setting assignments
void	AssignParameter (CMachine *pMachine, int group, int param, int track=TRACK_DEFAULT)
	Set the current assignment.
void	UnassignParameter ()
	Clear the current assignment.
Getting assignments
CMachine *	GetMachine ()
	Get the current target machine.
char const *	GetMachineName ()
	Get the name of the current target machine.
CMachineInfo const *	GetMInfo ()
	Get the info struct for the current target machine.
CMachineParameter const *	GetParamInfo ()
	Get the info struct for the current target parameter.
char const *	GetParamString ()
	Get a string describing the current target parameter.
char const *	GetAssignmentString ()
	Get a string describing the current target machine and parameter.
int	GetParamNumber_Grouped ()
	Get the currently assigned parameter number, with the first track parameter being number 0.
int	GetParamNumber_Ungrouped ()
	Get the currently assigned parameter number, with the first track parameter numbered one greater than the last global parameter.
int	GetGroup ()
	Get the group of the currently assigned parameter.
bool	GotParam ()
	Check whether we have a current assignment.
Control changes
void	ControlChange_NextTick (int track, int value)
	Send a parameter change on the next tick.
void	ControlChange_NextTick (int value)
	As ControlChange_NextTick(int,int), but with TRACK_DEFAULT as the track number.
void	ControlChange_Immediate (int track, int value)
	Send a parameter change "immediately".
void	ControlChange_Immediate (int value)
	As ControlChange_Immediate(int,int), but with TRACK_DEFAULT as the track number.
Notifications
virtual void	onChangeAssignment ()
	Override this to do something when assignment settings change.
GUI helper functions
int	GetMachineNamesToCombo (HWND hWnd, int ComboID, const char *ExcludeName)
	Populate a combo box with machine names.
int	GetParamNamesToList (CMachine *pmac, HWND hWnd, int ListID, int TypesAllowed)
	Populate a list box with parameter names.
int	GetParamNamesToCombo (CMachine *pmac, HWND hWnd, int ComboID, int TypesAllowed)
	Like GetParamNamesToList(), but for populating a combo box.
bool	SelectMachineInCombo (HWND hWnd, int ComboID)
	Select the currently assigned machine in a combo box previously populated by GetMachineNamesToCombo().
bool	SelectParameterInList (HWND hWnd, int ListID)
	Select the currently assigned parameter in a combo box previously populated by GetParamNamesToList().
bool	SelectParameterInCombo (HWND hWnd, int ComboID)
	Like SelectParameterInList(), but for a combo box.
void	AssignParameter (char *MacName, char *ParaName, int track=TRACK_DEFAULT)
	Set the current assignment, based on strings previously written into dialog items with GetMachineNamesToCombo() and GetParamNamesToList() or GetParamNamesToCombo().
Static Public Member Functions
Event handlers
static bool	OnAddMachine (CMachine *pmac)
	You must call this as a handler for the gAddMachine event.
static bool	OnDeleteMachine (CMachine *pmac)
	You must call this as a handler for the gDeleteMachine event.
static void	SetEventHandlers (CMICallbacks *pCB, int which=ALL_EVENT_HANDLERS)
	Set OnAddMachine() and OnDeleteMachine() as handlers for the appropriate events, by calling CMICallbacks::SetEventHandler.
Control change batching
static void	BeginImmediateBatch ()
	Enter batch mode for "immediate" control changes.
static void	EndImmediateBatch ()
	Exit batch mode for "immediate" control changes.
PAL
static void	ShowPAL ()
	Show the GUI for BTDSys Peer Assignment List.

---

Detailed Description

Encapsulates an assignment to a single parameter.

Definition at line 130 of file peerctrl.h.

---

Constructor & Destructor Documentation

CPeerCtrl::CPeerCtrl

(

)

Constructor suitable for creating instances before mi::Init() (eg as members of your mi class).

If you use this form, you must remember to call Init() before using this instance.

CPeerCtrl::CPeerCtrl	(	CMachine *	pmac,
		CMachineInterface *	pmi
	)

Constructor suitable for creating instances within or after mi::Init().

This form calls Init() for you.

Parameters:

	pmac	Your machine's CMachine pointer (obtained by pCB->GetThisMachine()).
	pmi	You machine's CMachineInterface pointer.

---

Member Function Documentation

static bool CPeerCtrl::OnAddMachine

(

CMachine *

pmac

)

[static]

You must call this as a handler for the gAddMachine event.

During song loading, if your peer machine loads before the target machine, we use OnAddMachine() to watch for the target machine being loaded.

Parameters:

pmac

The added machine.

Returns:

true

See also:

SetEventHandlers()

static bool CPeerCtrl::OnDeleteMachine

(

CMachine *

pmac

)

[static]

You must call this as a handler for the gDeleteMachine event.

It unassigns CPeerCtrl instances when their target machines are deleted.

Parameters:

pmac

The deleted machine.

Returns:

true

See also:

SetEventHandlers()

static void CPeerCtrl::SetEventHandlers	(	CMICallbacks *	pCB,
		int	which = ALL_EVENT_HANDLERS
	)			[static]

Set OnAddMachine() and OnDeleteMachine() as handlers for the appropriate events, by calling CMICallbacks::SetEventHandler.

In most cases, you can just call SetEventHandlers() in Init or MDKInit and forget about event handlers from that point on. If you need to do your own handling of those events, make sure you call OnAddMachine() and OnDeleteMachine() from your own handlers as appropriate.

Parameters:

	pCB	Your peer machine's pCB member.
	which	Which event handlers to set. "Or" together one or more of EVENT_HANDLER_ADD, EVENT_HANDLER_DELETE, and EVENT_HANDLER_RENAME.

void CPeerCtrl::Init	(	CMachine *	pmac,
		CMachineInterface *	pmi
	)

Initialise this instance.

Call this if and only if you use the CPeerCtrl() constructor.

Parameters:

	pmac	Your machine's CMachine pointer (obtained by pCB->GetThisMachine()).
	pmi	You machine's CMachineInterface pointer.

void CPeerCtrl::SetLabel

(

const std::string &

label

)

Set a human-readable label for this CPeerCtrl instance.

This label will be shown in PAL, for example. For a typical peer machine with one CPeerCtrl per track, the label will be a string of the form "Track %i" where i is the track number; such a label can easily be set with SetLabelAsTrackNumber().

void CPeerCtrl::SetLabel

(

const char *

label

)

As SetLabel(const std::string&), but takes a null-terminated C string.

The string is copied, so you may safely overwrite it or free it after calling this function.

void CPeerCtrl::SetLabelAsTrackNumber

(

int

t

)

Set the label (see SetLabel()) to a string of the form "Track %i", where i is replaced by the integer t.

void CPeerCtrl::ReadFileData

(

CMachineDataInput *const

pi

)

Read settings from the song file.

Call this in your mi::Init() function.

Parameters:

pi

The data input object

See also:

WriteFileData()

void CPeerCtrl::PushFileData	(	const char *	macname,
		int	paramnum,
		int	group
	)

Give CPeerCtrl some data to treat as if it was read by ReadFileData().

This is intended for porting old peer machines to PeerLib, and should not be used in new machines.

Parameters:

	macname	The target machine name, or NULL if not assigned.
	paramnum	The parameter number, as returned by GetParamNumber_Grouped().
	group	The parameter group (GROUP_GLOBAL or GROUP_TRACK).

See also:

GetMachineName(), GetParamNumber_Grouped(), GetGroup()

void CPeerCtrl::WriteFileData	(	CMachineDataOutput *const	po,
		bool	backwardsCompatible = false
	)

Write settings to the song file.

Call this in your mi::Save() function.

Parameters:

	po	The data output object
	backwardsCompatible	Set to true to write file data compatible with version 1 of the library. In particular, assigned track numbers will not be saved. This is mainly for old machines, which presumably take care of their own track number assignments.

See also:

ReadFileData()

void CPeerCtrl::AssignParameter	(	CMachine *	pMachine,
		int	group,
		int	param,
		int	track = TRACK_DEFAULT
	)

Set the current assignment.

Parameters:

	pMachine	The target machine.
	group	The group of the target parameter (one of GROUP_GLOBAL, GROUP_TRACK or GROUP_ATTRIBUTE).
	param	The number of the target parameter, in the format described for GetParamNumber_Ungrouped().
	track	The target track number. Can be omitted.

See also:

UnassignParameter

void CPeerCtrl::UnassignParameter

(

)

Clear the current assignment.

See also:

AssignParameter(CMachine*, int, int, int)

char const* CPeerCtrl::GetAssignmentString

(

)

Get a string describing the current target machine and parameter.

Typically this string is displayed in the machine's context menu and assignment dialog.

int CPeerCtrl::GetParamNumber_Grouped

(

)

Get the currently assigned parameter number, with the first track parameter being number 0.

This is the format used by CMICallbacks::ControlChange, for example, and is also the format expected by AssignParameter(CMachine*, int, int, int).

Returns:

The parameter number, or -1 if no parameter is assigned.

See also:

GetParamNumber_Ungrouped

int CPeerCtrl::GetParamNumber_Ungrouped

(

)

Get the currently assigned parameter number, with the first track parameter numbered one greater than the last global parameter.

This is the format used by CMachineInterface::DescribeValue, for example.

Returns:

The parameter number, or -1 if no parameter is assigned.

See also:

GetParamNumber_Grouped

bool CPeerCtrl::GotParam

(

)

Check whether we have a current assignment.

Returns:

true if there is a current assignment, otherwise false.

static void CPeerCtrl::BeginImmediateBatch

(

)

[static]

Enter batch mode for "immediate" control changes.

After calling this function, calls to ControlChange_Immediate() will not take effect until the next call to EndImmediateBatch(). CMachineInterface::Tick() will only be called once per target machine; for example, this might be used to ensure that the target machine receives the note and the velocity at the same time.

CPeerCtrl::BeginImmediateBatch();
for (int t=0; t<numTracks; t++)
{
        track[t]->peerNote->ControlChange_Immediate(track[t]->notenum);
        track[t]->peerVelo->ControlChange_Immediate(track[t]->velocity);
}
CPeerCtrl::EndImmediateBatch();

See also:

EndImmediateBatch()

static void CPeerCtrl::EndImmediateBatch

(

)

[static]

Exit batch mode for "immediate" control changes.

See BeginImmediateBatch() for details.

void CPeerCtrl::ControlChange_NextTick	(	int	track,
		int	value
	)

Send a parameter change on the next tick.

Now that Buzz can do immediate control changes natively, this function is not as useful as it once was. In fact it is deprecated, and is only available if you add PEERLIB_NEXTTICK to your project's C++ preprocessor definition list (Project properties -> C/C++ -> Preprocessor -> Preprocessor Definitions in VC++2005).

Referenced by ControlChange_NextTick().

virtual void CPeerCtrl::onChangeAssignment

(

)

[inline, virtual]

Override this to do something when assignment settings change.

This includes when the target machine is found during song loading, which, depending on the order in which Buzz initialises the machines, may not happen immediately upon calling ReadFileData() but may instead happen in OnAddMachine().

Definition at line 341 of file peerctrl.h.

int CPeerCtrl::GetMachineNamesToCombo	(	HWND	hWnd,
		int	ComboID,
		const char *	ExcludeName
	)

Populate a combo box with machine names.

Parameters:

	hWnd	The handle of your dialog window.
	ComboID	The dialog item ID of your combo box.
	ExcludeName	A machine name to exclude from the list. Typically used to prevent a peer machine from controlling itself.

Returns:

The number of combo box items added.

int CPeerCtrl::GetParamNamesToList	(	CMachine *	pmac,
		HWND	hWnd,
		int	ListID,
		int	TypesAllowed
	)

Populate a list box with parameter names.

Parameters:

	pmac	The machine whose parameters to list.
	hWnd	The handle of your dialog window.
	ListID	The dialog item ID of your list box.
	TypesAllowed	Any combination of the ALLOW_ constants.

Returns:

The number of list items added.

bool CPeerCtrl::SelectMachineInCombo	(	HWND	hWnd,
		int	ComboID
	)

Select the currently assigned machine in a combo box previously populated by GetMachineNamesToCombo().

Parameters:

	hWnd	The handle of your dialog window.
	ComboID	The dialog item ID of your combo box.

bool CPeerCtrl::SelectParameterInList	(	HWND	hWnd,
		int	ListID
	)

Select the currently assigned parameter in a combo box previously populated by GetParamNamesToList().

Parameters:

	hWnd	The handle of your dialog window.
	ListID	The dialog item ID of your list box.

void CPeerCtrl::AssignParameter	(	char *	MacName,
		char *	ParaName,
		int	track = TRACK_DEFAULT
	)

Set the current assignment, based on strings previously written into dialog items with GetMachineNamesToCombo() and GetParamNamesToList() or GetParamNamesToCombo().

Parameters:

	MacName	The machine name string.
	ParaName	The parameter name string.
	track	The track number, or TRACK_DEFAULT to assign to no particular track.

static void CPeerCtrl::ShowPAL

(

)

[static]

Show the GUI for BTDSys Peer Assignment List.

---

The documentation for this class was generated from the following file:

• peerctrl.h