1Tk::ObjScanner(3)     User Contributed Perl Documentation    Tk::ObjScanner(3)
2
3
4

NAME

6       Tk::ObjScanner - a GUI to scan any perl data structure or object
7

SYNOPSIS

9           # regular use
10           use Tk::ObjScanner;
11
12           my $mw  = MainWindow->new;
13
14           my $scanner1 = $mw->ObjScanner(
15               -caller => $object,
16               -title=>"windows"
17           )->pack;
18
19           my $scanner2 = $mw->ObjScanner(
20               -caller             => $object,
21               -title              => 'demo setting the scanner options',
22               -background         => 'white',
23               -selectbackground   => 'beige',
24               -foldImage          => $mw->Photo(-file => Tk->findINC('folder.xpm')),
25               -openImage          => $mw->Photo(-file => Tk->findINC('openfolder.xpm')),
26               -itemImage          => $mw->Photo(-file => Tk->findINC('textfile.xpm')),
27           )->pack( -expand => 1, -fill => 'both' ) ;
28
29           # non-intrusive scan style
30
31           # user code to produce data
32           Tk::ObjScanner::scan_object($mydata) ;
33           # resume user code
34

DESCRIPTION

36       The scanner provides a GUI to scan the attributes of an object. It can
37       also be used to scan the elements of a hash or an array.
38
39       This widget can be used as a regular widget in a Tk application or can
40       be used as an autonomous popup widget that will display the content of
41       a data structure. The latter is like a call to a graphical
42       Data::Dumper. The scanner can be used in an autonomous way with the
43       "scan_object" function.
44
45       The scanner is a composite widget made of a menubar and Tk::HList.
46       This widget acts as a scanner to the object (or hash ref) passed with
47       the 'caller' parameter. The scanner will retrieve all keys of the
48       hash/object and insert them in the HList.
49
50       When the user double clicks on a key, the corresponding value will be
51       added in the HList.
52
53       If the value is a multi-line scalar, the scalar will be displayed in a
54       popup text window. Code ref will be deparsed and shown also in the pop-
55       up window.
56
57       Tied scalar, hash or array internal can also be scanned by clicking on
58       the middle button to open them.
59
60       Weak references are recognized (See WeakRef for details)
61

Autonomous widget

63   scan_object( data )
64       This function is not exported and must be called this way:
65
66         Tk::ObjScanner::scan_object($data);
67
68       This function will load Tk and pop up a scanner widget. When the user
69       destroy the widget (with "File -" destroy> menu), the user code is
70       resumed.
71

Constructor parameters

73       "caller"
74           The ref of the object or hash or array to scan (mandatory). (you
75           can also use '"-caller"')
76
77       "-title"
78           The title of the menu created by the scanner (optional)
79
80       "-background"
81           The background color for subwidgets (optional)
82
83       "-selectbackground"
84           The select background color for HList (optional)
85
86       "-itemImage"
87           The image for a scalar item (optional, default 'file.xbm')
88
89       "-foldImage"
90           The image for a composite item (array or hash) when closed
91           (optional, default 'folder.xbm')
92
93       "-openImage"
94           The image for a composite item (array or hash) when open (optional,
95           default 'openfolder.xbm')
96
97       "-show_menu"
98           ObjScanner can feature a menu with 'reload' button, 'show tied
99           info', 'view pseudo-hash' check box. (optional default 0).
100
101       "-destroyable"
102           If set, a menu entry will allow the user to destroy the scanner
103           widget. (optional, default 1) . You may want to set this parameter
104           to 0 if the destroy can be managed by a higher level object. This
105           parameter is ignored if show_menu is unset.
106
107       "-view_pseudo"
108           If set, will interpret pseudo hashes as hash (default 0). This
109           option is disabled for Perl 5.09 and later.
110
111       "-show_tied"
112           If set, will indicate if a variable is a tied variable. You can see
113           the internal data of the tied variable by double clicking on the
114           middle button. (default 1)
115

WIDGET-SPECIFIC METHODS

117   updateListBox
118       Update the keys of the listbox. This method may be handy if the scanned
119       object wants to update the listbox of the scanner when the scanned
120       object gets new attributes.
121

CAVEATS

123       The name of the widget is misleading as any data (not only object) may
124       be scanned. This widget is in fact a DataScanner.
125
126       ObjScanner may fail if an object involves a lot of internal perl magic.
127       In this case, I'd be glad to hear about and I'll try to fix the
128       problem.
129
130       ObjScanner does not detect recursive data structures. It will just keep
131       on displaying the tree until the user gets tired of clicking on the
132       HList items.
133
134       There's no sure way to detect if a reference is a pseudo-hash or not.
135       When a reference is believed to be a pseudo-hash, ObjScanner will
136       display the content of the reference like a hash. If the reference is
137       should not be displayed like a pseudo-hash, you can turn off the
138       pseudo-hash view with the check button on the top right of the widget.
139
140       Aynway, pseudo-hashes are deprecated from perl 5.8.0. Hence they are
141       also deprecated in ObjScanner.
142
143       The icon used for tied scalar changes from scalar icon to folder icon
144       when opening the object hidden behind the tied scalar (using the middle
145       button). I sure could use a better icon for tied items. (hint hint)
146

THANKS

148       To Rudi Farkas for all the improvements provided to ObjScanner.
149
150       To Slaven Rezic for:
151
152       •   The propotype code of the pseudo-hash viewer.
153
154       •   The idea to use B::Deparse to view code ref.
155

CONTRIBUTORS

157       Many thanks to Achim Bohnet for all the tests, patches (and reports) he
158       made. Many improvements were made thanks to his efforts.
159
160       Thanks to Rudi Farkas for the 'watch' patch.
161
162       Thanks to Slavec Rezic for the pseudo-hash prototype.
163
164       Thanks to heytitle for the documentation fixes
165

AUTHOR

167       Dominique Dumont, ddumont@cpan.org
168
169       Copyright (c) 1997-2004,2007,2014,2017 Dominique Dumont. All rights
170       reserved.  This program is free software; you can redistribute it
171       and/or modify it under the same terms as Perl itself.
172

SEE ALSO

174       perl, Tk, Tk::HList, B::Deparse
175
176
177
178perl v5.32.1                      2021-01-27                 Tk::ObjScanner(3)
Impressum