# Copyright 2010, 2011, 2012 Kevin Ryde
# This file is part of Glib-Ex-ObjectBits.
#
# 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/>.
package Glib::Ex::EnumBits;
use 5.008;
use strict;
use warnings;
use Carp;
# uncomment this to run the ### lines
#use Smart::Comments;
use Exporter;
our @ISA = ('Exporter');
our @EXPORT_OK = qw(to_display
to_display_default
to_description);
our $VERSION = 15;
sub to_display {
my ($enum_class, $nick) = @_;
### EnumBits to_display(): "$enum_class $nick"
if (@_ != 2) {
croak 'EnumBits to_display() wrong number of arguments';
}
if (my $coderef = $enum_class->can('EnumBits_to_display')) {
### $coderef
if (defined (my $str = $enum_class->$coderef($nick))) {
return $str;
}
}
if (defined (my $str = do {
no strict 'refs';
${"${enum_class}::EnumBits_to_display"}{$nick}
})) {
return $str;
}
return to_display_default ($enum_class, $nick);
}
sub to_display_default {
my ($enum_class, $nick) = @_;
### EnumBits to_display_default(): $nick
if (@_ != 2) {
croak 'EnumBits to_display_default() wrong number of arguments';
}
my $str = join (' ',
map {ucfirst}
split(/[-_ ]+
|(?<=[^[:upper:][:digit:]])(?=\d) # before a digit
|(?<=\d)(?=\D) # after a digit
|(?<=[[:lower:]])(?=[[:upper:]])
|(?<=[[:upper:]])(?=[[:upper:]][[:lower:]])
/x,
$nick));
if (defined $enum_class
&& defined (my $textdomain = do {
no strict 'refs';
${"${enum_class}::EnumBits_textdomain"}
})
&& Locale::Messages->can('dgettext')) {
$str = Locale::Messages::dgettext ($textdomain, $str);
}
return $str;
}
sub to_description {
my ($enum_class, $nick) = @_;
if (@_ < 2) {
croak "Not enough arguments for EnumBits to_description()";
}
if (my $coderef = $enum_class->can('EnumBits_to_description')) {
return $enum_class->$coderef($nick);
}
return undef;
}
1;
__END__
# # cf g_enum_get_value_by_name() and g_enum_get_value_by_nick()
# sub to_nick {
# my ($enum_class, $value) = @_;
# if (my $h = to_info ($enum_class, $value)) {
# return $h->{'nick'};
# } else {
# return undef;
# }
# }
#
# sub to_info {
# my ($enum_class, $value) = @_;
# my @info = Glib::Type->list_values($enum_class);
# foreach my $h (@info) {
# if ($value eq $h->{'name'}
# || $value eq $h->{'nick'}) {
# return $h;
# }
# }
# if (looks_like_number($value)) {
# foreach my $h (@info) {
# if ($value == $h->{'value'}) {
# return $h;
# }
# }
# }
# return undef;
# }
=for stopwords Ryde enum Enum Glib tooltip Glib-Ex-ObjectBits
=head1 NAME
Glib::Ex::EnumBits -- misc Glib enum helpers
=head1 SYNOPSIS
use Glib::Ex::EnumBits;
=head1 FUNCTIONS
=head2 Display
=over
=item C<< $str = Glib::Ex::EnumBits::to_display ($enum_class, $nick) >>
Return a string to display C<$nick> from C<$enum_class>. This is meant to
be suitable for a menu, label, etc.
C<$enum_class> is a class name such as C<"Glib::UserDirectory">. A class
method and hash are consulted, otherwise C<to_display_default> below is
used. That default is often enough.
If C<$enum_class> has a C<< $enum_class->EnumBits_to_display ($nick) >>
method then it's called and a non-C<undef> 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 C<%EnumBits_to_display> variable that it's checked and
a non-C<undef> there used,
Glib::Type->register_enum ('My::Things',
'foo', 'bar-ski', 'quux');
%My::Things::EnumBits_to_display = ('foo' => 'Food',
'bar-ski' => 'Barrage');
Setting that may provoke a "used only once" warning (see L<perldiag>) in a
program, though normally not in a module. Use C<no warnings 'once'>, or
C<package> and C<our>,
{
package My::Things;
Glib::Type->register_enum (__PACKAGE__, 'foo', 'bar');
our %EnumBits_to_display = ('foo' => 'Oof');
}
C<package> style like this can be handy if setting up a C<to_description>
below too.
=item C<< $str = Glib::Ex::EnumBits::to_display_default ($enum_class, $nick) >>
Return a string form for value C<$nick> from C<$enum_class>. The nick is
split into words and numbers, and C<ucfirst> applied to each word. So for
example
"some-val1" -> "Some Val 1"
The C<$enum_class> parameter is not currently used, but it's the same as
C<to_display> above and might be used in the future for better default
mangling. C<$enum_class> can be C<undef> to crunch for an unknown enum.
=back
=head2 Description
=over
=item C<< $str = Glib::Ex::EnumBits::to_description ($enum_class, $nick) >>
Return a string description of value C<$nick> from C<$enum_class>, or
C<undef> if nothing known. This is meant to be a long form perhaps for a
tooltip etc.
If C<$enum_class> has a C<< $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 C<%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');
=back
=head1 EXPORTS
Nothing is exported by default, but the functions can be requested in usual
C<Exporter> style,
use Glib::Ex::EnumBits 'to_display_default';
print to_display_default ($class, $nick);
There's no C<: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.
=head1 SEE ALSO
L<Glib>,
L<Glib::Type>,
L<Gtk2::Ex::ComboBox::Enum>
=head1 HOME PAGE
L<http://user42.tuxfamily.org/glib-ex-objectbits/index.html>
=head1 LICENSE
Copyright 2010, 2011, 2012 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 L<http://www.gnu.org/licenses/>.
=cut