NAME
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.
AUTHOR
Ofey Aikon, <ofey_aikon@gmail.com>
BUGS
You tell me :)
ACKNOWLEDGEMENTS
To the wonderful gtk-perl list.
COPYRIGHT & LICENSE
Copyright 2004 Ofey Aikon, All Rights Reserved.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.
You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.