NAME

Gtk2::Ex::NumAxis -- numeric axis display widget

SYNOPSIS

use Gtk2::Ex::NumAxis;
my $axis = Gtk2::Ex::NumAxis->new (adjustment => $adj);

WIDGET HIERARCHY

Gtk2::Ex::NumAxis is a subclass of Gtk2::DrawingArea, but don't rely on more than Gtk2::Widget, and probably don't rely on it being a windowed widget.

Gtk2::Widget
  Gtk2::DrawingArea
    Gtk2::Ex::NumAxis

DESCRIPTION

A Gtk2::Ex::NumAxis widget displays a vertical axis of values like

+---------+
|         |
| -- 8.5  |
|         |
| -- 9    |
|         |
| -- 9.5  |
|         |
| -- 10   |
|         |
| -- 10.5 |
|         |
+---------+

The numbers are the "page" portion of a Gtk2::Adjustment and update with changes in that Adjustment. A unit step 1, 2 or 5 for the display is chosen according to what fits in the window.

Decimal places are added as necessary and the min-decimals property can force a certain minimum decimals for example to show dollars and cents. The number-to-text signal allows things like thousands separators or different decimal point.

Pixel y=0 is the "value" from the adjustment and the window height is the "page" amount, so that pixel y=winheight (one past the bottom of the window) is "value+page". The inverted property swaps that to the "value" at the bottom of the display.

Size Request

An axis has a desired width, but doesn't ask for any particular height. However the height which is applied by the container parent determines the step between displayed values, and thus how many decimal places are needed, which can affect what width is necessary.

If the drawing code notices a number shown is wider than a width previously requested then a resize is queued. Hopefully this only happens if a number-to-text handler is doing strange things with values. It potentially means a disconcerting size increase while scrolling, but at least ensures values are not truncated. Of course a size request is only ever a request, the parent container determines how much space its children get.

A Gtk2::Ex::NoShrink container can help keep a lid on resizing, if for instance changes to the Adjustment range would often cause a different width.

FUNCTIONS

$axis = Gtk2::Ex::NumAxis->new (key=>value,...)

Create and return a new NumAxis widget. Optional key/value pairs set initial properties per Glib::Object->new.

my $adj = Gtk2::Adjustment->new (5,0,20, 1,8, 10);
Gtk2::Ex::NumAxis->new (adjustment => $adj,
                        min_decimals => 1);

$axis->set_scroll_adjustments ($hadj, $vadj)

This usual Gtk2::Widget method sets the adjustment property to $vadj.

If there's a horizontal orientation option in the future then when set it would take the $hadj instead, probably just from the current orientation, not keeping both adjustments and switching between them.

PROPERTIES

adjustment (Gtk2::Adjustment, default undef)

The adjustment object giving the values to display and track. NumAxis is blank until an adjustment is set and has a non-zero page-size.

inverted (boolean, default 0)

Draw the adjustment value at the bottom of the widget and page-size increasing up the window, as opposed to the default of value at the top going downwards. This sense of "inverted" is the same as in a Gtk2::VScrollbar.

min-decimals (integer, default 0)

The minimum number of decimal places to show on the numbers. Further decimals are shown if the unit step chosen needs more.

In the future there might be an orientation property for a horizontal axis, and perhaps some transforms for log scale or similar.

SIGNALS

number-to-text ($number double, $decimals int -> return string)

Callback to format a number for display with a given number of decimal places. The default display is a plain sprintf("%.*f"). This signal allows things like a thousands separator or different decimal point. For example using Number::Format,

my $nf = Number::Format->new (-thousands_sep => ' ',
                              -decimal_point => ',');
sub my_number_to_text_handler {
  my ($axis, $number, $decimals) = @_;
  return $nf->format_number ($number, $decimals,
                             1); # include trailing zeros
}
$axis->signal_connect (number_to_text
                       => \&my_number_to_text_handler);

The $decimals parameter is how many decimals are being shown. This is at least min-decimals but can be more if a higher resolution fits in the axis window. The handler can decide how many trailing zeros to actually show.

Strings formed shouldn't be too bizarre, mainly because the widget width is established just from some representative high and low values. Things like +/- sign or leading and trailing zeros are fine.

BUILDABLE

Gtk2::Ex::NumAxis inherits the usual widget Gtk2::Buildable interface in Gtk 2.12 and up, allowing Gtk2::Builder to construct a NumAxis. The class name is Gtk2__Ex__NumAxis and properties and signal handlers can be set in the usual way. Here's a sample fragment, or see examples/builder.pl in the NumAxis sources for a complete program.

<object class="Gtk2__Ex__NumAxis" id="my_axis">
  <property name="adjustment">my_adj</property>
  <signal name="number-to-text" handler="my_number_to_text"/>
</object>

SEE ALSO

Gtk2::Widget, Gtk2::Adjustment, Gtk2::VScrollbar, Gtk2::Builder, Gtk2::Ex::NoShrink

For number formatting see Number::Format, Locale::Currency::Format, PAB3::Utils (has an strfmon)

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-numaxis/index.html

COPYRIGHT

Copyright 2007, 2008, 2009, 2010 Kevin Ryde

Gtk2-Ex-NumAxis is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Gtk2-Ex-NumAxis is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gtk2-Ex-NumAxis. If not, see http://www.gnu.org/licenses/.

cpanm Gtk2::Ex::NumAxis

perl -MCPAN -e shell
install Gtk2::Ex::NumAxis