Olivier Bouteille > Tk-SlideShow-0.07 > Tk::SlideShow



Annotate this POD


New  1
Open  0
View/Report Bugs
Module Version: 0.07   Source  


Tk::SlideShow -- a Tk Perl module for building slide-like presentations.


This module provide Perl with the ability to :

To summarize the philosophy of Tk::SlideShow, you have to understand that slides will be defined and descripted :

in a Perl script,

for everything that is easier to define in Perl,

interactively (with mouse)

for everything that is easier to define interactively. These informations will be saved automaticaly on slide's specific files -- in Perl of course.

In this document, I have tried to interlace a tutorial and a full description approach. This may sound it a little bit amazing, but I think it was possible in this case.


First of all, to build a presentation with Tk::SlideShow, you had better create a presentation specific directory for keeping all the files that will be created.

In this directory, you have to edit the main script : This script will have to use Tk::SlideShow; and some of its methods.

The init method lets Tk::SlideShow self initialize for a new presentation. It understands 2 parameters as the sizes (resp. width and height) of the main window. Without these parameters, the sizes of the window will be the mawimum sizes of the X11 root. But sometimes, like me, you have a bigger definition on your Unix desktop than on your laptop. And perhaps, you will preferably travel the world with your laptop rather than with your desktop, to show your presentations. So, for example, you will design your presentation for a definition of 1024x768 instead of 1600x1280 desktop 21 inch screen. Your script will therefor begin with something like :

        my $p = Tk::SlideShow->init(1024,768);

As Larry says often, it's useless to or die. Method init return an instance of class Tk::SlideShow. You may feel it useless to use an instance of Tk::SlideShow that will be probably uniq during the life of the script execution, but this help for internal locality of variables and also reduce the number of character to type. Now to invoke a Tk::SlideShow method, you will just have to type $p->method rather than Tk::SlideShow->method (remember, laziness ...).

Methods mw, can, h and w help you to access internals objets and variables respectively : MainWindow, Canvas, width and height of it. In case you need them you probably had better to insert this small line in the beginning of your script :

        my ($mw,$c,$h,$w) = ($p->mw, $p->canvas, $p->h, $p->w);

For pratical reason, I will suppose in future examples that these lines are at the beginning of my examples scripts without mentioning it.

Now, I am sure you're dying to know how to create a simple slide. This is simple, as promised above. Let's look at it first and explain it afterward :

        $p->add('hello', sub {
                $p->Text('t1','Hello World !');

Just try (run) it (remember : As I said before, you have to add lines at the beginning of your script) !

While running the script with Perl, it will create a big window containing a Tk Canvas : in the middle : a text. Note that you are able to drag the text "Hello World !" with the button 1, where you want it to be. Pressing key s, you will save its positions. Pressing key q will quit the presentation. If you play it again, you will find your text at the same place were you let it just after you press key s. Pressing key space or backspace let's you navigate thru different slides. Here, you just have one .. so ...

This is how it looks. Now let's explain what it means :

First, I call the save method. As described more precisely later, this make all your slides sensible to a keypress on s for saving the artistic caracteristics of your slides on a file.

Then I call method add. This is for pushing a new slide on the pile of slides. I give to arguments : a name to the slide to reference it later and because I like to gave a name to what I am creating, and a codeREF which is the real slide definition. This sub will be called when the time of showing the slide has come.

Here I put a small text : Hello world. note that I do not specify it's place. I just give the text. I will specify it's place later, during the artistic step of the presentation building. The artistic specifications, by the way, will be loaded when calling method load.

At the end of my small example, I call the method play to ask Tk::SlideShow to play all the slides in sequence.

That's all !

It sounds simple, doesn't it ?

I'm sure you have tones of questions, for how to do this or that. But that's not the point of this simple example to answer your questions. It's just a first contact with Tk::SlideShow.


Let's now have a look at all the methods more precisely. I will continue to give examples, of course.

Method add

As, I'm sure you have understood : the central method for you is the add method. This is where you are going to specify your slides.

As I mention above, this method add a new slide on the pile of already existing slides.

You have to give it a uniq name (or id) as a first parameter. It lets you reference it in the future more easely (as you will see later). This name can be whatever a filename (without its directory) can be. Keep in mind, that the position of most of your objects will be saved in file call slide-name.pl, where name will be replace by the first argument to method add.

Then you have to give it a sub reference (as a second argument).

Method current

During building your presentation, you will probably have to test several times the look of what you have done and to add artistic value to it. So, you need a method that helps you to jump to a particular slide, given its name. This method is current. That's the reason why I recommend to add a line before the call to method play :

        $p->current(shift || 0);

So that if your presentation is in file pres.pl and you start it like this,

        prompt-unix> pres.pl hello

you will directly see the slide named hello. Actually, slides are internally stored in a ARRAY, and you can also specify the index of your slide in this ARRAY :

        prompt-unix> pres.pl 2347

This will accelerate the access to a very big presentation !

Methods save and load

As mention above, these methods deal with persistance of your added artistic value. So, I am sure you realize how important they are :-) !

The method save may be called, but only once (is needed). It just indicates to Tk::SlideShow that you do want Tk::SlideShow to save the modifications you have done during the presentation until pressing key s. If this is not what you want, just comment the $p->save; line.

The method load must be called when you want Tk::SlideShow to load what have been saved by method save : mainly, the position of the objects your are going to define. You may specify a filename as an argument to method load (you will see later in this documentation, where this is relevant), but most of the time this is useless.

There is (at least) one file per slide that contains positions and other characteristics of objects (color, fonts). The file will have the name slide-xxx where xxx is the name of the slide (that is the name you give as a first argument to method add). This file contains a Perl script that is automaticaly generated by Tk::SlideShow. So you will have at least as many files as you have slides. That's a good reason, I think, for creating a specific directory for your presentation.

It may sound obscure that you may have to specify an argument, but we will see later that it is very usefull in some cases.

But remember : you call method save once, and method load many times, often at least once per slide.

Method bg

This method is used to specify a sub reference that will be called before playing a slide. It stands for background.

(This sub will receive the Tk::SlideShow object as argument.)

Here is an example :

    $p->bg( sub {
                 $c->createText($w,0,-text,"Olivier Bouteille",
                                -anchor => 'ne',
                                -font => $s->f1,
                                -fill => 'yellow');

Remember $c is a global variable that I suppose you have initialized previously as mentioned above. It contains the canvas where all objects will be drawn. That the second and the last time I recall it to you.

In this example, this is clear that you like chocolate ... as a color for the background of you presentation, and that you like to insist on the fact that you are the author of the presentation :-).

For simplicity I have added the possibility to specify only a color as an argument instead of a sub reference. So :


will work as a simplify expression of

      $p->bg( sub {$c->configure(-background,'chocolate')};

General look of your presentation script

To summarize what you have learned up to now, here's the look of the script of your presentation :

        use Tk::SlideShow;

        my $p = Tk::SlideShow->init(1024,768);
        my ($mw,$c,$h,$w) = ($p->mw, $p->canvas, $p->h, $p->w);

        $p->add('menu',         sub { ...; $p->load });
        $p->add('introduction', sub { ...; $p->load });
        $p->add('development',  sub { ...; $p->load });
        $p->add('conclusion',   sub { ...; $p->load });

        $p->current(shift || 0);

Now you should be able to build any presentation. But it would be to tedious to specify everything. So there are some more concept in Tk::SlideShow that will help your expression.

Sprites ^

Sprites are graphics objects that you can place or change interactively on a slide. You describe it in Perl, and you place it with the mouse. Sometimes you can also modify there shape interactively. The characteristics that will be modified interactively will be called IC (i.e. Interactive Characteristique) of Sprites in this document.

These objects may be as complicated as Tk canvas drawing. They are composed of Tk/Canvas items.

Each Sprite has a name (an identifier) as they are very important for Tk::SlideShow. This name has to be uniq in a slide, but you can reuse it in differents slides. In a first approach, the syntax for the is a string without a character /. In fact this character is possible but it has a special meaning for Tk::SlideShow as we will see it later. The name will be used to tag (in the sens of Tk tags) every canvas items composing a Sprite.

There is a set of methods that can be applied on them.

Tk::SlideShow provide some builtin Sprites, but you can add some more Sprite.

After being described in the Perl script, they aspect and position my be modified during running the presentation.

builtin Sprites

You have already met a Sprite, without knowing it : The Text Sprite. You create a Text Sprite by calling the method Text on the Tk::SlideShow object. This is very simple :

        $p->Text('ident', 'text body', @options);

The ident is mandatory. @options are optionals and directly passed to Tk when creating a canvas text item. So, look at Tk documentation to know what options you can use.

What has been done for text has also been done for image. The syntax is as follow :


and for animated images :


Specificaly for the Sprite Text, I have added an interactive font family chooser and a color chooser. You may access it by double clicking respectively with button 1 and 2 on the Sprite text itself.. I'm not sure, this functionnality is necessary : I usualy prefer to have a structured access (i.e. in the script) to font families and color.

Now, here is a more useful definition of a slide :

        $p->add('menu', sub {
           $p->Text('title','Abstract',-font => $p->f3);
           my $i = 0;
           for (split(/,/,'Introduction,Development,Conclusion')) {
                $p->Text("i$i",$_,$p->f1); $i++;

Here are some comments on this slide definition :

So, a more suitable definition of the slide would be something like :

        $p->add('summarize', sub {
                items(qw(Introduction Development Conclusion));

Simple, isn't it ?

There exists some more Sprite in Tk::SlideShow, but their definition is so simple that I think it will be more suitable to look at the code in the file Tk/SlideShow/Sprite.pm and think of it as custumable examples.

adding your own Sprite

Yes it's possible. Actually, this is very simple. Just have a look at Tk/SlideShow.pm and you will find that it takes only a few lines to do it, or to reuse it.

A Sprite is just a Perl object with an identifier that is also used as Tk tag. It store a relative coordinates x,y), tag name, and all others IC. It knows how to give a Perl persistant string of itself.

You can add characteristic to this object either by inheriting class Tk::SlideShow::Sprite, or by simply adding keys to the Perl object (which is not very academic !).

Let's take examples :

Example 1

Imagine you want to create a new kind of Sprite. A little logo that symbolise a man in front of a computer.

Here's the function you may write :

          sub compuman { # given an id as a standalone argument
            my $s = $p->newSprite(shift);
            my $id = $s->id;
            # here are options
            my @o1 = (-width ,4,-fill, 'black', -tags ,$id);
            my @o2 = (-fill,'blue', -tags ,$id);
            my @o3 = (-width ,4,-fill,'red', -tags ,$id);
            $c->createLine(qw(10 20 10 40 25 40 25 50),@o1);      # chair
            $c->createLine(qw(15 15 15 35 30 35 30 50 35 50),@o1);# body
            $c->createOval(qw(11 11 18 18),@o2);                  # head
            $c->createLine(qw(15 25 30 25),@o1);                  # feet
            $c->createLine(qw(30 27 40 22),@o3);                  # keyboard
            $c->createPolygon(qw(35 20 40 0 55 10 55 20),@o3);    # screen
            $c->createLine(qw(45 20 45 30 35 30 35 30),@o3);      # screen foot
            return $s;

What this example shows is :

Once this little function written, I can use it everywhere in the presentation, to place computer men symbols as many times as I'd like. I will be able to place it interactively, and to save it's position pressing on the s key.

Example 2

Imagine you would like to have text surrounded by a frame, and with a special color background, that you will reused a lot in your presentation. Here is the kind of function you may write :

        sub framed {
          my ($id,$text) = @_;
          my $s = $p->newSprite($id);
          my $idw = $c->createText(0,0,'-text',$t, -justify, 'center',
                           -font => $p->f1, -tags => $id);
          $c->createRectangle($c->bbox($idw), -fill,'light blue',-tags => $id);
          return $s;

Then, each time in a definition, you would like to have such a framed text, then just call framed like this.

        frame ('id1',"This is an\nImportant message");

Example 3

Let's have an other example, a more classic example. Imagine you want to explain a source example (perl, of course) in your presentation. You will probably want to have a Sprite specialized representing these scripts examples. To be consistant, you want it to look very similar in the whole presentation slides. Even perhaps in all the presentations you will build in your job, or even ... your life (horror !)

Here's what you can do :

        sub example { # given the id and the text of the script
          my ($id,$t) = @_;
          my $s = $p->newSprite($id);
          my @t = (-tags => $id);
          # here is the label of the script
          $c->createText(0,0,-text,'Script example', -font => $p->f1,
                         @t, -anchor => 'sw');
          # the text of the script example
          my $idw = $c->createText(0,0,-text,$t,-font => $p->ff1, @t,
                          -anchor => 'nw');
          # a rectangle around the example with a nice background
          $c->createRectangle($c->bbox($idw), -fill,'light green',$p);
          return $s;

Here, I've created an new Sprite, which consists of a 2 text items. One with a fixe text : Script Example and one with the the text of the example which is passed as an argument to the function.

Note that font used for these texts (f1 and ff1) will be explained later.

Example 4

Let's animate our Sprites, now. Here's something that will be difficult to do with PowerPoint, as far as I know.

Let's look at this function :

    sub ticker {
      my ($id,$text) = @_;
      my $s = $p->newSprite($id>->pan(1);
      my $idw = $c->createText(0,0,-text,$text, 
                               -font => $p->f1, -tags => $id,);
      sub wrap_round {
        my $tag = shift;
        my $t = $c->itemcget($tag,-text);
        $c->dchars($tag,'0');                   # delete the first  character.
        $c->insert($tag,'end',substr($t,0,1));  # add it at the end of string.
      return $s;

This function create a new type of Sprite that display a single line of text that looks like a ticker tape. For animation, I use the Tk/after method, of course.

Simple and powerful, isn't it : This is just Perl and Tk !

Managing progression in the slide discovery ^

Often, you'd like to explain progressively a complex slide. So, you'd like to let Sprites appear in a particular order, so that attendees will discover the complex slide progresively.

Tk::SlideShow provides you with the ability to let the Sprites appear progresively as you press button 3 of your mouse. They will appear, slipping from top, bottom, left or right edge of the slide.

Here's how to do it (reusing the subs title and items decribed previously) :

        $p->add('menu', sub {
           # ....

What we see here is that after loading the position of our title and items, I ask for title to appear slipping from bottom to it's place when I will press button 3. If I press it again and again, I will see the items arriving on my slide, slipping for the left side of it to there final place. You may have used as well method a_right or a_top for making them arrive repectively from right or from top side of the slide. Note that you can play back this evolution by pressing Control-Button-3.

If you need to let several Sprites enter the slide together, then just give an refARRAY of tags of these Sprites instead of just one tag. As an example you may try, just add [] around map instruction in the previous example :


You will see that the 3 items will arrive on the slide simultaneously !

You are also able to let appear a Sprite suddenly by using method a_warp.

Sometimes you may want to make a Sprite leave the slide. Just replace the prefix a_ (standing for arrive) by l_ (standing for leaving).

Sometimes, it is useful to show a Sprite evolving thru a path. This is done by using method a_multipos. You have to give it a number of position, the Sprite have to take. It will move from one position to another by clicking on button 3. As usual you don't have to specify in the script the coordinates of the positions. Just the number of position. When you play the slide for the first time, the Sprite will stand in a default position. Just drag it where you wan't it to be with button 1. Do this for each position. Then save it (press s key). It will remenber where you have mouse-ly specified each position. The script example is trivial :

        $p->add('workflow', sub {
           # ....

That will help describing the different stage of a document in workflow system, for example. Here, the document will have 10 differents position, it will remember.

You may want to specify the positions explicitly (computed, e.g.) in the script. This is posible, of course. Just use the method multipos on the Sprite object, and give an ARRAY of the positions just like you will define a line in a Tk canvas.

Linking Sprites ^

It's often useful to link Sprite together, with a line, or an arrow or whatever.

Tk::SlideShow provide you with this ability.

For example, to link two Sprites with a simple line with a title on the middle of the line, just call method newLink as follows :


Interactively, you will be able to change the attach point of the link (here, a line) by clicking on the line, with Button 1 or 3. The attach point will turn around the bounding box of the Sprite, successively following the eigth cardinals points (nw, n, ne, e, se, s, sw, w).

If you want an simple arrow, replace Link by Arroa, a Double arrowreplace Link by DblArrow.


Note that you can change IC of arrows shape using keyboard Up, Down, Left, Right when mouse is over the arrow, and their Control counter part if the mouse is on the arrow.

You can also change the attach (cardinal) point of the arrow (which inherit from link) on each Sprite it links together, by clicking button 1 or 3 on the arrow.

You can even add your new way of linking Sprites. As an example, I provide in Tk::SlideShow a method newOrg that will helps you to create hierarchical organisation graph. Look at Tk::SlideShow examples to see how it looks. Look at Tk/SlideShow.pm definition of newOrg method to see how in less than 20 lines it is done, and at the example below, using Org Sprite.

hyperlinks ^

Sometimes it may be useful to jump from one slide to another by clicking on a Sprite. This is also implemented. Here's how to do it.

        $p->warp('i1','<Double-1>', 'introduction');

In this example, if you double click with button 1 on Sprite i1, you will jump directly to slide named introduction.

Big Fontes ^

X11 is not so much provided with big fonts, such as these one you want to use for a presentation. So you have to take a scalable font and to resize it. Tk::SlideShow provide you with a minimal set of fonts.

There are severals methods for that, used in my previous examples :


This method return a scalable charter font of a point size of 150. If you give it an argument, this will be taken to be multiplied to 150. The family used by default is charter. You may change this default family by using the method family with the new family as argument. The list of family depends on your distribution of X11. On my Linux box I have approximatly 20 family that are all free fonts.

Here's where you may get these nice and funny fonts :

f1, f2, ..., f5

These method return proportional fonts bigger and bigger, that I feel sufficient for my presentations.

ff1, ff2, ... ff5

These methods return fixed fonts bigger and bigger, that I feel sufficient for my presentations.

Sprites id with / ^

Sprites interactive characteristics (IC) are stored in slide id dependent file. For example, in a slide called menu, Sprites IC will be stored in file slide-menu.pl. If you want these Sprites IC not to be stored in slide id dependent file, you just have to prefix the Sprite id with the name of the file followed by a /. For example, a Sprite called org/i1 will see its IC be stored in file org.

The reason for this functionnality, is that there are case where you would like to resuse Sprites, in severals Slides.

Here are some examples :

Example 1

Imagine you want you presentation to have on all slides (or most of them) the menu of it on the right side of each slide. You may define this variable at the begining of your script :

        my @plan = (
            'intro'      => "Introduction",
            'pos'        => "Position of the problem",
            'present'    => "Presentation",
            'dev'        => "Development",
            'solutions'  => "Solutions",
            'conclusion' => "Conclusion" );

Left members stand for slide identifiers, and right members are text you will see on the slide.

So, you may write this small sub :

  sub small_summarize {
    my $count = 0;
    my @p = @plan;
    while(@p) {
      my ($slide,$title) = (shift @p, shift @p);
      my $id = "som/i$count";
      $p->Text($id,$title, -font, $p->f1, -fill,'blue', -anchor,'w');
      $count ++;
    $p->load('som'); # this load only place for sprites names som/...

You learn here that you can get the current id of the slide being played, with method currentName.

You will have to call the small_summarize method at the begin of each slide definition.

Interactively, the first time you will see the small menu, you will be able to place it manually, and save it (by pressing s key). Then, each time you will reuse this sub, Sprites define in will be placed at the same position. This is achieved because of the fact that the Sprite ids starts with string som/ so that there IC will be stored in file som.

Example 2

Imagine now that you would like to present your organisation. You would like to show your organisation graph one each slide.

You describe you organisation in a Perl variable :

        my %org = ( 'a' => "Computer\nService",
                    'a.b' => "Design\nDepartment",
                    'a.c' => "Develop\nDepartment");

You may use the framed Sprite define above to put the entities description.

        sub org {
          my %sprites;
          # creating boixes
          $sprites{$name}= $p->Framed("org/$name",$desc)
            while my($name,$desc) = each %org ;

          # creating links
          while(my($name,$sprite) = each %sprites) {
            my ($sup) = ($name =~ /(.*)\.\w+/);
                if exists $sprites{$sup};

You will have to place your boxes as you like during a first try of playing your slides (as usual now).

Then you will just have to call sub org at the beginning of each slide you would like this graph to be seen.

Note that :


As far as I am concerned, I feel that considering a paper copy of slides as a documentation of a presentation is non sense. You have to add your speach added value to it. That's why, in case I want to let some documentation, I like to add to my presentation, a documentation to each slides. This helps me also to prepare the presentation.

To add documentation to my slides, I have choosen to use html as a language. Maybe in a future release, somebody else will want to express attach documentation to slide in a different language (maybe pod).

So, that's the reason for the method html on a Tk::SlideShow::Diapo object.

To let you add an header and a footer to your presentation paper, I have added 2 methods for the Tk::SlideShow object : htmlheader and htmlfooter.

To output the whole documentation on a file, you may use the method html on the Tk::SlideShow object (note that this is not on the Tk::SlideShow::Diapo object this time). This method take the name of a directory where it will produce differents snapshots of your slides, plus HTML documentation explicitly attached to each slides (or Tk::SlideShow::Diapo).

Note that the technic used to snapshot your slides is by using the X11 command xwd. Then it is converted in GIF image format, so that your images will be viewable on most of browsers. As for now, I use convert (from ImageMagick) to convert xwd to gif format as well as for realizing the thumbnail.

So to sumarize this here's the look of a more complete example of a Tk::SlideShow script :

        use Tk::SlideShow;

        my $p = Tk::SlideShow->init(1024,768);
        my ($mw,$c,$h,$w) = ($p->mw, $p->canvas, $p->h, $p->w);
        my $d; # stands for a diapo.
        $d = $p->add('menu',         sub { ...; $p->load });
        $d->html('blah blah on the menu slide');
        $d = $p->add('introduction', sub { ...; $p->load });
        $d->html('blah blah on the introduction slide');
        $d = $p->add('development',  sub { ...; $p->load });
        $d->html('blah blah on the development slide');
        $d = $p->add('conclusion',   sub { ...; $p->load });
        $d->html('blah blah on the conclusion slide');

        if (grep (/-html/,@ARGV)) {
          exit 0;

        $p->current(shift || 0);

If you prefer to start your presentation as a wide template, and cut anything that is not useful, you may use the only exported method : template. This will produce on the STDOUT a perl script that has some very general slides and subroutines. So to start a new presentation you may run :

        perl -MTk::SlideShow -e template > mynewpresentationscript.pl


Here is a summurized synopsis of Tk::SlideShow methods. Remember that it is an alpha stage release. I hope the API will not change, but it is not garanteed (by me) up to now. So if you already use this interface for building presentation, you'd better keep the file SlideShow.pm used, not to far.

Base Level

  use Tk::SlideShow;
  my $p = Tk::SlideShow->new;   # initialize canvas according 
                                # to the current screen
  $p->bg(?sub|color?);          # change background 
  my $d = $p->add(?'nom',sub);  # add a slide
  $d->html('..');               # add html documentation
  my ($mw,$c,$h,$w) = ($p->mw,$p->canvas,$p->h,$p->w);
                                # retrieve context variables 
  $p->current(?slideid);        # retrieve/set current slide
  $p->currentName;              # retrieve current Name of the slide
                        # jump on slideid in case of tkevent on spriteid
  $p->save;             # make the presentation save-able by pressing 's'
  $p->load(?file)       # load sprites locations from file or 
                        # default slide file
  $p->play;             # play the slides

                        # make designated sprites arrive on the slide
                        # from top left bottom or right
                        # sequencialy in this order 
                        # on button3 click.       
                        # make them leave the slide instead of arrive 
                        # make the spriteid evolve on a button 3 click thru 
                        # up to nbposition

  $p->html('directory') # produces on complete html documentation
                        # get/set documentation header/footer


  $p->newSprite($id);    # create an empty sprite
                         # return a predefined Text sprite
                         # Predefined tk window Sprite
  $p->Image($filename);  # Predefined Image Sprite
  $p->Anim($filename);   # Predefined Animation GIF Sprite


Olivier Bouteille (bouteille@dial.oleane.com)

Will you be kind enough to excuse my poor english, and send me corrections.


Perl(1). et Tk/perl

syntax highlighting: