Introduction

Copyright © 2013-2015 MultiMedia Soft

Introduction

 Return to chapter overview

Musical Instrument Digital Interface (MIDI) is a technical standard that describes a protocol, digital interface and connectors and allows a wide variety of electronic musical instruments, computers and other related devices to connect and communicate with one another.

Active MIDI DJ Console for .NET is a .NET class developed by MultiMedia Soft that makes it easy to add support for managing MIDI input and output devices and commercial DJ Consoles to multimedia applications written with Microsoft Visual Studio.

MIDI is nothing more than data containing a list of events or messages that tell an electronic device (musical instrument, computer sound card, etc.) how to generate a certain sound or how to react to a certain operation request: Active MIDI DJ Console for .NET allows opening communication between connected external electronic devices and the PC running the container application.

Once communication is opened, Active MIDI DJ Console for .NET allows receiving MIDI data from the input channel connected to the external MIDI device and notifying MIDI data reception to the container application; as you may understand the communication between the external MIDI device and this component is obviously bidirectional so the control allows sending MIDI data, through short MIDI messages or through raw MIDI messages (also known as SysEx messages), to the output channel connected to the external MIDI device.

If there should be the need to send any MIDI message incoming from an external MIDI device in output to another external MIDI device, Active MIDI DJ Console for .NET could be used as a sort of bridge or repeater, allowing direct communication between the two external MIDI devices.

Thanks to the mentioned bidirectional communication, Active MIDI DJ Console for .NET can easily manage input/output of MIDI data with commercial DJ Consoles available on the market. As you may know, each MIDI DJ Console comes with its own set of MIDI commands for notifying that a button control has been pushed or that a slider control has been moved or that a rotary knob control has been rotated on the physical console; at the same time, each MIDI DJ Console comes with its own set of MIDI commands for switching a led on or off or for displaying a string of characters on one or more display segments (VFD) available on the physical console.

Due to the fact that each DJ console, also when coming from the same vendor/manufacturer, may use a different set of MIDI commands, Active MIDI DJ Console for .NET comes with a set of methods allowing to create, edit and modify profiles (also known as maps) for each of the connected DJ consoles: in this way the container application could virtually connect to any model of DJ console by allowing the final user to create his own profiles or by loading profiles created by other users.

As a further feature, Active MIDI DJ Console for .NET allows creating a graphical virtual piano keyboard which may be used to display notes played on a connected physical MIDI piano keyboard and generating MIDI notes to send to an output MIDI device or synthesizer installed inside the system.

The component is fully UNICODE compliant so can support languages using the double-byte convention.

Many tutorials are available to help you beginning your development with this powerful control.

Supported target systems

· Windows XP (x86 and x64 versions)
· Windows Server 2003 (x86 and x64 versions)
· Windows Vista (x86 and x64 versions)
· Windows Server 2008 (x86 and x64 versions)
· Windows 7 (x86 and x64 versions)
· Windows 8 (x86 and x64 versions)
· Windows 10 (x86 and x64 versions)

Supported .NET frameworks

· NET Framework 2.0
· NET Framework 3.0
· NET Framework 3.5 ("Client profile" not supported)
· NET Framework 4.0 ("Client profile" not supported)
· NET Framework 4.5
· NET Framework 4.6

IMPORTANT NOTES:

For redistribution of the control with your application, we recommend you to take a close look to the Files to be included with your application section.


Copyright information

Copyright information

© Copyright MultiMedia Soft 2013-2014. ALL RIGHTS RESERVED

MultiMedia Soft product specifications are subject to change without notice.

Trademarks

Active MIDI DJ Console for .NET is a registered trademark of MultiMedia Soft.

Audio Waveform Analyzer for .NET is a registered trademark of MultiMedia Soft.

Audio DJ Studio for .NET is a registered trademark of MultiMedia Soft.

Windows, ActiveX, .NET Framework, Visual C#, Visual Basic and Visual Studio.NET are registered trademarks of the Microsoft Corporation.

All other brand or product names used in this online help are trademarks of their respective holders.


License agreement

License agreement

PLEASE READ THE FOLLOWING LICENSE AGREEMENT. IT WILL BE NECESSARY FOR YOU TO AGREE TO BE BOUND BY THE TERMS OF THIS AGREEMENT BEFORE BEING PERMITTED TO CONTINUE TO USE THE PRODUCT.

VERY IMPORTANT-CAREFULLY READ : This MultiMedia Soft License Agreement (hereinafter "LICENSE") is a legal agreement between you (either an individual or a single entity) and MultiMedia Soft, for the "Active MIDI DJ Console for .NET" component (hereinafter " SOFTWARE ").

By installing, copying or otherwise using the SOFTWARE, you agree to be bound by the terms of this LICENSE. If you do not agree to the terms of this LICENSE, you cannot use this SOFTWARE for any purposes.

The SOFTWARE is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The SOFTWARE is licensed, not sold.

I.        LICENSE GRANT for "COMMERCIAL EDITION". This LICENSE grants you the following rights:

A. The SOFTWARE's license is "PER DEVELOPER": this means that one single software developer may use this SOFTWARE on one or more computers until no other developers have access to the computer in order to develop the application that will contain the SOFTWARE. The SOFTWARE is in "use" on a computer when it is loaded into temporary memory (i.e. RAM) or installed into permanent memory (e.g. hard disk, CD-ROM, or other storage device) of that computer. However, installation on a network server for the sole purpose of internal distribution to one or more other computer(s) shall not constitute "use" for which a separate license is required.

B. Solely with respect to electronic documents included with the SOFTWARE, you may make a copy (either in hardcopy or electronic form), provided that the number of copies made shall not exceed the number of licenses you own for that SOFTWARE, and further provided that such copies shall be used only for internal purposes and are not republished or distributed to any third party.

C. You may use the trial versions of the SOFTWARE for the limited purposes of demonstrations and trials.

II.        Deprecated.

III.        TITLE; COPYRIGHT. All title and copyrights in and to the SOFTWARE (including but not limited to any images, photographs, animation, video, audio, music and text incorporated into the SOFTWARE), and any copies of the SOFTWARE are owned by MultiMedia Soft. The SOFTWARE is protected by copyright laws and international treaty provisions. Therefore, you must treat the SOFTWARE like any other copyrighted material, except that you may either (A) make one copy of the SOFTWARE solely for backup or archival purposes or (B) install the SOFTWARE on a single computer provided you keep the original solely for backup or archival purposes.

IV.        ADDITIONAL RIGHTS AND LIMITATIONS.

A. Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer, decompile, or disassemble the SOFTWARE.

B. No Separation of Components. The SOFTWARE is licensed as a single product and the software programs comprising the SOFTWARE may not be separated for use by more than one user at a time.

C. Rental. You may not rent or lease the SOFTWARE.

D. Software Transfer. You may NOT transfer any of your rights under this LICENSE without written permission by MultiMedia Soft. With the "PERSONAL EDITION" no license transfer is allowed.

E. Temporary LICENSE Transfer for outsourcing development purposes. You may transfer your LICENSE to another developer for the amount of time requested to complete the outsourced development: the transfer must be requested to MultiMedia Soft and, in any case, You are not allowed to request more than one transfer to outsourced developers. With the "PERSONAL EDITION" no license transfer is allowed.

F. Termination. Without prejudice to any other rights, MultiMedia Soft may terminate this LICENSE if you fail to comply with the terms and conditions of this LICENSE. In such event, you must destroy all copies of the SOFTWARE.

V.        REDISTRIBUTABLE COMPONENTS.

A. Sample Code. In addition to the license granted in Section 1, MultiMedia Soft grants you the right to use and modify the source code versions of those portions of the SOFTWARE which are identified in the documentation as the Sample Code and located in the \SAMPLES(xx) subdirectory(s) of the SOFTWARE provided you comply with section 4.c.

B. Redistributable Code. In addition to the license granted in Section 1, MultiMedia Soft grants you a nonexclusive, royalty-free right to reproduce and distribute the object code version of those portions of the SOFTWARE designated in the SOFTWARE as (i) those portions of the SOFTWARE which are identified in the documentation as the OCX ("OCX") Control; (ii) those portions of the SOFTWARE which are identified in the documentation as REDISTRIBUTABLE DLLs ("DLLs"); and (iii) SAMPLE CODE (collectively, "REDISTRIBUTABLES"), provided you comply with Section 4.c.

C. Redistribution Requirements. If you redistribute the REDISTRIBUTABLES, you agree to (i) distribute the REDISTRIBUTABLES in object code form only in conjunction with and as part of your software application product which adds significant and primary functionality and which is designed, developed, and tested to operate in the Microsoft Windows and/or Windows NT environments; (ii) not use MultiMedia Soft's name, logo or trademarks to market your software application product; (iii) include a valid copyright notice on your SOFTWARE; (iv) indemnify, hold harmless, and defend MultiMedia Soft from and against any claims or lawsuits, including attorney's fees, that arise or result from the use and distribution of your software application product; and (v) not permit further distribution of the REDISTRIBUTABLES by your end user.

LIMITED WARRANTY. EXCEPT WITH RESPECT TO REDISTRIBUTABLES, WHICH ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, MULTIMEDIA SOFT WARRANTS THAT THE SOFTWARE WILL PERFORM SUBSTANTIALLY IN ACCORDANCE WITH THE ACCOMPANYING ONLINE HELP MATERIALS.

NO OTHER WARRANTIES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, MULTIMEDIA SOFT DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH REGARD TO THE SOFTWARE. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS, WHICH VARY FROM STATE/JURISDICTION TO STATE/JURISDICTION.

NO LIABILITIES FOR CONSEQUENTIAL DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL MULTIMEDIA SOFT BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF MULTIMEDIA SOFT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES AND JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.

LICENSEE ACKNOWLEDGES THAT IT HAS READ AND UNDERSTANDS THIS AGREEMENT AND AGREES TO BE BOUND BY ITS TERMS. LICENSEE FURTHER AGREES THAT THIS AGREEMENT IS THE COMPLETE AND EXCLUSIVE STATEMENT OF THE AGREEMENT BETWEEN LICENSEE AND LICENSOR, AND SUPERCEDES ANY PROPOSAL OR PRIOR AGREEMENT, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS RELATING TO THE SUBJECT MATER OF THIS AGREEMENT.


Files to be included with your application

Files to be included with your application

Important note about installed version

This section of the documentation applies to the full purchased version only: the trial version of the component comes with an internal protection schema against fraudulent uses which will block most functionalities when the component is redistributed outside of the development machine where the trial version was originally installed through the provided setup program.

Files that you need to redistribute with your application depend upon the platform target:

· If compiling for "Any CPU"

- the class assembly

ActiveDjConsoleNetApi.dll if your application was targeted for .NET framework 2.0, 3.0 or 3.5 and the reference to ActiveDjConsoleNetApi was used inside the project

ActiveDjConsoleNetApiF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to ActiveDjConsoleNetApiF4 was used inside the project

- the x86 version of the engine DjConsMmsEng.DLL

- the x64 version of the engine DjConsMmsEng64.DLL

· If compiling specifically for x86

- the class assembly

ActiveDjConsoleNetApi.dll if your application was targeted for .NET framework 2.0, 3.0 or 3.5 and the reference to ActiveDjConsoleNetApi was used inside the project

ActiveDjConsoleNetApiF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to ActiveDjConsoleNetApiF4 was used inside the project

- the x86 version of the engine DjConsMmsEng.DLL

· If compiling specifically for x64

- the class assembly

ActiveDjConsoleNetApi.dll if your application was targeted for .NET framework 2.0, 3.0 or 3.5 and the reference to ActiveDjConsoleNetApi was used inside the project

ActiveDjConsoleNetApiF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to ActiveDjConsoleNetApiF4 was used inside the project

- x64 version of the engine DjConsMmsEng64.DLL

You can find redistributable files mentioned above inside the folder in which you installed Active MIDI DJ Console for .NET (default "C:\Program Files\Active MIDI DJ Console for .NET\Redist").

Important note about the folder chosen for installing our files

In order to avoid the "DLL Hell" problem, it's strongly recommended that you install the mentioned files into the same folder in which you will install the EXE of your container application on the target system and not inside the Windows\System32 or Windows\SysWOW64 folders.

How to create a "ClickOnce" setup containing our component using Visual Studio .NET

· Inside the "Solution Explorer" open "References"
· Locate and select the reference to ActiveDjConsoleNetApi
· Inside the "Properties" window locate the "Copy Local" property and set it to "True"

· Inside the "Solution Explorer" right-click the project name
· From the context menu select "Add\Existing Item..."
· Inside the "Objects of type" combobox select "Executable files"
· Locate the directory where DjConsMmsEng.dll and DjConsMmsEng64.dll are installed (by default should be under "C:\Program Files\Active MIDI DJ Console for .NET\Redist")
· Select DjConsMmsEng.dll and DjConsMmsEng64.dll and press the "Add" button
· for both of them change the "Copy to Output Directory" property to "Copy always"
· Rebuild the ClickOnce package


Product history

Product history

Version 1.1.0.0

New features

· Added a version of the component specifically compiled against .NET framework 4


How to contact MultiMedia Soft

How to contact MultiMedia Soft

Apart from the quality of our products, one of our strongest points is a superior customer support: we always answer technical questions, sent through our Contact us web page, within the first 24 hours also on Saturday and on Sunday.

Through our web site

Contact page

http://www.multimediasoft.com/contact/

Forum

http://www.multimediasoft.com/forum

Through Postal address:

MultiMedia Soft

Strada Pelizzina 21

10081 Castellamonte (TO)

Italy

Through Telephone:

+39 0124 640005 Number provided for Italian speaking only: in order to avoid language misunderstandings, no phone support is available in languages different from Italian so, in order to submit your questions in English, please, fill the form provided on our contact page or, in alternative, use our forum.

Through Fax:

+39 0124 233112758

+39 02 700433430


How to report bugs to our technical support

How to report bugs to our technical support

If you should experience problems using the control, you are encouraged to contact our customer support specifying the following topics:

· Operating system (Windows XP, Vista, 7, etc.) and version; if using a Windows NT based system (like Windows 2000 and Windows XP), specify which Service Pack has been installed.
· Name, Release and Version of the programming environment (e.g. Visual Studio.NET 2008).
· Eventually, create a log file generated by the Microsoft's DxDiag.exe application and send it to us for evaluation.
· If possible, prepare a little project that reproduces the problem on your system: being able to reproduce the problem on our systems will speed up the problem solution.
· An accurate description of the steps to reproduce the issue.

We will try to solve the problem as soon as possible and, if required, we will inform you when the fixed control will be available.


Tutorials

Tutorials

How to install the component on your development PC

Adding the component to a Visual Studio project

How to use the control in your projects

How to synchronize the container application with the control

How to manage MIDI devices

How to manage MIDI DJ consoles

How to manage the virtual MIDI piano keyboard

How to use enumerated types


How to install the component on your development PC

How to install the component on your development PC

This product has been developed for usage with versions of Visual Studio 2005 or higher and requires the availability of .NET Framework version 2.0 or higher.

In order to install this product on your system, follow the steps listed below:

· Be sure to exit any application currently running on your system.
· Launch the downloaded adjconsnet_f.exe (adjconsnet_t.exe for the trial version) file and follow contained instructions.
· Once the setup package has installed all the needed files, it will automatically register our component inside the Global Assembly Cache.
· From now on you will be able to add the component to your .NET based projects. For details about inserting the component into a Visual Studio project, take a look to the Adding the component to a Visual Studio project section.


Adding the component to a Visual Studio project

Adding the API to a Visual Studio project

Find below required steps:

· Open the project you are working on
· Inside the "Solution Explorer" right-click the mouse button on the "References" item
· From the context menu select the "Add reference..." menu item; this will open the "Add reference" dialog box.
· Select the ".NET" tab
· On the list of installed components find the component named "Active MIDI DJ Console for .NET" as displayed below

· As you can see there are two versions of the component: the one with assembly name "ActiveDjConsoleNetApiF4.dll" is intended for usage with container applications targeted for .NET framework 4 or higher while the one with assembly name "ActiveDjConsoleNetApi.dll" is intended for usage with container applications targeted for .NET framework 2.0, 3.0 or 3.5 so you may decide which of the two version best fits your needs.
· Pressing the "OK" button will bring you again to your project working area and the References item of the Solution Explorer will appear like this:

· You can now start developing your code around the control as described inside the How to use the component in your projects section

IMPORTANT NOTE ABOUT THE TARGETED .NET FRAMEWORK INSIDE VISUAL STUDIO 2010

When a new application is created from scratch through the Visual Studio 2010 wizard, by default the targeted .NET framework is set to ".NET framework 4 Client Profile": this version of the .NET framework is a subset of the .NET framework 4 and one of its main limitations is the fact that you cannot reference an assembly that is not in the ".NET Framework 4 Client Profile" so, in order to be able compiling the application referencing one of our components, assuming that the project name is "MyApp", you will have to perform following steps:

· Select the "Project/MyApp Properties..." menu item
· Inside the "Application" tab, locate the "Target framework" combobox
· Set the ".NET framework 4" option in place of the ".NET framework 4 Client Profile" option
· Close the properties window
· Compile the application


How to use the component in your projects

How to use the component in your projects

First of all let us say that if this guide should not be clear to you, feel free to contact our support team for any doubt or curiosity you may have: we usually answer all of our customers questions in less than 24 hours. Note that the purpose of this guide is to give a taste of the main features available inside Active MIDI DJ Console for .NET.

As an integration to this guide, a certain number of examples of use of this component can be found inside the "Samples" folder: if during the setup phase you left the installation directory to its default, you will find them inside "C:\Program Files\Active MIDI DJ Console for .NET\Samples".

The first needed step is to add the component's reference to your project: see the Adding the component to a Visual Studio project section for details.

At this point we need to create a new instance of the component's class and, before starting MIDI management, to initialize the component: for this purpose it's mandatory a call to the Init method. The code snippet below shows how to perform instancing and initialization of the component inside a Winform application:

Visual Basic .NET

Imports Microsoft.VisualBasic

Imports System

Imports System.Collections.Generic

Imports System.ComponentModel

Imports System.Data

Imports System.Drawing

Imports System.Text

Imports System.Windows.Forms

// import the component's namespace

Imports ActiveDjConsoleNetApi

Namespace ProfileEditor

Public Partial Class FormMain

Inherits Form

Public Sub New()

InitializeComponent()

End Sub

' instance the component

Dim m_djConsole As ActiveDjConsoleNetApi.ActiveDjConsoleNetApi = New ActiveDjConsoleNetApi.ActiveDjConsoleNetApi()

Private Sub FormMain_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load

' initialize the component

m_djConsole.Init()

' do other stuffs with the component

...

End Sub

Private Sub FormMain_FormClosing(ByVal sender As Object, ByVal e As FormClosingEventArgs) Handles MyBase.FormClosing

' dispose the component

m_djConsole.Dispose()

End Sub

End Class

End Namespace

Visual C#

using System;

using System.Collections.Generic;

using System.ComponentModel;

using System.Data;

using System.Drawing;

using System.Text;

using System.Windows.Forms;

// add the component's namespace

using ActiveDjConsoleNetApi;

namespace ProfileEditor

{

public partial class FormMain : Form

{

public FormMain()

{

InitializeComponent();

}

// instance the component

ActiveDjConsoleNetApi.ActiveDjConsoleNetApi m_djConsole = new ActiveDjConsoleNetApi.ActiveDjConsoleNetApi();

private void FormMain_Load(object sender, EventArgs e)

{

// initialize the component

m_djConsole.Init();

// do other stuffs with the component

...

}

private void FormMain_FormClosing(object sender, FormClosingEventArgs e)

{

// dispose the component

m_djConsole.Dispose();

}

}

}

IMPORTANT: Before exiting the container application, in order to avoid memory leaks, it's recommended that you explicitly call the Dispose method of the component.

After having initialized the component, we can start adding the code needed for interfacing with physical and virtual MIDI devices connected and/or installed inside the system and leveraging the control's main fields of competency:

· Receiving/sending standard and raw MIDI commands from/to the connected MIDI input/output devices: see the How to manage MIDI devices tutorial for details.
· Managing interaction of the container application with connected MIDI DJ Consoles through mapping profiles: see the How to manage MIDI DJ consoles tutorial for details.
· Managing the user interface of the embedded virtual MIDI piano keyboard: see the How to manage the virtual MIDI piano keyboard tutorial for details.


How to synchronize the container application with the control

How to synchronize the container application with the control

 Return to chapter overview

In order to allow managing feedback coming from the component's code to the container application code, Active MIDI DJ Console for .NET gives the possibility to setup a certain number of callback delegates that inform about events occurring between the component and external MIDI devices; the list of supported events is available on the table below:

