NAME

Gtk2::Ex::Units -- widget sizes in various units

SYNOPSIS

use Gtk2::Ex::Units;

Gtk2::Ex::Units::set_default_size_with_subsizes
    ($dialog, [ $entry, '40 em' ],
              [ $textview, '20 em', '10 lines' ]);

$pixels = Gtk2::Ex::Units::em($widget);

DESCRIPTION

This is some functions for working with sizes of widgets etc expressed in units like em, line height, millimetres, etc.

The best feature is set_default_size_with_subsizes which helps establish a sensible initial size for a dialog or toplevel window when it includes text entry widgets etc which don't have a desired size, or not when empty.

EXPORTS

Nothing is exported by default, but the functions can be requested individually or with :all in the usual way (see Exporter).

use Gtk2::Ex::Units qw(em ex);

FUNCTIONS

String Sizes

$pixels = Gtk2::Ex::Units::width ($target, $str)

$pixels = Gtk2::Ex::Units::height ($target, $str)

Return a size in pixels on $target for a string $str like

10 chars       # width of a average character
6 ems          # width of an "M" character
1 digit        # width of an average digit 0 to 9
2 ex           # height of an "x" character
1 line         # height of a line (baseline to baseline)
10 mm          # millimetres, per screen size
2.5 inches     # inches, per screen size
5 pixels       # already pixels, just return 5
100            # no units, just return 100

Either singular like "inch" or plural "inches" can be given. The number part can include decimals, and the return may not be an integer.

"em", "ex", "char", "digit" and "line" follow the basic sizes functions below, for the font in $target. For them $target can be a Gtk2::Widget or a Pango layout Gtk2::Pango::Layout.

"mm" and "inch" are based on the screen size for $target. For them $target can be a Gtk2::Widget, a Gtk2::Gdk::Window, or anything with a get_screen giving a Gtk2::Gdk::Screen. In Gtk 2.0.x there's only one screen and $target is currently ignored in that case.

Currently "em" and "digit" are only for use as a width, and ex and line only for a height. In the future they may be supported on the opposite axis, perhaps based on what rotated text would look like. (The same pixels, or scaled if pixels aren't square?)

Gtk2::Ex::Units::set_default_size_with_subsizes ($toplevel, $subsize, ...)

$requisition = Gtk2::Ex::Units::size_request_with_subsizes ($widget, $subsize, ...)

Establish a widget size based on temporary forced sizes for some of its children. Generally the child widgets will be things like Gtk2::TreeView or Gtk2::Viewport which don't have a size while empty but where you want to allow room for likely contents.

Each $subsize argument is an arrayref

[ $widget, $width, $height ]

$width and $height are put through the width and height functions above, so they can be either a count of pixels, or a string like "6 ems" or "10 lines". -1 means the widget's desired size in that axis (as usual for set_size_request), and undef means the current size request setting of that axis (ie. no change to it).

set_default_size_with_subsizes is for use on Gtk2::Window toplevel or dialog widgets and applies the size to $toplevel->set_default_size. This gives a good initial size for $toplevel, but allows the user to expand or shrink later.

Gtk2::Ex::Units::set_default_size_with_subsizes
    ($dialog, [ $textview, '40 ems', '10 lines' ]);

size_request_with_subsizes is for use on any container widget and just returns a new Gtk2::Requisition with the size determined.

Basic Sizes

In the following functions $target can be a Gtk2::Widget or a Pango::Layout.

$pixels = Gtk2::Ex::Units::em ($target)

$pixels = Gtk2::Ex::Units::ex ($target)

Return the width of an "M", or the height of an "x", in pixels, for $target.

Currently an em includes inter-character spacing, so that "3 ems" makes room for "MMM", but an ex is just the inked height of that character.

$pixels = Gtk2::Ex::Units::char_width ($target)

$pixels = Gtk2::Ex::Units::digit_width ($target)

Return the average width in pixels of a character or just a digit (0-9), for $target.

Currently these are per Pango's get_approximate_char_width and get_approximate_digit_width. In a proportional font some characters or some of the digits may be wider than the average.

$pixels = Gtk2::Ex::Units::line_height ($target)

Return the height of a line, in pixels, for $target. This the height of the glyphs in the target font, plus any Pango line spacing per ($layout->set_spacing).

SEE ALSO

Gtk2::Gdk::Screen, for screen size in pixels and millimetres (or Gtk2::Gdk for the Gtk 2.0.x single-screen sizes).

Math::Units

HOME PAGE

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

LICENSE

Copyright 2007, 2008, 2009, 2010, 2011 Kevin Ryde

Gtk2-Ex-WidgetBits 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-WidgetBits 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-WidgetBits. If not, see http://www.gnu.org/licenses/.