NAME¶
Tk::ObjScanner - a GUI to scan any perl data structure or object
SYNOPSIS¶
# regular use
use Tk::ObjScanner;
my $scanner = $mw->ObjScanner( -caller => $object,
-title=>"windows") -> pack ;
my $mw -> ObjScanner
(
-caller => $object,
-title => 'demo setting the scanner options',
-background => 'white',
-selectbackground => 'beige',
-foldImage => $mw->Photo(-file => Tk->findINC('folder.xpm')),
-openImage => $mw->Photo(-file => Tk->findINC('openfolder.xpm')),
-itemImage => $mw->Photo(-file => Tk->findINC('textfile.xpm')),
)
-> pack(-expand => 1, -fill => 'both') ;
# non-intrusive scan style
# user code to produce data
Tk::ObjScanner::scan_object($mydata) ;
# resume user code
DESCRIPTION¶
The scanner provides a GUI to scan the attributes of an object. It can also be
used to scan the elements of a hash or an array.
This widget can be used as a regular widget in a Tk application or can be used
as an autonomous popup widget that will display the content of a data
structure. The latter is like a call to a graphical Data::Dumper. The scanner
can be used in an autonomous way with the "scan_object" function.
The scanner is a composite widget made of a menubar and Tk::HList. This widget
acts as a scanner to the object (or hash ref) passed with the 'caller'
parameter. The scanner will retrieve all keys of the hash/object and insert
them in the HList.
When the user double clicks on a key, the corresponding value will be added in
the HList.
If the value is a multi-line scalar, the scalar will be displayed in a popup
text window. Code ref will be deparsed and shown also in the pop-up window.
Tied scalar, hash or array internal can also be scanned by clicking on the
middle button to open them.
Weak references are recognized (See WeakRef for details)
scan_object( data )¶
This function is not exported and must be called this way:
Tk::ObjScanner::scan_object($data);
This function will load Tk and pop up a scanner widget. When the user destroy
the widget (with "File -" destroy> menu), the user code is
resumed.
Constructor parameters¶
- "caller"
- The ref of the object or hash or array to scan (mandatory). (you can also
use '"-caller"')
- "-title"
- The title of the menu created by the scanner (optional)
- "-background"
- The background color for subwidgets (optional)
- "-selectbackground"
- The select background color for HList (optional)
- "-itemImage"
- The image for a scalar item (optional, default 'file.xbm')
- "-foldImage"
- The image for a composite item (array or hash) when closed (optional,
default 'folder.xbm')
- "-openImage"
- The image for a composite item (array or hash) when open (optional,
default 'openfolder.xbm')
- "-show_menu"
- ObjScanner can feature a menu with 'reload' button, 'show tied info',
'view pseudo-hash' check box. (optional default 0).
- "-destroyable"
- If set, a menu entry will allow the user to destroy the scanner widget.
(optional, default 1) . You may want to set this parameter to 0 if the
destroy can be managed by a higher level object. This parameter is ignored
if show_menu is unset.
- "-view_pseudo"
- If set, will interpret pseudo hashes as hash (default 0). This option is
disabled for Perl 5.09 and later.
- "-show_tied"
- If set, will indicate if a variable is a tied variable. You can see the
internal data of the tied variable by double clicking on the middle
button. (default 1)
updateListBox¶
Update the keys of the listbox. This method may be handy if the scanned object
wants to update the listbox of the scanner when the scanned object gets new
attributes.
CAVEATS¶
The name of the widget is misleading as any data (not only object) may be
scanned. This widget is in fact a DataScanner.
ObjScanner may fail if an object involves a lot of internal perl magic. In this
case, I'd be glad to hear about and I'll try to fix the problem.
ObjScanner does not detect recursive data structures. It will just keep on
displaying the tree until the user gets tired of clicking on the HList items.
There's no sure way to detect if a reference is a pseudo-hash or not. When a
reference is believed to be a pseudo-hash, ObjScanner will display the content
of the reference like a hash. If the reference is should not be displayed like
a pseudo-hash, you can turn off the pseudo-hash view with the check button on
the top right of the widget.
Aynway, pseudo-hashes are deprecated from perl 5.8.0. Hence they are also
deprecated in ObjScanner.
The icon used for tied scalar changes from scalar icon to folder icon when
opening the object hidden behind the tied scalar (using the middle button). I
sure could use a better icon for tied items. (hint hint)
THANKS¶
To Rudi Farkas for all the improvements provided to ObjScanner.
To Slaven Rezic for:
- •
- The propotype code of the pseudo-hash viewer.
- •
- The idea to use B::Deparse to view code ref.
AUTHOR¶
Dominique Dumont, ddumont@cpan.org
Copyright (c) 1997-2004,2007 Dominique Dumont. All rights reserved. This program
is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
SEE ALSO¶
perl, Tk, Tk::HList, B::Deparse