NAME
UI::Various::core - core functions of UI::Various
SYNOPSIS
# This module should never be used directly!
# It is used indirectly via the following:
use UI::Various;ABSTRACT
This module is the main worker module for the UI::Various package.
DESCRIPTION
The documentation of this module is mainly intended for developers of the package itself.
Basically the module is a singleton providing a set of functions to be used by the other modules of UI::Various.
EXPORT
No data structures are exported, the core module is only accessed via its functions (and initialised with the import method indirectly called via use UI::Various;).
METHODS and FUNCTIONS
import - initialisation of UI::Various package
Otherwise this method just exports the core functions to our other modules.
language - get or set currently used language
internal implementation of UI::Various::language
logging - get or set currently used logging-level
internal implementation of UI::Various::logging
stderr - get or set currently used handling of output
internal implementation of UI::Various::stderr
using - get currently used UI as text string
internal implementation of UI::Various::using
ui - get currently used UI
$interface = UI::Various::core::ui();example:
$_ = UI::Various::core::ui() . '::Main::_init';
{ no strict 'refs'; &$_($self); }description:
This function returns the full name of the currently used user interface, e.g. to access its methods.
returns:
full name of UI
fatal - abort with error message
fatal($message_id, @message_data);example:
fatal('bad_usage_of__1_as__2', __PACKAGE__, $pkg);
fatal('UI__Various__core_must_be_1st_used_from_UI__Various');parameters:
$message_id ID of the text or format string in language module
@message_data optional additional text data for format stringdescription:
This function looks up the format (or simple) string passed in $message_id in the text hash of the currently used language, formats it together with the @message_data with sprintf and passes it on to croak.
error / warning / info - print error / warning / info message
error($message_id, @message_data);
warning($message_id, @message_data);
info($message_id, @message_data);example:
warning('message__1_missing_in__2', $message_id, $UI->{language});parameters:
$message_id ID of the text or format string in language module
@message_data optional additional text data for format stringdescription:
If the current logging level is lower than ERROR / WARNING / INFO these functions do nothing. Otherwise they print the formatted message using _message.
_message has logging level to be printed as additional 1st parameter. It checks the logging level, looks up the format (or simple) string passed in $message_id in the text hash of the currently used language, formats the latter together with the @message_data with sprintf and passes it on to carp (in case of errors or warnings) or warn (in case of informational messages).
returns:
always undef (to allow something like return error(...); indicating the error to the caller)
message - return formatted message
$string = message($message_id, @message_data);example:
$_ = message('can_t_open__1__2', $_, $!);parameters:
$message_id ID of the text or format string in language module
@message_data optional additional text data for format stringdescription:
This function just returns the formatted message for the given $message_id and @message_data, e.g. to be used within a compound widget.
returns:
the formatted message as string
debug - print debugging message
debug($level, @message);example:
debug(1, __PACKAGE__, '::new');parameters:
$level debug-level of the message (>= 1)
@message the text to be printeddescription:
If the current logging level is lower than DEBUG_n (with n being the $level specified in the call) this function does nothing. Otherwise it prints the given text. Note that debugging messages are always English, so they can be added / removed / changed anytime without bothering about the UI::Various::language modules. Also note that debug messages are printed with warn and prefixed with DEBUG and some blanks according to the debug-level.
msg - look-up text for currently used language
$message = msg($message_id);example:
$_ = sprintf(msg($message_id), @_);parameters:
$message_id ID of the text or format string in language moduledescription:
This method looks up the format (or simple) string passed in $message_id in the text hash of the currently used language and returns it.
construct - common constructor for UI elements
$ui_element = UI::Various::Element->new(%attributes);example:
$ui_element = UI::Various::Element->new();
$ui_element = UI::Various::Element->new(attr1 => $val1, attr2 => $val2);
$ui_element = UI::Various::Element->new({attr1 => $val1, attr2 => $val2});parameters:
%attributes optional hash with initial attribute valuesdescription:
This function contains the common constructor code of all UI element classes ( UI::Various::[A-Z]*). Initial values can either be passed as an array of key/value pairs or as a single reference to a hash containing those key/value pairs. Note that if the class defines a (private) setter method _attr (tried 1st) or a (public) accessor attr (tried 2nd), it is used to assign the value before falling back to a simple assignment.
The internal implementation has the following interface:
$self = construct($attributes, $re_allowed_params, $self, @_);It is used like this:
sub new($;\[@$])
{
return construct({ DEFAULT_ATTRIBUTES },
'^(?:' . join('|', ALLOWED_PARAMETERS) . ')$',
@_);
}The additional parameters are:
$attributes reference to hash with default attributes
$re_allowed_params regular expression matching all allowed parameters
$self name of class or reference to other element of class
@_ parameters passed to caller's C<new>returns:
blessed new UI element
access - common accessor for UI elements
$value = $ui_element->attribute();
$ui_element->attribute($value);parameters:
$value optional value to be setdescription:
This function contains the common accessor code of all UI element classes ( UI::Various::[A-Z]*) aka implementing a combined standard getter / setter. When it's called with a value, the attribute is set. In all cases the current (after modification, if applicable) value is returned. If the value is a SCALAR reference it is stored as reference but returned as value.
The internal implementation has the following interface:
$value = access($attribute, $sub_set, $self, $new_value);It is used like this:
sub attribute($;$)
{
return access('attribute', sub{ ... }, @_);
}
or simply
sub attribute($;$)
{
return access('attribute', undef, @_);
}The additional parameters are:
$attribute name of the attribute
$sub_set optional reference to a subroutine called when
the function is used as a setter (see below)
$self reference to the class object
@_ the optional new value and possible other parameters
passed to C<$sub_set>The optional subroutine gets the new value passed in $_ and must return the value to be set in $_ as well. To allow for complicated tests and/or side-effects it gets $self and possible additional parameters passed in @_. The return value of the subroutine itself decides, if the attribute is modified: If it's undef, the previous value is kept. In all other cases the attribute gets the new value as defined in $_. Note that the subroutine gets the value even in case of a SCALAR reference.
If no additional code is needed, the parameter can be undef as in the 2nd example above.
returns:
the current value of the attribute (SCALAR references are dereferenced)
set - common setter for UI elements
$ui_element->attribute($value);parameters:
$value mandatory value to be setdescription:
This function contains the common setter code of all UI element classes ( UI::Various::[A-Z]*). Basically it's an accessor with a mandatory value to be set. Like access it returns the updated value. If the value is a SCALAR reference it is stored as reference but returned as value.
The internal implementation has the following interface:
$value = set($attribute, $sub_set, $self, $new_value);It is used like this:
sub _attribute($$)
{
return set('attribute', sub{ ...; }, @_);
}
or simply
sub _attribute($$)
{
return set('attribute', undef, @_);
}The additional parameters are:
$attribute name of the attribute
$sub_set optional reference to a subroutine called within the
setter
$self name of class or reference to other element of class
@_ the new value and possible other parameters passed
to C<$sub_set>The optional subroutine gets the new value passed in $_ and must return the value to be set in $_ as well. To allow for complicated tests and/or side-effects it gets $self and possible additional parameters passed in @_. The return value of the subroutine itself decides, if the attribute is modified: If it's undef, the previous value is kept. In all other cases the attribute gets the new value as defined in $_. Note that the subroutine gets the value even in case of a SCALAR reference.
If no additional code is needed, the parameter can be undef as in the 2nd example above.
returns:
the new value of the attribute (SCALAR references are dereferenced)
get - common getter for UI elements
$value = $ui_element->attribute();description:
This function contains the common getter code of all UI element classes ( UI::Various::[A-Z]*), implementing a very simple getter returning the current value of the attribute (but still with all sanity checks). Note that if the attribute is a SCALAR reference it is nonetheless returned as value. (If you really need the reference itself, access it directly as $ui_element-{attribute}>.)
The internal implementation has the following interface:
$value = get($attribute, $self);It is used like this:
sub attribute($) { return get('attribute', @_); }The additional parameters are:
$attribute name of the attribute
$self name of class or reference to other element of classreturns:
the current value of the attribute (SCALAR references are dereferenced)
access_varref - special accessor for UI elements needing SCALAR ref.
$value = $ui_element->attribute();
$ui_element->attribute(\$variable);parameters:
$variable optional SCALAR reference to be setdescription:
This function contains a variant of the common accessor access that is used by attributes needing a SCALAR reference to a variable. Those still always return the current value of the variable when used as getter, but the setter directly uses the SCALAR reference.
The internal implementation has the following interface (note the missing subroutine):
$value = access_varref($attribute, $self, $new_value);It is used like this:
sub attribute($;$)
{
return access_varref('attribute', @_);
}The additional parameters are:
$attribute name of the attribute
$self reference to the class object
$r_variable the optional SCALAR referencereturns:
the current value of the attribute (the SCALAR reference is dereferenced)
dummy_varref - create a dummy SCALAR reference
$scalar = dummy_varref();description:
This function returns a SCALAR reference to a dummy variable initialised with an empty string. Note that each call returns a reference to a different variable. The function can be used to initialise use constant constants.
returns:
a scalar reference to an empty variable
_tui_color - translate any colour into internal terminal colour
my $tui_colour = _tui_color($colour);description:
For the given colour (6 character hex-value) this internal function returns the corresponding valid terminal colour index (one of 216 possible, for details see bg in UI::Various::widget).
Note that the interface of this function is internal and may change in the future or even disappear at all.
returns:
TUI colour index, a number in [0, 215]
SEE ALSO
LICENSE
Copyright (C) Thomas Dorner.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE file for more details.
AUTHOR
Thomas Dorner <dorner (at) cpan (dot) org>