10.2.1. General discussion on Gtk2::Gdk::Pixmap.

Pixmaps are data structures that contain pictures. These pictures can be used in various places, but most commonly as icons on the X desktop, or as cursors.

A pixmap which only has 2 colors is called a bitmap, and there are a few additional routines for handling this common special case.

To understand pixmaps, it would help to understand how the X window system works. Under X, applications do not need to be running on the same computer that is interacting with the user. Instead, the various applications, called "clients", all communicate with a program which displays the graphics and handles the keyboard and mouse. This program which interacts directly with the user is called a "display server" or "X server." Since the communication might take place over a network, it's important to keep some information with the X server. Pixmaps, for example, are stored in the memory of the X server. This means that once pixmap values are set, they don't need to keep getting transmitted over the network; instead a command is sent to "display pixmap number XYZ here." Even if you aren't using X with Gtk+ currently, using constructs such as Pixmaps will make your programs work acceptably under X.

Data to create the Gtk2::Gdk::Pixmap

Although there may be more fancy ways (including Gtk2::Gdk::Drawable's draw functions) to get something to display on the Gtk2::Gdk::Pixmap, the ones we will discuss here are using data in the XPM format.

XPM format is a readable pixmap representation for the X Window System. It is widely used and many different utilities are available for creating image files in this format. It has, just like GIF format, also a "Alpha Channel" that is used to create shaped images. Think about the shapes of cursors!

XPM data can be fetched from files, or it can be created from an inline data structure. To create it inline, you have to be familiar with the data structure of the XPM format. This is outside the scope of the book, and the reader is advised to look it up via any search engine on the Internet.

To create a Gtk2::Gdk::Pixmap from inline XPM data, you use the following method:

($pixmap, $mask) = Gtk2::Gdk::Pixmap->create_from_xpm_d ($drawable, $transparent_color, @xpm_data)
	

You will notice that this method creates a pixmap AND a mask. The mask is a bitmap, that will be used when we need to display the pixmap image. It specifies which bits of the pixmap are opaque. The $drawable is any realized Gtk2::Gdk::Window. $transparent_color usually is undef, which will use the default transparent color. You then supply it the array of strings which is a presentation of the XPM image.

To create a Gtk2::Gdk::Pixmap from a file, you use the following method:

(pixmap, mask) = Gtk2::Gdk::Pixmap->create_from_xpm ($drawable, $transparent_color, $filename) 
	

You will notice that this method creates a pixmap AND a mask. The mask is a bitmap, that will be used when we need to display the pixmap image. It specifies which bits of pixmap are opaque. The $drawable is any realized Gtk2::Gdk::Window.$transparent_color usually is undef, which will use the default transparent color. You then supply it the name of the XPM file.

Now we know more about Gtk2::Gdk::Pixmap, we can have a look at how we implement it along with other methods to create the bouncing ball animation.

10.2.2. Creating the animation.

The program will do the following:

• Move in steps (horizontal and vertical) across the screen.

• With every step, change the image displayed, to give the impression of motion.

• As soon as it reached the end of the screen, be it the top,bottom or sides, it must "bounce" and change direction after the bounce.

• Whenever the mouse enters the displayed window, it should change to a predefined image, and stop any stepping and image changing.

10.2.3. The program's interface.

10.2.4. The Code.

The program can be found here: 'Bouncing Ball'

	
 #! /usr/bin/perl -w
 use strict;
 use Gtk2 -init;
 use Glib qw/TRUE FALSE/;
 
 #array pointers to indicate the displayed file
 my $current_file = 0;
 my $current_bounce = 0;
 my $current_side_bounce = 0;
 #direction indicators for the stepping sub
 my $up_flag = FALSE;
 my $left_flag = FALSE;
 #indicate if it is currently bouncing up/down
 my $bounce_flag =FALSE;
 #indicate if it is currently bouncing sideways
 my $side_bounce_flag =FALSE;
 
 #Initial position horizontal and vertical
 my $x =5;
 my $y=5;
 #flag to indicate if the image changing and movement stepping
 #should be stopped
 my $freeze_flag = FALSE;
 #step size
 my $step_x = 10;
 my $step_y = 10;
 
 #Pre Widget prep START --------
 
 #list of files to show if not bouncing
 my @file_list = qw/t1.xpm t2.xpm t3.xpm t4.xpm t5.xpm t6.xpm t7.xpm t8.xpm t9.xpm/;
  my $list_count = scalar @file_list;
 
 #list of files to show for top and bottom bouncing
 my @bounce_top_bottom = qw/t1.xpm b1.xpm b2.xpm b3.xpm b2.xpm b1.xpm t1.xpm/;
  my $bounce_top_bottom_count = scalar @bounce_top_bottom;
  
 #list of files to show for side bouncing
 my @bounce_sides = qw/t3.xpm s1.xpm s2.xpm s3.xpm s2.xpm s1.xpm t3.xpm/;
  my $bounce_sides_count = scalar @bounce_sides;
 
 #Pre Widget prep END --------
 #timeout that will repeat.
 Glib::Timeout->add (200,sub{ &change() });
 
 #popup windows will create shaped windows.
  my $window = Gtk2::Window->new ('popup');
  $window->resize(4,4);
  
  	#create an event box that will house the pixmaps
   	my $eventbox = Gtk2::EventBox->new ();
   	#set the freeze flag when we enter or leave the eventbox
   	$eventbox->signal_connect('enter-notify-event' => sub { $freeze_flag = TRUE});
  	$eventbox->signal_connect('leave-notify-event' => sub { $freeze_flag = FALSE});
 
 		my $img = Gtk2::Image->new();
 
 	$eventbox->add($img);
 $window->add ($eventbox);
 
 #discover which size of screen we have
 my $screen = $window->get_screen();
 my $screen_width = $screen->get_width();
 my $screen_height = $screen->get_height();
 
 $window->show_all;
 
 	#first run
 	&change();
 Gtk2->main;
 
 sub change {
 
 	#IF the freese flag is set, put a message for the user, and return	
 	if ($freeze_flag) {
 		my($pxm_current, $msk_current) = Gtk2::Gdk::Pixmap->create_from_xpm ($window->window,undef, "./pix/stop.xpm");
 		$img->set_from_pixmap ($pxm_current, $msk_current);
 		$window->window->shape_combine_mask($msk_current, 0, 0);	
 	return TRUE;
 	
 	} 
 	#----------------------------------
 	
 	my ($w_w,$w_h) = $window->get_size;
 	
 	#we test for the following"
 	#	1.) if x values are to far, if YES, we bounce 
 	# 	sides and reverse the direction
 	#	2.) if y values are to far, if YES, we bounce
 	# 	top_bottom and reverse the direction 
 	
 	#test x:
 	my $max_x = $screen_width - $w_w;
 	if($x > $max_x){
 		$left_flag = TRUE;
 		$side_bounce_flag = TRUE;
 	}
 	
 	if ($x < 0){
 		$left_flag = FALSE;
 		$side_bounce_flag = TRUE;
 	}		
 	
 	#test y:
 	my $max_y = $screen_height - $w_h;
 	if ($y > $max_y){
 		$up_flag = TRUE;
 		$bounce_flag = TRUE;
 	}
 	
 	if ($y < 0){
 		$up_flag = FALSE;
 		$bounce_flag = TRUE;
 	}
 	
 	#this will shrink the window prior to changing the image
 	$window->resize(4,4);
 	#move the window to the new position
 	$window->move($x,$y);
 	
 	
 	if ((!($bounce_flag))&&(!($side_bounce_flag))){
 	
 		&do_steps();
 		&do_motions();
 	}
 	
 	($side_bounce_flag)	&&(&bounce_side);
 	($bounce_flag)		&&(&bounce_top_bottom);
 	return TRUE;
  
 }
 
 sub bounce_top_bottom {
 	#working through the top/bottom bounce list of images
 	my $file_string = "./pix/".$bounce_top_bottom[$current_bounce];
 	$current_bounce ++;
 	
 	my($pxm_current, $msk_current) = Gtk2::Gdk::Pixmap->create_from_xpm ($window->window,undef, "$file_string");
 	$img->set_from_pixmap ($pxm_current, $msk_current);
 	$window->window->shape_combine_mask($msk_current, 0, 0);
 	
 	if($current_bounce == $bounce_top_bottom_count -1){
 	#if we got to the end of the list, we have to reset a few variables.
 	#and do the step thing to continue moving
 		$bounce_flag = FALSE;
 		$current_bounce = FALSE;
 		&do_steps();
 		
 	}	
 		
 }
 
 sub bounce_side {
 	#working through the side bounce list of images
 	my $file_string = "./pix/".$bounce_sides[$current_side_bounce];
 	$current_side_bounce ++;
 	
 	my($pxm_current, $msk_current) = Gtk2::Gdk::Pixmap->create_from_xpm ($window->window,undef, "$file_string");
 	$img->set_from_pixmap ($pxm_current, $msk_current);
 	$window->window->shape_combine_mask($msk_current, 0, 0);
 	
 	if($current_side_bounce == $bounce_sides_count -1){
 	#if we got to the end of the list, we have to reset a few variables.
 	#and do the step thing to continue moving
 		$side_bounce_flag = FALSE;
 		$current_side_bounce = FALSE;
 		&do_steps();
 		
 	}	
 	
 }
 
 sub do_steps {
 
 	#depending on the $up_flag we will step up or down
 	if ($up_flag){
 		$y = $y - $step_y;
 	}else{
 		$y = $y + $step_y;
 	}
 
 	#depending on the $left_flag we will step to the left or right
 	if ($left_flag){
 		$x = $x - $step_x;
 		
 	}else{
 		$x = $x + $step_x;
 		
 	}
 
 }
 
 sub do_motions {
 	#when we are not bouncing, we are in motion, this gives the illusion
 	my $file_string = "./pix/".$file_list[$current_file];
 		$current_file ++;
 		
 	($current_file == $list_count)&&($current_file = 0);
 		
 	my($pxm_current, $msk_current) = Gtk2::Gdk::Pixmap->create_from_xpm ($window->window,undef, "$file_string");
 	$img->set_from_pixmap ($pxm_current, $msk_current);
 	$window->window->shape_combine_mask($msk_current, 0, 0);
 
 }

	

10.2.5. Discussing the code.

This section will discuss bits and pieces of the code above.

1. To get the size of the screen where the program is displayed we get the Gtk2::Gdk::Screen of the Gtk2::Window. This will then be used to get the width and height of the screen.

   #discover which size of screen we have
   	my $screen = $window->get_screen();
   	my $screen_width = $screen->get_width();
   	my $screen_height = $screen->get_height();
   		

2. To get the Gtk2::Gdk::Pixmap on the Gtk2::Image widget, we use the following method.

   $img->set_from_pixmap ($pxm_current, $msk_current);
   		

3. To shape the window to the shape of the widget, we use the following method. (Please remember that the window itself has to be of type popup. This type of window does not have any borders etc.)

   $window->window->shape_combine_mask($msk_current, 0, 0);
   		

   This does not need to be just a window, but can be any widget that has a realized Gtk2::Gdk::Window. You can then "shrink" the window around the whole lot by using Gtk2::Gdk::Window's $window->set_child_shapes method.

4. To set the position of the window, we use it's move method.

   $window->move($x,$y);
   		

5. We resize the window to a size smaller than the size of the Gtk2::Image in order to get it to a minimum size as soon as we change the image. This will ensure the mask and the image are on the same spot on the screen.

   $window->resize(4,4);
   		

6. To discover if the window is near the edge of the screen, we have to keep track of the size of the displayed window, and add it to the current position of the window. Once we have that values, we can do our tests to see if it reached the edge of the screen.

   my ($w_w,$w_h) = $window->get_size;
   		

7. To react when the mouse enters the displayed area we use a Gtk2::EventBox. This is because Gtk2::Image (just like Gtk2::Label) do not have an associated Gtk2::Gdk::Window. We therefore put the Gtk2::Image inside the Gtk2::EventBox to catch signals on the Gtk2::Image.

   my $eventbox = Gtk2::EventBox->new ();
   #set the freeze flag when we enter or leave the eventbox
   $eventbox->signal_connect('enter-notify-event' => sub { $freeze_flag = TRUE});
   $eventbox->signal_connect('leave-notify-event' => sub { $freeze_flag = FALSE});
   	my $img = Gtk2::Image->new();
   $eventbox->add($img);
   		

The rest of the code is straight forward Perl and should be easy to follow, since it is heavily commented.