Xfce Foundation Classes
 « Main Page | Index


Ruler widgets are used to indicate the location of the mouse pointer in a given window. A window can have a vertical ruler spanning across its width and a horizontal ruler spanning down its 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. You can create a horizontal ruler with the following constructors:


HRuler(Gtk::MetricType metric);

and a vertical ruler with these constructors:


VRuler(Gtk::MetricType metric);

The first horizontal and vertical constructor will create a new ruler with the metric type of Gtk::PIXELS. The last horizontal and vertical constructor will create a new ruler with the specified metric type.

Units of measure for rulers can be one of the following values from the Gtk::MetricType enum:
  • PIXELS (the default)
The metric type can be set at any time by calling:

void set_metric(Gtk::MetricType metric);

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:

void set_range(double lower, double upper, double position, double 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.  The 'position' argument defines the initial position of the pointer indicator within the ruler.

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

ruler->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 like this instead:

ruler->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 of the widget should be connected to the 'motion_notify_event' method of the ruler.

To follow all mouse movements within a window area, you would use:

window->signal_motion_notify_event().connect(ruler, ruler->gtk_widget_class()->motion_notify_event);

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.

The header file for the Ruler example is <rulers.hh>

#include <xfc/main.hh>
#include <xfc/gtk/ruler.hh>
#include <xfc/gtk/window.hh>

using namespace Xfc;

class RulerWindow : public Gtk::Window

and the source file is <rulers.cc>

#include "rulers.hh"
#include <xfc/gtk/box.hh>
#include <xfc/gtk/drawingarea.hh>
#include <xfc/gtk/table.hh>
#include <xfc/gtk/private/widgetclass.hh>


    // Create a table for placing the ruler and the drawing area
    Gtk::Table *table = new Gtk::Table(3, 2);

    Gtk::DrawingArea *area = new Gtk::DrawingArea(600, 400);
    table->attach(*area, 1, 2, 1, 2, Gtk::EXPAND | Gtk::FILL, Gtk::FILL);

    // 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.
    Gtk::HRuler *hruler = new Gtk::HRuler;
    hruler->set_range(7, 13, 0, 20);
    table->attach(*hruler, 1, 2, 0, 1, Gtk::EXPAND | Gtk::SHRINK | Gtk::FILL, Gtk::FILL);
    // Some C code that connects the drawing area "motion_notify_event" directly to the hruler.  
    GCallback callback = GCallback(GTK_WIDGET_GET_CLASS(hruler->gtk_widget())->motion_notify_event);
    g_signal_connect_swapped(area->g_object(), "motion_notify_event", callback, hruler->gtk_widget());

    // 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.
    Gtk::VRuler *vruler = new Gtk::VRuler;
    vruler->set_range(0, 400, 10, 400);
    table->attach(*vruler, 0, 1, 1, 2, Gtk::FILL, Gtk::EXPAND | Gtk::SHRINK | Gtk::FILL);
    // Some C code that connects the drawing area's "motion_notify_event" directly to the vruler.   
    callback = GCallback(GTK_WIDGET_GET_CLASS(vruler->gtk_widget())->motion_notify_event);
    g_signal_connect_swapped(area->g_object(), "motion_notify_event", callback, vruler->gtk_widget());

    // Now show everything


int main (int argc, char *argv[])
    using namespace Main;

    init(&argc, &argv);

    RulerWindow window;

    return 0;

Compiling Ruler

If you compiled and installed XFC yourself, you will find the source code for Ruler in the <examples/howto/rulers> source directory along with a Makefile. If XFC came pre-installed, or you installed it from an RPM package, you will find the source code in the </usr/share/doc/xfcui-X.X/examples/howto/rulers> subdirectory. In this case you will have to create the Makefile yourself (replace X.X with the version number of the libXFCui library you have installed).

To create a Makefile for Ruler, add the following lines to a new text file and save it using the name "Makefile":

CC = g++

CFLAGS = -Wall -O2

rulers: rulers.cc rulers.hh
    $(CC) rulers.cc -o rulers $(CFLAGS) `pkg-config xfcui-X.X --cflags --libs`

    rm -f *.o rulers

If you cut and paste these lines make sure the whitespace before $(CC) and rm is a tab character. When you compile and run this program you will see the following window appear:

Copyright © 2004-2005 The XFC Development Team Top
XFC 4.4