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.