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