Max_size arg to gtk_ruler_set_range()

[Syd Logan <logansyd netscape net>]

The include files says:

struct _GtkRuler
{
...
/* The maximum size of the ruler */
gfloat max_size;
};

Ok, somewhat obfuscated, so I tried to dig into it. The only place(s) it
is used are in gtk_[hv]ruler_draw_tics(). While I can follow the code
easily enuf in a debugger, I'm at a loss of words to describe (in my book)
exactly how one goes about choosing an appropriate value. The
documentation on the Gtk+ web site (any of it) is inadequate or wrong
given what I have seen. Here's what I have to say as I flesh out a
description for my book, perhaps someone can summarize what i am seeing
(while I go on to write about something else):

The file gtkruler.c defines the following table, which is used internally
by GtkRuler:

static const GtkRulerMetric ruler_metrics[] =

 {"Pixels", "Pi", 1.0, { 1, 2, 5, 10, 25, 50, 100, 250, 500, 1000 },
      { 1, 5, 10, 50, 100 }},
 {"Inches", "In", 72.0, { 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 },
      { 1, 2, 4, 8, 16 }},
 {"Centimeters", "Cn", 28.35, { 1, 2, 5, 10, 25, 50, 100, 250, 500, 1000 },
      { 1, 5, 10, 50, 100 }},
};

Let's focus on the first entry, which is used whenever the metric
attribute is set to GTK_PIXELS, as it is what most applications use, and
it is the easiest to understand. The fourth field of the "Pixels" entry is
an array of integers:

{ 1, 2, 5, 10, 25, 50, 100, 250, 500, 1000 }

Each of these values represents a label increment. Let's assume that the
range of the ruler is [0, 300]. The entry 5 would mean labels are drawn by
the ruler in increments of 5, i.e., the 0, 5, 10, ..., 300 ticks would all
be labeled by the ruler widget for the range [0, 300]. If the label only
ranges in value from [0, 10], the only increments that make sense are 1,
2, and 5. The width or height of the ruler, and the width or height of the
font that is used to draw the labels affects what increments can be drawn
by the ruler: the wider or taller the font, and the less wide (tall) the
ruler translate into less ticks that can be labeled, and thus favoring
label increments that are larger.

So, exactly what part does the max_size argument play in all of this? The
only way to know for sure is to look at the source code. First, the width
of the ruler is obtained (line 001). Following this, two variables, lower
and upper, are computed (lines 002 and 003):

001 width = widget->allocation.height;
002 upper = ruler->upper / ruler->metric->pixels_per_unit;
003 lower = ruler->lower / ruler->metric->pixels_per_unit;

For this example, the variable width = 282, ruler->upper = 300,
ruler->lower = 0, and ruler->metric->pixels_per_unit is 1 (since the
metric is GTK_PIXELS). As a result, upper is assigned 300, and lower is
assigned 0. With these values, the variable increment is given the value
4.06320275e-34 on line 004:

004 increment = (gfloat) width / (upper - lower);

For the following code, let ruler->max_size = 1 and font->ascent = 11. Then:

005 scale = ceil (ruler->max_size / ruler->metric->pixels_per_unit);
006 sprintf (unit_str, "%d", scale);
007 digit_height = font->ascent; /* assume descent == 0 ? */

we have scale = 1 and digit_height = 11. On line 008, text_height is
assigned the value 12:

008 text_height = strlen (unit_str) * digit_height + 1;

Then, we go into a loop, looking at values in the metric ruler_scale field
until it, times the increment, is greater than twice the text_height (24
in this case):

009 for (scale = 0; scale < MAXIMUM_SCALES; scale++)
010     if (ruler->metric->ruler_scale[scale] * fabs(increment) >
                      2 * text_height)
011             break;

The loop terminates with scale = 6, meaning the label increment is 50.
Accordingly, labels are drawn at intervals of 50, e.g., 0, 50, 100, ...,
300. Let's try again with a max_size of 128. In this case, the loop
above terminates with scale set to 6, which indexes the value 100 in the
metric_ruler scale field. Sure enough, only ticks 0, 100, and 200 are
printed this time.

Let's increase the size of the ruler by widening the window and see how
that affects the drawing of ticks. Here, the ruler size is 706 pixels, and
with a ruler->max_size set to 1, the loop stops with scale = 4, meaning
the label increment is 25. Thus, labels are drawn at 0, 25, 50, 75, ...,
300. With the max_size attribute set to 128, ticks are labeled at
intervals of 50.

...

Thanks in advance,

syd





____________________________________________________________________
Get your own FREE, personal Netscape WebMail account today at http://home.netscape.com/webmail