View on
Brandon Fosdick > USB-Descriptor-4 > USB::HID::Report::Field



Annotate this POD

View/Report Bugs
Module Version: 1   Source  


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


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, ... );


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);


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.



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.


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

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


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



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


Get/Set the field's ReportCount property.


Get/Set the field's maximum logical value.


Get/Set the field's minimum logical value.

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

Get/Set both logical_min and logical_max.


Get/Set the field's Usage Page.


Get/Set the field's ReportSize property.


Get/Set the field's Usage.


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


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.


Brandon Fosdick, <bfoz at>


Please report any bugs or feature requests to bug-usb-hid-report-field at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc USB::HID::Report::Field

You can also look for information at:



Copyright 2011 Brandon Fosdick.

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

syntax highlighting: