DSSI support libraries: DSSIUIClient Class Reference

List of all members.


Public Member Functions
	DSSIUIClient (int argc, char **argv)
	This constructor starts an OSC receiver thread and sets up all OSC callbacks.
	~DSSIUIClient ()
	This destructor will mark any allocated shared memory for destruction, send an /exiting message to the plugin host, and stop and deallocate the OSC receiver thread.
bool	is_valid () const
	Returns `true` if the initialisation went OK and we haven't received a /quit message yet.
const string &	get_identifier () const
	Returns the identifier string given by the plugin host.
void	connect_adjustment (Adjustment *adj, int port)
	Connects a Gtk::Adjustment to a DSSI port.
void	send_control (int port, float value)
	Sends the control value `value` to input port number `port` in the plugin.
void	send_program (int bank, int program)
	Change the plugin's program.
void	send_update_request ()
	Tell the host that we want an update of all the controls, program and configuration values for the plugin.
void	send_configure (const string &key, const string &value)
	Send a configuration value to the plugin.
void	send_midi (const char event[4])
	Send a MIDI event to the plugin.
void	send_exiting ()
	Tell the plugin host that the GUI is about to quit (you shouldn't have to call this explicitly, it is called when this DSSIUIClient object is destroyed).
void *	allocate_shared_memory (int bytes)
	This function allocates a segment of shared memory and tells the plugin about it using a configure() call.
template<class T>
T *	create_shared_object ()
	This function uses allocate_shared_memory() to allocate enough shared memory for an object of type `T` and then run the placement `new` operator to initialise it.
bool	plugin_has_attached ()
	Returns true if the plugin has attached to the shared memory segment.
Public Attributes
signal< void, int, float >	control_received
	This signal is emitted when the host sends a new control value.
signal< void, int, int >	program_received
	Emitted when the host sends a program change.
signal< void, const string, const string >	configure_received
	Emitted when the host sends a configuration value.
Dispatcher	show_received
	Emitted when the host wants the UI to be visible.
Dispatcher	hide_received
	Emitted when the host wants to hide the UI.
Dispatcher	quit_received
	Emitted when the host wants the UI to exit.
signal< void >	plugin_attached
	Emitted when the plugin has attached to the shared memory segment.

Detailed Description

It has public functions for all the messages that the UI can send to the host, and public signals for all the messages that the host can send to the UI, which will be emitted when a message is received. It also handles some of the required communication with the host, such as sending an /exiting message when the DSSIUIClient object is destroyed. It also has a function that will handle all the nastyness involved in setting up a shared memory segment that the plugin and the UI can use to communicate messages that are not specified by DSSI.

#include <gtkmm.h>
#include "dssiuiclient.hpp"

using namespace sigc;
using namespace Gtk;

int main(int argc, char** argv) {
  
  // create a client that will talk to the DSSI host
  DSSIUIClient dssi(argc, argv);
  
  // initialise gtkmm
  Main kit(argc, argv);
  
  // create the GUI
  Window win;
  HScale scale(0, 1, 0.001);
  scale.set_size_request(200, -1);
  win.add(scale);
  
  // connect signals
  dssi.connect_adjustment(scale.get_adjustment(), 1);
  dssi.show_received.connect(mem_fun(win, &Window::show_all));
  dssi.hide_received.connect(mem_fun(win, &Window::hide));
  dssi.quit_received.connect(&Main::quit);
  win.signal_delete_event().connect(bind_return(hide(&Main::quit), true));
  
  // tell the host to send us data, then start the main loop
  dssi.send_update_request();
  kit.run();
  
  return 0;
}

If the above code is compiled and linked with dssiuiclient.cpp and liblo and gtkmm, the result will be a fully functional DSSI UI.

The function connect_adjustment() connects a Gtk::Adjustment to a DSSI control port. In the example above the Adjustment object belonging to the HScale widget is connected to DSSI port 1, which means that whenever the user moves the scale control messages will be sent to the DSSI host with the new value for port 1, and whenever the host sends an update for port 1, the scale widget will move to reflect the new value.

Constructor & Destructor Documentation

DSSIUIClient::DSSIUIClient	(	int	argc,
		char **	argv
	)

This constructor starts an OSC receiver thread and sets up all OSC callbacks.

Since you probably want to connect signals and slots before the host starts sending you data, this function will not send an update request to the host. You will have to do that yourself using send_update_request().

The parameters argc and argv should be the arguments given to your main() function - the DSSI host uses them to pass information.

DSSIUIClient::~DSSIUIClient

(

)

This destructor will mark any allocated shared memory for destruction, send an /exiting message to the plugin host, and stop and deallocate the OSC receiver thread.

Member Function Documentation

void * DSSIUIClient::allocate_shared_memory

(

int

bytes

)

This function allocates a segment of shared memory and tells the plugin about it using a configure() call.

The plugin should use dssi_shm_attach() to attach to the shared memory segment - this function handles all the nasty problems that can arise if the host decides to save the configure() message and send it again later, or send it to another instance of the plugin. This function can only be used once during the lifetime of this DSSIUIClient object, if you try to use it a second time it will simply return NULL. If you need to allocate more memory segments after the first one you can use the normal shm functions (see the man page for shm_get(2)) and send the segment IDs directly to the plugin using a ringbuffer in the initial shared segment (for example). The memory segment allocated using this function will be marked for deallocation when this DSSIUIClient object is destroyed. The segment won't actually be deallocated until the plugin detaches from it.

void DSSIUIClient::connect_adjustment	(	Adjustment *	adj,
		int	port
	)

Connects a Gtk::Adjustment to a DSSI port.

The Adjustment object will be updated when /control messages are received for that port, and /control messages will be sent to the host when the value of the Adjustment object changes.

template<class T>
T* DSSIUIClient::create_shared_object	(		)	`[inline]`

This function uses allocate_shared_memory() to allocate enough shared memory for an object of type T and then run the placement new operator to initialise it.

Your type T must have a default constructor, if it doesn't you will get a compilation error.

const string & DSSIUIClient::get_identifier

(

)

const

Returns the identifier string given by the plugin host.

bool DSSIUIClient::is_valid

(

)

const

Returns true if the initialisation went OK and we haven't received a /quit message yet.

bool DSSIUIClient::plugin_has_attached

(

)

Returns true if the plugin has attached to the shared memory segment.

void DSSIUIClient::send_configure	(	const string &	key,
		const string &	value
	)

Send a configuration value to the plugin.

void DSSIUIClient::send_control	(	int	port,
		float	value
	)

Sends the control value value to input port number port in the plugin.

void DSSIUIClient::send_exiting

(

)

Tell the plugin host that the GUI is about to quit (you shouldn't have to call this explicitly, it is called when this DSSIUIClient object is destroyed).

void DSSIUIClient::send_midi

(

const char

event[4]

)

Send a MIDI event to the plugin.

The effect will be exactly the same as if it had been sent by the plugin host.

void DSSIUIClient::send_program	(	int	bank,
		int	program
	)

Change the plugin's program.

void DSSIUIClient::send_update_request

(

)

Tell the host that we want an update of all the controls, program and configuration values for the plugin.

This is called automatically when this DSSIUIClient object is created unless the wait parameter to the constructor is true.

Member Data Documentation

signal<void, const string, const string> DSSIUIClient::configure_received

Emitted when the host sends a configuration value.

The parameters are the configuration key and the configuration value.

signal<void, int, float> DSSIUIClient::control_received

This signal is emitted when the host sends a new control value.

The parameters are the control port number and the new control value.

signal<void, int, int> DSSIUIClient::program_received

Emitted when the host sends a program change.

The parameters are the bank and program numbers.

Dispatcher DSSIUIClient::quit_received

Emitted when the host wants the UI to exit.

This DSSIUIClient object will not send or receive any OSC messages after it has received this message, but you still have to quit the program yourself.

Dispatcher DSSIUIClient::show_received

Emitted when the host wants the UI to be visible.

A DSSI GUI should not show any windows until this signal is emitted.

DSSIUIClient Class Reference

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation