Gtk-Perl Tutorial
PrevNext

Chapter 30. Rulers

Inheritance Hierarchy

Object
   +--- Widget
         +--- Ruler
         

Ruler widgets are used to indicate the location of the mouse pointer in a given window. A window can have a horizontal ruler spanning across the width and a vertical ruler spanning down the height. A small triangular indicator on the ruler shows the exact location of the pointer relative to the ruler.

A ruler must first be created. Horizontal and vertical rulers are created using

$hruler = new Gtk::HRuler();

$vruler = new Gtk::VRuler();

Once a ruler is created, we can define the unit of measurement. Units of measure for rulers can be 'pixels', 'inches' or 'centimeters'. This is set using:

$ruler->set_metric( $metric );

The default measure is 'pixels'.

Other important characteristics of a ruler are how to mark the units of scale and where the position indicator is initially placed. These are set for a ruler using

$ruler->set_range( $lower, $upper, $position, $max_size );

The $lower and $upper arguments define the extent of the ruler, and $max_size is the largest possible number that will be displayed. $position defines the initial position of the pointer indicator within the ruler.

A vertical ruler can span an 800 pixel wide window thus:

$vruler->set_range( 0, 800, 0, 800 );

The markings displayed on the ruler will be from 0 to 800, with a number for every 100 pixels. If instead we wanted the ruler to range from 7 to 16, we would code:

$vruler->set_range( 7, 16, 0, 20 );

The indicator on the ruler is a small triangular mark that indicates the position of the pointer relative to the ruler. If the ruler is used to follow the mouse pointer, the 'motion_notify_event' signal should be connected to the 'motion_notify_event' method of the ruler. To follow all mouse movements within a window area, we would use:

        $area->signal_connect( "motion_notify_event",
                               sub { $ruler->motion_notify_event( $_[1] ); } );

30.1. Ruler Example

The following example creates a drawing area with a horizontal ruler above it and a vertical ruler to the left of it. The size of the drawing area is 600 pixels wide by 400 pixels high. The horizontal ruler spans from 7 to 13 with a mark every 100 pixels, while the vertical ruler spans from 0 to 400 with a mark every 100 pixels. Placement of the drawing area and the rulers is done using a table.

Ruler Program Source 

      
#!/usr/bin/perl -w

use Gtk;
use strict;

set_locale Gtk;
init Gtk;

my $false = 0;
my $true = 1;

my $xsize = 600;
my $ysize = 400;

my $window;
my $table;
my $area;
my $hrule;
my $vrule;


# Create the window
$window = new Gtk::Window( "toplevel" );
$window->signal_connect( "delete_event", sub { Gtk->exit( 0 ); } );
$window->border_width( 10 );

# Create a table for placing the ruler and the drawing area
$table = new Gtk::Table( 3, 2, $false );
$window->add( $table );

# Create the drawing area.
$area = new Gtk::DrawingArea();
$area->size( $xsize, $ysize );
$table->attach( $area, 1, 2, 1, 2, [ 'expand', 'fill' ], 'fill', 0, 0 );
$area->set_events( [ 'pointer_motion_mask', 'pointer_motion_hint_mask' ] );

# The horizontal ruler goes on top. As the mouse moves across the
# drawing area, a motion_notify_event is passed to the
# appropriate event handler for the ruler.
$hrule = new Gtk::HRuler();
$hrule->set_metric( 'pixels' );
$hrule->set_range( 7, 13, 0, 20 );
$area->signal_connect( "motion_notify_event",
		       sub { $hrule->motion_notify_event( $_[1] ); } );
$table->attach( $hrule, 1, 2, 0, 1,
		[ 'expand', 'shrink', 'fill' ],
		'fill', 0, 0 );

# The vertical ruler goes on the left. As the mouse moves across
# the drawing area, a motion_notify_event is passed to the
# appropriate event handler for the ruler.
$vrule = new Gtk::VRuler();
$vrule->set_metric( 'pixels' );
$vrule->set_range( 0, $ysize, 10, $ysize );
$area->signal_connect( "motion_notify_event",
		       sub { $vrule->motion_notify_event( $_[1] ); } );
$table->attach( $vrule, 0, 1, 1, 2,
		[ 'fill', 'expand', 'shrink' ],
		'fill', 0, 0 );

# Now show everything
$area->show();
$hrule->show();
$vrule->show();
$table->show();
$window->show();

main Gtk;
exit( 0 );


# END EXAMPLE PROGRAM

Ruler Example Screenshot

If you look closely, you will notice that my mouse pointer doesn't appear in the above image (because the screenshot program I'm using removes it), but you can tell where it is by the arrows in the ruler. I will look into a program that keeps the pointer in the screenshot.

PrevHomeNext
Tooltip WidgetsUpColor Selection