Situations | Corresponding callback delegate | Method for initializing the delegate
The configuration of MIDI devices is changed | CallbackMidiDevicesConfigChanged | CallbackMidiDevicesConfigChangedSet
A MIDI device, previously opened through the MidiDevices.Open method, is disconnected from the system after a manual removal | CallbackMidiDevicesOpenRemoved | CallbackMidiDevicesOpenRemovedSet
A short MIDI event is received from a MIDI input device | CallbackMidiDevicesEventShortReceived | CallbackMidiDevicesEventShortReceivedSet
A raw MIDI event is received from a MIDI input device | CallbackMidiDevicesEventRawReceived | CallbackMidiDevicesEventRawReceivedSet
A physical button mapped into the DJ Console profile has been pressed | CallbackMidiDjConsoleEventButtonPressed | CallbackMidiDjConsoleEventButtonPressedSet
A physical button mapped into the DJ Console profile has been released. | CallbackMidiDjConsoleEventButtonReleased | CallbackMidiDjConsoleEventButtonReleasedSet
A physical range control (sliders, jog wheels, rotary knobs, etc.) mapped into the DJ Console profile has been moved | CallbackMidiDjConsoleEventRangeMoved | CallbackMidiDjConsoleEventRangeMovedSet
A manual action (for example the pressing of a button, the movement of a slider or of a jog wheel) is performed on a console's physical control which has not been mapped into the DJ Console profile loaded inside the instance of the component or when the reception of events specific for mapped controls has been disabled through a call to the MidiDjConsole.EnableMappedEvents method. | CallbackMidiDjConsoleEventUnmapped | CallbackMidiDjConsoleEventUnmappedSet
One of the keys on the virtual piano keyboard, previously created through the MidiVirtualKeyboard.Create method, is pressed or released | CallbackMidiKeyboardNotification | CallbackMidiKeyboardNotificationSet

Events monitoring is performed inside secondary working threads of the component so, when a delegate is needed to update user interface elements of your application, for example changing the status of a checkbox or filling a combo box, the multi-threading situation must be considered: the relationship between threads and delegates is secondary threads cannot just call methods like the application's primary thread, so a function pointer is needed and delegates act as function pointers.

Let's see a couple of code snippets that clarify how a callback delegate can be instantiated and managed.

Visual Basic .NET

// import the component's namespace

Imports ActiveDjConsoleNetApi

Namespace ProfileEditor

Public Partial Class FormMain

Inherits Form

Public Sub New()

InitializeComponent()

End Sub

' instance the component

Dim m_djConsole As ActiveDjConsoleNetApi.ActiveDjConsoleNetApi = New ActiveDjConsoleNetApi.ActiveDjConsoleNetApi()

' predispose the delegate and the callback

Private Delegate Sub ConfigChangedCallbackDelegate(ByVal nChangeType As enumMidiDevicesConfigChanges, ByVal nUserData As Int32)

Private addrCallbackMidiDevicesConfigChanged As CallbackMidiDevicesConfigChanged

' the subroutine that manages the callback

Private Sub MidiDevicesConfigChangedCallback(ByVal nChangeType As enumMidiDevicesConfigChanges, ByVal nUserData As Int32)

' check if we are being invoked from a secondary thread

If Me.InvokeRequired Then

' this callback is being called from a secondary thread so, in order to access eventual controls on the form, we must

' call Invoke using this same function as a delegate

Me.Invoke(New ConfigChangedCallbackDelegate(AddressOf MidiDevicesConfigChangedCallback), nChangeType, nUserData)

Return

End If

' display a debug message about the occurred event

System.Diagnostics.Debug.WriteLine("MidiDevicesConfigChanged: " & nChangeType.ToString())

' we can now safely access controls on the user interface

...

End Sub

Private Sub PredisposeCallbacks()

' predispose the callback that will notify about a change within the configuration of MIDI devices

addrCallbackMidiDevicesConfigChanged = New CallbackMidiDevicesConfigChanged(AddressOf MidiDevicesConfigChangedCallback)

m_djConsole.CallbackMidiDevicesConfigChangedSet(addrCallbackMidiDevicesConfigChanged, 0)

End Sub

Private Sub FormMain_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load

' initialize the component

m_djConsole.Init()

' predispose the callbacks

PredisposeCallbacks()

End Sub

End Class

End Namespace

Visual C#

// add the component's namespace

using ActiveDjConsoleNetApi;

namespace ProfileEditor

{

public partial class FormMain : Form

{

public FormMain()

{

InitializeComponent();

}

// instance the component

ActiveDjConsoleNetApi.ActiveDjConsoleNetApi m_djConsole = new ActiveDjConsoleNetApi.ActiveDjConsoleNetApi();

// predispose the delegate and the callback

delegate void ConfigChangedCallbackDelegate(enumMidiDevicesConfigChanges nChangeType, Int32 nUserData);

CallbackMidiDevicesConfigChanged addrCallbackMidiDevicesConfigChanged;

// the function that manages the callback

void MidiDevicesConfigChangedCallback(enumMidiDevicesConfigChanges nChangeType, Int32 nUserData)

{

// check if we are being invoked from a secondary thread

if (this.InvokeRequired)

{

// this callback is being called from a secondary thread so, in order to access controls on the form, we must

// call Invoke using this same function as a delegate

this.Invoke(new ConfigChangedCallbackDelegate(MidiDevicesConfigChangedCallback), nChangeType, nUserData);

return;

}

// display a debug message about the occurred event

System.Diagnostics.Debug.WriteLine("MidiDevicesConfigChanged: " + nChangeType.ToString());

// we can now safely access controls on the user interface

...

}

private void PredisposeCallbacks()

{

// predispose the callback that will notify about a change within the configuration of MIDI devices

addrCallbackMidiDevicesConfigChanged = new CallbackMidiDevicesConfigChanged(MidiDevicesConfigChangedCallback);

m_djConsole.CallbackMidiDevicesConfigChangedSet(addrCallbackMidiDevicesConfigChanged, 0);

}

private void FormMain_Load(object sender, EventArgs e)

{

// initialize the component

m_djConsole.Init();

// predispose the callbacks

PredisposeCallbacks()

}

}

}

IMPORTANT NOTE ABOUT DELEGATES AND THEIR SCOPE: When an instance of a callback delegate is passed to one of the API functions, the delegate object is not reference counted. This means that the .NET framework would not know that it might still being used by the API so the Garbage Collector might remove the delegate instance if the variable holding the delegate is not declared as global. As a general rule, make sure to always keep your delegate instance in a variable which lives as long as the API needs it by using a global variable or member.


How to manage MIDI devices

How to manage MIDI devices

Active MIDI DJ Console for .NET, through the MidiDevices property which encapsulates functionalities of the ClassMidiDevices class, can separately enumerate MIDI input and output devices installed inside the system through the MidiDevices.CountGet method. After completing the enumeration, information about each device can be obtained through the MidiDevices.InfoGet method.

Enumeration of MIDI devices is not automatically updated when a new MIDI device is connected or disconnected from the system but the container application is immediately informed about the change through the CallbackMidiDevicesConfigChanged delegate. After receiving this event, the container application can reset the current configuration through the MidiDevices.Reset method, allowing an updated enumeration when invoking again the MidiDevices.CountGet and MidiDevices.InfoGet methods.

The container application can establish communication with MIDI devices connected to the system in three ways:

· input only, for example when the connected device is a MIDI keyboard sending keystrokes to the application through MIDI events.
· output only, for example when the connected device is a synthesizer which needs to convert a MIDI event, like a "note on" or a "note off", into an audible sound.
· both input and output, for example when the connected device is a DJ Console sending MIDI events to notify the application about a button being pushed or a slider being moved and receiving MIDI events when there is the need to switch a led on or off.

The component can establish communication with a MIDI device through the MidiDevices.Open method; if the MIDI device works as both an input and an output device there is the need to perform two calls to the MidiDevices.Open method: a first one for the input device and a second one for the output device. Each call to the MidiDevices.Open method returns a unique identifier of the opened device and this identifier will be used for accessing the device itself through other existing methods: for example, the unique identifier is used when there is the need to obtain information about the opened device through the MidiDevices.InfoGetByUniqueId method or when there is the need to close the communication with the device through the MidiDevices.Close method; if the MIDI device was opened in both input and output modes, through two separate calls to the MidiDevices.Open method, there will be the need to close the device through two separate calls to the MidiDevices.Close method.

You can verify if communication with a certain input or output device is currently opened or closed through the MidiDevices.IsOpened method.

After the connection with a MIDI device has been opened, if the related physical MIDI device should be disconnected from the system the container application would be notified through the CallbackMidiDevicesOpenRemoved delegate.

Management of input devices

When an input MIDI device is opened, the component stays tuned in order to catch any incoming MIDI event sent by the external MIDI device: when an incoming MIDI event is detected, the component notifies the container application through one of the following callback delegates:

· the CallbackMidiDevicesEventShortReceived delegate for short MIDI events like "note on", "note off", "control change" and many others. If the container application shouldn't be interested in receiving notifications about each different type of incoming short MIDI event, it could set a filter through the MidiDevices.InputEventFilterSet method.
· the CallbackMidiDevicesEventRawReceived delegate for raw MIDI events (also known as "SysEx").

Both types of MIDI events are "time-stamped", meaning that each event is marked with a value expressed in milliseconds reporting the time elapsed from the moment in which the MIDI input device was opened through the call to the MidiDevices.Open method.

Management of output devices

When an output MIDI device is opened, the component can send it MIDI events. As seen for input devices, outgoing MIDI events can be short or raw MIDI events:

· the MidiDevices.EventWriteShort method allows sending short MIDI events like "note on", "note off", "control change" and others.
· the MidiDevices.EventWriteRaw method allows sending raw MIDI events

Direct communication between input and output MIDI devices

When the container application doesn't need a direct processing of incoming MIDI events, for example when an external MIDI keyboard needs to send MIDI notes to an external synthesizer that will produce the corresponding audible sound, it can work as a sort of bridge and establish a direct connection between the input MIDI device (the MIDI keyboard) and the output MIDI device (the synthesizer) by routing all of the incoming MIDI events to the output MIDI device: this communication can be established through the MidiDevices.InputOutputConnect method and interrupted at a later time through the MidiDevices.InputOutputDisconnect method.

Samples of usage of MIDI devices can be found inside the various Visual Basic.NET and Visual C# projects installed with the component's setup package:

- ProfileEditor

- MidiMonitor

- PianoKeyboard


How to manage MIDI DJ consoles

How to manage MIDI DJ consoles

Active MIDI DJ Console for .NET, through the MidiDjConsole property which encapsulates functionalities of the ClassMidiDjConsole class, can interface with external MIDI DJ Consoles and Controllers by receiving MIDI events from the console and by sending MIDI commands to the console itself.

Connecting the MIDI DJ Console

The connection between the console and the component can be started in two steps:

· opening the input and output MIDI devices of the console through respective calls to the MidiDevices.Open method: each call will generate the unique identifiers of the corresponding device.
· connecting the console to the component by providing the unique identifiers of the input and output devices to the MidiDjConsole.Connect method.

The the console and the component can be disconnected at a later time in two steps:

· disconnecting the console from the component through the MidiDjConsole.Disconnect method
· closing the input and output MIDI devices of the console through respective calls to the MidiDevices.Close method.

At any time you can know if a connection is established through the MidiDjConsole.IsConnected method.

Profiling the MIDI DJ Console

As you may know, each MIDI DJ Console comes with its own set of MIDI commands for notifying that a button control has been pushed or that a slider control has been moved or that a rotary knob control has been rotated on the physical console; at the same time, each MIDI DJ Console comes with its own set of MIDI commands for switching a led on or off or for displaying numbers on one or more VFD (Vacuum Fluorescent Display) available on the physical console.

Due to the fact that each DJ console, also when coming from the same vendor/manufacturer, may use a different set of MIDI commands, Active MIDI DJ Console for .NET comes with a set of methods allowing to create, edit and modify profiles (also known as maps) for each of the connected DJ consoles: in this way the container application could virtually connect to any model of DJ console by allowing the final user to create his own profiles or by loading profiles created by other users.

Each instance of the control can manage one single profile so, in case the container application should need to manage at the same time multiple connections to DJ consoles connected to the system, there would be the need to allocate more instances of the control.

When the single instance of the control is initialized, an empty profile is immediately available for usage so there is no need to create a new one: in case a profile should have already been programmatically filled with items or loaded from a file, it could be emptied through the MidiDjConsole.ProfileReset method.

A profile contains the following elements which allow identifying the MIDI DJ Console for which the profile was written:

· the "friendly" name of the MIDI DJ console which can be obtained/modified through the MidiDjConsole.ProfileInfoStringGet and MidiDjConsole.ProfileInfoStringSet methods having the nStringType parameter set to PROF_INFO_STRING_DEVICE_NAME

· the product's identifier (also known as "PID") and the vendor's identifier (also known as "VID" or "MID") of the console. These two elements are read-only, can be obtained through the MidiDjConsole.ProfileInfoIdentifiersGet method and are saved automatically inside the profile's output XML file when saved to disk through the MidiDjConsole.ProfileSave method; in order to save the current profile which will be specific for a single model of DJ Console, the control needs that a connection with the physical MIDI DJ Console is established as mentioned on the section "Connecting the MIDI DJ Console" described above. When the saved XML file containing the profile will be loaded at a later time through the MidiDjConsole.ProfileLoad method, the control will verify that the connected console declares the same PID and VID and will return an error code if these fields should not match. In case the DJ console shouldn't be physically connected, you could in any case save the profile on a XML file on disk through the MidiDjConsole.ProfileSaveWithoutDevice method: profile's items will be save but the PID and VID identifiers will be obviously missing.

· the name of the profile which can be obtained/modified through the MidiDjConsole.ProfileInfoStringGet and MidiDjConsole.ProfileInfoStringSet methods having the nStringType parameter set to PROF_INFO_STRING_NAME

· the description of the profile which can be obtained/modified through the MidiDjConsole.ProfileInfoStringGet and MidiDjConsole.ProfileInfoStringSet methods having the nStringType parameter set to PROF_INFO_STRING_DESCRIPTION

· the author of the profile which can be obtained/modified through the MidiDjConsole.ProfileInfoStringGet and MidiDjConsole.ProfileInfoStringSet methods having the nStringType parameter set to PROF_INFO_STRING_AUTHOR

· an URL to a web site containing further information about the profile which can be obtained/modified through the MidiDjConsole.ProfileInfoStringGet and MidiDjConsole.ProfileInfoStringSet methods having the nStringType parameter set to PROF_INFO_STRING_URL

· a set of items describing each of the physical controls available on the MIDI DJ Console: each profiled item contains the type of item, the description and the MIDI event/command used to identify the physical control. See the "Items for console's physical controls" section below for details.

· if supported by the specific console, a set of displays (also known as VFD) describing each of the physical VFD available on the MIDI DJ Console. See the "Displays" section below for details.

Items for console's physical controls

A profile's item is identified through a string of characters containing its name: when developing a profile you have the possibility to define your own set of names but it's strongly recommended assigning to each item the same name contained inside the technical specifications of the MIDI DJ console. Profile's item can be:

· enumerated through the MidiDjConsole.ProfileItemCountGet method in conjunction with the MidiDjConsole.ProfileItemNameGet method
· added to the profile through the MidiDjConsole.ProfileItemAdd method
· modified through the MidiDjConsole.ProfileItemModify method
· removed from the profile through the MidiDjConsole.ProfileItemRemove method
· checked for presence through the MidiDjConsole.ProfileItemExistsByName method

Each item belongs to a specific type; supported types are:

· push button: this input control is a two states button (pressed / released) and you can be informed about manual actions happening on it through the CallbackMidiDjConsoleEventButtonPressed and CallbackMidiDjConsoleEventButtonReleased delegates. After having added the button to the profile through the MidiDjConsole.ProfileItemAdd method you can set the short MIDI command for this type of control through the MidiDjConsole.ProfileButtonMidiCommandSet method and obtain the current one through the MidiDjConsole.ProfileButtonMidiCommandGet method.

· push button with embedded led: mostly identical to the previous type of item and notified through the same delegates, this type of button differs from the previous one for the fact that it carries a led inside which can be switched on or off using exactly the same short MIDI command reported when the button is pressed or released. Most of times the MIDI event for indicating an action occurring on the button is a "note on" (hex 90) for button pressed and a "note off" (hex 80) for button released followed by the code identifying the specific button; when the embedded led can be switched on or off using exactly the same MIDI command then you can use this specific type of button: it's important to note that this condition is not mandatory so you are free to separate the push button from the led by using two different items inside the profile.

· range control: this type is again an input control and is used for physical controls which may assume a range of values (typically from 0 to 127) like sliders and rotary knobs and for other controls which may report values indicating a specific action, for example if a jog wheel has been rotated clockwise or anti-clockwise. A manual action happening on one of these controls will be notified through the CallbaclMidiDjConsoleEventRangeMoved delegate. After having added the control to the profile through the MidiDjConsole.ProfileItemAdd method you can set the short MIDI command for this type of control through the MidiDjConsole.ProfileRangeMidiCommandSet method and obtain the current one through the MidiDjConsole.ProfileRangeMidiCommandGet method.

· led control and VFD (Vacuum Fluorescent Display) led items: differently from previous types of controls which work has input controls, this ones work as an output control and identifies a led that can be switched on or off through the MidiDjConsole.ProfileLedSwitch method or that can be blinked at a specific rate through the MidiDjConsole.ProfileLedBlink method. After having added the control to the profile through the MidiDjConsole.ProfileItemAdd method you can set the short MIDI command for this type of control through the MidiDjConsole.ProfileLedMidiCommandSet method and obtain the current one through the MidiDjConsole.ProfileLedMidiCommandGet method.

· VFD (Vacuum Fluorescent Display) items not behaving as a simple led: differently from previous VFD led items, this ones work as an output control but not with a simple on/off status: to this category usually belong elements displaying numbers, for example the track number or the position of the track. After having added the control to the profile through the MidiDjConsole.ProfileItemAdd method you can set the short MIDI command for this type of control through the MidiDjConsole.ProfileDisplayMidiCommandSet method and obtain the current one through the MidiDjConsole.ProfileDisplayMidiCommandGet method. Data to display can be sent to the proper item through the MidiDjConsole.ProfileDisplayDataSet method.

In case a manual action should happen on a physical input control still not added to the profile, the container application would be in any case notified through the CallbackMidiDjConsoleEventUnmapped delegate. Under certain situations, for example inside an application that would allow the final user developing a new profile or modifying an existing one, you may have the need to get an unmapped event also for items already stored inside the profile; for example, if a specific button should be already mapped inside the profile, when pressing the button you would receive the CallbackMidiDjConsoleEventButtonPressed delegate but you would no more get the specific short MIDI command used to map the button; by disabling events for already mapped items you could get the CallbackMidiDjConsoleEventUnmapped delegate for all of the physical controls and, if needed, you may modify the item inside the profile accordingly: this can be done by disabling mapped events through the MidiDjConsole.EnableMappedEvents method. The "ProfileEditor" project available inside the samples works exactly like this.

For each item contained inside the profile you can obtain the specific type (push button, led, etc.) through the MidiDjConsole.ProfileItemTypeGet and other information through the MidiDjConsole.ProfileItemInfoStringGet method.

At the beginning of this section dedicated to profile's items, we have already seen that we can enumerate items stored inside the profile through the MidiDjConsole.ProfileItemCountGet method in conjunction with the MidiDjConsole.ProfileItemNameGet method: these methods don't make distinctions about the type of control to which the item belongs: if you should need enumerating a specific type of control, for example push buttons only, you may use the combination of MidiDjConsole.ProfileTypedItemCountGet and MidiDjConsole.ProfileTypedItemNameGet methods.

If you need to verify if a specific short MIDI command has already been assigned to a specific type of control, you can use one between the MidiDjConsole.ProfileButtonNameGetByMidiCommand method for push buttons (with or without embedded led), MidiDjConsole.ProfileRangeNameGetByMidiCommand method for range controls and MidiDjConsole.ProfileLedNameGetByMidiCommand method for led controls.

VFD display segments

As already mentioned before, displays are usually known as VFD (Vacuum Fluorescent Display) and may contain one or more segments having a certain number of variable characters (each segment allowing to display a word or a very short sentence) and a certain number of leds which may switch on/off a fixed word or character. The image below shows the VFD belonging to deck A of a Denon DN-HC4500 console.

VFD leds can be switched on/off or blinked by adding them inside the profile as described inside the "Items for console's physical controls" section above; management of VFD segments is a bit more complex and the possibility to display variable words using an embedded character set is quite difficult to profile; the number of manufacturers using this kind of display on some of their console models is quite limited so, for this reason, the component doesn't allow adding VFD segments to the profile but their management is embedded directly inside the control itself.

At the moment Active MIDI DJ Console for .NET comes with native support for displays of the Denon DN-HC4500 console only: other models may be added upon specific request by sending us the technical specifications of the console.

Displays segments can be enumerated through the MidiDjConsole.DisplaySegmentCountGet method in conjunction with the MidiDjConsole.DisplaySegmentInfoGet method; once enumerated you can show single characters or strings of characters using the following methods:

· the MidiDjConsole.ProfileDisplaySymbol method allows displaying a character's symbol inside a specific cell of the given segment.
· the MidiDjConsole.ProfileDisplayString method allows displaying a string of characters on the given segment
· the MidiDjConsole.ProfileDisplayStringScroll method allows scrolling a string of characters on the given segment

