Tk::ObjScanner(3pm)

Tk::ObjScanner 💅✨

okay bestie, gather round, because this is the Tk::ObjScanner page from the User Contributed Perl Documentation and it is genuinely one of the most useful little gremlins in the Tk toolbox 🫶

---

✨ NAME ✨

Tk::ObjScanner — a GUI to scan any perl data structure or object. like, any. it's giving "graphical Data::Dumper" and we are obsessed 💖

---

🌸 SYNOPSIS 🌸

    # regular use
    use Tk::ObjScanner;

    my $mw  = MainWindow->new;

    my $scanner1 = $mw->ObjScanner(
        -caller => $object,
        -title=>"windows"
    )->pack;

    my $scanner2 = $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 hands you a whole GUI to poke at the attributes of an object 🔍. It can also scan the elements of a hash or an array, so it's not just an object girlie — it does it all.

This widget can be dropped into a Tk application like any regular widget, or it can be an autonomous popup widget that just shows you the content of a data structure. That second vibe is basically a call to a graphical Data::Dumper. And if you want it fully autonomous, there's the scan_object function for that 👑

The scanner is a composite widget — a menubar plus Tk::HList — and it acts as a scanner pointed at the object (or hash ref) you hand over in the 'caller' parameter. It goes and grabs all the keys of that hash/object and inserts them into the HList. periodt.

When you double click on a key, the matching value gets added into the HList ✨

If that value is a multi-line scalar, it'll pop up in a text window. Code refs get deparsed and shown in that pop-up window too. fancy.

Tied scalars, hashes or arrays — their internals can also be scanned: just click the middle button to open them up 🎀

Weak references are recognized too (go read WeakRef for the details, iykyk).

---

🧚 Autonomous widget 🧚

scan_object( data )

This function is not exported, so you have to call it the long way, like this:

  Tk::ObjScanner::scan_object($data);

Calling it loads Tk and pops up a scanner widget for you 💫. When the user destroys that widget (via the "File -" destroy> menu), your user code just... resumes. no cap. 🫶

---

👑 Constructor parameters 👑

• "caller" — the ref of the object or hash or array you want to scan (mandatory). and yes, you can also use "-caller".
• -title — the title of the menu that the scanner creates (optional).
• -background — the background color for the subwidgets (optional).
• -selectbackground — the select background color for the HList (optional).
• -itemImage — the image used for a scalar item (optional, default 'file.xbm').
• -foldImage — the image for a composite item (array or hash) while it's closed (optional, default 'folder.xbm').
• -openImage — the image for a composite item (array or hash) while it's open (optional, default 'openfolder.xbm').
• -show_menu — ObjScanner can show a menu with a 'reload' button and 'show tied info' (optional, default 0).
• -destroyable — if you set this, a menu entry lets the user destroy the scanner widget (optional, default 1). you might wanna set it to 0 if the destroy is handled by some higher-level object instead. heads up: this parameter is ignored if show_menu is unset ⚠️
• -destroy_label — the label used for the "destroy" menu entry.
• -show_tied — if set, it'll tell you whether a variable is a tied variable. and you can see the internal data of that tied variable by double clicking the middle button (default 1).

---

💜 WIDGET-SPECIFIC METHODS 💜

updateListBox

Updates the keys of the listbox 🔄. This method is handy when the scanned object wants to refresh the scanner's listbox after the scanned object picks up new attributes. like a lil glow-up for your list, love that for it.

---

💀 CAVEATS 💀

The name of this widget is misleading — any data can be scanned, not just objects. This thing is, in fact, a DataScanner. the audacity of the naming fr fr 😭

ObjScanner may fail if an object involves a lot of internal perl magic. if that happens, the author would be glad to hear about it and will 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 HList items 💀 (which, honestly, is a whole mood)

The icon used for a tied scalar changes from the scalar icon to a folder icon when you open the object hiding behind the tied scalar (that's the middle button, remember). and yes, a better icon for tied items would be lovely. (hint hint) 🙈

---

🎀 THANKS 🎀

To Rudi Farkas for all the improvements provided to ObjScanner.

To Slaven Rezic for:

• The idea to use B::Deparse to view code ref.

---

🌈 CONTRIBUTORS 🌈

Many thanks to Achim Bohnet for all the tests, patches (and reports) he made. Many improvements were made thanks to his efforts 🫶

Thanks to Rudi Farkas for the 'watch' patch.

Thanks to heytitle for the documentation fixes.

---

⭐ AUTHOR ⭐

Dominique Dumont, ddumont@cpan.org

---

🍓 SEE ALSO 🍓

perl, Tk, Tk::HList, B::Deparse, data_viewer

---

and that's the whole page bestie — brought to you by perl v5.36.0, dated 2023-10-27, and it's a Tk::ObjScanner(3pm) situation 💖 now go scan something slay ✨