NAME

UR::Object::Viewer::PlateView - provides a Gtk viewer for displaying 384 or 96 well plates, colorizing wells, and notifying applications about Gtk events on clickable well buttons

SYNOPSIS

# assuming $window is a previously created gtk window

my $plate = new UR::Object::Viewer::PlateView(plate_type=>'384 well plate');
$window->add($plate->get_widget);
$window->show_all();

# wells can be passed in as eithern ames or DNA Locations

my $dl = GSC::DNALocation->get(location_name=>'a06',
                               location_type=>'384 well plate');

# color all of a1 plus a few other wells light green

$plate->set_well_color(wells=>[$dl,'h12','a07'], 
                       sectors=>['a1'], 
                       color=>'light green');

# register a well handler
$plate->register_well_handler(event_type=>'released',
                              code=>\&test,
                              sectors=>['a1'],
                              return_well_info=>['well_name',
                                                 'dna_location']);

DESCRIPTION

This module allows the developer to represent 384 or 96 well plates as sets of buttons. Buttons representing wells can be easily colorized by passing in entire sets of wells, sectors, or both.

Well information can be provided as well number (e.g. well h12 = well 96) or as GSC::DNALocation objects.

The application can also register to be notified of gtk events, such as when a button is clicked and released, or when it receives mouse focus. This is done without exposing the internal Gtk representation to any application.

ToolTips can also be added to wells to present additional information when the user hovers their mouse over buttons.

METHODS

This module provides publicly accessible methods for setting and clearing well colors, registering and deregistering well handlers, and setting ToolTips.

new

The constructor accepts one parameter, which is the type of plate to view.

my $plate = new UR::Object::Viewer::PlateView(plate_type=>'384 well plate');

Current choices are either '384 well plate' or '96 well plate'.

The constructor returns a PlateView object, which is NOT a Gtk widget. You must use the get_widget method to obtain the actual plate viewer widget.

get_widget

Returns the plate viewer widget.

set_well_color

Applies a color to a set of wells, a set of plate sectors, or both.

Wells can be represented by well name ('h12'), well number (96), or by a GSC::DNALocation object.

The color must be a text version of a GTK color.

$plate->set_well_color(sectors=>['a1'], wells=>['b2','c2',$dl], color=>'lightgreen');

sectors or wells hash keys can be left undefined if unused.

clear_well_color

Clears a color from a set of wells, a set of plate sectors, or both.

Wells can be represented by well name ('h12'), well number (96), or by a GSC::DNALocation object.

$plate->clear_well_color(sectors=>['a1'], wells=>['b2','c2',$dl]);

sectors or wells hash keys can be left undefined if unused.

register_well_handler

Registers a callback to be performed in repsonse to GTK events processed by the buttons representing wells.

my $id = $plate->register_well_handler(event_type=>'released',
                                       code=>\&code_ref,
                                       sectors=>['a1'],
                                       args=>['something1','something2'],
                                       return_well_info=>['well_name','dna_location']);

On a GTK event specified by event_type, the code reference 'code' will be executed. Arguments to this routine can be specified by including them in the 'args' arrayref.

Optionally, information about the well will be appended to the arguments if requested. If the array referenced by 'return_well_info' includes any of the following:

'well_number'
'well_name'
'dna_location'

the appropriate data will be included in the argument vector, after all previously specified arguments. The data will also be appended in the above order, regardless of the order in which the identifiers appeared within return_well_info.

RETURN VALUE:

Returns an integer ID allowing you to refer to this handler later for deregistering it via deregister_well_handler.

deregister_well_handler

Deregisters a callback previously assigned to deregister_well_handler.

$plate->deregister_well_handler(id=>$id);

The 'id' parameter must be a previously defined integer ID returned by register_well_handler.

set_well_tooltips

Assigns tool-tips to wells.

A hash is passed into set_well_tooltips, wherein the keys are wells and their corresponding values are the text to use as the tooltip.

The wells can be represented as either well numbers, well names, or GSC::DNALocations.