Friday, February 25, 2005

Gtk2::Ex::RecordsFilter

Gtk2::Ex::RecordsFilter - A high level widget to browse reasonably large amounts of relational data and select a subset of records. This widget is inspired by the song browser of iTunes.

SYNOPSIS
use Gtk2 -init;
use Gtk2::Ex::RecordsFilter;
# Create a recordset
my $recordset = [
[Automobiles,Cars,Toyota,Camry],
[Automobiles,SUV,BMW,Xi],
[Automobiles,SUV,Toyota,Highlander],
[Automobiles,Cars,Mitsubishi,Lancer]
];
# Create the recordsfilter object
my $recordsfilter = Gtk2::Ex::RecordsFilter->new;

# Specify the headers for the columns
my $headers = ['Category', 'Sub-Category', 'Brand', 'Model'];
Gtk2::Ex::RecordsFilter->set_headers($headers);
# Inject data into the widget
Gtk2::Ex::RecordsFilter->set_data($recordset);
# Get a ref to its widget
my $recordsfilter_widget = $recordsfilter->get_widget();
# Create the root window
my $window = Gtk2::Window->new;
$window->signal_connect(destroy => sub { Gtk2->main_quit; });
$window->set_default_size(500, 300);
# Add the widget to the root window
$window->add($recordsfilter_widget);
$window->show_all;
Gtk2->main;


DESCRIPTION

When working with large amounts of relational records (csv files, database records, music files index), a common task is to filter out a subset or records from a given set. For example, in a master-detail database design, the master recordset, which is typically smaller than the detail recordset, can be filtered out and the filtered subset of master records can then be used to perform additional tasks on the detail records that they point to.

A common example of this usage is the song browser in your own mp3 player application (for example, the iTunes application). This application will allow you to choose an mp3 file (the detail record) based on criteria such as Artist, Album, Song (the master record). Once the master record is choosen (i.e., the Artist, Album and Song) it then performs a task on the detail record (i.e., play the mp3 file).

This Gtk2::Ex::RecordsFilter widget is inspired by the iTunes song browser widget. But this widget carries certain functionality which is not present in the iTunes song browser. The iTunes song browser allows the user to choose one song (one master record) at a time and play it. However, a more general usage should allow the user to choose multiple master records at a time. One approach for such multiple selections is to enable the user to click on different records with the CTRL key pressed and then choose all the highlighted records in one shot. This widget takes a different approach, which I call the 'shopping cart' approach. This is explained in the next section.

USER INTERACTION
The top half the widget shows all the master records. The records are shown in a hierarchical fashion similar to the iTunes song browser. Clicking on a parent node on the left-most box will cause all the boxes on its right to show only the child nodes.

The user can click on any entry in the top half and then click on the add to selection button and the record will show up in the bottom half. If the entry clicked is in one of the left boxes, then the widget automatically discovers all the child nodes and adds them to the selection. Upon adding to selection, the record is removed from the top half and shows up in the bottom half. The remove from selection button works in the reverse way.

The user can click on multiple records in the top half using the CTRL key.




METHODS


Gtk2::Ex::RecordsFilter->new
my $recordsfilter = Gtk2::Ex::RecordsFilter->new;

The widget can be used to select a subset of these records (into a selection list). The methods get_selected_rows and get_unselected_rows can be used to view the selection ( or unselection) at any point.

'Selected' portion is referred to as the 'RIGHT' side (bottom). 'Unselected' portion is referred to as the 'LEFT' side (top)

Gtk2::Ex::RecordsFilter->set_data

$recordsfilter->set_data($recordset);

The recordset is injected into the widget using this method. The widget will automatically create the HPaned children and the Selection buttons.

Gtk2::Ex::RecordsFilter->get_widget

my $recordsfilter_widget = $recordsfilter->get_widget();

This method returns the widget of the filter object.

Gtk2::Ex::RecordsFilter->get_selected_rows

my $selected_rows = $recordsfilter->get_selected_rows();
print Dumper $selected_rows;

This method returns the selected_rows contained in the bottom half of filter widget. A common usage is to have an Apply button which, when clicked, will invoke this method and use the returned results. Check out the examples directory to see this in action.

$apply_button->signal_connect (clicked =>
sub {
my $selected_rows = $recordsfilter->get_selected_rows();
print Dumper $selected_rows;
}
);

Gtk2::Ex::RecordsFilter->get_unselected_rows

my $selected_rows = $recordsfilter->get_unselected_rows();
print Dumper $selected_rows;

This method returns the unselected_rows contained in the top half of filter widget. This method too can be used with an Apply button like the one shown above.


Comments: Post a Comment

<< Home

This page is powered by Blogger. Isn't yours?