TITLE:: HIDElementProto
summary:: Prototype HID element to match with HIDFunc
categories:: External Control>HID
related:: Classes/HIDFunc, Classes/HIDdef, Classes/HIDProto, Classes/HID, Classes/HIDElement, Classes/HIDInfo, Guides/Working_with_HID

DESCRIPTION::
Human input devices can be used as controllers for making music. This class can be used in conjunction with link::Classes/HIDFunc:: or link::Classes/HIDdef:: to match incoming messages with a particular link::Classes/HID:: device.

HIDElementProto has all the variables that specify an HID element. The more of these variables you specify, the more need to be matched when filtering the incoming HID data.


CLASSMETHODS::

METHOD:: new
Create a new instance of HIDElementProto.

METHOD:: newType
Create a new instance of HIDElementProto based on usage id and usage page id of the element.

ARGUMENT:: uName
Name of the usage ID to match

ARGUMENT:: pName
Name of the usage page to match

returns:: an HIDElementProto


METHOD:: newTypeID
Create a new instance of HIDElementProto based on usage id and usage page id of the element.

ARGUMENT:: uID
Usage ID to match

ARGUMENT:: pID
Usage page ID to match

returns:: an HIDElementProto

METHOD:: newFromDict
Create a new instance of HIDElementProto based on an IdentityDictionary with a set of parameters to match.


ARGUMENT:: dict
An IdentityDictionary with a set of parameters to match. The keys in the dictionary should be one of the instance variables of HIDElementProto.

returns:: an HIDElementProto



INSTANCEMETHODS::

SUBSECTION:: Instance variables that can be used to match a device

METHOD:: id
The element index that should be matched. This index may vary between operating systems (see also link::Classes/HIDElement::).


METHOD:: usageName
The usage name of the element to match (see also link::Classes/HIDElement::).

METHOD:: pageName
The usage page name of the element to match (see also link::Classes/HIDElement::).

METHOD:: usage
The usage index of the element to match (see also link::Classes/HIDElement::).

METHOD:: usagePage
The usage page index of the element to match (see also link::Classes/HIDElement::).


METHOD:: usageMin
The minimum usage index of the element to match (see also link::Classes/HIDElement::).


METHOD:: usageMax
The maximum usage index of the element to match (see also link::Classes/HIDElement::).



METHOD:: type
The type of the element to match (see also link::Classes/HIDElement::).


METHOD:: typeSpec
The typeSpec of the element to match (see also link::Classes/HIDElement::).


METHOD:: ioType
The IO type of the element to match - input (1), output (2) or feature (3) (see also link::Classes/HIDElement::).


METHOD:: iotypeName
The IO type of the element to match - code::\input::, code::\output:: or code::\feature:: (see also link::Classes/HIDElement::).


SUBSECTION:: Methods to match

METHOD:: matches
Match the argument with the template.


ARGUMENT:: ele
An instance of HIDElement

returns:: a Boolean indicating whether the incoming HID matches the template


METHOD:: shouldMatch
The variables that should be matched when filtering

returns:: a Set with variable names.


SUBSECTION:: Methods to add matching parameters

METHOD:: addTypeMatch
Add a match for usage name and usage page name of the element.

ARGUMENT:: uName
The usage name to match

ARGUMENT:: pName
The page name to match

METHOD:: addTypeIDMatch
Add a match for usage id and usage page id of the element.

ARGUMENT:: uID
The usage id to match

ARGUMENT:: pID
The usage page id to match


METHOD:: addDictionaryMatch
Add an IdentityDictionary with a set of parameters to match. The keys in the dictionary should be one of the instance variables of HIDElementProto.

ARGUMENT:: dict
An IdentityDictionary with a set of parameters to match.



EXAMPLES::

code::
// create an prototype element with usageName \X
c = HIDElementProto.new.usageName_( \X );
a = HIDFunc.proto( { |...args| args.postln; }, c );
a.free;
::