NAME

Tk::GridColumns - Columns widget for Tk using Tk::grid

SYNOPSIS

use Tk::GridColumns;

my $gc = $top->GridColumns( ... );
...
$gc->refresh;

DESCRIPTION

A Tk::GridColumns is similar to a Tk::HList but its implementation gives you more freedom: The header and data information is stored in two array refs, so that you just have to adjust these and then ->refresh() the widget to make the changes visible. You can define how much space each column will take (grid: -weight). You can change almost everything: define your own item bindings ( Example: Editable), change the appearance of the widget very easily using default attributes for the column buttons and the data items (Example: Appearance), add scrollbars to the widget (Example: Scrolled), ...

Take a look at the example code to discover if this module is an appropriate solution for your tasks.

EXPORT

Nothing

EXAMPLES

Simple

#!/usr/bin/perl

use strict;
use warnings;
use Tk;
use Tk::GridColumns;

my $mw = tkinit( -title => 'Tk::GridColumns example -- Simple' );

my $gc = $mw->GridColumns(
    -data => [ map { [ $_, chr 97 + rand $_*2 ] } 1 .. 10 ], # some data
    -columns => \my @columns, # need to define columns after creating the
                              # object, because of the sort '-command'
)->pack(
    -fill => 'both',
    -expand => 1,
);

@columns = (
    {
        -text => 'Number',
        -command => $gc->sort_cmd( 0, 'num' ),
    },
    {
        -text => 'String',
        -command => $gc->sort_cmd( 1, 'abc' ),
        -weight => 1, # this columns gets the remaining space
    },
);

$gc->refresh;

MainLoop;

Scrolled

#!/usr/bin/perl

use strict;
use warnings;
use Tk;
use Tk::GridColumns;

my $mw = tkinit( -title => 'Tk::GridColumns example -- Scrolled' );
$mw->geometry( "=300x200+100+100" );

my $gc = $mw->Scrolled(
    'GridColumns' =>
    -scrollbars => 'ose',
    -data => [ map { [ $_, chr 97 + rand $_+5 ] } 1 .. 20 ],
    -columns => \my @columns,
)->pack(
    -fill => 'both',
    -expand => 1,
)->Subwidget( 'scrolled' ); # do not forget this one ;)

@columns = (
    {
        -text => 'Number',
        -command => $gc->sort_cmd( 0, 'num' ),
    },
    {
        -text => 'String',
        -command => $gc->sort_cmd( 1, 'abc' ),
        -weight => 1,
    },
);

$gc->refresh;

MainLoop;

Editable

#!/usr/bin/perl

use strict;
use warnings;
use Tk;
use Tk::GridColumns;

my $mw = tkinit( -title => 'Tk::GridColumns example -- Editable' );

my $gc = $mw->GridColumns(
    -data => \my @data, # ease the data access
    -columns => \my @columns,
    -item_bindings => { '<Double-ButtonPress-1>' => \&edit_item },
)->pack(
    -fill => 'both',
    -expand => 1,
);

@columns = (
    {
        -text => 'Number',
        -command => $gc->sort_cmd( 0, 'num' ),
    },
    {
        -text => 'String',
        -command => $gc->sort_cmd( 1, 'abc' ),
        -weight => 1,
    },
);

@data = map { [ $_, chr 97 + rand $_*2 ] } 1 .. 10;

$gc->refresh;

MainLoop;

sub edit_item {
    my( $self, $w, $row, $col ) = @_;
    
    $w->destroy; # destroy the widget that currently displays the data
    
    my $entry = $self->Entry(
        -textvariable => \$data[$row][$col],
        -width => 0,
    )->grid(
        -row => $row+1,
        -column => $col,
        -sticky => 'nsew',
    );
    
    $entry->selectionRange( 0, 'end' );
    $entry->focus; # so the user can instantly start editing

    $entry->bind( '<Return>' => sub { $self->refresh_items } );
    $entry->bind( '<FocusOut>' => sub { $self->refresh_items } );
} # edit_item

Appearance

#!/usr/bin/perl

use strict;
use warnings;
use Tk;
use Tk::GridColumns;

my $mw = tkinit( -title => 'Tk::GridColumns example -- Appearance' );

my $gc = $mw->GridColumns(
    -data => [ map { [ $_, chr 97 + rand $_*2 ] } 1 .. 10 ],
    -columns => \my @columns,
    -bg => 'black',
    -colattr => {
        -fg => 'green', -bg => 'black',
        -activeforeground => 'green',
        -activebackground => 'black',
    },
    -itemattr => { -fg => 'green', -bg => 'black' },
)->pack(
    -fill => 'both',
    -expand => 1,
);

@columns = (
    {
        -text => 'Number',
        -command => $gc->sort_cmd( 0, 'num' ),
    },
    {
        -text => 'String',
        -command => $gc->sort_cmd( 1, 'abc' ),
        -weight => 1,
    },
);

$gc->refresh;

MainLoop;

TODO

There is much work to do and now I found some time to update the module. And hopefully I will update it more often in the next months :)

* Selection:
    - select() and deselect() that react on the -selectmode
    - select_item(), select_row(), select_col() and the deselect() ones
    - 'from' and 'to' parameters for the select() and deselect() routines
* Refreshing:
    - refresh_item(), refresh_row(), refresh_col() so that you can refresh
      only the parts that need to get refreshed
* more documentation

SEE ALSO

Tk, Tk::grid, Tk::Pane, Tk::Scrolled, Tk::HList, Tk::Columns, Tk::MListbox, Tk::Table, Tk::TableMatrix

AUTHOR

Matthias Wienand, <matthias.wienand@googlemail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Matthias Wienand

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.