A sample of usage of MIDI DJ Consoles profiling and testing can be found inside the "ProfileEditor" Visual Basic.NET and Visual C# projects installed with the component's setup package.


How to manage the virtual MIDI piano keyboard

How to manage the virtual MIDI piano keyboard

Active MIDI DJ Console for .NET, through the MidiVirtualKeyboard property which encapsulates functionalities of the ClassMidiVirtualKeyboard class, implements a graphical gadget called "virtual MIDI piano keyboard" which allows playing notes by pressing the mouse over the available keys or to display notes being played by an external MIDI physical keyboard connected to the system.

The virtual piano keyboard can be displayed with three different orientations as seen on the screenshots below

Horizontal

Vertical left

Vertical right

and can have a variable number of keys with a maximum of 128.

The virtual piano keyboard can be instanced on the user interface of your application through the MidiVirtualKeyboard.Create method; as for all of the other windows control, the virtual piano keyboard can be moved and resized (MidiVirtualKeyboard.Move method), shown or hidden (MidiVirtualKeyboard.Show method), refreshed (MidiVirtualKeyboard.Refresh method) or destroyed (MidiVirtualKeyboard.Destroy method).

Once the virtual piano keyboard has been instanced, the user can establish a connection with an external input MIDI device through the MidiVirtualKeyboard.MidiInputConnect method and with an external output MIDI device through the MidiVirtualKeyboard.MidiOutputConnect method. Disconnection can be respectively managed at a later time through the MidiVirtualKeyboard.MidiInputDisconnect and MidiVirtualKeyboard.MidiOutputDisconnect methods.

Once the connection has been established, the virtual piano keyboard can start sending notes to an eventually connected output MIDI device by clicking keys through the left button of the mouse (but also through his fingers in case of availability of a touch screen) or by calling the MidiVirtualKeyboard.Note method. The container application can be informed when a specific key is pressed or released through the CallbackMidiKeyboardNotification delegate.

In case you should simply need to display on the virtual piano keyboard that a note was played through an external MIDI input device connected to the system, the MidiVirtualKeyboard.Note method allows simulating a key pressure without generating a clone of the same note that would be normally sent to an eventually connected output MIDI device: the purpose of its bSimulated parameter is exactly this.

The range of displayed keys can be modified at any time through the MidiVirtualKeyboard.RangeSet method and its graphical settings can be retrieved and modified through the MidiVirtualKeyboard.GraphicalSettingsGet and MidiVirtualKeyboard.GraphicalSettingsSet methods.

A sample of usage of the MIDI virtual piano keyboard profiling and testing can be found inside the "PianoKeyboard" Visual Basic.NET and Visual C# projects installed with the component's setup package.


How to use enumerated types

How to use enumerated types

The use of enumerated types improves the readability of your code and, thanks to the features offered by Microsoft's Intellisense, will ease the coding phase.

The following is the full list of enumerated types with their associated properties:

Enumerated type | Corresponding properties or parameters
enumDjcErrorCodes | LastError property and return value of most methods
enumDjcMidiKeyboardOrientations | MidiVirtualKeyboard.Create method
enumInfoStringType | MidiDevices.InfoGet and MidiDevices.InfoGetByUniqueId methods
enumMidiDevicesConfigChanges | MidiDevicesConfigChanged event
enumProfileInfoStringType | MidiDjConsole.ProfileInfoStringGet and MidiDjConsole.ProfileInfoStringSet methods
enumProfileItemInfoStringType | MidiDjConsole.ProfileItemInfoStringGet method
enumDjConsoleItemType | MidiDjConsole.ProfileItemAdd and MidiDjConsole.ProfileItemModify methods
enumInternalProfiles | MidiDjConsole.ProfileLoadInternal method

The following examples, under different development environments, show how to use enumerated types in your code.

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual Basic.NET

After typing the code

If m_djConsole.LastError

press the "=" key on your keyboard: IntelliSense displays the list of possible values that can be assigned to a parameter passed to a method or to a property as seen on the screenshot below:

Select the m_djConsole.enumDjcErrorCodes.ERR_DJC_NOERROR value so the complete line of code will be:

If m_djConsole.LastError = enumDjcErrorCodes.ERR_DJC_NOERROR Then

 ' do something

 ...

Else

 ' do something else

 ...

End If

Microsoft Visual C#.NET

This environment requires a couple of additional lines of code to make use of Intellisense. First, you must add the components namespace to your code so the following line must be inserted at the beginning of the form management file:

using ActiveDjConsoleNetApi;

After typing the code...

