File Coverage

blib/lib/UI/Various.pm
Criterion Covered Total %
statement 22 22 100.0
branch 4 4 100.0
condition n/a
subroutine 8 8 100.0
pod n/a
total 34 34 100.0


line stmt bran cond sub pod time code
1             package UI::Various;
2              
3             # Author, Copyright and License: see end of file
4              
5             =head1 NAME
6              
7             UI::Various - graphical/non-graphical user interface without external programs
8              
9             =head1 SYNOPSIS
10              
11             use UI::Various;
12              
13             =head1 ABSTRACT
14              
15             B
16             restrictions.> Currently it provides basic functionality only (no dialogues,
17             no frills).
18              
19             Did you ever need to decide if a graphical or text based user interface is
20             best for your Perl application? A GUI may be easier to use, but will not
21             run on run on a server without a window system (like X11 or Wayland) and
22             makes testing it more difficult. The solution to this dilemma is
23             UI::Various.
24              
25             UI::Various is a simple variable graphical and non-graphical user interface
26             (UI). Unlike L is uses no external programs. Instead,
27             depending on the Perl UI packages installed on a machine, it used the best
28             one available from a list of different UI systems. If none could be found
29             at all, it falls back to a very simple query/response interface on the
30             terminal / console using only core components. To make an application as
31             accessible as possible (for the visually impaired or any automated script)
32             it also allows selection of a specific (installed) UI by the user via the
33             environment variable C.
34              
35             Of course this variability does not come without some simplifications:
36              
37             At any time there can be only one active window and one (modal) dialogue "in
38             front" of that window. See L for more details. All graphics,
39             pictures or icons (unless the later are part of the character set used) need
40             alternative descriptions for the text based interfaces, which can make a big
41             difference in the usability.
42              
43             =head1 DESCRIPTION
44              
45             UI::Various is a user interface (UI) choosing the best available UI from a
46             list of supported ones to an end-user. Preferably - but depending on
47             installed Perl packages and the environment, especially the environment
48             variables C and C - this would be a graphical user interface
49             (GUI), but it can fallback to a non-graphical alternative (terminal user
50             interface aka TUI) and a very simple command-line based one as last resort.
51              
52             Currently UI::Various supports the following UIs (the sequence here is also
53             the default selection sequence):
54              
55             =over
56              
57             =item C>
58              
59             probably the oldest GUI available for Perl, needs a defined C
60             environment variable
61              
62             =item C
63              
64             the standard terminal UI using the L package
65              
66             =item C
67              
68             a builtin query/response console interface still using ANSI colours, simple
69             graphics and L for the input (only Perl core modules)
70              
71             =item (finally) C
72              
73             a very simple builtin query/response console interface where nested
74             container elements must be selected to interact with something inside; they
75             are also simply displayed in sequence without other arrangement
76              
77             =back
78              
79             If the environment variable C is set, contains one of the values above
80             and meets all requirements for the corresponding UI, it's taking precedence
81             over the list in the C statement.
82              
83             =head1 LIMITS
84              
85             As it is quite difficult to (as a developer) implement and/or (as a user)
86             understand a terminal based UI with multiple parallel windows to interact
87             with, only one window may be active at any time. For simple modal queries
88             this window may open a dialogue window blocking itself until the dialogue
89             returns. However, it is possible to have a list of multiple windows and
90             switch between them: One is active and the others are inactive, waiting to
91             be activated again. See C and
92             C.
93              
94             Check buttons may not have variable texts.
95              
96             Radio buttons can only be arranged vertically.
97              
98             =head1 KNOWN BUGS
99              
100             Setting an attribute of any object to C will not work with Perl
101             versions prior to 5.20 (see L, bugs #7508 and #109726). The
102             only possible (and dirty!) workaround is setting the member of the internal
103             hash directly.
104              
105             Boxes can not have visible borders in L as they are currently
106             "faked" and do not use a proper L element.
107              
108             Methods, member variables, etc. starting with an underscore (C<_>) are
109             considered to be internal only. Their usage and interfaces may change
110             between versions in an incompatible way!
111              
112             We (try to) use US English for identifiers while using GB English for the
113             documentation. This is intended and not a bug!
114              
115             =cut
116              
117             #########################################################################
118              
119 23     23   1580724 use v5.14;
  23         222  
120 23     23   2258 use strictures;
  23         7104  
  23         152  
121 23     23   6382 no indirect 'fatal';
  23         4704  
  23         149  
122 23     23   3379 no multidimensional;
  23         12945  
  23         185  
123 23     23   914 use warnings 'once';
  23         37  
  23         840  
124              
125 23     23   115 use Carp; # may only be used in import!
  23         48  
  23         1958  
126              
127             our $VERSION = "0.22";
128              
129 23     23   10111 BEGIN { require UI::Various::core; }
130              
131             #########################################################################
132              
133             =head1 METHODS
134              
135             =cut
136              
137             #########################################################################
138             #########################################################################
139              
140             =head2 B - import and initialisation of UI::Various package
141              
142             use UI::Various;
143             or
144             use UI::Various({});
145              
146             =head3 example:
147              
148             use UI::Various({ use => [qw(Tk RichTerm)],
149             log => 'INFO',
150             language => 'de',
151             stderr => 1,
152             include => [qw(Main Window Button)]});
153              
154             =head3 parameters:
155              
156             use prioritised list of UI packages to be checked/used
157             language (initial) language used by the package itself
158             (both for debugging and UI elements)
159             log (initial) level of logging
160             stderr (initial) handling of STDERR output
161             include list of UI element packages to include as well
162              
163             =head3 description:
164              
165             This method initialised the UI::Various package. It checks for the UI
166             packages available and selects / initialises the best one available. In
167             addition it sets up the handling of error messages and the (initial)
168             language and debug level of the package.
169              
170             The prioritised list of UI packages (C) is a list of one or usually
171             more than one of the possible interface identifiers listed above. Note that
172             the last resort UI C is always added automatically to the end of
173             this list.
174              
175             =head4 C
176              
177             configures the initial language used by the package itself, both for
178             messages and the UI elements. Currently 2 languages are supported:
179              
180             =over
181              
182             =item de
183              
184             =item en (default)
185              
186             =back
187              
188             =head4 C
189              
190             sets the initial level of logging output:
191              
192             =over
193              
194             =item C
195              
196             Log only fatal errors that cause UI::Various (and thus the application using
197             it) to abort.
198              
199             =item C
200              
201             Also log non-fatal errors like bad parameters replaced by default values.
202             This is the default value.
203              
204             =item C or C
205              
206             Also log warnings like features not supported by the currently used UI or
207             messages missing for the currently used (non-English) language.
208              
209             =item C or C
210              
211             Also log information messages like the UI chosen at startup.
212              
213             =item C
214              
215             Also log debugging messages of various debugging levels, mainly used for
216             development. Note that debugging messages are always English.
217              
218             =back
219              
220             =head4 C
221              
222             configures the handling of output send to STDERR:
223              
224             =over
225              
226             =item C<3>
227              
228             suppress all output to STDERR (usually not a good idea!)
229              
230             =item C<2>
231              
232             catch all error messages and print them when the program exits (or you
233             switch back to C<0>) in order to avoid cluttering the terminal output,
234             e.g. when running under Curses
235              
236             =item C<1>
237              
238             identical to C<2> when using a TUI and identical to C<0> when using a GUI
239              
240             =item C<0>
241              
242             print error messages etc. immediately to STDERR (default)
243              
244             =back
245              
246             Note that configuration C<1> suppresses the standard error output of
247             external programs (e.g. using C or back-ticks) instead of capturing
248             it. Also note that some fatal errors during initialisation are not caught.
249              
250             =head4 C
251              
252             defines a list of UI elements to automatically import as well. It defaults
253             to the string C, but may contain a reference to an array containing the
254             name of specific UI elements like C>, L <
255             Window|UI::Various::Window>, L < Text|UI::Various::Text>, L <
256             Button|UI::Various::Button>, etc. instead. If it is set to the string
257             C, no other UI element package is imported automatically.
258              
259             =cut
260              
261             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
262              
263             sub import($;%)
264             {
265 41     41   16438 my $pkg = shift;
266             # Use fully qualified names until import of core is complete!
267 41 100       205 ref($pkg) and
268             UI::Various::core::fatal('bad_usage_of__1_pkg_is__2',
269             __PACKAGE__, ref($pkg));
270 40 100       160 $pkg eq __PACKAGE__ or
271             UI::Various::core::fatal('bad_usage_of__1_as__2', __PACKAGE__, $pkg);
272 39         148 UI::Various::core->import(@_);
273             }
274              
275             #########################################################################
276              
277             =head2 B - get or set currently used language
278              
279             $language = language();
280             $language = language($new_language);
281              
282             =head3 example:
283              
284             if (language() ne 'en') ...
285              
286             =head3 parameters:
287              
288             $language optional new language to be used
289              
290             =head3 description:
291              
292             This function returns the currently used language. If the optional
293             parameter C<$new_language> is set and a supported language, the language is
294             first changed to that.
295              
296             =cut
297              
298             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
299             sub language(;$)
300             {
301             return UI::Various::core::language(@_);
302             }
303              
304             #########################################################################
305              
306             =head2 B - get or set currently used logging-level
307              
308             $log_level = $logging();
309             logging($new_level);
310              
311             =head3 example:
312              
313             logging('WARN');
314              
315             =head3 parameters:
316              
317             $new_level optional new logging-level to be used
318              
319             =head3 description:
320              
321             This function returns the currently used logging-level. If the optional
322             parameter C<$new_level> is set and a supported keyword (see possible values
323             for the corresponding parameter C of C
324             initialisation of UI::Various package>> above), the logging-level is first
325             changed to that.
326              
327             =cut
328              
329             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
330             sub logging(;$)
331             {
332             return UI::Various::core::logging(@_);
333             }
334              
335             #########################################################################
336              
337             =head2 B - get or set currently used handling of output
338              
339             $output = $stderr();
340             stderr($new_value);
341              
342             =head3 example:
343              
344             stderr(1) if stderr() == 3;
345              
346             =head3 parameters:
347              
348             $new_value optional new output-handling
349              
350             =head3 description:
351              
352             This function returns the currently used variant for the handling of output
353             to STDERR (see possible values for the corresponding parameter of
354             C> above).
355             If the optional parameter C<$new_value> is set and a supported log, the
356             handling is first changed to that.
357              
358             =cut
359              
360             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
361             sub stderr(;$)
362             {
363             return UI::Various::core::stderr(@_);
364             }
365              
366             #########################################################################
367              
368             =head2 B - get currently used UI
369              
370             $interface = $using();
371              
372             =head3 description:
373              
374             This function returns the currently used user interface.
375              
376             =cut
377              
378             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
379             sub using()
380             {
381             return UI::Various::core::using();
382             }
383              
384             1;
385              
386             __END__