File Coverage

blib/lib/UI/Various/Dialog.pm
Criterion Covered Total %
statement 34 34 100.0
branch n/a
condition n/a
subroutine 13 13 100.0
pod 3 3 100.0
total 50 50 100.0


line stmt bran cond sub pod time code
1             package UI::Various::Dialog;
2              
3             # Author, Copyright and License: see end of file
4              
5             =head1 NAME
6              
7             UI::Various::Dialog - general top-level dialogue widget of L
8              
9             =head1 SYNOPSIS
10              
11             use UI::Various;
12             my $main = UI::Various::main();
13             my $dialog = $main->dialog();
14             $dialog->add(UI::Various::Text->new(text => 'Hello World!'));
15             ...
16             $main->mainloop();
17              
18             =head1 ABSTRACT
19              
20             This module defines the general (main) dialogue object of an application
21             using L. Apart from being modal a dialogue is very similar to
22             a C.
23              
24             =head1 DESCRIPTION
25              
26             Besides the common attributes inherited from C and
27             C the C widget knows the following
28             additional attributes:
29              
30             =head2 Attributes
31              
32             =over
33              
34             =cut
35              
36             #########################################################################
37              
38 8     8   92 use v5.14;
  8         25  
39 8     8   43 use strictures;
  8         13  
  8         42  
40 8     8   1311 no indirect 'fatal';
  8         16  
  8         42  
41 8     8   406 no multidimensional;
  8         22  
  8         61  
42 8     8   291 use warnings 'once';
  8         15  
  8         442  
43              
44             our $VERSION = '0.22';
45              
46 8     8   47 use UI::Various::core;
  8         14  
  8         43  
47 8     8   380 use UI::Various::toplevel;
  8         15  
  8         462  
48 8     8   40 BEGIN { require 'UI/Various/' . UI::Various::core::using() . '/Dialog.pm'; }
49              
50             require Exporter;
51             our @ISA = qw(UI::Various::toplevel);
52             our @EXPORT_OK = qw();
53              
54             #########################################################################
55              
56             =item title [rw, optional]
57              
58             an optional title string for the dialogue as string or variable reference
59              
60             =cut
61              
62             sub title($;$)
63             {
64 25     25 1 68 return access('title', undef, @_);
65             }
66              
67             #########################################################################
68             #
69             # internal constants and data:
70              
71 8         591 use constant ALLOWED_PARAMETERS =>
72 8     8   53 (UI::Various::widget::COMMON_PARAMETERS, qw(title));
  8         14  
73 8     8   65 use constant DEFAULT_ATTRIBUTES => (title => '');
  8         15  
  8         1616  
74              
75             #########################################################################
76             #########################################################################
77              
78             =back
79              
80             =head1 METHODS
81              
82             Besides the accessors (attributes) described above and the attributes and
83             methods of L, L and
84             L, the following additional methods are provided by
85             the C class itself:
86              
87             =cut
88              
89             #########################################################################
90              
91             =head2 B - constructor
92              
93             see L
94             constructor for UI elements>
95              
96             =cut
97              
98             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
99              
100             sub new($;\[@$])
101             {
102 9     9 1 2026 debug(2, __PACKAGE__, '::new');
103 9         61 my $self = construct({ DEFAULT_ATTRIBUTES },
104             '^(?:' . join('|', ALLOWED_PARAMETERS) . ')$',
105             @_);
106             # Get "Window Manager" singleton even if it is not yet existing:
107 9         44 local $_ = UI::Various::Main->new();
108 9         55 $_->add($self);
109 9         22 return $self;
110             }
111              
112             #########################################################################
113              
114             =head2 B - remove dialogue from application
115              
116             $dialog->destroy();
117              
118             =head3 description:
119              
120             C removes the dialogue and all its UI elements from the application
121             (and its L
), hopefully
122             freeing all memory used by the UI. (This may vary depending on the
123             underlying UI package used.) If the dialogue was a stand-alone one, this
124             also causes the C
125             of an application>> to be finished.
126              
127             Note that a dialogue can not be reused again after destruction as it's
128             broken down into its components to get rid of circular dependencies that may
129             block clean-up of memory. If you want to open the same dialogue again, you
130             have to recreate it.
131              
132             =cut
133              
134             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
135              
136             sub destroy($)
137 1     1 1 4 { fatal('specified_implementation_missing'); }
138              
139             1;
140              
141             #########################################################################
142             #########################################################################
143              
144             =head1 SEE ALSO
145              
146             L
147              
148             =head1 LICENSE
149              
150             Copyright (C) Thomas Dorner.
151              
152             This library is free software; you can redistribute it and/or modify it
153             under the same terms as Perl itself. See LICENSE file for more details.
154              
155             =head1 AUTHOR
156              
157             Thomas Dorner Edorner (at) cpan (dot) orgE
158              
159             =cut