The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
USB-Descriptor-4
River stage zero No dependents
++
/ USB::HID::Report::Field

NAME

USB::HID::Report::Field - USB HID Report Field

SYNOPSIS

An object representation of a USB HID Report Field. USB::HID::Report::Field doesn't directly correspond to any particular part of a HID report desriptor. It provides a convenience interface for specifying the properties of a report field that can be translated into the appropriate descriptor items.

    use USB::HID::Report::Field;

    my $field = USB::HID::Report::Field->new( 'usage' => 1, ... );
    $field->set_attribute('variable');
    ...

DESCRIPTION

USB::HID::Report::Field is an abstract representation of a field in a USB HID Report. When added to an instance of USB::HID::Report it can be used to generate the items in HID Report Descriptor.

Several convenience constructors are provided for creating commonly used field types.

    use USB::HID::Report::Field;

    # Button 1
    my $button = USB::HID::Report::Field->button( 'usage' => 1 );
    # 7 bits of padding
    my $constant = USB::HID::Report::Field->constant(7);

CONSTRUCTORS

Several convenience constructors are provided for creating commonly used field types. Each constructor accepts the same arguments as the default constructor (new()). Some constructors also accept a simplified argument set.

$field = USB::HID::Report::Field->new('usage'=>$usage, ...);

Constructs and returns a new USB::HID::Report::Field object using the passed options. Each option key is the name of an accessor method.

$button = USB::HID::Report::Field->button();

Constructs and returns a USB::HID::Report::Field configured as a button. Usage Page and ReportSize are automatically set and override any corresponding arguments. Specify a Usage to set the button number.

Alternatively, a single scalar can be passed to set the button number:

    $button = USB::HID::Report::Field->button(3);       # Button 3
$padding = USB::HID::Report::Field->constant($num_bits);

Constructs and returns a USB::HID::Report::Field configured to be used as constant padding bits in a report. Pass a single integer to set the number of bits. Alternatively, a hash containing a 'bits' key can be used to set the number of bits.

ARRAYIFICATION

$field->bytes(\%state)

Returns an array of bytes containing all of the items for the field. Uses %state to avoid repeating items that have been emitted by previous fields.

MAIN ITEM ATTRIBUTES

HID report Main Items have a number of attributes that can be set. Anything that isn't explicitly set defaults to 0. These attributes correspond to the names of the bits of the "Main Items" specified on page 28 of the Device Class Definition for Human Interface Devices Version 1.11.

The attribute names accepted by set_attribute are:

    constant variable relative wrap nonlinear noprefered null volatile buffered
    data array absolute nowrap linear preferred nonull nonvolatile bitfield
$field->attributes(...)

Set the list of attributes for the field object and replace any existing list. Returns all currently set attributes.

$field->set_attribute(...)

Add the passed attributes to the current list of attributes. Returns all currently set attributes, including the passed arguments.

ATTRIBUTES

$field->bits($num_bits)

Sets size to 1 and count to $num_bits. Returns count,

$field->count()

Get/Set the field's ReportCount property.

$field->logical_max()

Get/Set the field's maximum logical value.

$field->logical_min()

Get/Set the field's minimum logical value.

$field->logical_range($min, $max)

Get/Set both logical_min and logical_max.

$field->page($page_number)

Get/Set the field's Usage Page.

$field->size()

Get/Set the field's ReportSize property.

$field->usage($usage_number)

Get/Set the field's Usage.

$field->usage_max()

Get/Set the upper end of the usage range for field objects that correspond to multiple Main Items.

$field->usage_min()

Get/Set the lower end of the usage range for field objects that correspond to mutiple Main Items.

$field->usage_range($min, $max)

Get/Set both usage_min and usage_max.

AUTHOR

Brandon Fosdick, <bfoz at bfoz.net>

BUGS

Please report any bugs or feature requests to bug-usb-hid-report-field at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=USB-HID-Report-Field. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc USB::HID::Report::Field

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Brandon Fosdick.

This program is released under the terms of the BSD License.