The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Gtk2-Ex-NumAxis-5
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.2     8.4     8.6     8.8     9.0 |
    | -- 10   |       +--------------------------------------+
    |         |
    | -- 10.5 |
    |         |
    +---------+

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

Decimal places are shown 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 formatting like a thousands separator 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. (This is the same sense as "inverted" on Gtk2::Scrollbar.)

Scrolling

A scroll-event handler moves the Adjustment for mouse wheel and similar events arriving on the NumAxis. If the control key is held down then it's moved by page-increment, otherwise step-increment.

In a horizontal NumAxis an up and down scroll is applied as well as right and left. Conversely a vertical takes right and left too. This is a bit experimental but allows a mouse with only a vertical wheel to move a horizontal NumAxis.

Size Request

A vertical NumAxis has a desired width, but doesn't ask for any particular height. A horizontal NumAxis conversely has a desired height but no particular width.

For a vertical NumAxis the height provided by the container parent determines the step between displayed values and thus how many decimal places are needed, which can in turn 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 such a resize only happens if a number-to-text handler is doing strange things. It may cause 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 is the usual Gtk2::Widget method setting the adjustment property to $hadj when horizontal or $vadj when vertical.

Currently either $hadj or $vadj is taken according to 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 it has a non-zero page-size.

inverted (boolean, default 0)

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

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

This sense of inverted is the same as 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, but at least this many are always shown.

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 an sprintf("%.*f"). This signal allows things like a thousands separator or different decimal point. For example a 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 either min-decimals or more if a higher resolution fits in the axis window. The handler can decide how many trailing zeros to actually show (or any separator within the decimals, etc).

Strings formed shouldn't be too bizarre, mainly because the NumAxis width is established just from some representative values based on the adjustment upper and lower (but not necessarily those particular 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, so Gtk2::Builder can 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, 2011 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/.