NAME

Glib::Ex::EnumBits -- misc Glib enum helpers

SYNOPSIS

 use Glib::Ex::EnumBits;

FUNCTIONS

Display

$str = Glib::Ex::EnumBits::to_display ($enum_class, $nick)

Return a string to display $nick from $enum_class. This is meant to be suitable for a menu, label, etc.

$enum_class is a class name such as "Glib::UserDirectory". A class method and hash are consulted, otherwise to_display_default() below is used. That default is often enough.

If $enum_class has a $enum_class->EnumBits_to_display ($nick) method then it's called and if the values is not undef then it's used. For example,

    Glib::Type->register_enum ('My::Things',
                               'foo', 'bar-ski', 'quux');
    sub My::Things::EnumBits_to_display {
      my ($class, $nick) = @_;
      return "some thing $nick";
    }

Or if the class has a %EnumBits_to_display package variable then it's checked and if the hash value is not undef then it's used,

    Glib::Type->register_enum ('My::Things',
                               'foo', 'bar-ski', 'quux');
    %My::Things::EnumBits_to_display = ('foo'     => 'Food',
                                        'bar-ski' => 'Barrage');

In a program (rather than a module) setting the variable this way might provoke a "used only once" warning (see perldiag). Use no warnings 'once', or package and our,

    {
      package My::Things;
      Glib::Type->register_enum (__PACKAGE__, 'foo', 'bar');
      our %EnumBits_to_display = ('foo' => 'Oof');
    }

package style like this can be handy if setting up a to_description() below too.

$str = Glib::Ex::EnumBits::to_display_default ($enum_class, $nick)

Return a string form for value $nick from $enum_class. The nick is split into words and numbers and ucfirst() applied to each word. So for example

    "some-val1" -> "Some Val 1"

The $enum_class parameter is not currently used, but it's the same as to_display() above and might be used in the future for better default mangling. $enum_class can be undef to crunch a $nick from an unknown enum.

Description

$str = Glib::Ex::EnumBits::to_description ($enum_class, $nick)

Return a string description of value $nick from $enum_class, or undef if nothing known. This is meant to be a long form perhaps for a tooltip etc.

If $enum_class has a $enum_class->EnumBits_to_description ($nick) method then it's called,

    Glib::Type->register_enum ('My::Things',
                               'foo', 'bar-ski', 'quux');
    sub My::Things::EnumBits_to_description {
      my ($class, $nick) = @_;
      return "Long text about $nick";
    }

Or if the class has a %EnumBits_to_description hash table that it's used,

    Glib::Type->register_enum ('My::Things',
                               'foo', 'bar-ski', 'quux');
    %My::Things::EnumBits_to_description =
      ('foo'     => 'Some foo for thought',
       'bar-ski' => 'Horizontal line segment');

EXPORTS

Nothing is exported by default, but the functions can be requested in usual Exporter style,

    use Glib::Ex::EnumBits 'to_display_default';
    print to_display_default($class, $nick), "\n";

There's no :all tag since this module is meant as a grab-bag of functions and to import as-yet unknown things would be asking for name clashes.

SEE ALSO

Glib, Glib::Type, Gtk2::Ex::ComboBox::Enum

HOME PAGE

http://user42.tuxfamily.org/glib-ex-objectbits/index.html

LICENSE

Copyright 2010, 2011, 2012, 2014 Kevin Ryde

Glib-Ex-ObjectBits 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.

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