.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tk::ObjScanner 3pm"
.TH Tk::ObjScanner 3pm "2014-07-31" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tk::ObjScanner \- a GUI to scan any perl data structure or object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # regular use
\&  use Tk::ObjScanner;
\&
\&  my $scanner = $mw\->ObjScanner( \-caller => $object, 
\&                                 \-title=>"windows") \-> pack ;
\&
\&  my $mw \-> ObjScanner
\&  (
\&   \-caller          => $object,
\&   \-title           => \*(Aqdemo setting the scanner options\*(Aq,
\&   \-background      => \*(Aqwhite\*(Aq,
\&   \-selectbackground => \*(Aqbeige\*(Aq,
\&   \-foldImage       => $mw\->Photo(\-file => Tk\->findINC(\*(Aqfolder.xpm\*(Aq)),
\&   \-openImage       => $mw\->Photo(\-file => Tk\->findINC(\*(Aqopenfolder.xpm\*(Aq)),
\&   \-itemImage       => $mw\->Photo(\-file => Tk\->findINC(\*(Aqtextfile.xpm\*(Aq)),
\&  )
\&  \-> pack(\-expand => 1, \-fill => \*(Aqboth\*(Aq) ;
\&
\&  # non\-intrusive scan style
\&
\&  # user code to produce data
\&  Tk::ObjScanner::scan_object($mydata) ;
\&  # resume user code
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The scanner provides a \s-1GUI\s0 to scan the attributes of an object. It can
also be used to scan the elements of a hash or an array.
.PP
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
\&\f(CW\*(C`scan_object\*(C'\fR function.
.PP
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.
.PP
When the user double clicks on a key, the corresponding value will be added
in the HList.
.PP
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.
.PP
Tied scalar, hash or array internal can also be scanned by clicking on
the \fImiddle\fR button to open them.
.PP
Weak references are recognized (See WeakRef for details)
.SH "Autonomous widget"
.IX Header "Autonomous widget"
.SS "scan_object( data )"
.IX Subsection "scan_object( data )"
This function is not exported and must be called this way:
.PP
.Vb 1
\&  Tk::ObjScanner::scan_object($data);
.Ve
.PP
This function will load Tk and pop up a scanner widget. When the user
destroy the widget (with \f(CW\*(C`File \-\*(C'\fR destroy> menu), the user code is
resumed.
.SH "Constructor parameters"
.IX Header "Constructor parameters"
.ie n .IP """caller""" 4
.el .IP "\f(CWcaller\fR" 4
.IX Item "caller"
The ref of the object or hash or array to scan (mandatory). (you can
also use '\f(CW\*(C`\-caller\*(C'\fR')
.ie n .IP """\-title""" 4
.el .IP "\f(CW\-title\fR" 4
.IX Item "-title"
The title of the menu created by the scanner (optional)
.ie n .IP """\-background""" 4
.el .IP "\f(CW\-background\fR" 4
.IX Item "-background"
The background color for subwidgets (optional)
.ie n .IP """\-selectbackground""" 4
.el .IP "\f(CW\-selectbackground\fR" 4
.IX Item "-selectbackground"
The select background color for HList (optional)
.ie n .IP """\-itemImage""" 4
.el .IP "\f(CW\-itemImage\fR" 4
.IX Item "-itemImage"
The image for a scalar item (optional, default 'file.xbm')
.ie n .IP """\-foldImage""" 4
.el .IP "\f(CW\-foldImage\fR" 4
.IX Item "-foldImage"
The image for a composite item (array or hash) when closed
(optional, default 'folder.xbm')
.ie n .IP """\-openImage""" 4
.el .IP "\f(CW\-openImage\fR" 4
.IX Item "-openImage"
The image for a composite item (array or hash) when open
(optional, default 'openfolder.xbm')
.ie n .IP """\-show_menu""" 4
.el .IP "\f(CW\-show_menu\fR" 4
.IX Item "-show_menu"
ObjScanner can feature a menu with 'reload' button, 'show tied info',
\&'view pseudo\-hash' check box. (optional default 0).
.ie n .IP """\-destroyable""" 4
.el .IP "\f(CW\-destroyable\fR" 4
.IX Item "-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.
.ie n .IP """\-view_pseudo""" 4
.el .IP "\f(CW\-view_pseudo\fR" 4
.IX Item "-view_pseudo"
If set, will interpret pseudo hashes as hash (default 0). This option
is disabled for Perl 5.09 and later.
.ie n .IP """\-show_tied""" 4
.el .IP "\f(CW\-show_tied\fR" 4
.IX Item "-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)
.SH "WIDGET-SPECIFIC METHODS"
.IX Header "WIDGET-SPECIFIC METHODS"
.SS "updateListBox"
.IX Subsection "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.
.SH "CAVEATS"
.IX Header "CAVEATS"
The name of the widget is misleading as any data (not only object) may
be scanned. This widget is in fact a DataScanner.
.PP
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.
.PP
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.
.PP
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.
.PP
Aynway, pseudo-hashes are deprecated from perl 5.8.0. Hence they are
also deprecated in ObjScanner.
.PP
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)
.SH "THANKS"
.IX Header "THANKS"
To Rudi Farkas for all the improvements provided to ObjScanner.
.PP
To Slaven Rezic for:
.IP "\(bu" 4
The propotype code of the pseudo-hash viewer.
.IP "\(bu" 4
The idea to use B::Deparse to view code ref.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont, ddumont@cpan.org
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl, Tk, Tk::HList, B::Deparse