/ 
Gtk2-Ex-NumAxis-3
River stage one • 1 direct dependent • 1 total dependent
/ Gtk2::Ex::NumAxis

NAME

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

SYNOPSIS

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

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  |       |   :       :       :       :       :  |
|         |       |  8.5      9      9.5     10     10.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 x=0 or y=0 is the "value" from the adjustment and the window width or height is the "page" amount. The inverted property swaps that to the "value" at the bottom or right of the display.

Size Request

An vertical axis has a desired width, but doesn't ask for any particular height. Or a horizontal axis conversely has a desired height but no particular width.

For a vertical axis the height 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 a resize 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 $hadj when horizontal or $vadj when vertical.

Currently the respective adjustment is taken from the current orientation. The other is not recorded and is not switched to if the orientation is later changed. This is simplest, but is it a good idea? Orientation changes will be a bit unusual, but perhaps it should switch dynamically between the adjustments too.

PROPERTIES

orientation (enum Gtk2::Orientation, default "vertical")

The direction to draw in the axis, either vertically or horizontally.

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)

Vertically the normal drawing is the adjustment value at the top and numbers increasing downwards. If inverted is true then value is at the bottom and numbers increase upwards.

Conversely for horizontal the normal drawing is the adjustment value at the left and numbers increasing rightwards. If inverted is true then value is at the right and numbers increase to the left.

The sense of inverted here is the same as a Gtk2::HScrollbar or Gtk2::VScrollbar. If using an NumAxis and a scrollbar together then generally the inverted setting should be the same in the two.

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.

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/.