if (m_djConsole.LastError ==

and pressing the space bar (blank character) Intellisense is activated and automatically displays the correct enumerated type as follows:

after selecting the enumDjcErrorCodes type, press the "." key on your keyboard so the list of available options is displayed as seen below:

Select the ERR_DJC_NOERROR value so the complete line of code will be:

if (m_djConsole.LastError == enumDjcErrorCodes.ERR_DJC_NOERROR)

   // do something

   ....

else

   // do something else

   ....


LastError property (RO)

LastError property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property LastError As enumDjcErrorCodes

[C#]

public enumDjcErrorCodes LastError {get;}

[C++]

public: __property enumDjcErrorCodes get_LastError();

This property is Read-only

Remarks

Each call to one of the component's methods could generate an error: in case the called method should return an unexpected value, this property could give more details about the nature of the error. In case the called method should success, this property would assume the value ERR_DJC_NOERROR (0).

Here follows a list of the available error codes that could be returned by the component's methods calls:

Mnemonic value | Numeric value | Meaning
ERR_DJC_NOERROR | 0 | No error was generated by the latest method call
ERR_DJC_NOT_ENOUGH_MEMORY | -1 | Not enough memory
ERR_DJC_VALUE_OUT_OF_RANGE | -2 | Value out of range
ERR_DJC_INVALID_FILE | -3 | Invalid file
ERR_DJC_CANNOT_CREATE_FILE | -4 | Cannot create file
ERR_DJC_INVALID_MIDI_DEVICE | -5 | Invalid MIDI device
ERR_DJC_INVALID_RANGE | -6 | Invalid range
ERR_DJC_INVALID_KEYBOARD | -7 | Invalid keyboard
ERR_DJC_ALREADY_INITIALIZED | -8 | Already initialized
ERR_DJC_DEVICE_CLOSED | -9 | Device is closed
ERR_DJC_INVALID_EVENT | -10 | Invalid event
ERR_DJC_BUFFER_TOO_SMALL | -11 | The provided buffer is too small
ERR_DJC_DEVICE_ALREADY_ATTACHED | -12 | The MIDI device is already attached
ERR_DJC_NAME_ALREADY_AVAILABLE | -13 | The provided name is already in use by another existing item
ERR_DJC_CMD_ALREADY_AVAILABLE | -14 | The provided MIDI command is already in use by another existing item
ERR_DJC_INVALID_ITEM | -15 | Invalid item
ERR_DJC_UNSUPPORTED_ITEM | -16 | Unsupported item
ERR_DJC_MISSING_ITEM_NAME | -17 | The new item doesn't have a valid name
ERR_DJC_INVALID_PROFILE_TYPE | -18 | Invalid profile's item type
ERR_DJC_NO_DISPLAY | -19 | The MIDI DJ console doesn't have a display
ERR_DJC_INVALID_DISPLAY_SEGMENT | -20 | Invalid display's segment
ERR_DJC_INVALID_DISPLAY_CELL | -21 | Invalid display's cell
ERR_DJC_CONSOLE_NOT_CONNECTED | -22 | The DJ Console is not connected
ERR_DJC_INVALID_PROFILE | -23 | Invalid DJ Console profile
ERR_DJC_GENERIC | -100 | Generic or unknown error


MidiDevices property (RO)

MidiDevices property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property MidiDevices As ClassMidiDevices

[C#]

public ClassMidiDevices MidiDevices {get;}

[C++]

public: __property ClassMidiDevices* get_MidiDevices ();

This property is Read-only

Remarks

The embedded object for accessing MIDI devices.

This property encapsulates the functionality of the ClassMidiDevices class.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.


MidiDjConsole property (RO)

MidiDjConsole property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property MidiDevices As ClassMidiDevices

[C#]

public ClassMidiDevices MidiDevices {get;}

[C++]

public: __property ClassMidiDevices* get_MidiDevices ();

This property is Read-only

Remarks

The embedded object for accessing the MIDI DJ Console attached to the instance of the component.

This property encapsulates the functionality of the ClassMidiDjConsole class.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.


MidiVirtualKeyboard property (RO)

MidiVirtualKeyboard property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property MidiVirtualKeyboard As ClassMidiVirtualKeyboard

[C#]

public ClassMidiVirtualKeyboard MidiVirtualKeyboard {get;}

[C++]

public: __property ClassMidiVirtualKeyboard* get_MidiVirtualKeyboard ();

This property is Read-only

Remarks

The embedded object for managing the virtual MIDI piano keyboard.

This property encapsulates the functionality of the ClassidiVirtualKeyboard class.

For further details about the use of the virtual MIDI keyboard see the ClassidiVirtualKeyboard class section and the How to manage the virtual MIDI piano keyboard tutorial.


CallbackMidiDevicesConfigChangedSet method

CallbackMidiDevicesConfigChangedSet method

Remarks

Sets the function of the CallbackMidiDevicesConfigChanged callback delegate which notifies about changes inside the MIDI configuration.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDevicesConfigChangedSet (

function as CallbackMidiDevicesConfigChanged,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDevicesConfigChangedSet (

CallbackMidiDevicesConfigChanged function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDevicesConfigChangedSet (

CallbackMidiDevicesConfigChanged function,

Int32 nUserData

);

Parameter | Description
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDevicesEventRawReceivedSet method

CallbackMidiDevicesEventRawReceivedSet method

Remarks

Sets the function of the CallbackMidiDevicesConfigChanged callback delegate which notifies when a raw MIDI event is received from a specific MIDI input device.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDevicesEventRawReceivedSet (

nDeviceUniqueId as Int16,

function as CallbackMidiDevicesEventRawReceived,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDevicesEventRawReceivedSet (

Int16 nDeviceUniqueId,

CallbackMidiDevicesEventRawReceived function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDevicesEventRawReceivedSet (

Int16 nDeviceUniqueId,

CallbackMidiDevicesEventRawReceived function,

Int32 nUserData

);

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI device returned by a previous call to the MidiDevices.Open method
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDevicesEventShortReceivedSet method

CallbackMidiDevicesEventShortReceivedSet method

Remarks

Sets the function of the CallbackMidiDevicesConfigChanged callback delegate which notifies when a short MIDI event is received from a specific MIDI input device.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDevicesEventShortReceivedSet (

nDeviceUniqueId as Int16,

function as CallbackMidiDevicesEventShortReceived,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDevicesEventShortReceivedSet (

Int16 nDeviceUniqueId,

CallbackMidiDevicesEventShortReceived function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDevicesEventShortReceivedSet (

Int16 nDeviceUniqueId,

CallbackMidiDevicesEventShortReceived function,

Int32 nUserData

);

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI device returned by a previous call to the MidiDevices.Open method
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDevicesOpenRemovedSet method

CallbackMidiDevicesOpenRemovedSet method

Remarks

Sets the function of the CallbackMidiDevicesOpenRemoved callback delegate which notifies about disconnection of an opened MIDI device.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDevicesOpenRemovedSet (

function as CallbackMidiDevicesOpenRemoved,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDevicesOpenRemovedSet (

CallbackMidiDevicesOpenRemoved function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDevicesOpenRemovedSet (

CallbackMidiDevicesOpenRemoved function,

Int32 nUserData

);

Parameter | Description
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDjConsoleEventButtonPressedSet method

CallbackMidiDjConsoleEventButtonPressedSet method

Remarks

Sets the function of the CallbackMidiDjConsoleEventButtonPressed callback delegate which notifies when a physical button mapped into the DJ Console profile has been pressed.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDjConsoleEventButtonPressedSet (

function as CallbackMidiDjConsoleEventButtonPressed,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDjConsoleEventButtonPressedSet (

CallbackMidiDjConsoleEventButtonPressed function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDjConsoleEventButtonPressedSet (

CallbackMidiDjConsoleEventButtonPressed function,

Int32 nUserData

);

Parameter | Description
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDjConsoleEventButtonReleasedSet method

CallbackMidiDjConsoleEventButtonReleasedSet method

Remarks

Sets the function of the CallbackMidiDjConsoleEventButtonReleased callback delegate which notifies when a physical button mapped into the DJ Console profile has been released.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDjConsoleEventButtonReleasedSet (

function as CallbackMidiDjConsoleEventButtonReleased,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDjConsoleEventButtonReleasedSet (

CallbackMidiDjConsoleEventButtonReleased function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDjConsoleEventButtonReleasedSet (

CallbackMidiDjConsoleEventButtonReleased function,

Int32 nUserData

);

Parameter | Description
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDjConsoleEventRangeMovedSet method

CallbackMidiDjConsoleEventRangeMovedSet method

Remarks

Sets the function of the CallbackMidiDjConsoleEventRangeMoved callback delegate which notifies when a physical range control (sliders, jog wheels, rotary knobs, etc.) mapped into the DJ Console profile has been moved.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDjConsoleEventRangeMovedSet (

function as CallbackMidiDjConsoleEventRangeMoved,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDjConsoleEventRangeMovedSet (

CallbackMidiDjConsoleEventRangeMoved function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDjConsoleEventRangeMovedSet (

CallbackMidiDjConsoleEventRangeMoved function,

Int32 nUserData

);

Parameter | Description
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDjConsoleEventUnmappedSet method

CallbackMidiDjConsoleEventUnmappedSet method

Remarks

Sets the function of the CallbackMidiDjConsoleEventUnmapped callback delegate which notifies when a manual action is performed on a console's physical control which has not been mapped into the DJ Console profile.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiDjConsoleEventUnmappedSet (

function as CallbackMidiDjConsoleEventUnmapped,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiDjConsoleEventUnmappedSet (

CallbackMidiDjConsoleEventUnmapped function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiDjConsoleEventUnmappedSet (

CallbackMidiDjConsoleEventUnmapped function,

Int32 nUserData

);

Parameter | Description
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiKeyboardNotificationSet method

CallbackMidiKeyboardNotificationSet method

Remarks

Sets the function of the CallbackMidiKeyboardNotification callback delegate which notifies when one of the keys on the virtual piano keyboard is pressed or released.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of the virtual MIDI keyboard see the ClassMidiVirtualKeyboard class section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

Public Function CallbackMidiKeyboardNotificationSet (

function as CallbackMidiKeyboardNotification,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackMidiKeyboardNotificationSet (

CallbackMidiKeyboardNotification function,

Int32 nUserData

);

[C++]

public: enumErrorCodes CallbackMidiKeyboardNotificationSet (

CallbackMidiKeyboardNotification function,

Int32 nUserData

);

Parameter | Description
function | Callback function
nUserData | User instance data to pass to the callback function

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


GetControlVersion method

GetControlVersion method

Remarks

Retrieves the version of the control.

Syntax

[Visual Basic]

Public Function GetControlVersion (

) as String

[C#]

public string GetControlVersion (

);

[C++]

public: string GetControlVersion (

);

Return value

String containing the control's version.


GetEngineVersion method

GetEngineVersion method

Remarks

Retrieves the version of the multimedia engine.

Syntax

[Visual Basic]

Public Function GetEngineVersion (

) as String

[C#]

public string GetEngineVersion (

);

[C++]

public: string GetEngineVersion (

);

Return value

String containing the version of the multimedia engine.


Init method

Init method

Remarks

Initializes the control: the call to this method is mandatory and must be performed before calling any other method of the control, possibly in the container form initialization function: calling this method inside the constructor function of the container form will not work and could cause unpredictable results.

Syntax

[Visual Basic]

Public Function Init (

) As enumErrorCodes

[C#]

public enumErrorCodes Init (

);

[C++]

public: enumErrorCodes Init (

);

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


CallbackMidiDevicesConfigChanged delegate

CallbackMidiDevicesConfigChanged delegate

Remarks

Callback delegate invoked from a secondary thread when the configuration of MIDI devices is changed. This specific event is only generated for the first change of MIDI devices configuration and will not be fired again until the MidiDevices.Reset method is invoked.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDevicesConfigChangedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackMidiDevicesConfigChanged (

nChangeType as enumMidiDevicesConfigChanges,

nUserData as Int32

)

[C#]

public delegate void CallbackMidiDevicesConfigChanged (

enumMidiDevicesConfigChanges nChangeType,

Int32 nUserData

)

[C++]

public delegate void CallbackMidiDevicesConfigChanged (

enumMidiDevicesConfigChanges nChangeType,

Int32 nUserData

)

Parameter

Description

nChangeType

Specifies which type of change(s) occurred inside the configuration of MIDI devices.

Can be a combination of the following values:

Mnemonic constant | Value | Meaning
MIDI_CHANGE_INPUT_ADDED | 1 | An input MIDI device has been added
MIDI_CHANGE_INPUT_REMOVED | 2 | An input MIDI device has been removed
MIDI_CHANGE_OUTPUT_ADDED | 4 | An output MIDI device has been added
MIDI_CHANGE_OUTPUT_REMOVED | 8 | An output MIDI device has been removed

nUserData

User instance data


CallbackMidiDevicesEventRawReceived delegate

CallbackMidiDevicesEventRawReceived delegate

Remarks

Callback delegate invoked from a secondary thread when a raw MIDI event is received from a MIDI input device.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDevicesEventRawReceivedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackMidiDevicesEventRawReceived (

nDeviceUniqueId as Int16,

pBuffer as IntPtr,

nBufferLenght as Int32,

nTimeStamp as Int32,

nUserData as Int32

)

[C#]

public delegate void CallbackMidiDevicesEventRawReceived (

Int16 nDeviceUniqueId,

IntPtr pBuffer,

Int32 nBufferLenght,

Int32 nTimeStamp,

Int32 nUserData

)

[C++]

public delegate void CallbackMidiDevicesEventRawReceived (

Int16 nDeviceUniqueId,

IntPtr pBuffer,

Int32 nBufferLenght,

Int32 nTimeStamp,

Int32 nUserData

)

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI device returned by a previous call to the MidiDevices.Open method
pBuffer | The memory buffer containing raw data of the MIDI event. See the code snippets on the bottom of this page in order to see how to access raw data stored inside the buffer through marshaling.
nBufferLenght | Length in bytes of the given buffer
nTimeStamp | Reference that, on return from the method call, will contain the time stamp of the event expressed in milliseconds elapsed from the moment in which the MIDI input device was opened through a call to the MidiDevices.Open method.
nUserData | User instance data

The code snippets below show how to access raw data stored inside the buffer

Visual Basic .NET

Imports System.Runtime.InteropServices ' needed for data marshaling

Namespace ProfileEditor

Public Partial Class FormMain

Inherits Form

Public Sub New()

InitializeComponent()

End Sub

' instance the component

Dim m_djConsole As ActiveDjConsoleNetApi.ActiveDjConsoleNetApi = New ActiveDjConsoleNetApi.ActiveDjConsoleNetApi()

Public m_nIdInputDevice As Short

' predispose the delegate and the callback

Private Delegate Sub EventRawReceivedCallbackDelegate(ByVal nDeviceUniqueId As Int16, _

ByVal pBuffer As IntPtr, ByVal nBufferLenght As Int32, ByVal nTimeStamp As Int32, ByVal nUserData As Int32)

Private addrCallbackMidiDevicesEventRawReceived As CallbackMidiDevicesEventRawReceived

' the subroutine that manages the callback

Private Sub MidiDevicesEventRawReceivedCallback(ByVal nDeviceUniqueId As Int16, ByVal pBuffer As IntPtr, _

ByVal nBufferLenght As Int32, ByVal nTimeStamp As Int32, ByVal nUserData As Int32)

  ' check if we are being invoked from a secondary thread

   If Me.InvokeRequired Then

         Me.Invoke(New EventRawReceivedCallbackDelegate(AddressOf MidiDevicesEventRawReceivedCallback), _

nDeviceUniqueId, pBuffer, nBufferLenght, nTimeStamp, nUserData)

Return

   End If

   Dim strMessage As String = ""

   Dim i As Integer = 0

   Do While i < nBufferLenght

         ' use marshaling to access raw data in memory directly

         strMessage &= HexFormatted (Marshal.ReadByte(pBuffer, i), 2) & " "

         i += 1

   Loop

  ' display the string somewhere, for example inside am edit box

   TextRawInput.Text = strMessage

End Sub

Private Sub FormMain_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load

' initialize the component

m_djConsole.Init()

End Sub

       Private Sub CommandConnectDevices_Click(ByVal sender As Object, ByVal e As EventArgs) Handles CommandConnectDevices.Click

          ' open selected input device

           Dim nResult As enumDjcErrorCodes = 0

           nResult = m_djConsole.MidiDevices.Open(True, ComboMidiInputs.SelectedIndex, m_nIdInputDevice)

           If nResult <> enumDjcErrorCodes.ERR_DJC_NOERROR Then

              ' predispose the callback that will notify about reception of raw MIDI messages from the MIDI input device

               addrCallbackMidiDevicesEventRawReceived = New CallbackMidiDevicesEventRawReceived(AddressOf MidiDevicesEventRawReceivedCallback)

               m_djConsole.CallbackMidiDevicesEventRawReceivedSet(m_nIdInputDevice, addrCallbackMidiDevicesEventRawReceived, 0)

               Return

           End If

           MessageBox.Show("MIDI input device opening failed due to error " & nResult)

       End Sub

End Class

End Namespace

Visual C#

using System.Runtime.InteropServices; // needed for data marshaling

namespace ProfileEditor

{

public partial class FormMain : Form

{

public FormMain()

{

InitializeComponent();

}

// instance the component

ActiveDjConsoleNetApi.ActiveDjConsoleNetApi m_djConsole = new ActiveDjConsoleNetApi.ActiveDjConsoleNetApi();

public short m_nIdInputDevice;

// predispose the delegate and the callback

delegate void EventRawReceivedCallbackDelegate(Int16 nDeviceUniqueId,

                                       IntPtr pBuffer, Int32 nBufferLenght, Int32 nTimeStamp, Int32 nUserData);

CallbackMidiDevicesEventRawReceived     addrCallbackMidiDevicesEventRawReceived;

void MidiDevicesEventRawReceivedCallback(Int16 nDeviceUniqueId, IntPtr pBuffer, Int32 nBufferLenght, Int32 nTimeStamp, Int32 nUserData)

{

// check if we are being invoked from a secondary thread

if (this.InvokeRequired)

{

this.Invoke(new EventRawReceivedCallbackDelegate(MidiDevicesEventRawReceivedCallback), nDeviceUniqueId,

                                                           pBuffer, nBufferLenght, nTimeStamp, nUserData);

return;

}

string strMessage = "";

for (int i = 0; i < nBufferLenght; i++)

// use marshaling to access raw data in memory directly and store it inside a string

strMessage += HexFormatted (Marshal.ReadByte(pBuffer, i), 2) + " ";

// display the string somewhere, for example inside am edit box

TextRawInput.Text = strMessage;

}

private void FormMain_Load(object sender, EventArgs e)

{

// initialize the component

m_djConsole.Init();

}

private void CommandConnectDevices_Click(object sender, EventArgs e)

{

// open selected input device

enumDjcErrorCodes nResult = 0;

nResult = m_djConsole.MidiDevices.Open(true, ComboMidiInputs.SelectedIndex, ref m_nIdInputDevice);

if (nResult == enumDjcErrorCodes.ERR_DJC_NOERROR)

{

  // predispose the callback that will notify about reception of raw MIDI messages from the MIDI input device

   addrCallbackMidiDevicesEventRawReceived = new CallbackMidiDevicesEventRawReceived(MidiDevicesEventRawReceivedCallback);

   m_djConsole.CallbackMidiDevicesEventRawReceivedSet(m_nIdInputDevice, addrCallbackMidiDevicesEventRawReceived, 0);

   return;

}

MessageBox.Show("MIDI input device opening failed due to error " + nResult);

}

}

}


CallbackMidiDevicesEventShortReceived delegate

CallbackMidiDevicesEventShortReceived delegate

Remarks

Callback delegate invoked from a secondary thread when a short MIDI event is received from a MIDI input device.

MIDI events can be filtered, avoiding this event being generated, through the MidiDevices.InputEventFilterSet method.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDevicesEventShortReceivedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackMidiDevicesEventShortReceived (

nDeviceUniqueId as Int16,

nMidiCommand as Int16,

nMidiChannel as Int16,

nMidiData1 as Int16,

nMidiData2 as Int16,

nTimeStamp as Int32,

nUserData as Int32

)

[C#]

public delegate void CallbackMidiDevicesEventShortReceived (

Int16 nDeviceUniqueId,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiData1,

Int16 nMidiData2,

Int32 nTimeStamp,

Int32 nUserData

)

[C++]

public delegate void CallbackMidiDevicesEventShortReceived (

Int16 nDeviceUniqueId,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiData1,

Int16 nMidiData2,

Int32 nTimeStamp,

Int32 nUserData

)

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI device returned by a previous call to the MidiDevices.Open method
nMidiCommand | Number representing the MIDI command. A detailed summary of available MIDI commands/messages can be found inside the web site of the MIDI Manufacturers Association
nMidiChannel | Number representing the MIDI channel which received the MIDI command..
nMidiData1 | Number representing the first parameter related to the MIDI command.
nMidiData2 | Number representing the second parameter related to the MIDI command.
nTimeStamp | Reference that, on return from the method call, will contain the time stamp of the event expressed in milliseconds elapsed from the moment in which the MIDI input device was opened through a call to the MidiDevices.Open method.
nUserData | User instance data


CallbackMidiDevicesOpenRemoved delegate

CallbackMidiDevicesOpenRemoved delegate

Remarks

Callback delegate invoked from a secondary thread when a MIDI device, previously opened through the MidiDevices.Open method, is disconnected from the system after a manual removal.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDevicesOpenRemovedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackMidiDevicesOpenRemoved (

nDisconnectedInputDevice as Int16,

nDisconnectedOutputDevice as Int16,

nUserData as Int32

)

[C#]

public delegate void CallbackMidiDevicesOpenRemoved (

Int16 nDisconnectedInputDevice,

Int16 nDisconnectedOutputDevice,

Int32 nUserData

)

[C++]

public delegate void CallbackMidiDevicesOpenRemoved (

Int16 nDisconnectedInputDevice,

Int16 nDisconnectedOutputDevice,

Int32 nUserData

)

Parameter | Description
nDisconnectedInputDevice | The unique identifier of the disconnected MIDI input device returned by a previous call to the MidiDevices.Open method.
nDisconnectedOutputDevice | The unique identifier of the disconnected MIDI output device returned by a previous call to the MidiDevices.Open method.
nUserData | User instance data


CallbackMidiDjConsoleEventButtonPressed delegate

CallbackMidiDjConsoleEventButtonPressed delegate

Remarks

Callback delegate invoked from a secondary thread when a physical button mapped into the DJ Console profile has been pressed.

Events are sent to the container application only if a connection has been established between the instance of the component and the DJ Console through a call to the MidiDjConsole.Connect method.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDjConsoleEventButtonPressedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Delegate Sub MidiDjConsoleEventButtonPressed (

strButtonName as string,

nStringLength as Int32,

nTimeStamp as Int32,

nUserData as Int32

)

[C#]

public delegate void MidiDjConsoleEventButtonPressed (

string strButtonName,

Int32 nStringLength,

Int32 nTimeStamp,

Int32 nUserData

)

[C++]

public delegate void MidiDjConsoleEventButtonPressed (

string strButtonName,

Int32 nStringLength,

Int32 nTimeStamp,

Int32 nUserData

)

Parameter | Description
strButtonName | String containing the name given to the button control when mapped into the DJ Console profile
nStringLength | Length in characters of the string containing the name
nTimeStamp | The time stamp of the event expressed in milliseconds elapsed from the moment in which the MIDI input device of the DJ Console was opened through a call to the MidiDevices.Open method.
nUserData | User instance data


CallbackMidiDjConsoleEventButtonReleased delegate

CallbackMidiDjConsoleEventButtonReleased delegate

Remarks

Callback delegate invoked from a secondary thread when a physical button mapped into the DJ Console profile has been released.

Events are sent to the container application only if a connection has been established between the instance of the component and the DJ Console through a call to the MidiDjConsole.Connect method.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDjConsoleEventButtonReleasedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Delegate Sub MidiDjConsoleEventButtonReleased (

strButtonName as string,

nStringLength as Int32,

nTimeStamp as Int32,

nUserData as Int32

)

[C#]

public delegate void MidiDjConsoleEventButtonReleased (

string strButtonName,

Int32 nStringLength,

Int32 nTimeStamp,

Int32 nUserData

)

[C++]

public delegate void MidiDjConsoleEventButtonReleased (

string strButtonName,

Int32 nStringLength,

Int32 nTimeStamp,

Int32 nUserData

)

Parameter | Description
strButtonName | String containing the name given to the button control when mapped into the DJ Console profile
nStringLength | Length in characters of the string containing the name
nTimeStamp | The time stamp of the event expressed in milliseconds elapsed from the moment in which the MIDI input device of the DJ Console was opened through a call to the MidiDevices.Open method.
nUserData | User instance data


CallbackMidiDjConsoleEventRangeMoved delegate

CallbackMidiDjConsoleEventRangeMoved delegate

Remarks

Callback delegate invoked from a secondary thread when a physical range control (sliders, jog wheels, rotary knobs, etc.) mapped into the DJ Console profile has been moved.

Events are sent to the container application only if a connection has been established between the instance of the component and the DJ Console through a call to the MidiDjConsole.Connect method.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDjConsoleEventRangeMovedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackMidiDjConsoleEventRangeMoved (

strButtonName as string,

nStringLength as Int32,

nValue as Int32,

nTimeStamp as Int32,

nUserData as Int32

)

[C#]

public delegate void CallbackMidiDjConsoleEventRangeMoved (

string strButtonName,

Int32 nStringLength,

Int16 nValue,

Int32 nTimeStamp,

Int32 nUserData

)

[C++]

public delegate void CallbackMidiDjConsoleEventRangeMoved (

string strButtonName,

Int32 nStringLength,

Int16 nValue,

Int32 nTimeStamp,

Int32 nUserData

)

Parameter | Description
strButtonName | String containing the name given to the physical range control when mapped into the DJ Console profile
nStringLength | Length in characters of the string containing the name
nValue | The new value of the control
nTimeStamp | The time stamp of the event expressed in milliseconds elapsed from the moment in which the MIDI input device of the DJ Console was opened through a call to the MidiDevices.Open method.
nUserData | User instance data


CallbackMidiDjConsoleEventUnmapped delegate

CallbackMidiDjConsoleEventUnmapped delegate

Remarks

Callback delegate invoked from a secondary thread when a manual action (for example the pressing of a button, the movement of a slider or of a jog wheel) is performed on a console's physical control which has not been mapped into the DJ Console profile loaded inside the instance of the component or when the reception of events specific for mapped controls has been disabled through a call to the MidiDjConsole.EnableMappedEvents method.

Events are sent to the container application only if a connection has been established between the instance of the component and the DJ Console through a call to the MidiDjConsole.Connect method.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiDjConsoleEventUnmappedSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about interfacing with MIDI DJ Consoles see the ClassMidiDjConsole class section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackMidiDjConsoleEventUnmapped (

nMidiCommand as Int16,

nMidiChannel as Int16,

nMidiData1 as Int16,

nMidiData2 as Int16,

nTimeStamp as Int32,

nUserData as Int32

)

[C#]

public delegate void CallbackMidiDjConsoleEventUnmapped (

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiData1,

Int16 nMidiData2,

Int32 nTimeStamp,

Int32 nUserData

)

[C++]

public delegate void CallbackMidiDjConsoleEventUnmapped (

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiData1,

Int16 nMidiData2,

Int32 nTimeStamp,

Int32 nUserData

)

Parameter | Description
nMidiCommand | Number representing the MIDI command
nMidiChannel | Number representing the MIDI channel
nMidiData1 | Number representing the first parameter related to the MIDI event
nMidiData2 | Number representing the second parameter related to the MIDI event
nTimeStamp | The time stamp of the event expressed in milliseconds elapsed from the moment in which the MIDI input device of the DJ Console was opened through a call to the MidiDevices.Open method.
nUserData | User instance data


CallbackMidiKeyboardNotification delegate

CallbackMidiKeyboardNotification delegate

Remarks

Callback delegate invoked from a secondary thread when one of the keys on the virtual piano keyboard, previously created through the MidiVirtualKeyboard.Create method, is pressed or released.

In order to allow the component invoking this delegate at runtime, the container application must invoke the CallbackMidiKeyboardNotificationSet method passing the address of the callback function.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For further details about the use of the virtual MIDI keyboard see the ClassMidiVirtualKeyboard class section and the How to manage the virtual MIDI piano keyboard tutorial.

[Visual Basic]

Public Delegate Sub CallbackMidiKeyboardNotification (

hWndKeyboard as Int32,

nNote as Int16,

bPressed as Boolean,

bSimulated as Boolean,

nUserData as Int32

)

[C#]

public delegate void CallbackMidiKeyboardNotification (

Int32 hWndKeyboard,

Int16 nNote,

bool bPressed,

bool bSimulated,

Int32 nUserData

)

[C++]

public delegate void CallbackMidiKeyboardNotification (

Int32 hWndKeyboard,

Int16 nNote,

bool bPressed,

bool bSimulated,

Int32 nUserData

)

Parameter

Description

hWndKeyboard

Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method

nNote

Note played through pressure of one of the keys of the virtual piano keyboard. Can be a key number from 0 to 127; 60 means middle C

bPressed

Boolean flag that specifies if the key was pressed or released.

Supported values are the following:

Mnemonic constant | Meaning
false | The key was released
true | The key was pressed

bSimulated

Boolean flag that specifies if the key pressure is simulated. When the key pressure is simulated, the key appears pressed on the piano keyboard but no real event is generated on the MIDI stream in playback, allowing to display a note played through an external physical MIDI keyboard attached to one of the MIDI input channels.

Supported values are the following:

Mnemonic constant | Meaning
false | The call to this method will play the requested note on the MIDI stream in playback
true | The call to this method will not play the requested note on the MIDI stream in playback but will display the corresponding key as pressed on the piano keyboard.

nUserData

User instance data


ClassMidiDevices class

ClassMidiDevices class

The ClassMidiDevices class, accessible through the control's MidiDevices property contains methods needed to manage communication with input and output MIDI devices.

The ClassMidiDevices class is implemented through the following methods:

Close

CountGet

EventWriteRaw

EventWriteShort

InfoGet

InputEventFilterSet

InputOutputConnect

InputOutputDisconnect

IsOpened

Open

Reset

For further details about the use of MIDI devices see the How to manage MIDI devices tutorial.


MidiDevices.Close method

MidiDevices.Close method

Remarks

Closes a specific MIDI device installed inside the system which was previously opened through the MidiDevices.Open method.

When a MIDI device has been closed through this method, eventual connections with the specific MIDI input or output device, previously established through calls to MidiDevices.InputOutputConnect, MidiVirtualKeyboard.MidiInputConnect, MidiVirtualKeyboard.MidiOutputConnect or MidiDjConsole.Connect methods, will be automatically disconnected.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.Close (

nDeviceUniqueId as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.Close (

Int16 nDeviceUniqueId

);

[C++]

public: enumDjcErrorCodes MidiDevices.Close (

Int16 nDeviceUniqueId

);

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI device returned by a previous call to the MidiDevices.Open method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDevices.CountGet method

MidiDevices.CountGet method

Remarks

Reports the number of MIDI devices installed inside the system.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.CountGet (

bInput as Boolean,

ByRef nCount as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.CountGet (

bool bInput,

ref Int32 nCount

);

[C++]

public: enumDjcErrorCodes MidiDevices.CountGet (

bool bInput,

Int32 __gc *nCount

);

Parameter

Description

bInput

Boolean value that specifies if we want to obtain the number of input or of output devices.

Supported values are the following:

Mnemonic constant | Meaning
false | Enumerates output devices
true | Enumerates input devices

nCount

Reference that, on return from the method call, will contain the number of detected MIDI devices.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDevices.EventWriteRaw method

MidiDevices.EventWriteRaw method

Remarks

Sends a raw MIDI event to the MIDI output device previously opened through the MidiDevices.Open method.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.EventWriteRaw (

nDeviceUniqueId as Int16,

pBuffer() as Byte,

nBufferLen as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.EventWriteRaw (

Int16 nDeviceUniqueId,

char[] pBuffer,

Int32 nBufferLen

);

[C++]

public: enumDjcErrorCodes MidiDevices.EventWriteRaw (

Int16 nDeviceUniqueId,

char __gc[] pBuffer,

Int32 nBufferLen

);

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI output device returned by a previous call to the MidiDevices.Open method
pBuffer | Variant parameter containing the pointer to MIDI data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.

Samples

Below you can find a couple of samples that demonstrate how to send a raw MIDI message (a SysEx message in this case) to a MIDI output device (represented by the m_nIdOutputDevice variable filled by a previous call to the MidiDevices.Open method) in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub CommandSendSysExId_Click()

' allocate and fill the buffer

Dim SysExBuffer(6) As Byte

SysExBuffer(0) = &HF0

SysExBuffer(1) = &H7E

SysExBuffer(2) = &H7F

SysExBuffer(3) = &H6

SysExBuffer(4) = &H1

SysExBuffer(5) = &HF7

' send the raw SysSex MIDI message

ActiveDjConsole1.MidiDevices.EventWriteRaw m_nIdOutputDevice, VarPtr(SysExBuffer(0)), 6

End Sub

Visual C++ 6 with MFC

void CMyDialog::OnButtonSendSysExId()

{

// allocate and fill the buffer

BYTE    SysExBuffer[6];

SysExBuffer[0] = 0xF0;

SysExBuffer[1] = 0x7E;

SysExBuffer[2] = 0x7F;

SysExBuffer[3] = 0x06;

SysExBuffer[4] = 0x01;

SysExBuffer[5] = 0xF7;

// prepare the variant buffer

       VARIANT      va;

VariantInit (&va);

va.vt = VT_BYREF | VT_UI1;

va.pbVal = (BYTE *) SysExBuffer;

// send the raw SysSex MIDI message

m_ctrlActiveDjConsole1.GetMidiDevices().EventWriteRaw (m_nIdOutputDevice, va, 6);

}


MidiDevices.EventWriteShort method

MidiDevices.EventWriteShort method

Remarks

Sends a short MIDI event to the MIDI output device previously opened through the MidiDevices.Open method.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.EventWriteShort (

nDeviceUniqueId as Int16,

nMidiCommand as Int16,

nMidiChannel as Int16,

nMidiData1 as Int16,

nMidiData2 as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.EventWriteShort (

Int16 nDeviceUniqueId,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiData1,

Int16 nMidiData2

);

[C++]

public: enumDjcErrorCodes MidiDevices.EventWriteShort (

Int16 nDeviceUniqueId,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiData1,

Int16 nMidiData2

);

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI output device returned by a previous call to the MidiDevices.Open method
nMidiCommand | Number representing the MIDI command. A detailed summary of available MIDI commands/messages can be found inside the web site of the MIDI Manufacturers Association
nMidiChannel | Number representing the MIDI channel where the MIDI command is sent
nMidiData1 | Number representing the first parameter related to the MIDI command
nMidiData2 | Number representing the second parameter related to the MIDI command

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDevices.InfoGet method

MidiDevices.InfoGet method

Remarks

After completing the enumeration of MIDI devices installed inside the system, started through the MidiDevices.CountGet method, allows retrieving information about a specific MIDI device.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.InfoGet (

bInput as Boolean,

nDeviceIndex as Int16,

nInfoStringType as enumInfoStringType,

ByRef nVendorId as Int32,

ByRef nProductId as Int32

) as String

[C#]

public string MidiDevices.InfoGet (

bool bInput,

Int16 nDeviceIndex,

Int16 nInfoStringType,

ref Int32 nVendorId,

ref Int32 nProductId

);

[C++]

public: string MidiDevices.InfoGet (

bool bInput,

Int16 nDeviceIndex,

Int16 nInfoStringType,

Int32 __gc *nVendorId,

Int32 __gc *nProductId

);

Parameter

Description

bInput

Boolean value that specifies if the info request is related to an input or an output device.

Supported values are the following:

Mnemonic constant | Meaning
false | The info request is related to an output device
true | The info request is related to an input device

nDeviceIndex

Number representing the zero-based index of the MIDI device. The number of available MIDI devices installed inside the system can be obtained through the MidiDevices.CountGet method.

nInfoStringType

Specifies the type of information string we want to obtain.

Supported values are the following:

Mnemonic constant | Value | Meaning
INFO_STRING_TYPE_PRODUCT | 0 | Returns the name of the product only
INFO_STRING_TYPE_VENDOR | 1 | Returns the name of the product's vendor (manufacturer) only
INFO_STRING_TYPE_VENDOR_PRODUCT | 2 | Returns the name of the product's vendor (manufacturer) followed by the name of the product

nVendorId

Reference that, on return from the method call, will contain the number representing the vendor's (manufacturer) identifier (also known as VID or MID) for the MIDI device. The list of known identifiers can be found inside the MSDN website

nProductId

Reference that, on return from the method call, will contain the number representing the product's identifier (also known as PID) for the MIDI device. The list of known identifiers can be found inside the MSDN website

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested information.


MidiDevices.InfoGetByUniqueId method

MidiDevices.InfoGetByUniqueId method

Remarks

After completing the enumeration of MIDI devices installed inside the system, started through the MidiDevices.CountGet method, allows retrieving information about a specific MIDI device.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.InfoGetByUniqueId (

bInput as Boolean,

nDeviceUniqueId as Int16,

nInfoStringType as enumInfoStringType,

ByRef nVendorId as Int32,

ByRef nProductId as Int32

) as String

[C#]

public string MidiDevices.InfoGetByUniqueId (

bool bInput,

Int16 nDeviceUniqueId,

Int16 nInfoStringType,

ref Int32 nVendorId,

ref Int32 nProductId

);

[C++]

public: string MidiDevices.InfoGetByUniqueId (

bool bInput,

Int16 nDeviceUniqueId,

Int16 nInfoStringType,

Int32 __gc *nVendorId,

Int32 __gc *nProductId

);

Parameter

Description

bInput

Boolean value that specifies if the info request is related to an input or an output device.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The info request is related to an output device
BOOL_TRUE | 1 | The info request is related to an input device

nDeviceUniqueId

The unique identifier of the MIDI output device returned by a previous call to the MidiDevices.Open method

nInfoStringType

Specifies the type of information string we want to obtain.

Supported values are the following:

Mnemonic constant | Value | Meaning
INFO_STRING_TYPE_PRODUCT | 0 | Returns the name of the product only
INFO_STRING_TYPE_VENDOR | 1 | Returns the name of the product's vendor (manufacturer) only
INFO_STRING_TYPE_VENDOR_PRODUCT | 2 | Returns the name of the product's vendor (manufacturer) followed by the name of the product

nVendorId

Reference that, on return from the method call, will contain the number representing the vendor's (manufacturer) identifier (also known as VID or MID) for the MIDI device. The list of known identifiers can be found inside the MSDN website

nProductId

Reference that, on return from the method call, will contain the number representing the product's identifier (also known as PID) for the MIDI device. The list of known identifiers can be found inside the MSDN website

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested information.


MidiDevices.InputEventFilterSet method

MidiDevices.InputEventFilterSet method

Remarks

Allows filtering one or more MIDI events incoming from the given MIDI input device. Filtered MIDI events will be ignored and will not generate the MidiDevicesEventReceived event.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.InputEventFilterSet (

nDeviceUniqueId as Int16,

pBuffer() as Byte,

nBufferLen as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.InputEventFilterSet (

Int16 nDeviceUniqueId,

char[] pBuffer,

Int32 nBufferLen

);

[C++]

public: enumDjcErrorCodes MidiDevices.InputEventFilterSet (

Int16 nDeviceUniqueId,

char __gc[] pBuffer,

Int32 nBufferLen

);

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI input device returned by a previous call to the MidiDevices.Open method
pBuffer | Variant parameter containing the pointer to a buffer that contains inside each byte the MIDI command to be filtered.
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.

Samples

Below you can find a couple of samples that demonstrate how to filter the "Note On" and "Note Off" commands incoming from a MIDI input device (represented by the m_nIdInputDevice variable filled by a previous call to the MidiDevices.Open method) in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub CommandSetFilter_Click()

' allocate and fill the buffer

Dim FilterBuffer(2) As Byte

FilterBuffer(0) = &H90   ' Note On MIDI command

FilterBuffer(1) = &H80   ' Note Off MIDI command

' send the filter to the control

ActiveDjConsole1.MidiDevices.InputEventFilterSet m_nIdInputDevice, VarPtr(FilterBuffer(0)), 2

End Sub

Visual C++ 6 with MFC

void CMyDialog::OnButtonSetFilter()

{

// allocate and fill the buffer

BYTE    FilterBuffer[2];

FilterBuffer[0] = 0x90;   // Note On MIDI command

FilterBuffer[1] = 0x80;   // Note Off MIDI command

// prepare the variant buffer

       VARIANT      va;

VariantInit (&va);

va.vt = VT_BYREF | VT_UI1;

va.pbVal = (BYTE *) FilterBuffer;

// send the filter to the control

m_ctrlActiveDjConsole1.GetMidiDevices().InputEventFilterSet (m_nIdInputDevice, va, 2);

}


MidiDevices.InputOutputConnect method

MidiDevices.InputOutputConnect method

Remarks

Establishes a direct connection between the given MIDI input device and the given MIDI output device. After the connection is established, the connection can be terminated through the MidiDevices.InputOutputDisconnect method.

In order to establish the connection, both involved input and output devices must have been previously opened through the MidiDevices.Open method.

When the connection is established, each MIDI message incoming from the MIDI input device will be automatically forwarded to the MIDI output device.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.InputOutputConnect (

nInputDeviceUniqueId as Int16,

nOutputDeviceUniqueId as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.InputOutputConnect (

Int16 nInputDeviceUniqueId,

Int16 nInputDeviceUniqueId

);

[C++]

public: enumDjcErrorCodes MidiDevices.InputOutputConnect (

Int16 nInputDeviceUniqueId,

Int16 nInputDeviceUniqueId

);

Parameter | Description
nInputDeviceUniqueId | The unique identifier of the MIDI input device returned by a previous call to the MidiDevices.Open method.
nOutputDeviceUniqueId | The unique identifier of the MIDI output device returned by a previous call to the MidiDevices.Open method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDevices.InputOutputDisconnect method

MidiDevices.InputOutputDisconnect method

Remarks

Interrupts an existing direct connection between a MIDI input device and a MIDI output device previously established through the MidiDevices.InputOutputConnect method.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.InputOutputDisconnect (

nInputDeviceUniqueId as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.InputOutputDisconnect (

Int16 nInputDeviceUniqueId

);

[C++]

public: enumDjcErrorCodes MidiDevices.InputOutputDisconnect (

Int16 nInputDeviceUniqueId

);

Parameter | Description
nInputDeviceUniqueId | The unique identifier of the MIDI input device used for the previously established connection through the MidiDevices.InputOutputConnect method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDevices.IsOpened method

MidiDevices.IsOpened method

Remarks

Verify if the given MIDI input or output device is currently opened.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.IsOpened (

nDeviceUniqueId as Int16

) as Boolean

[C#]

public bool MidiDevices.IsOpened (

Int16 nDeviceUniqueId

);

[C++]

public: bool MidiDevices.IsOpened (

Int16 nDeviceUniqueId

);

Parameter | Description
nDeviceUniqueId | The unique identifier of the MIDI device returned by a previous call to the MidiDevices.Open method

Return value

Value | Meaning
TRUE | The MIDI device is opened.
FALSE | The MIDI device is closed.


MidiDevices.Open method

MidiDevices.Open method

Remarks

Opens a specific MIDI device installed inside the system and obtains back its unique identifier. An opened device can be close through the MidiDevices.Close method.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.Open (

bInput as Boolean,

nDeviceIndex as Int16,

ByRef nDeviceUniqueId as Integer

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.Open (

bool bInput,

Int16 nDeviceIndex,

ref Int16 nDeviceUniqueId

);

[C++]

public: enumDjcErrorCodes MidiDevices.Open (

bool bInput,

Int16 nDeviceIndex,

Int16 __gc *nDeviceUniqueId

);

Parameter

Description

bInput

Boolean value that specifies if the open request is related to an input or an output device.

Supported values are the following:

Mnemonic constant | Meaning
false | The opening request is related to an output device
true | The opening request is related to an input device

nDeviceIndex

Number representing the zero-based index of the MIDI device. The number of available MIDI devices installed inside the system can be obtained through the MidiDevices.CountGet method.

nDeviceUniqueId

Reference that, on return from the method call, will contain the unique identifier of the MIDI device: this identifier will be used with other methods that will require access to the specific MIDI device.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDevices.Reset method

MidiDevices.Reset method

Remarks

Resets the internal configuration of MIDI devices by closing all opened devices.

In case a new MIDI device should have been connected via USB or enabled through the system control panel, this call will allow the corresponding device to be added to the list of available MIDI devices.

In case an existing MIDI device should have been disconnected from the USB door or disabled through the system control panel, this call will allow the corresponding device to be removed from the list of available MIDI devices.

Each time a MIDI device is connected/disconnected or enabled/disabled, the container application is notified through the MidiDevicesConfigChanged event: this specific event is only generated for the first change of MIDI devices configuration and will not be fired again until the MidiDevices.Reset method is invoked.

For further details about the use of MIDI devices see the ClassMidiDevices class section and the How to manage MIDI devices tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDevices.Reset (

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDevices.Reset (

);

[C++]

public: enumDjcErrorCodes MidiDevices.Reset (

);

Return value

None


ClassMidiDjConsole class

ClassMidiDjConsole class

The ClassMidiDjConsole class, accessible through the control's MidiDjConsole property contains methods needed to manage communication between the instance of the control and a physical MIDI DJ Console attached to the system.

The ClassMidiDjConsole class is implemented through the following methods:

Connect

Disconnect

EnableMappedEvents

IsConnected

ProfileInfoIdentifiersGet

ProfileInfoStringGet

ProfileInfoStringSet

ProfileInternalCountGet

ProfileInternalLoad

ProfileInternalNameGet

ProfileLoad

ProfileReset

ProfileSave

ProfileSaveWithoutDevice

ProfileTypedItemCountGet

ProfileTypedItemNameGet

ProfileItemAdd

ProfileItemCountGet

ProfileItemExistsByName

ProfileItemInfoStringGet

ProfileItemModify

ProfileItemNameGet

ProfileItemRemove

ProfileItemTypeGet

ProfileButtonMidiCommandGet

ProfileButtonMidiCommandSet

ProfileButtonNameGetByMidiCommand

ProfileRangeMidiCommandGet

ProfileRangeMidiCommandSet

ProfileRangeNameGetByMidiCommand

ProfileLedBlink

ProfileLedSwitch

ProfileLedMidiCommandGet

ProfileLedMidiCommandSet

ProfileLedNameGetByMidiCommand

ProfileDisplayDataSet

ProfileDisplayNameGetByMidiCommand

ProfileDisplayMidiCommandGet

ProfileDisplayMidiCommandSet

DisplaySegmentManagementAvailable

DisplaySegmentCountGet

DisplaySegmentInfoGet

DisplaySegmentSymbolShow

DisplaySegmentStringShow

DisplaySegmentStringScroll

For further details about interfacing with MIDI DJ Consoles see the How to manage MIDI DJ consoles tutorial.


MidiDjConsole.Connect method

MidiDjConsole.Connect method

Remarks

Establishes a connection between the instance of the component and the given MIDI input and output devices of a DJ Console. After the connection is established, the connection can be terminated through the MidiDjConsole.Disconnect method.

In order to establish the connection, both involved input and output devices of the DJ Console must have been previously opened through the MidiDevices.Open method.

When a connection is established, the DJ Console can report back to the instance of the component all of the events occurring on the console's physical controls and receive commands from the container application, for example switching a led on/off, blinking a led or display a string of characters on an eventual display.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.Connect (

nInputDeviceUniqueId as Int16,

nOutputDeviceUniqueId as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.Connect (

Int16 nInputDeviceUniqueId,

Int16 nInputDeviceUniqueId

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.Connect (

Int16 nInputDeviceUniqueId,

Int16 nInputDeviceUniqueId

);

Parameter | Description
nInputDeviceUniqueId | The unique identifier of the MIDI input device returned by a previous call to the MidiDevices.Open method.
nOutputDeviceUniqueId | The unique identifier of the MIDI output device returned by a previous call to the MidiDevices.Open method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.Disconnect method

MidiDjConsole.Disconnect method

Remarks

Interrupts the direct connection previously established through the MidiDjConsole.Connect method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.Disconnect (

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.Disconnect (

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.Disconnect (

);

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.DisplaySegmentCountGet method

MidiDjConsole.DisplaySegmentCountGet method

Remarks

Certain models of DJ consoles come with one or more displays, also known as "VFD" which stands for "Vacuum Fluorescent Display", allowing to display a string of alphanumeric characters: this method allows enumerating VFD segments whose management is embedded inside the component. After completing the enumeration, the name of each segment and related parameters can be retrieved through the MidiDjConsole.DisplaySegmentInfoGet method.

You can verify if the control comes with support for managing VFD segments of the connected DJ Console through the MidiDjConsole.DisplaySegmentManagementAvailable method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.DisplaySegmentCountGet (

ByRef nCount as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.DisplaySegmentCountGet (

ref Int32 nCount

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.DisplaySegmentCountGet (

Int32 __gc *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the number of available display segments.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.DisplaySegmentInfoGet method

MidiDjConsole.DisplaySegmentInfoGet method

Remarks

Obtains the name and other information about the given VFD segment.

You can verify if the control comes with support for managing VFD segments of the connected DJ Console through the MidiDjConsole.DisplaySegmentManagementAvailable method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.DisplaySegmentInfoGet (

nIndex as Int32,

ByRef nMidiChannel as Int16,

ByRef nCells as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.DisplaySegmentCountGet (

Int32 nIndex,

ref Int16 nMidiChannel,

ref Int16 nCells

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.DisplaySegmentCountGet (

Int32 nIndex,

Int16 __gc *nMidiChannel,

Int16 __gc *nCells

);

Parameter | Description
nIndex | Zero-based index of the VFD segment. The maximum number of available segments can be retrieved through the MidiDjConsole.DisplaySegmentCountGet method.
nMidiChannel | Reference that, on return from the method call, will contain the MIDI channel used to access the proper VFD when sending MIDI commands. The value of this parameter strictly depends upon the model of the DJ Console in use.
nCells | Reference that, on return from the method call, will contain the number of cells (characters) available inside the given segment.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the name of the VFD segment.


MidiDjConsole.DisplaySegmentManagementAvailable method

MidiDjConsole.DisplaySegmentManagementAvailable method

Remarks

Verifies if the component comes with support for managing VFD segments, if any, of the connected DJ console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.DisplaySegmentManagementAvailable (

) as Boolean

[C#]

public bool MidiDjConsole.DisplaySegmentManagementAvailable (

);

[C++]

public: bool MidiDjConsole.DisplaySegmentManagementAvailable (

);

Return value

Value | Meaning
TRUE | The control comes with support for managing VFD segments of the connected DJ Console.
FALSE | The control doesn't come with support for managing VFD segments of the connected DJ Console.


MidiDjConsole.DisplaySegmentStringScroll method

MidiDjConsole.DisplaySegmentStringScroll method

Remarks

Allows displaying a scrolling string of text on the given VFD segment at a specific rate. Scrolling always occurs from right to left.

You can verify if the control comes with support for managing VFD segments of the connected DJ Console through the MidiDjConsole.DisplaySegmentManagementAvailable method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.DisplaySegmentStringScroll (

nIndex as Int32,

pBuffer() as Byte,

nBufferLen as Int32,

nDelay as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.DisplaySegmentStringScroll (

Int32 nIndex,

char[] pBuffer,

Int32 nBufferLen,

Int32 nDelay

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.DisplaySegmentStringScroll (

Int32 nIndex,

char __gc[] pBuffer,

Int32 nBufferLen,

Int32 nDelay

);

Parameter

Description

nIndex

Zero-based index of the VFD segment. The maximum number of available segments can be retrieved through the MidiDjConsole.DisplaySegmentCountGet method.

pBuffer

Variant parameter containing the pointer to the memory buffer containing the string to scroll.

The character set in use is usually provided inside the technical specifications of the DJ Console in use.

nBufferLen

Length in bytes of the given buffer. Usually one single byte is required to store one single character.

The length of the buffer can be up to 256 bytes, allowing a string longer than the number of available cells per segment to be scrolled.

In case the source buffer should have a size larger than 256 bytes, only the first 256 bytes would be taken into consideration while bytes exceeding this size would be ignored.

nDelay

Number representing the applied scrolling rate expressed in milliseconds. The minimal accepted value is 50 milliseconds; values under this limit will be automatically capped to 50.

If for example this parameter should be set to 1000, the scrolling of the displayed string would occur every second.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.DisplaySegmentStringShow method

MidiDjConsole.DisplaySegmentStringShow method

Remarks

Displays a string of characters on the given VFD segment.

If you need to display a single character instead of a string of characters, use the MidiDjConsole.DisplaySegmentSymbolShow method.

In case the string to display should be longer respect to the available number of cells per segment, you could make the string scrolling at a given rate through the MidiDjConsole.DisplaySegmentStringScroll method.

You can verify if the control comes with support for managing VFD segments of the connected DJ Console through the MidiDjConsole.DisplaySegmentManagementAvailable method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.DisplaySegmentStringShow (

nIndex as Int32,

pBuffer() as Byte,

nBufferLen as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.DisplaySegmentStringShow (

Int32 nIndex,

char[] pBuffer,

Int32 nBufferLen

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.DisplaySegmentStringShow (

Int32 nIndex,

char __gc[] pBuffer,

Int32 nBufferLen

);

Parameter

Description

nIndex

Zero-based index of the VFD segment. The maximum number of available segments can be retrieved through the MidiDjConsole.DisplaySegmentCountGet method.

pBuffer

Variant parameter containing the pointer to the memory buffer containing the string to display.

The character set in use is usually provided inside the technical specifications of the DJ Console in use.

nBufferLen

Length in bytes of the given buffer. Usually one single byte is required to store one single character.

The length of the buffer can be up to 256 bytes. In case the source buffer should have a size larger than the total number of segment's cells, only the first bytes corresponding to the number of cells would be taken into consideration while bytes exceeding this size would be ignored.

The maximum number of cells available for the given segment can be obtained through the MidiDjConsole.DisplaySegmentInfoGet method.

In case the given buffer should be smaller than the number of available cells, remaining cells would be automatically filled with blank characters.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.DisplaySegmentSymbolShow method

MidiDjConsole.DisplaySegmentSymbolShow method

Remarks

Displays a character's symbol on a specific cell of the given VFD segment. If you need to display a string of characters instead of a single character, use the MidiDjConsole.DisplaySegmentStringShow method.

You can verify if the control comes with support for managing VFD segments of the connected DJ Console through the MidiDjConsole.DisplaySegmentManagementAvailable method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.DisplaySegmentSymbolShow (

nIndex as Int32,

nSymbol as Int16,

nCell as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.DisplaySegmentSymbolShow (

Int32 nIndex,

Int16 nSymbol,

Int16 nCell

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.DisplaySegmentSymbolShow (

Int32 nIndex,

Int16 nSymbol,

Int16 nCell

);

Parameter | Description
nIndex | Zero-based index of the VFD segment. The maximum number of available segments can be retrieved through the MidiDjConsole.DisplaySegmentCountGet method.
nSymbol | The numerical value of the character's symbol to display. The characters set in use should be provided inside the technical specifications of the DJ Console in use.
nCell | The 1-based numerical value of the cell that will display the character's symbol within the display segment. The maximum number of cells available for the given segment can be obtained through the MidiDjConsole.DisplaySegmentInfoGet method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.EnableMappedEvents method

MidiDjConsole.EnableMappedEvents method

Remarks

Enables/disabled the possibility for the container application to receive specific events for buttons and range controls.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.EnableMappedEvents (

bEnable as Boolean

)

[C#]

public void MidiDjConsole.EnableMappedEvents (

bool bEnable

);

[C++]

public: void MidiDjConsole.EnableMappedEvents (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if the container application will receive specific events for buttons and range controls.

Supported values are the following:

Mnemonic constant

Meaning

false

When a manual action (pressing of buttons, movement of sliders or jog wheels) is performed on a physical control on the DJ console, the container application is notified through the generic MidiDjConsoleEventUnmapped event also if the physical control has been mapped inside the DJ Console profile loaded into the instance of the control.

true (default)

When a manual action (pressing of buttons, movement of sliders or jog wheels) is performed on a physical control mapped inside the DJ Console profile loaded into the instance of the control, the container application is notified through a specific event:

· MidiDjConsoleEventButtonPressed and MidiDjConsoleEventButtonReleased events for buttons
· MidiDjConsoleEventRangeMoved.event for range controls (sliders, jog wheels, rotary knobs, etc.)

Return value

None


MidiDjConsole.IsConnected method

MidiDjConsole.IsConnected method

Remarks

Verify the presence of a connection between the instance of the component and a DJ Console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.IsConnected (

ByRef nInputDeviceUniqueId as Int16,

ByRef nOutputDeviceUniqueId as Int16

) as Boolean

[C#]

public bool MidiDjConsole.IsConnected (

ref Int16 nInputDeviceUniqueId,

ref Int16 nInputDeviceUniqueId

);

[C++]

public: bool MidiDjConsole.IsConnected (

Int16 __gc *nInputDeviceUniqueId,

Int16 __gc *nInputDeviceUniqueId

);

Parameter | Description
nInputDeviceUniqueId | Reference that, on return from the method call, will contain the unique identifier of the MIDI input device used to establish the connection to the DJ Console through the MidiDjConsole.Connect method. In case there should be no connection available, the returned value would be set to -1.
nOutputDeviceUniqueId | Reference that, on return from the method call, will contain the unique identifier of the MIDI output device used to establish the connection to the DJ Console through the MidiDjConsole.Connect method. In case there should be no connection available, the returned value would be set to -1.

Return value

Value | Meaning
TRUE | The DJ Console is connected.
FALSE | The DJ Console is disconnected.


MidiDjConsole.ProfileButtonMidiCommandGet method

MidiDjConsole.ProfileButtonMidiCommandGet method

Remarks

Obtains parameters of the short MIDI command specific for a button item stored inside the profile. See the MidiDjConsole.ProfileButtonMidiCommandSet method for details about the structure of a short MIDI command representing a push button item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileButtonMidiCommandGet (

strItemName as String,

ByRef nMidiCommandPressed as Int16,

ByRef nMidiCommandReleased as Int16,

ByRef nMidiChannel as Int16,

ByRef nMidiDataPressed as Int16,

ByRef nMidiDataReleased as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileButtonMidiCommandGet (

string strItemName,

ref Int16 nMidiCommandPressed,

ref Int16 nMidiCommandReleased,

ref Int16 nMidiChannel,

ref Int16 nMidiDataPressed,

ref Int16 nMidiDataReleased

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileButtonMidiCommandGet (

string strItemName,

Int16 __gc *nMidiCommandPressed,

Int16 __gc *nMidiCommandReleased,

Int16 __gc *nMidiChannel,

Int16 __gc *nMidiDataPressed,

Int16 __gc *nMidiDataReleased

);

Parameter

Description

strItemName

String containing the name of the push button item.

If no push button item with this specific name should be available inside the profile, the method would fail and would return an error code.

nMidiCommandPressed

Reference that, on return from the method call, will contain the number representing the MIDI command issued when the physical button is pressed. In many cases the value of this parameter is 144 (hex 90) which indicates a "Note On" MIDI command.

nMidiCommandReleased

Reference that, on return from the method call, will contain the number representing the MIDI command issued when the physical button is released: in some case this value could be identical to the value returned inside the nMidiCommandPressed parameter in which case the pressed/released status would be identified by different values of the nMidiDataPressed and nMidiDataReleased parameters below.

nMidiChannel

Reference that, on return from the method call, will contain the number representing the MIDI channel.

nMidiDataPressed

Reference that, on return from the method call, will contain the number representing the "Data" parameter of the MIDI command issued when the physical button is pressed.

The "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicate the code of the pressed button and its status (pressed/released).

Separate values of the "Data1" and "Data2" bytes can be extracted from this parameter using custom functions and/or macros.

nMidiDataReleased

Reference that, on return from the method call, will contain the number representing the "Data" parameter of the MIDI command issued when the physical button is released.

As mentioned above, the "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicate the code of the pressed button and its status (pressed/released): in some case this value could be identical to the value returned inside the nMidiDataPressed parameter in which case the pressed/released status would be identified by different values of the nMidiCommandPressed and nMidiCommandReleased parameters above.

Separate values of the "Data1" and "Data2" bytes can be extracted from this parameter using custom functions and/or macros.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileButtonMidiCommandSet method

MidiDjConsole.ProfileButtonMidiCommandSet method

Remarks

Sets parameters of the short MIDI command specific for a button item stored inside the profile. Current parameters of the short MIDI command can be obtained through the MidiDjConsole.ProfileButtonMidiCommandGet method.

A short command is sent to the instance of the component by the DJ Console when a physical push button is pressed or released on the DJ Console.

The short MIDI command is composed of 3 bytes combining 4 elements:

· One byte composed by the code of the MIDI Command, typically a "Note On" (hex 90) or a "Note off" (hex 80), on the more significant 4 bits and by the MIDI channel on the less significant 4 bits.
· Two bytes of MIDI "Data": the combinations of these 2 bytes usually indicates the physical button of the DJ console and, in some case, its pressed/released status.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileButtonMidiCommandSet (

strItemName as String,

nMidiCommandPressed as Int16,

nMidiCommandReleased as Int16,

nMidiChannel as Int16,

nMidiDataPressed as Int16,

nMidiDataReleased as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileButtonMidiCommandSet (

string strItemName,

Int16 nMidiCommandPressed,

Int16 nMidiCommandReleased,

Int16 nMidiChannel,

Int16 nMidiDataPressed,

Int16 nMidiDataReleased

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileButtonMidiCommandSet (

string strItemName,

Int16 nMidiCommandPressed,

Int16 nMidiCommandReleased,

Int16 nMidiChannel,

Int16 nMidiDataPressed,

Int16 nMidiDataReleased

);

Parameter

Description

strItemName

String containing the name of the push button item.

If no push button item with this specific name should be available inside the profile, the method would fail and would return an error code.

nMidiCommandPressed

The number representing the MIDI command issued when the physical button is pressed.

nMidiCommandReleased

The number representing the MIDI command issued when the physical button is released: in some case this value could be identical to the value of the nMidiCommandPressed parameter in which case the pressed/released status would be identified by different values of the nMidiDataPressed and nMidiDataReleased parameters below.

nMidiChannel

The number representing the MIDI channel.

Some DJ Console makes use of this parameter in order to discriminate between the DJ Console's decks, in other cases it's simply left to 0.

nMidiDataPressed

The number representing the "Data" parameter of the MIDI command issued when the physical button is pressed.

The "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicate the code of the pressed button and its status (pressed/released).

Separate values of the "Data1" and "Data2" bytes can be extracted from this parameter using custom functions and/or macros.

nMidiDataReleased

The number representing the "Data" parameter of the MIDI command issued when the physical button is released.

As mentioned above, the "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicate the code of the pressed button and its status (pressed/released): in some case this value could be identical to the value of the nMidiDataPressed parameter in which case the pressed/released status would be identified by different values of the nMidiCommandPressed and nMidiCommandReleased parameters above.

Separate values of the "Data1" and "Data2" bytes can be combined in one single 16 bits integer value using custom functions and/or macros.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileButtonNameGetByMidiCommand method

MidiDjConsole.ProfileButtonNameGetByMidiCommand method

Remarks

Given parameters of a short MIDI command, obtains the name of the push button item stored inside the DJ Console profile having this specific MIDI command, if available. See the MidiDjConsole.ProfileButtonMidiCommandSet method for details about the structure of a short MIDI command representing a push button item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileButtonNameGetByMidiCommand (

nMidiCommandPressed as Int16,

nMidiCommandReleased as Int16,

nMidiChannel as Int16,

nMidiDataPressed as Int16,

nMidiDataReleased as Int16

) as String

[C#]

public string MidiDjConsole.ProfileButtonNameGetByMidiCommand (

Int16 nMidiCommandPressed,

Int16 nMidiCommandReleased,

Int16 nMidiChannel,

Int16 nMidiDataPressed,

Int16 nMidiDataReleased

);

[C++]

public: string MidiDjConsole.ProfileButtonNameGetByMidiCommand (

Int16 nMidiCommandPressed,

Int16 nMidiCommandReleased,

Int16 nMidiChannel,

Int16 nMidiDataPressed,

Int16 nMidiDataReleased

);

Parameter | Description
nMidiCommandPressed | The number representing the MIDI command issued when the physical button is pressed.
nMidiCommandReleased | The number representing the MIDI command issued when the physical button is released.
nMidiChannel | The number representing the MIDI channel.
nMidiDataPressed | The number representing the "Data" parameter of the MIDI command issued when the physical button is pressed.
nMidiDataReleased | The number representing the "Data" parameter of the MIDI command issued when the physical button is released.

Return value

Value | Meaning
Empty string | No push button item available having the provided MIDI command is stored inside the profile.
Valid string | String containing the name of the push button item having the provided MIDI command.


MidiDjConsole.ProfileDisplayDataSet method

MidiDjConsole.ProfileDisplayDataSet method

Remarks

Sends data to a VFD display control item, stored inside the profile, by sending to the DJ Console the related MIDI command set through a previous call to the MidiDjConsole.ProfileDisplayMidiCommandSet method or loaded through an eventual call to the MidiDjConsole.ProfileLoad method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileDisplayDataSet (

strItemName as String,

nData as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileDisplayDataSet (

string strItemName,

Int16 nData

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileDisplayDataSet (

string strItemName,

Int16 nData

);

Parameter | Description
strItemName | String containing the name of the VFD display item. If no VFD display item with this specific name should be available inside the profile, the method would fail and would return an error code.
nData | Value to set: see the technical specifications of the physical DJ Console for possible values.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileDisplayMidiCommandGet method

MidiDjConsole.ProfileDisplayMidiCommandGet method

Remarks

Obtains parameters of the short MIDI command specific for a VFD display control item stored inside the profile. See the MidiDjConsole.ProfileDisplayMidiCommandSet method for details about the structure of a short MIDI command representing a display control item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileDisplayMidiCommandGet (

strItemName as String,

ByRef nMidiCommand as Int16,

ByRef nMidiChannel as Int16,

ByRef nMidiControlCode as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileDisplayMidiCommandGet (

string strItemName,

ref Int16 nMidiCommand,

ref Int16 nMidiChannel,

ref Int16 nMidiControlCode

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileDisplayMidiCommandGet (

string strItemName,

Int16 __gc *nMidiCommand,

Int16 __gc *nMidiChannel,

Int16 __gc *nMidiControlCode

);

Parameter | Description
strItemName | String containing the name of the VFD display item. If no range control item with this specific name should be available inside the profile, the method would fail and would return an error code.
nMidiCommand | Reference that, on return from the method call, will contain the number representing the MIDI command issued when display's content needs to be modified. In many cases the value of this parameter is 176 (hex B0) which indicates a "Control change" MIDI command.
nMidiChannel | Reference that, on return from the method call, will contain the number representing the MIDI channel.
nMidiControlCode | Reference that, on return from the method call, will contain the number representing the code of the physical display control item.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileDisplayMidiCommandSet method

MidiDjConsole.ProfileDisplayMidiCommandSet method

Remarks

Sets parameters of the short MIDI command specific for a VFD display control item stored inside the profile. Current parameters of the short MIDI command can be obtained through the MidiDjConsole.ProfileDisplayMidiCommandGet method.

The short MIDI command is composed of 2 bytes combining 3 elements:

· One byte composed by the code of the MIDI Command, typically a "Control change" (hex B0) on the more significant 4 bits and by the MIDI channel on the less significant 4 bits.
· One byte of MIDI "Data", usually indicated as "Data1", representing the code of the physical display control.

Data to display on the VFD display element are sent through the second byte of MIDI data, usually indicated as "Data2", and can be sent through the MidiDjConsole.ProfileDisplayDataSet method.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileDisplayMidiCommandSet (

strItemName as String,

nMidiCommand as Int16,

nMidiChannel as Int16,

nMidiControlCode as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileDisplayMidiCommandSet (

string strItemName,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileDisplayMidiCommandSet (

string strItemName,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

Parameter | Description
strItemName | String containing the name of the VFD display item. If no range control item with this specific name should be available inside the profile, the method would fail and would return an error code.
nMidiCommand | The MIDI command issued when display's content needs to be modified. In many cases the value of this parameter is 176 (hex B0) which indicates a "Control change" MIDI command.
nMidiChannel | The number representing the MIDI channel.
nMidiControlCode | The number representing the code (Data1 field described above) of the VFD display control item.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileDisplayNameGetByMidiCommand method

MidiDjConsole.ProfileDisplayNameGetByMidiCommand method

Remarks

Given parameters of a short MIDI command, obtains the name of the VFD display control item stored inside the DJ Console profile having this specific MIDI command, if available. See the MidiDjConsole.ProfileDisplayMidiCommandSet method for details about the structure of a short MIDI command representing a VFD display control item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileDisplayNameGetByMidiCommand (

nMidiCommand as Int16

nMidiChannel as Int16,

nMidiControlCode as Int16

) as String

[C#]

public string MidiDjConsole.ProfileDisplayNameGetByMidiCommand (

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

[C++]

public: string MidiDjConsole.ProfileDisplayNameGetByMidiCommand (

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

Parameter | Description
nMidiCommand | The MIDI command issued when display's content needs to be modified. In many cases the value of this parameter is 176 (hex B0) which indicates a "Control change" MIDI command.
nMidiChannel | The number representing the MIDI channel.
nMidiControlCode | The number representing the code of the VFD display control item sent through the Data1 byte of the short MIDI command.

Return value

Value | Meaning
Empty string | No range control item available having the provided MIDI command is stored inside the profile.
Valid string | String containing the name of the display item having the provided MIDI command.


MidiDjConsole.ProfileInfoIdentifiersGet method

MidiDjConsole.ProfileInfoIdentifiersGet method

Remarks

Once a profile has been loaded from a XML file through the MidiDjConsole.ProfileLoad method, obtains the product's and vendor's identifiers of the DJ Console for which the profile was originally written: this information is useful when there is the need to check if the loaded profile is the correct one for the physical connected DJ Console; product and vendor identifiers of the physically connected DJ Console can be retrieved through the MidiDevices.InfoGet method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileInfoIdentifiersGet (

ByRef nVendorId as Int32,

ByRef nProductId as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileInfoIdentifiersGet (

ref Int32 nVendorId,

ref Int32 nProductId

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileInfoIdentifiersGet (

Int32 __gc *nVendorId,

Int32 __gc *nProductId

);

Parameter | Description
nVendorId | Reference that, on return from the method call, will contain the number representing the vendor's (manufacturer) identifier (also known as VID or MID) for the MIDI DJ Console. The list of known identifiers can be found inside the MSDN website
nProductId | Reference that, on return from the method call, will contain the number representing the product's identifier (also known as PID) for the MIDI DJ Console. The list of known identifiers can be found inside the MSDN website

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileInfoStringGet method

MidiDjConsole.ProfileInfoStringGet method

Remarks

Obtains a string containing information about the DJ Console profile. The current specific information string can be modified through the MidiDjConsole.ProfileInfoStringSet method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileInfoStringGet (

nStringType as enumProfileInfoStringType

) as String

[C#]

public string MidiDjConsole.ProfileInfoStringGet (

enumProfileInfoStringType nStringType

);

[C++]

public: string MidiDjConsole.ProfileInfoStringGet (

enumProfileInfoStringType nStringType

);

Parameter

Description

nStringType

Specifies the type of information string to obtain.

Supported values are the following:

Mnemonic constant | Value | Meaning
PROF_INFO_STRING_DEVICE_NAME | 0 | Name of the MIDI device as reported to the system by the driver of the DJ Console
PROF_INFO_STRING_NAME | 1 | Name of the profile.
PROF_INFO_STRING_DESCRIPTION | 2 | Description of the profile.
PROF_INFO_STRING_AUTHOR | 3 | Author which developed the profile
PROF_INFO_STRING_URL | 4 | URL to a web page containing eventual further information about the profile

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested information.


MidiDjConsole.ProfileInfoStringSet method

MidiDjConsole.ProfileInfoStringSet method

Remarks

Modifies a string containing information about the DJ Console profile. The current specific information string can be obtained through the MidiDjConsole.ProfileInfoStringGet method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileInfoStringSet (

nStringType as enumProfileInfoStringType,

strInfo as String

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileInfoStringSet (

enumProfileInfoStringType nStringType,

string strInfo

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileInfoStringSet (

enumProfileInfoStringType nStringType,

string strInfo

);

Parameter

Description

nStringType

Specifies the type of information string to modify.

Supported values are the following:

Mnemonic constant | Value | Meaning
PROF_INFO_STRING_DEVICE_NAME | 0 | Name of the MIDI device as reported to the system by the driver of the DJ Console
PROF_INFO_STRING_NAME | 1 | Name of the profile. The name's string is UNICODE compliant so can support languages using the double-byte convention.
PROF_INFO_STRING_DESCRIPTION | 2 | Description of the profile. The description's string is UNICODE compliant so can support languages using the double-byte convention.
PROF_INFO_STRING_AUTHOR | 3 | Author which developed the profile The author's string is UNICODE compliant so can support languages using the double-byte convention.
PROF_INFO_STRING_URL | 4 | URL to a web page containing eventual further information about the profile

strInfo

String containing information to insert.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileItemAdd method

MidiDjConsole.ProfileItemAdd method

Remarks

Adds a new item inside the profile of the DJ Console. The added item can be modified at a later time through the MidiDjConsole.ProfileItemModify method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileItemAdd (

strItemName as String,

nItemType as enumDjConsoleItemType,

strItemDescr as String,

strItemTag as String

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileItemAdd (

string strItemName,

enumDjConsoleItemType nItemType,

string strItemDescr,

string strItemTag

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileItemAdd (

string strItemName,

enumDjConsoleItemType nItemType,

string strItemDescr,

string strItemTag

);

Parameter

Description

strItemName

String containing the name of the new item.

Although not mandatory, it's strongly suggested to assign to the new item the same name assigned by the technical specifications of the specific DJ Console for which the profile is being written.

Duplication of items names is not allowed: if an other item having the same name should be already available inside the profile, the call to this method would fail and would return an error code; you can know if a specific name has already been assigned to an existing item through the MidiDjConsole.ProfileItemExistsByName method.

The item's name is UNICODE compliant so can support languages using the double-byte convention.

nItemType

Specifies the type of the item to add to the profile.

Supported values are the following:

Mnemonic constant | Value | Meaning
DJC_ITEM_TYPE_BUTTON | 0 | Simple push button control
DJC_ITEM_TYPE_BUTTON_WITH_LED | 1 | Push button control with an embedded led driven by the same MIDI command. The usage of this type is not mandatory when the push button and its led have the same MIDI command; if you want you can keep the push button separated from its led inside the profile.
DJC_ITEM_TYPE_RANGE | 2 | Range control: sliders, rotary knobs and jog wheels are included in this category.
DJC_ITEM_TYPE_LED | 3 | Led control or VFD (Vacuum Fluorescent Display) symbol driven as a led.
DJC_ITEM_TYPE_DISPLAY | 4 | VFD (Vacuum Fluorescent Display) element not driven as a simple led, for example the track number or the position of the track.

strItemDescr

String containing the friendly description of the item.

strItemTag

String containing the tag string of the item. You can use this string to assign a custom behaviour to the item of the profile without affecting any of its other settings or causing side effects.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileItemCountGet method

MidiDjConsole.ProfileItemCountGet method

Remarks

Enumerates items contained inside the profile of the DJ Console. After completing the enumeration, the name of each item can be retrieved through the MidiDjConsole.ProfileItemNameGet method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.ProfileItemCountGet (

ByRef nCount as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileItemCountGet (

ref Int32 nCount

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileItemCountGet (

Int32 __gc *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the number of available items. Items belonging to a specific type (like buttons, leds, etc.) can be enumerated using the MidiDjConsole.ProfileTypedItemCountGet method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileItemExistsByName method

MidiDjConsole.ProfileItemExistsByName method

Remarks

Verify the presence of an item having the given name inside the profile of the DJ Console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileItemExistsByName (

strItemName as String

) as Boolean

[C#]

public bool MidiDjConsole.ProfileItemExistsByName (

string strItemName

);

[C++]

public: bool MidiDjConsole.ProfileItemExistsByName (

string strItemName

);

Parameter | Description
strItemName | String containing the name of the item.

Return value

Value | Meaning
TRUE | The item having the given name is available inside the profile of the DJ Console.
FALSE | The item having the given name is not available inside the profile of the DJ Console.


MidiDjConsole.ProfileItemInfoStringGet method

MidiDjConsole.ProfileItemInfoStringGet method

Remarks

Obtains a string containing information about a specific item contained inside the DJ Console profile.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileItemInfoStringGet (

strItemName as String,

nStringType as enumProfileItemInfoStringType

) as String

[C#]

public string MidiDjConsole.ProfileItemInfoStringGet (

string strItemName,

enumProfileItemInfoStringType nStringType

);

[C++]

public: string MidiDjConsole.ProfileItemInfoStringGet (

string strItemName,

enumProfileItemInfoStringType nStringType

);

Parameter

Description

strItemName

String containing the name of the item.

nStringType

Specifies the type of information string to obtain.

Supported values are the following:

Mnemonic constant | Value | Meaning
DJC_ITEM_STRING_DESCRIPTION | 0 | Returns the friendly description of the item.
DJC_ITEM_STRING_TAG | 1 | Returns the tag string of the item.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested information.


MidiDjConsole.ProfileItemModify method

MidiDjConsole.ProfileItemModify method

Remarks

Modifies an existing item contained inside the profile of the DJ Console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileItemModify (

strItemName as String,

nItemType as enumDjConsoleItemType,

strItemDescr as String,

strItemTag as String

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileItemModify (

string strItemName,

enumDjConsoleItemType nItemType,

string strItemDescr,

string strItemTag

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileItemModify (

string strItemName,

enumDjConsoleItemType nItemType,

string strItemDescr,

string strItemTag

);

Parameter

Description

strItemName

String containing the name of the item to modify.

If no item with this specific name should be available inside the profile, the method would fail and would return an error code.

The item's name is UNICODE compliant so can support languages using the double-byte convention.

nItemType

Specifies the type of the item.

Supported values are the following:

Mnemonic constant | Value | Meaning
DJC_ITEM_TYPE_BUTTON | 0 | Simple push button control
DJC_ITEM_TYPE_BUTTON_WITH_LED | 1 | Push button control with an embedded led driven by the same MIDI command. The usage of this type is not mandatory when the push button and its led have the same MIDI command; if you want you can keep the push button separated from its led inside the profile.
DJC_ITEM_TYPE_RANGE | 2 | Range control: sliders, rotary knobs and jog wheels are included in this category.
DJC_ITEM_TYPE_LED | 3 | Led control or VFD (Vacuum Fluorescent Display) symbol driven as a led.
DJC_ITEM_TYPE_DISPLAY | 4 | VFD (Vacuum Fluorescent Display) element not driven as a simple led, for example the track number or the position of the track.

strItemDescr

String containing the friendly description of the item.

strItemTag

String containing the tag string of the item. You can use this string to assign a custom behaviour to the item of the profile without affecting any of its other settings or causing side effects.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileItemNameGet method

MidiDjConsole.ProfileItemNameGet method

Remarks

Obtains the name of a specific item contained inside the profile of the DJ Console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileItemNameGet (

nIndex as Int32

) as String

[C#]

public string MidiDjConsole.ProfileItemNameGet (

Int32 nIndex

);

[C++]

public: string MidiDjConsole.ProfileItemNameGet (

Int32 nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the item whose name must be obtained. Existing items can be enumerated through the MidiDjConsole.ProfileItemCountGet method.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the name of the item. The item's name is UNICODE compliant so can support languages using the double-byte convention.


MidiDjConsole.ProfileItemRemove method

MidiDjConsole.ProfileItemRemove method

Remarks

Removes an existing item from the profile of the DJ Console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileItemRemove (

strItemName as String

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileItemRemove (

string strItemName

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileItemRemove (

string strItemName

);

Parameter | Description
strItemName | String containing the name of the item to remove.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileItemTypeGet method

MidiDjConsole.ProfileItemTypeGet method

Remarks

Obtains the type of physical control for an item available inside the profile of the DJ Console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileItemTypeGet (

strItemName as String,

ByRef nItemType as enumDjConsoleItemType

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileItemTypeGet (

string strItemName,

ref enumDjConsoleItemType nItemType

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileItemTypeGet (

string strItemName,

enumDjConsoleItemType __gc *nItemType

);

Parameter

Description

strItemName

String containing the name of the item whose type must be retrieved.

nItemType

Reference that, on return from the method call, will contain the type of the item.

Supported values are the following:

Mnemonic constant | Value | Meaning
DJC_ITEM_TYPE_BUTTON | 0 | The item is a push button control.
DJC_ITEM_TYPE_BUTTON_WITH_LED | 1 | The item is a button control with an embedded led are enumerated.
DJC_ITEM_TYPE_RANGE | 2 | The item is a range control.
DJC_ITEM_TYPE_LED | 3 | The item is a led control or a VFD (Vacuum Fluorescent Display) symbol driven as a led.
DJC_ITEM_TYPE_DISPLAY | 4 | The item is a VFD (Vacuum Fluorescent Display) element not driven as a simple led, for example the track number or the position of the track.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileInternalCountGet method

MidiDjConsole.ProfileInternalCountGet method

Remarks

Enumerates profiles of DJ Console models already stored inside the component. After completing the enumeration, the name of each profile can be retrieved through the MidiDjConsole.ProfileInternalNameGet method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.ProfileInternalCountGet (

ByRef nCount as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileInternalCountGet (

ref Int32 nCount

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileInternalCountGet (

Int32 __gc *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the number of available profiles.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileInternalLoad method

MidiDjConsole.ProfileInternalLoad method

Remarks

Loads a profile, written for a specific model of DJ Console, which is already stored internally to the component.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileInternalLoad (

nProfile as enumInternalProfiles

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileInternalLoad (

enumInternalProfiles nProfile

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileInternalLoad (

enumInternalProfiles nProfile

);

Parameter

Description

nProfile

Identifier of the internal profile.

The total number of internal profiles stored inside the component can be obtained through the MidiDjConsole.ProfileInternalCountGet method.

Below the table containing models of DJ Consoles for which there is the availability of an internal profile:

Mnemonic constant | Value | Meaning
PROFILE_HERCULES_DJ_CONTROL_INSTINCT | 0 | Profile for Hercules DJ Control Instinct
PROFILE_NUMARK_DJ2GO | 1 | Profile for Numark DJ2GO
PROFILE_DENON_DN_HC4500 | 2 | Profile for Denon DN-HC4500

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileInternalNameGet method

MidiDjConsole.ProfileInternalNameGet method

Remarks

Obtains the name of a specific DJ Console profile already stored inside the component.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileInternalNameGet (

nProfile as enumInternalProfiles

) as String

[C#]

public string MidiDjConsole.ProfileInternalNameGet (

enumInternalProfiles nProfile

);

[C++]

public: string MidiDjConsole.ProfileInternalNameGet (

enumInternalProfiles nProfile

);

Parameter

Description

nProfile

Identifier of the internal profile.

The total number of internal profiles stored inside the component can be obtained through the MidiDjConsole.ProfileInternalCountGet method.

Below the table containing models of DJ Consoles for which there is the availability of an internal profile:

Mnemonic constant | Value | Meaning
PROFILE_HERCULES_DJ_CONTROL_INSTINCT | 0 | Profile for Hercules DJ Control Instinct
PROFILE_NUMARK_DJ2GO | 1 | Profile for Numark DJ2GO
PROFILE_DENON_DN_HC4500 | 2 | Profile for Denon DN-HC4500

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the name of the profile.


MidiDjConsole.ProfileLedBlink method

MidiDjConsole.ProfileLedBlink method

Remarks

Starts blinking the physical led associated to the given led item.

For DJ Consoles not supporting native blinking there is the possibility to simulate blinking programmatically by specifying a certain delay: in case of simulation the component will send to the console the MIDI command for switching the led on and off set through a previous call to the MidiDjConsole.ProfileLedMidiCommandSet method or loaded through an eventual call to the MidiDjConsole.ProfileLoad method.

Blinking can be stopped at any time by switching the same led on or off through the MidiDjConsole.ProfileLedSwitch method.

Certain models of console come with a specific MIDI command for blinking a led natively but usually don't allow specifying at which rate this should occur: through simulation, the usage of this specific method gives more freedom about the blinking rate also for console supporting native blinking at a fixed rate.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileLedBlink (

strItemName as String,

bSimulated as Boolean,

nBlinkDelay as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileLedBlink (

string strItemName,

bool bSimulated,

Int32 nBlinkDelay

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileLedBlink (

string strItemName,

bool bSimulated,

Int32 nBlinkDelay

);

Parameter

Description

strItemName

String containing the name of the led item.

If no led item with this specific name should be available inside the profile, the method would fail and would return an error code.

bSimulated

Boolean value specifying if the blinking is simulated or native.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Led blinking occurs natively by sending to the console the appropriate MIDI command. When this option is selected the nBlinkDelay parameter below is ignored.
BOOL_TRUE | 1 | Led blinking is simulated by the control which automatically sends to the console the sequence of on/off MIDI commands. The blink rate is determined through the nBlinkDelay parameter below.

nBlinkDelay

Number representing the applied blinking rate expressed in milliseconds. The minimal accepted value is 50 milliseconds; values under this limit will be automatically capped to 50.

If for example this parameter should be set to 1000, the led would start blinking by staying on for 1 seconds, then off for 1 seconds and so on.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileLedMidiCommandGet method

MidiDjConsole.ProfileLedMidiCommandGet method

Remarks

Obtains parameters of the short MIDI command specific for a led item stored inside the profile. See the MidiDjConsole.ProfileLedMidiCommandSet method for details about the structure of a short MIDI command representing a led item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileLedMidiCommandGet (

strItemName as String,

ByRef nMidiCommandOn as Int16,

ByRef nMidiCommandOff as Int16,

ByRef nMidiCommandBlink as Int16,

ByRef nMidiChannel as Int16,

ByRef nMidiDataOn as Int16,

ByRef nMidiDataOff as Int16,

ByRef nMidiDataBlink as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileLedMidiCommandGet (

string strItemName,

ref Int16 nMidiCommandOn,

ref Int16 nMidiCommandOff,

ref Int16 nMidiCommandBlink,

ref Int16 nMidiChannel,

ref Int16 nMidiDataOn,

ref Int16 nMidiDataOff,

ref Int16 nMidiDataBlink

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileLedMidiCommandGet (

string strItemName,

Int16 __gc *nMidiCommandOn,

Int16 __gc *nMidiCommandOff,

Int16 __gc *nMidiCommandBlink,

Int16 __gc *nMidiChannel,

Int16 __gc *nMidiDataOn,

Int16 __gc *nMidiDataOff,

Int16 __gc *nMidiDataBlink

);

Parameter

Description

strItemName

String containing the name of the led item.

If no led item with this specific name should be available inside the profile, the method would fail and would return an error code.

nMidiCommandOn

Reference that, on return from the method call, will contain the number representing the MIDI command issued when the physical led needs to be switched on.

nMidiCommandOff

Reference that, on return from the method call, will contain the number representing the MIDI command issued when the physical led needs to be switched off: in some case this value could be identical to the value of the nMidiCommandOn parameter in which case the on/off status would be identified by different values of the nMidiDataOn and nMidiDataOff parameters below.

nMidiCommandBlink

Reference that, on return from the method call and only for DJ Consoles supporting native blinking, will contain the number representing the MIDI command issued when the physical led needs to blink.

For DJ Consoles not supporting native blinking, the returned value will be 0.

nMidiChannel

Reference that, on return from the method call, will contain the number representing the MIDI channel.

Some DJ Console makes use of this parameter in order to discriminate between the DJ Console's decks, in other cases it's simply left to 0.

nMidiDataOn

Reference that, on return from the method call, will contain the number representing the "Data" parameter of the MIDI command issued when the physical led needs to be switched on.

The "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicates the code of the led and its status (on/off).

Separate values of the "Data1" and "Data2" bytes can be extracted from this parameter using custom functions and/or macros.

nMidiDataOff

Reference that, on return from the method call, will contain the number representing the "Data" parameter of the MIDI command issued when the physical led needs to be switched off.

As mentioned above, the "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicates the code of the led and its status (on/off): in some case this value could be identical to the value of the nMidiDataOn parameter in which case the on/off status would be identified by different values of the nMidiCommandOn and nMidiCommandOff parameters above.

Separate values of the "Data1" and "Data2" bytes can be combined in one single 16 bits integer value using custom functions and/or macros.

nMidiDataBlink

Reference that, on return from the method call and only for DJ Consoles supporting native blinking, will contain the number representing the "Data" parameter of the MIDI command issued when the physical led needs to be blinked.

For DJ Consoles not supporting native blinking, the returned value will be 0.

As mentioned above, the "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicates the code of the led and its status (on/off/blink).

Separate values of the "Data1" and "Data2" bytes can be combined in one single 16 bits integer value using custom functions and/or macros.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileLedMidiCommandSet method

MidiDjConsole.ProfileLedMidiCommandSet method

Remarks

Sets parameters of the short MIDI command specific for a led item stored inside the profile. Current parameters of the short MIDI command can be obtained through the MidiDjConsole.ProfileLedMidiCommandGet method.

A short command is sent by the instance of the component to the DJ Console when there is the need to switch a physical led on or off on the DJ Console.

The short MIDI command is composed of 3 bytes combining 4 elements:

· One byte composed by the code of the MIDI Command, typically a "Note On" (hex 90) or a "Note off" (hex 80) or a "Control change" (hex B0), on the more significant 4 bits and by the MIDI channel on the less significant 4 bits.
· Two bytes of MIDI "Data": the combinations of these 2 bytes usually indicates the physical led of the DJ console and, in some case, its on/off status.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileLedMidiCommandSet (

strItemName as String,

nMidiCommandOn as Int16,

nMidiCommandOff as Int16,

nMidiCommandBlink as Int16,

nMidiChannel as Int16,

nMidiDataOn as Int16,

nMidiDataOff as Int16,

nMidiDataBlink as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileLedMidiCommandSet (

string strItemName,

Int16 nMidiCommandOn,

Int16 nMidiCommandOff,

Int16 nMidiCommandBlink,

Int16 nMidiChannel,

Int16 nMidiDataOn,

Int16 nMidiDataOff,

Int16 nMidiDataBlink

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileLedMidiCommandSet (

string strItemName,

Int16 nMidiCommandOn,

Int16 nMidiCommandOff,

Int16 nMidiCommandBlink,

Int16 nMidiChannel,

Int16 nMidiDataOn,

Int16 nMidiDataOff,

Int16 nMidiDataBlink

);

Parameter

Description

strItemName

String containing the name of the led item.

If no led item with this specific name should be available inside the profile, the method would fail and would return an error code.

nMidiCommandOn

The number representing the MIDI command issued when the physical led needs to be switched on.

nMidiCommandOff

The number representing the MIDI command issued when the physical led needs to be switched off: in some case this value could be identical to the value of the nMidiCommandOn parameter in which case the on/off status would be identified by different values of the nMidiDataOn and nMidiDataOff parameters below.

nMidiCommandBlink

The number representing the MIDI command issued when the physical led needs to blink.

Only intended for usage with DJ Consoles supporting blink natively, set this parameter to 0 for other DJ Consoles.

nMidiChannel

The number representing the MIDI channel.

Some DJ Console makes use of this parameter in order to discriminate between the DJ Console's decks, in other cases it's simply left to 0.

nMidiDataOn

The number representing the "Data" parameter of the MIDI command issued when the physical led needs to be switched on.

The "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicates the code of the led and its status (on/off).

Separate values of the "Data1" and "Data2" bytes can be extracted from this parameter using custom functions and/or macros.

nMidiDataOff

The number representing the "Data" parameter of the MIDI command issued when the physical led needs to be switched off.

As mentioned above, the "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicates the code of the led and its status (on/off): in some case this value could be identical to the value of the nMidiDataOn parameter in which case the on/off status would be identified by different values of the nMidiCommandOn and nMidiCommandOff parameters above.

Separate values of the "Data1" and "Data2" bytes can be combined in one single 16 bits integer value using custom functions and/or macros.

nMidiDataBlink

The number representing the "Data" parameter of the MIDI command issued when the physical led needs to be blinked.

Only intended for usage with DJ Consoles supporting blink natively, set this parameter to 0 for other DJ Consoles.

As mentioned above, the "Data" parameter is a 16 bits integer value which combines 2 bytes ("Data1" and "Data2") which usually indicates the code of the led and its status (on/off/blink).

Separate values of the "Data1" and "Data2" bytes can be combined in one single 16 bits integer value using custom functions and/or macros.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileLedNameGetByMidiCommand method

MidiDjConsole.ProfileLedNameGetByMidiCommand method

Remarks

Given parameters of a short MIDI command, obtains the name of the led item stored inside the DJ Console profile having this specific MIDI command, if available. See the MidiDjConsole.ProfileLedMidiCommandSet method for details about the structure of a short MIDI command representing a led item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileLedNameGetByMidiCommand (

nMidiCommandOn as Int16,

nMidiCommandOff as Int16,

nMidiCommandBlink as Int16,

nMidiChannel as Int16,

nMidiDataOn as Int16,

nMidiDataOff as Int16,

nMidiDataBlink as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileLedNameGetByMidiCommand (

Int16 nMidiCommandOn,

Int16 nMidiCommandOff,

Int16 nMidiCommandBlink,

Int16 nMidiChannel,

Int16 nMidiDataOn,

Int16 nMidiDataOff,

Int16 nMidiDataBlink

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileLedNameGetByMidiCommand (

Int16 nMidiCommandOn,

Int16 nMidiCommandOff,

Int16 nMidiCommandBlink,

Int16 nMidiChannel,

Int16 nMidiDataOn,

Int16 nMidiDataOff,

Int16 nMidiDataBlink

);

Parameter

Description

nMidiCommandOn

The number representing the MIDI command issued when the physical led needs to be switched on.

nMidiCommandOff

The number representing the MIDI command issued when the physical led needs to be switched off.

nMidiCommandBlink

The number representing the MIDI command issued when the physical led needs to be blinked.

Only intended for usage with DJ Consoles supporting blink natively, set this parameter to 0 for other DJ Consoles.

nMidiChannel

The number representing the MIDI channel.

nMidiDataOn

The number representing the "Data" parameter of the MIDI command issued when the physical led needs to be switched on.

nMidiDataOff

The number representing the "Data" parameter of the MIDI command issued when the physical led needs to be switched off.

nMidiDataBlink

The number representing the "Data" parameter of the MIDI command issued when the physical led needs to be blinked.

Only intended for usage with DJ Consoles supporting blink natively, set this parameter to 0 for other DJ Consoles.

Return value

Value | Meaning
Empty string | No led item available having the provided MIDI command is stored inside the profile.
Valid string | String containing the name of the led item having the provided MIDI command.


MidiDjConsole.ProfileLedSwitch method

MidiDjConsole.ProfileLedSwitch method

Remarks

Switches on or off the physical led associated to a led item, stored inside the profile, by sending to the DJ Console the related MIDI command set through a previous call to the MidiDjConsole.ProfileLedMidiCommandSet method or loaded through an eventual call to the MidiDjConsole.ProfileLoad method.

A led can also work in blink mode through the MidiDjConsole.ProfileLedBlink method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileLedSwitch (

strItemName as String,

bSwitchOn as Boolean

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileLedSwitch (

string strItemName,

bool bSwitchOn

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileLedSwitch (

string strItemName,

bool bSwitchOn

);

Parameter

Description

strItemName

String containing the name of the led item.

If no led item with this specific name should be available inside the profile, the method would fail and would return an error code.

bSwitchOn

Boolean value that specifies if the led must be switched on or off.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Switch the led off
BOOL_TRUE | 1 | Switch the led on

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileLoad method

MidiDjConsole.ProfileLoad method

Remarks

Loads a profile, written for a specific model of DJ Console, from a XML file stored on disk into the instance of the component. A XML file can be written manually through a normal text editor or saved through a call to MidiDjConsole.ProfileSave or MidiDjConsole.ProfileSaveWithoutDevice methods.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileLoad (

strPathname as String

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileLoad (

string strPathname

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileLoad (

string strPathname

);

Parameter | Description
strPathname | String representing the absolute pathname of the XML file containing the DJ Console profile to load.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileRangeMidiCommandGet method

MidiDjConsole.ProfileRangeMidiCommandGet method

Remarks

Obtains parameters of the short MIDI command specific for a range control item (slider, rotary knob or Jog wheel) stored inside the profile. See the MidiDjConsole.ProfileRangeMidiCommandSet method for details about the structure of a short MIDI command representing a range control item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileRangeMidiCommandGet (

strItemName as String,

ByRef nMidiCommand as Int16,

ByRef nMidiChannel as Int16,

ByRef nMidiControlCode as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileRangeMidiCommandGet (

string strItemName,

ref Int16 nMidiCommand,

ref Int16 nMidiChannel,

ref Int16 nMidiControlCode

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileRangeMidiCommandGet (

string strItemName,

Int16 __gc *nMidiCommand,

Int16 __gc *nMidiChannel,

Int16 __gc *nMidiControlCode

);

Parameter | Description
strItemName | String containing the name of the range control item. If no range control item with this specific name should be available inside the profile, the method would fail and would return an error code.
nMidiCommand | Reference that, on return from the method call, will contain the number representing the MIDI command issued when the range control is moved. In many cases the value of this parameter is 176 (hex B0) which indicates a "Control change" MIDI command.
nMidiChannel | Reference that, on return from the method call, will contain the number representing the MIDI channel.
nMidiControlCode | Reference that, on return from the method call, will contain the number representing the code of the physical range control item (slider, rotary knob or Jog wheel).

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileRangeMidiCommandSet method

MidiDjConsole.ProfileRangeMidiCommandSet method

Remarks

Sets parameters of the short MIDI command specific for a range control item (slider, rotary knob or Jog wheel) stored inside the profile. Current parameters of the short MIDI command can be obtained through the MidiDjConsole.ProfileRangeMidiCommandGet method.

A short command is sent to the instance of the component by the DJ Console when a physical range control is moved on the DJ Console.

The short MIDI command is composed of 3 bytes combining 4 elements:

· One byte composed by the code of the MIDI Command, typically a "Control change" (hex B0) on the more significant 4 bits and by the MIDI channel on the less significant 4 bits.
· One first byte of MIDI "Data", usually indicated as "Data1", representing the code of the physical control which was moved.
· One second byte of MIDI "Data", usually indicated as "Data2", representing the value reported by the moved physical control.

When setting the short MIDI command specific for a control range item, only the Data1 field is important while the Data2 field, being variable, can be ignored.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileRangeMidiCommandSet (

strItemName as String,

nMidiCommand as Int16,

nMidiChannel as Int16,

nMidiControlCode as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileRangeMidiCommandSet (

string strItemName,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileRangeMidiCommandSet (

string strItemName,

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

Parameter | Description
strItemName | String containing the name of the range control item. If no range control item with this specific name should be available inside the profile, the method would fail and would return an error code.
nMidiCommand | The MIDI command issued when the range control is moved. In many cases the value of this parameter is 176 (hex B0) which indicates a "Control change" MIDI command.
nMidiChannel | The number representing the MIDI channel.
nMidiControlCode | The number representing the code (Data1 field described above) of the physical range control item (slider, rotary knob or Jog wheel).

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileRangeNameGetByMidiCommand method

MidiDjConsole.ProfileRangeNameGetByMidiCommand method

Remarks

Given parameters of a short MIDI command, obtains the name of the range control item (slider, rotary knob or Jog wheel) stored inside the DJ Console profile having this specific MIDI command, if available. See the MidiDjConsole.ProfileRangeMidiCommandSet method for details about the structure of a short MIDI command representing a range control item.

The combination of MIDI command parameters is usually defined inside the technical specifications of the physical DJ Console and may vary a lot depending upon the DJ Console in use.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileRangeNameGetByMidiCommand (

nMidiCommand as Int16

nMidiChannel as Int16,

nMidiControlCode as Int16

) as String

[C#]

public string MidiDjConsole.ProfileRangeNameGetByMidiCommand (

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

[C++]

public: string MidiDjConsole.ProfileRangeNameGetByMidiCommand (

Int16 nMidiCommand,

Int16 nMidiChannel,

Int16 nMidiControlCode

);

Parameter | Description
nMidiCommand | The MIDI command issued when the range control is moved. In many cases the value of this parameter is 176 (hex B0) which indicates a "Control change" MIDI command.
nMidiChannel | The number representing the MIDI channel.
nMidiControlCode | The number representing the code of the physical range control item (slider, rotary knob or Jog wheel).

Return value

Value | Meaning
Empty string | No range control item available having the provided MIDI command is stored inside the profile.
Valid string | String containing the name of the range control item having the provided MIDI command.


MidiDjConsole.ProfileReset method

MidiDjConsole.ProfileReset method

Remarks

Reset the profile currently loaded into the instance of the component.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.ProfileReset (

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileReset (

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileReset (

);

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileSave method

MidiDjConsole.ProfileSave method

Remarks

Saves the current profile, written for a specific DJ Console and loaded into the instance of the component, into a XML file for later usage. A saved profile can be reloaded at a later time through the MidiDjConsole.ProfileLoad method.

Due to the fact that the profile will contain the product and vendor identifiers for a specific DJ Console, the usage of this methods requires the DJ Console to be physically connected to the system and also connected to the instance of the component through a previous call to the MidiDjConsole.Connect method. In case the DJ Console shouldn't be physically connected to the system or connected to the instance of the component, you could in any case save the profile while "offline" through the MidiDjConsole.ProfileSaveWithoutDevice method.

The XML file is normally saved in ANSI format: in case one or more of the saved strings should contain UNICODE characters, the file would be automatically saved in UTF-8 format.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileSave (

strPathname as String,

bStoreHexValues as Boolean

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileSave (

string strPathname,

bool bStoreHexValues

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileSave (

string strPathname,

bool bStoreHexValues

);

Parameter

Description

strPathname

String representing the absolute pathname of the destination XML file to save.

bStoreHexValues

Boolean value that specifies if the numerical values of the various profile's items are stored inside the file as decimal or hexadecimal values.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Numerical values are stored in decimal format.
BOOL_TRUE | 1 | Numerical values are stored in hexadecimal format with the "0x" prefix.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileSaveWithoutDevice method

MidiDjConsole.ProfileSaveWithoutDevice method

Remarks

Saves a DJ Console profile into a XML file for later usage. A saved profile can be reloaded at a later time through the MidiDjConsole.ProfileLoad method.

Differently from the MidiDjConsole.ProfileSave method, which requires the specific DJ Console to be physically connected to the system and to the instance of the component, this method can be used while working "offline".

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileSaveWithoutDevice (

strPathname as String,

bStoreHexValues as Boolean

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileSaveWithoutDevice (

string strPathname,

bool bStoreHexValues

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileSaveWithoutDevice (

string strPathname,

bool bStoreHexValues

);

Parameter

Description

strPathname

String representing the absolute pathname of the destination XML file to save.

bStoreHexValues

Boolean value that specifies if the numerical values of the various profile's items are stored inside the file as decimal or hexadecimal values..

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Numerical values are stored in decimal format.
BOOL_TRUE | 1 | Numerical values are stored in hexadecimal format with the "0x" prefix.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileTypedItemCountGet method

MidiDjConsole.ProfileTypedItemCountGet method

Remarks

Enumerates items of a specific type contained inside the profile of the DJ Console. After completing the enumeration, the name of each item of the enumerated type can be retrieved through the MidiDjConsole.ProfileTypedItemNameGet method.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDjConsole.ProfileTypedItemCountGet (

nItemType as enumDjConsoleItemType,

ByRef nCount as Int32

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiDjConsole.ProfileTypedItemCountGet (

enumDjConsoleItemType nItemType,

ref Int32 nCount

);

[C++]

public: enumDjcErrorCodes MidiDjConsole.ProfileTypedItemCountGet (

enumDjConsoleItemType nItemType,

Int32 __gc *nCount

);

Parameter

Description

nItemType

Specifies the type of item whose number must be obtained.

Supported values are the following:

Mnemonic constant | Value | Meaning
DJC_ITEM_TYPE_ALL | -1 | Include all types of items inside the enumeration. This option has the same effect of a call to the MidiDjConsole.ProfileItemCountGet method.
DJC_ITEM_TYPE_BUTTON | 0 | Only simple push button controls are enumerated.
DJC_ITEM_TYPE_BUTTON_WITH_LED | 1 | Only push button controls with an embedded led are enumerated.
DJC_ITEM_TYPE_RANGE | 2 | Only range controls are enumerated.
DJC_ITEM_TYPE_LED | 3 | Only led and VFD (Vacuum Fluorescent Display) controls are enumerated.
DJC_ITEM_TYPE_DISPLAY | 4 | Only VFD (Vacuum Fluorescent Display) elements not driven as a simple led are enumerated.

nCount

Reference that, on return from the method call, will contain the number of items of the given type

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiDjConsole.ProfileTypedItemNameGet method

MidiDjConsole.ProfileTypedItemNameGet method

Remarks

Obtains the name of a specific item contained inside the profile of the DJ Console.

For further details about interfacing with MIDI DJ Consoles see the MidiDjConsole object section and the How to manage MIDI DJ consoles tutorial.

Syntax

[Visual Basic]

MidiDevices.MidiDjConsole.ProfileTypedItemNameGet (

nItemType as enumDjConsoleItemType,

nIndex as Int32

) as String

[C#]

public string MidiDjConsole.ProfileTypedItemNameGet (

enumDjConsoleItemType nItemType,

Int32 nIndex

);

[C++]

public: string MidiDjConsole.ProfileTypedItemNameGet (

enumDjConsoleItemType nItemType,

Int32 nIndex

);

Parameter

Description

nItemType

Specifies the type of item whose name must be obtained.

Supported values are the following:

Mnemonic constant | Value | Meaning
DJC_ITEM_TYPE_ALL | -1 | Obtains the name of a control without distinction of type. This option has the same effect of a call to the MidiDjConsole.ProfileItemNameGet method.
DJC_ITEM_TYPE_BUTTON | 0 | Obtains the name of a push button control.
DJC_ITEM_TYPE_BUTTON_WITH_LED | 1 | Obtains the name of a button control with an embedded led are enumerated.
DJC_ITEM_TYPE_RANGE | 2 | Obtains the name of a range control.
DJC_ITEM_TYPE_LED | 3 | Obtains the name of a led control or VFD (Vacuum Fluorescent Display) symbol.
DJC_ITEM_TYPE_DISPLAY | 4 | Obtains the name of a VFD (Vacuum Fluorescent Display) element not driven as a simple led, for example the track number or the position of the track.

nIndex

Number representing the zero-based index of the item whose name must be obtained. Existing items of a specific type can be enumerated through the MidiDjConsole.ProfileTypedItemCountGet method.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the name of the item.


ClassMidiVirtualKeyboard class

ClassMidiVirtualKeyboard class

The ClassMidiVirtualKeyboard class, accessible through the control's MidiVirtualKeyboard property, contains methods needed to manage a graphical virtual piano keyboard.

The ClassMidiVirtualKeyboard class is implemented through the following methods:

Create

Destroy

GraphicalSettingsGet

GraphicalSettingsSet

MidiInputConnect

MidiInputDisconnect

MidiOutputConnect

MidiOutputDisconnect

Move

Note

RangeSet

Refresh

Show

For further details about the use of the virtual MIDI keyboard see the How to manage the virtual MIDI piano keyboard tutorial.


MidiVirtualKeyboard.Create method

MidiVirtualKeyboard.Create method

Remarks

Creates a new virtual piano keyboard on the given parent window.

Notes played on the virtual piano, through the left button of the mouse, will be directly sent to the MIDI stream in playback on the given player.

Keys pressure/release can be simulated through the MidiVirtualKeyboard.Note method, for example for displaying a note played through an external physical MIDI keyboard attached to one of the MIDI input channels.

The container application is notified each time a key on the virtual keyboard is pressed or released through the MidiKeyboardNotification event.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.Create (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32,

nLowNote as Int16,

nHighNote as Int16,

bSendEventNotif as Boolean,

nOrientation as enumDjcMidiKeyboardOrientations

) as IntPtr

[C#]

public IntPtr MidiVirtualKeyboard.Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Int16 nLowNote,

Int16 nHighNote,

bool bSendEventNotif,

enumDjcMidiKeyboardOrientations nOrientation

);

[C++]

public: IntPtr MidiVirtualKeyboard.Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Int16 nLowNote,

Int16 nHighNote,

bool bSendEventNotif,

enumDjcMidiKeyboardOrientations nOrientation

);

Parameter

Description

hWndParent

Handle of the parent window, usually the container form.

nLeft

Left position of the keyboard window, expressed in client coordinates (pixels) of hWndParent

nTop

Top position of the keyboard window, expressed in client coordinates (pixels) of hWndParent

nWidth

Width of the keyboard window, expressed in pixels

nHeight

Height of the keyboard window, expressed in pixels

nLowNote

Lower note displayed on the virtual piano keyboard. Can be a value between 0 and 127 but must always be a natural note (white key).

nHighNote

Higher note displayed on the virtual piano keyboard. Can be a value between 2 and 127 but must always be a natural note (white key).

bSendEventNotif

Reserved for future uses. Set this value to BOOL_FALSE.

nOrientation

Orientation of the piano keyboard.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_KEYBOARD_ORIENT_HORIZONTAL | 0 | The piano keyboard orientation is horizontal as in the picture below
MIDI_KEYBOARD_ORIENT_VERTICAL_LEFT | 1 | The piano keyboard orientation is left vertical as in the picture below
MIDI_KEYBOARD_ORIENT_VERTICAL_RIGHT | 2 | The piano keyboard orientation is right vertical as in the picture below

Return value

Value | Meaning
IntPtr.Zero | An error occurred, check the LastError property value in order to get the error code
Other values | Handle (HWND) of the new virtual piano keyboard


MidiVirtualKeyboard.Destroy method

MidiVirtualKeyboard.Destroy method

Remarks

Destroys an existing virtual piano keyboard.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.Destroy (

hWndKeyboard as IntPtr

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiVirtualKeyboard.Destroy (

IntPtr hWndKeyboard

);

[C++]

public: enumDjcErrorCodes MidiVirtualKeyboard.Destroy (

IntPtr hWndKeyboard

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.GraphicalSettingsGet method

MidiVirtualKeyboard.GraphicalSettingsGet method

Remarks

Retrieves the current graphical settings for the given virtual piano keyboard. Settings can be modified through the MidiVirtualKeyboard.GraphicalSettingsSet method.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.GraphicalSettingsGet (

hWndKeyboard as IntPtr,

ByRef settings as MIDI_VIRTUAL_KEYBOARD_SETTINGS

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiVirtualKeyboard.GraphicalSettingsGet (

IntPtr hWndKeyboard,

ref MIDI_VIRTUAL_KEYBOARD_SETTINGS settings

);

[C++]

public: enumDjcErrorCodes MidiVirtualKeyboard.GraphicalSettingsGet (

IntPtr hWndKeyboard,

MIDI_VIRTUAL_KEYBOARD_SETTINGS __gc *settings

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method
pParamData | Address of a data structure of type MIDI_VIRTUAL_KEYBOARD_SETTINGS that receives in output graphical settings of the keyboard.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.GraphicalSettingsSet method

MidiVirtualKeyboard.GraphicalSettingsSet method

Remarks

Modifies graphical settings for the given virtual piano keyboard. Current settings can be modified through the MidiVirtualKeyboard.GraphicalSettingsGet method.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.GraphicalSettingsSet (

hWndKeyboard as IntPtr,

settings as MIDI_VIRTUAL_KEYBOARD_SETTINGS

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiVirtualKeyboard.GraphicalSettingsSet (

IntPtr hWndKeyboard,

MIDI_VIRTUAL_KEYBOARD_SETTINGS settings

);

[C++]

public: enumDjcErrorCodes MidiVirtualKeyboard.GraphicalSettingsSet (

IntPtr hWndKeyboard,

MIDI_VIRTUAL_KEYBOARD_SETTINGS settings

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method
pParamData | Address of a data structure of type MIDI_VIRTUAL_KEYBOARD_SETTINGS containing graphical settings to apply to the keyboard.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.MidiInputConnect method

MidiVirtualKeyboard.MidiInputConnect method

Remarks

Connects the virtual piano keyboard to the given MIDI input device. After the connection is established, the connected MIDI input device can be disconnected through the MidiVirtualKeyboard.MidiInputDisconnect method.

In order to establish the connection, the involved input device must have been previously opened through the MidiDevices.Open method.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.MidiInputConnect (

hWndKeyboard as IntPtr,

nDeviceUniqueId as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiVirtualKeyboard.MidiInputConnect (

IntPtr hWndKeyboard,

Int16 nDeviceUniqueId

);

[C++]

public: enumDjcErrorCodes MidiVirtualKeyboard.MidiInputConnect (

IntPtr hWndKeyboard,

Int16 nDeviceUniqueId

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method
nDeviceUniqueId | The unique identifier of the MIDI input device returned by a previous call to the MidiDevices.Open method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.MidiInputDisconnect method

MidiVirtualKeyboard.MidiInputDisconnect method

Remarks

Disconnects the virtual piano keyboard, previously connected through the MidiVirtualKeyboard.MidiInputConnect method, from the given MIDI input device.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.MidiInputDisconnect (

hWndKeyboard as IntPtr

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiVirtualKeyboard.MidiInputDisconnect (

IntPtr hWndKeyboard

);

[C++]

public: enumDjcErrorCodes MidiVirtualKeyboard.MidiInputDisconnect (

IntPtr hWndKeyboard

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.MidiOutputConnect method

MidiVirtualKeyboard.MidiOutputConnect method

Remarks

Connects the virtual piano keyboard to the given MIDI output device. After the connection is established, the connected MIDI output device can be disconnected through the MidiVirtualKeyboard.MidiOutputDisconnect method.

In order to establish the connection, the involved output device must have been previously opened through the MidiDevices.Open method.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.MidiOutputConnect (

hWndKeyboard as IntPtr,

nDeviceUniqueId as Int16

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiVirtualKeyboard.MidiOutputConnect (

IntPtr hWndKeyboard,

Int16 nDeviceUniqueId

);

[C++]

public: enumDjcErrorCodes MidiVirtualKeyboard.MidiOutputConnect (

IntPtr hWndKeyboard,

Int16 nDeviceUniqueId

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method
nDeviceUniqueId | The unique identifier of the MIDI output device returned by a previous call to the MidiDevices.Open method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.MidiOutputDisconnect method

MidiVirtualKeyboard.MidiOutputDisconnect method

Remarks

Disconnects the virtual piano keyboard, previously connected through the MidiVirtualKeyboard.MidiOutputConnect method, from the given MIDI output device.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.MidiOutputDisconnect (

hWndKeyboard as IntPtr

) as enumDjcErrorCodes

[C#]

public enumDjcErrorCodes MidiVirtualKeyboard.MidiOutputDisconnect (

IntPtr hWndKeyboard

);

[C++]

public: enumDjcErrorCodes MidiVirtualKeyboard.MidiOutputDisconnect (

IntPtr hWndKeyboard

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.Move method

MidiVirtualKeyboard.Move method

Remarks

Moves or resizes an existing virtual piano keyboard.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.Move (

hWndKeyboard as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr MidiVirtualKeyboard.Move (

IntPtr hWndKeyboard,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr MidiVirtualKeyboard.Move (

IntPtr hWndKeyboard,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method
nLeft | Left position of the keyboard window, expressed in parent's client coordinates (pixels)
nTop | Top position of the keyboard window, expressed in parent's client coordinates (pixels)
nWidth | Width of the keyboard window, expressed in pixels
nHeight | Height of the keyboard window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.Note method

MidiVirtualKeyboard.Note method

Remarks

Acts on the key corresponding to the given note on the virtual piano keyboard. The key pressure can be real, e.g. generating a note on the MIDI stream, or simulated: in this latest case the key on the keyboard results to be pressed but no sound is generated.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.Note (

hWndKeyboard as IntPtr,

nNote as Int16,

nVelocity as Int16

) as IntPtr

[C#]

public IntPtr MidiVirtualKeyboard.Note (

IntPtr hWndKeyboard,

Int16 nNote,

Int16 nVelocity

);

[C++]

public: IntPtr MidiVirtualKeyboard.Note (

IntPtr hWndKeyboard,

Int16 nNote,

Int16 nVelocity

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method
nNote | Note to play. Can be a key number from 0 to 127; 60 means middle C
nVelocity | Velocity of the note. 0 means key released while values from 1 to 127 mean pressure.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.RangeSet method

MidiVirtualKeyboard.RangeSet method

Remarks

Modifies the range of key notes on the given virtual piano keyboard.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.RangeSet (

hWndKeyboard as IntPtr,

nLowNote as Int16,

nHighNote as Int16

) as IntPtr

[C#]

public IntPtr MidiVirtualKeyboard.RangeSet (

IntPtr hWndKeyboard,

Int16 nLowNote,

Int16 nHighNote

);

[C++]

public: IntPtr MidiVirtualKeyboard.RangeSet (

IntPtr hWndKeyboard,

Int16 nLowNote,

Int16 nHighNote

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method
nLowNote | Lower note displayed on the virtual piano keyboard. Can be a value between 0 and 127 but must always be a natural note (white key).
nHighNote | Higher note displayed on the virtual piano keyboard. Can be a value between 2 and 127 but must always be a natural note (white key).

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.Refresh method

MidiVirtualKeyboard.Refresh method

Remarks

Refreshes an existing virtual piano keyboard.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.Refresh (

hWndKeyboard as IntPtr

) as IntPtr

[C#]

public IntPtr MidiVirtualKeyboard.Refresh (

IntPtr hWndKeyboard

);

[C++]

public: IntPtr MidiVirtualKeyboard.Refresh (

IntPtr hWndKeyboard

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MidiVirtualKeyboard.Show method

MidiVirtualKeyboard.Show method

Remarks

Shows/hides an existing virtual piano keyboard.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

Syntax

[Visual Basic]

MidiVirtualKeyboard.Show (

hWndKeyboard as IntPtr,

bShow as Boolean

) as IntPtr

[C#]

public IntPtr MidiVirtualKeyboard.Show (

IntPtr hWndKeyboard,

bool bShow

);

[C++]

public: IntPtr MidiVirtualKeyboard.Show (

IntPtr hWndKeyboard,

bool bShow

);

Parameter

Description

hWndKeyboard

Handle of the virtual keyboard as returned by the call to the MidiVirtualKeyboard.Create method

bShow

Boolean value that specifies if the given virtual piano keyboard must be shown or hidden.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Hides the keyboard
BOOL_TRUE | Shows the keyboard

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumDjcErrorCodes.ERR_DJC_NOERROR (0) | The method call was successful.


MIDI_VIRTUAL_KEYBOARD_SETTINGS structure

MIDI_VIRTUAL_KEYBOARD_SETTINGS structure

The MIDI_VIRTUAL_KEYBOARD_SETTINGS structure describes the graphical settings applied to a specific virtual piano keyboard. The current settings can be retrieved through the MidiVirtualKeyboard.GraphicalSettingsGet method and modified through the MidiVirtualKeyboard.GraphicalSettingsSet method. Below you can see an example of a horizontal virtual piano keyboard with default colors.

For further details about the use of the virtual MIDI keyboard see the MidiVirtualKeyboard object section and the How to manage the virtual MIDI piano keyboard tutorial.

C# definition

public class MIDI_KEYBOARD_SETTINGS

{

public Color      colorBackground;

public Color      colorWhiteKeys;

public Color      colorBlackKeys;

public Color      colorWhiteKeysBorders;

public Color      colorBlackKeysBorders;

public Color      colorWhiteKeysPressed;

public Color      colorBlackKeysPressed;

public Color      colorWhiteKeysPressedBorders;

public Color      colorBlackKeysPressedBorders;

};

Member | Description
colorBackground | The color used for rendering the keyboard's background (default is set to Black)
colorWhiteKeys | The color used for rendering white keys (default is set to White)
colorBlackKeys | The color used for rendering black keys (default is set to Black)
colorWhiteKeysBorders | The color used for rendering the border of white keys (default is set to Black)
colorBlackKeysBorders | The color used for rendering the border of black keys (default is set to Black)
colorWhiteKeysPressed | The color used for rendering white keys in pressed state (default is set to Light Blue)
colorBlackKeysPressed | The color used for rendering black keys in pressed state (default is set to Light Blue)
colorWhiteKeysPressedBorders | The color used for rendering the border of white keys in pressed state (default is set to Black)
colorBlackKeysPressedBorders | The color used for rendering the border of black keys in pressed state (default is set to Black)