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 size $str like

6 ems          # width of an "M" character
1 digit        # width of a 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. Decimals can be given, and the return may not be an integer.

"em", "ex", "digit" and "line" follow the basic sizes functions below, according to 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.

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, probably 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.

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

Return the width of the widest digit "0" to "9", in pixels, for $target. In a proportional font a "1" might be narrower than a "9", making digit_width an over-estimate of the size you need for some values.

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

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

SEE ALSO

Gtk2::Gdk::Screen for screen size in pixels and millimetres

Math::Units

HOME PAGE

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

LICENSE

Copyright 2007, 2008, 2009 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/.