MatchingBE.pm untested

filter: Statementstmt 0.0% 0 / 192 Branchbran 0.0% 0 / 50 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 0.0% 0 / 23 Podpod 0.0% 0 / 19 totaltotal 0.0% 0 / 293 CC 26 SCAR 27.4
CC
26
Cov
0%
validate
56.0
set_selected_value
20.0
Populate
12.0
CRAP 15.5
1 package Tk::MatchingBE;
2 use strict;
3 use warnings;
4 use Carp;
5  
6  
7 =head1 NAME
8  
9 Tk::MatchingBE - A single-selection BrowseEntry with 'matching' Entry widget
10  
11 =head1 SYNOPSIS
12  
13 require Tk::MatchingBE;
14  
15 $mw->MatchingBE(-choices => [qw/foo bar baz/])->pack;
16  
17  
18 =head1 DESCRIPTION
19  
20 Tk::MatchingBE is a Tk::BrowseEntry which allows for a single selection from
21 a given list of choices/options.
22 In order to find the right item in the choices list, the Entry widgets content
23 is matched against the lists elements as the user types. The first matching
24 item gets selected and the list is popped up if a match occurs.
25 Key-press events causing non-matching content of the Entry are ignored.
26 The only exception here are 'Delete' events. Matching is case insensitive
27 and metacharacters are disabled (\Q). '<Return>' will select the active entry,
28 popdown the list and trigger -selectcmd. Possible states of the widget
29 are undef or a single selection - accessible per value or index.
30 Tk::MatchingBE is a Tk::BrowseEntry derived widget.
31  
32 =head1 METHODS
33  
34 B<Tk::MatchingBE> supports the following methods:
35  
36 =over 4
37  
38 =item B<choices(>[qw/a list of possible choices/]B<)>
39  
40 Get/Set the choices list (arrayref).
41  
42 =item B<labels_and_values(>[{label=>'aLabel',value=>'aValue'},{},{}]B<)>
43  
44 Get/Set the choices list with value/label associations. Labels are displayed
45 in the Listbox. Selected value can be accessed with get_selected_value
46  
47 =item B<get_selected_index>
48  
49 Get the selected index.
50  
51 =item B<set_selected_index(>anIntegerB<)>
52  
53 Set the selected index.
54  
55 =item B<get_selected_value>
56  
57 Get the selected value. Returns the selected 'value' in case -labels_and_values
58 has been set. Returns the selected 'label' (Listbox entry) if -choices has
59 been set.
60  
61 =item B<set_selected_value>
62  
63 Sets the selected 'value' in case -labels_and_values has been set. Croaks otherwise.
64  
65 =back
66  
67 =head1 OPTIONS
68  
69 B<Tk::MatchingBE> supports the following options:
70  
71 =over 4
72  
73 =item B<-choices>
74  
75 Get/set the list of possible choices.
76  
77 =item B<-labels_and_values>
78  
79 Get/set the choices list with value/label associations (see above).
80  
81 =item B<-value_variable>
82  
83 Ties a variable to the widget using 'get/set_selected_value' methods.
84  
85 =item B<-selectcmd>
86  
87 A callback to be called when the user selects an entry.
88  
89 =back
90  
91 =head1 EXAMPLE
92  
93 use Tk;
94 use Tk::MatchingBE;
95  
96 my $mw = tkinit;
97 my $be = $mw->MatchingBE(-choices=>[qw/aaa bbb ccc ddd asd/])->pack;
98 $be->set_selected_index(0);
99 $mw->Button(-text => 'selected',
100 -command => sub{
101 for (qw/get_selected_index
102 get_selected_value/){
103 print $be->$_, "\n";
104 }
105 },
106 )->pack;
107  
108 $mw->Button(-text => 'next_item',
109 -command => sub{
110 my $i = $be->get_selected_index;
111 $i = ($i+1) % 5 ;
112 $be->set_selected_index($i);
113 },
114 )->pack;
115 MainLoop;
116  
117  
118 =head1 SEE ALSO
119  
120 This module was written for Tk::ChoicesSet. There are others that offer more
121 flexibility like:
122  
123 =over 4
124  
125 =item B<JBrowseEntry>
126  
127 =item B<JComboBox>
128  
129 =item B<MatchEntry>
130  
131 =back
132  
133 =head1 AUTHOR
134  
135 Christoph Lamprecht, ch.l.ngre@online.de
136  
137 =head1 COPYRIGHT AND LICENSE
138  
139 Copyright (C) 2008 by Christoph Lamprecht
140  
141 This library is free software; you can redistribute it and/or modify
142 it under the same terms as Perl itself, either Perl version 5.8.7 or,
143 at your option, any later version of Perl 5 you may have available.
144  
145  
146 =cut
147  
148 our $VERSION = '0.11';
149  
150 require Tk::BrowseEntry;
151 our @ISA = 'Tk::BrowseEntry';
152 Tk::Widget->Construct('MatchingBE');
153  
154  
155 sub Populate{
156 my ($self,$args) = @_;
157 $self->SUPER::Populate($args);
158 $self->{_MatchingBE}{selected_index} = undef;
159 $self->{_MatchingBE}{value_variable_ref} = undef;
160 $self->{_MatchingBE}{values} = undef;
161 $self->{_MatchingBE}{value_to_index} = undef;
162  
163 my $lv = exists $args->{-labels_and_values}
164 ? delete $args->{-labels_and_values}
165 : undef;
166 my @config_lv;
167 if (defined $lv){
168 @config_lv = (-labels_and_values => $lv);
169 }
170 my $entry = $self->Subwidget('entry');
171 my $lb = $self->Subwidget('slistbox');
172 $self->ConfigSpecs(-bg => [$entry,undef,undef,'white'],
173 -selectcmd => ['CALLBACK',undef,undef,undef],
174 -labels_and_values => ['METHOD',undef,undef,undef],
175 -value_variable => ['METHOD',undef,undef,undef],
176 );
177  
178 $self->configure(@config_lv,
179 -validate => 'key',
180 -validatecommand => [$self,'validate'],
181
182 );
183 $entry->bind('<Return>', [$self,'_key_return']);
184 $entry->bind('<Up>', [$lb,'UpDown',-1]);
185 $entry->bind('<Down>', [$lb,'UpDown',1]);
186 $self->OnDestroy(sub{$self->_untie_value_variable});
187 }
188  
189 sub validate{
190 my $self = shift;
191 my @args = @_;
192 my $searchstr = $args[0];
193  
194 # don't care about programmatic changes of -textvariable
195 # -validate => 'key' triggers more than it should...
196 # $action == 7 in case of delete key
197 # $action == 8 in case of insert key
198
199 my $action = $args[4];
200 return 1 if ($action < 7);
201 # print "validating for entry [$self] action is [$action]\n";
202 my $is_delete = ($action == 7);
203  
204 my @entries = $self->choices;
205 my $matched = 0;
206 my $index = 0;
207 my $allow = 0;
208  
209 # don't try to match an empty string
210 if ((length $searchstr) > 0){
211 for my $entry (@entries){
212 eval{$matched = $entry =~ m/\Q$searchstr/i};
213 last if ($matched);
214 $index ++;
215 }
216 }
217 my $lb = $self->Subwidget('slistbox')->Subwidget('scrolled');
218  
219 if ($matched){
220 # set the selection and popup
221 $self->_select_index($index);
222 $self->PopupChoices;
223 $allow = 1;
224 }elsif(length $searchstr == 0){
225 # we didn't test - empty searchstring -
226 # clear selection and popdown :
227 $self->_select_index(undef);
228 $self->Popdown;
229 $allow = 1;
230 }elsif($is_delete){
231 # allow change in Entry in case of a Key-delete event
232 # we didn't get a match so set index to undef
233 $self->_select_index(undef);
234 $allow = 1;
235 }else{
236 # we tested through the list without a match
237 # don't change our lb selection
238 # don't allow for the entries content to change
239 $allow = 0;
240 }
241 return $allow;
242 }
243  
244 sub get_selected_index{
245 my $self = shift;
246 my $index = $self->{_MatchingBE}{selected_index};
247 return $index;
248 }
249  
250 sub set_selected_index{
251 my $self = shift;
252 my $index = shift;
253 my $lb = $self->Subwidget('slistbox')->Subwidget('scrolled');
254 # get last valid index of listbox
255 # index('end') points to the last + 1 element:
256 my $max = $lb->index('end') - 1;
257 croak "index out of bounds" if ($index || 0) > $max;
258 $self->{_MatchingBE}{suspend_selectcmd} = 1;
259 eval{
260 $self->_select_index($index);
261 $self->LbCopySelection;
262 };
263 $self->{_MatchingBE}{suspend_selectcmd} = 0;
264 return '';
265 }
266  
267 sub get_selected_value{
268 my $self = shift;
269 unless ($self->{_MatchingBE}{value_to_index}){
270 return $self->get_selected_label;
271 }
272 my $index = $self->{_MatchingBE}{selected_index};
273 return undef unless (defined $index);
274 my $value = $self->{_MatchingBE}{values}[$index];
275 return $value;
276 }
277  
278 sub get_selected_label{
279 my $self = shift;
280 my $index = $self->{_MatchingBE}{selected_index};
281 # keep listbox from croaking:
282 return undef unless (defined $index);
283 my $value = $self->Subwidget('slistbox')->get($index);
284 return $value;
285 }
286 sub set_selected_value{
287 my $self = shift;
288 my $value = $_[0];
289 unless ($self->{_MatchingBE}{value_to_index}){
290 croak "no -labels_and_values specified, can't set value in MatchingBE";
291 }
292 my $index;
293 if (! defined $value){
294 $index = undef;
295 }else{
296 $index = $self->{_MatchingBE}{value_to_index}{$value};
297 unless( defined $index ){
298 croak "can't find index for value [$value],"
299 ."can't set value in MatchingBE";
300 }
301 }
302 $self->set_selected_index($index);
303 }
304  
305 sub choices{
306 my $self = shift;
307 my $choices = $_[0];
308 unless ($choices){return $self->SUPER::choices}
309 $self->{_MatchingBE}{value_to_index} = undef;
310 $self->{_MatchingBE}{values} = undef;
311 $self->SUPER::choices($choices);
312 $self->set_selected_index(undef);
313 }
314  
315 sub _select_index{
316 my $self = shift;
317 my $index = $_[0];
318 my $lb = $self->Subwidget('slistbox')->Subwidget('scrolled');;
319 $lb->selectionClear(0,'end');
320 if (defined $index){
321 $lb->selectionSet($index);
322 $lb->see($index);
323 }else{
324 $lb->see(0);
325 }
326 $self->_cache_index($index);
327 }
328  
329  
330 sub LbCopySelection{
331 # Copy the selected value from the listbox to the entry
332 # if any, otherwise delete the entries content. Popdown...
333 # This must be overridden to clear the entry in case of an
334 # undefined selection.
335 # Default in Tk::BrowseEntry was to select 0 (first element).
336 my $self = shift;
337 my $index = $self->LbIndex('emptyOK');
338 #my $print_index = (defined $index) ? $index : 'undef';
339 #print "LbCopySel found index [$print_index]in [$self]\n";
340 $self->_cache_index($index);# needed here?
341 if (defined $index){
342 $self->SUPER::LbCopySelection;
343 }else{
344 #print "deleting entry content \n";
345 $self->Subwidget('entry')->delete(0,'end');
346 # handled by BrowseEntry...
347 # if ($self->{'_BE_popped'}) {
348 $self->Popdown;
349 #}
350 }
351 }
352  
353 sub Popdown{
354 # had to override this to call -selectcmd
355 # this is the only place where we need to call it
356 my $self = shift;
357 $self->SUPER::Popdown(@_);
358
359 unless ($self->{_MatchingBE}{suspend_selectcmd}){
360 my $callback = $self->cget('-selectcmd');
361 $callback->Call if $callback;
362 }
363 }
364  
365 sub _cache_index{
366 my $self = shift;
367 my $index = $_[0];
368 $self->{_MatchingBE}{selected_index} = $index;
369 }
370  
371 sub _key_return{
372 my $self = shift;
373 if ($self->{'_BE_popped'}) {
374 $self->LbCopySelection;
375 }else{
376 # should this popup the list??
377 }
378 Tk->break;
379 }
380  
381 sub value_variable{
382 my $self = shift;
383 my $varref = $_[0];
384 unless ($varref){return $self->{_MatchingBE}{value_variable_ref}}
385 $self->_untie_value_variable;
386 unless (defined $self->{_MatchingBE}{values}){
387 croak "Can't tie a -value_variable unless -labels_and_values "
388 ."are set.";
389 }
390 $self->{_MatchingBE}{value_variable_ref} = $varref;
391 my $value = $$varref;
392 tie ($$varref, 'MatchingBETier',$self);
393 # if (defined $value){
394 $self->set_selected_value($value);
395 # }
396 }
397  
398 sub _untie_value_variable{
399 my $self = shift;
400 my $varref = $self->{_MatchingBE}{value_variable_ref} || \0 ;
401 untie $$varref;
402 }
403  
404 sub labels_and_values{
405 my $self = shift;
406 my $l_v = $_[0];
407 #expecting a structure like:
408 # [
409 # {label => 'foo', value => 1},
410 # {label => 'bar', value => 2},
411 # {label => 'baz', value => 3},
412 # ];
413 unless ($l_v){
414 ### called as getter###
415 my @labels = $self->SUPER::choices;
416 my $values_ref = $self->{_MatchingBE}{values}||[];
417 my @r_v;
418 my $i = 0;
419 for my $label(@labels){
420 push @r_v ,{label=>$label, value=>$values_ref->[$i]};
421 $i++;
422 }
423 return \@r_v;
424 }
425 ### called as setter ###
426 my @choices;
427 my $index = 0;
428 ### untie the value_variable first?? ###
429 #$self->_untie_value_variable;
430 my $value_to_index = $self->{_MatchingBE}{value_to_index} = {};
431 my $values = $self->{_MatchingBE}{values} = [];
432 for my $element (@$l_v){
433 if (exists $value_to_index->{$element->{value}}){
434 croak "MatchingBE: -labels_and_values "
435 ."must provide unique values [".$element->{value}."]\n" ;
436 }
437 $value_to_index->{$element->{value}}= $index;
438 push @choices, $element->{label};
439 push @$values, $element->{value};
440 $index++;
441 }
442 $self->SUPER::choices(\@choices);
443 $self->set_selected_index( undef );
444 }
445  
446  
447 package MatchingBETier;
448  
449 sub TIESCALAR{
450 my $class = shift;
451 my ( $w) = @_;
452 my $tied = bless { mbe => $w,
453 }, $class;
454 return $tied;
455 }
456  
457 sub FETCH{
458 my $self = shift; # tied instance
459 return ($self->{mbe})->get_selected_value;
460 }
461  
462 sub STORE{
463 my $self = shift;
464 my $val = shift;
465 ($self->{mbe})->set_selected_value($val);
466 }
467  
468 1;