NAME

       "Devel::MAT::UI" - extend the user interface of a "Devel::MAT" explorer

DESCRIPTION

       This virtual package provides methods that Devel::MAT::Tool classes can use to extend the
       user interface provided by a Devel::MAT explorer program.  This package does not exist in
       a real .pm file; instead, the methods should be provided directly by the explorer program.
       A tool class can rely on being able to call them without doing anything special - do not
       attempt to "use Devel::MAT::UI".

METHODS

   register_icon
         Devel::MAT::UI->register_icon( name => $name, ... )

       A tool may call this to register a named icon image with the UI, for later use in an SV
       list column or SV detail. The name of the icon is taken from the "name" key, and the
       specific UI implementation will use one of the other keys to provide the value for its
       type.

       This icon is used by SV list columns or SV details where the "type" is "icon". The value
       set gives the name the icon was registered with.

       svg => PATH (GTK)
           Gives a path name to an SVG file containing image data. This path is relative to the
           share directory of the package, managed by File::ShareDir.

   provides_radiobutton_set
         Devel::MAT::UI->provides_radiobutton_set( @buttons )

       A tool may call this to declare that it wishes to have a set of radiobuttons as a choice
       of options to be displayed in the toolbar of the user interface.  Each button is specified
       in a HASH reference in the @buttons list containing the following keys:

       text => STRING
           The text to display on the button

       icon => STRING
           The name of the previously-registered icon to display with the button

       tooltip => STRING
           Descriptive text to associate with the button to further explain it

       code => CODE
           A code reference to invoke when the button is activated.

       The buttons will be displayed in a group of their own, such that selecting one will
       deactivate all the others in the same set.

   provides_svlist_column
         $column = Devel::MAT::UI->provides_svlist_column( type => ..., title => ... )

       A tool may call this to declare that it wishes to provide a new column to display in the
       main SV list on the user interface. It returns an opaque column value that should be
       passed to "set_svlist_column_values" to provide data for the column.

       type => STRING
           The type of the column. This may be "int", "text" or "icon".

       title => STRING
           The title to display in the column header.

   COLUMN_TYPE
   COLUMN_ADDR
   COLUMN_DESC
   COLUMN_SIZE
   COLUMN_BLESSED
   COLUMN_OUTREFS
   COLUMN_INREFS
       Opaque column values to represent the predefined SV list columns.

   set_svlist_column_values
         Devel::MAT::UI->set_svlist_column_values( column => $column, from => $from )

       A tool may call this to provide the values to display in the SV list column it earlier
       created by calling "provides_svlist_column", or to replace the values in any of the
       predefined columns.

       column => SCALAR
           The value returned from "provides_svlist_column".

       from => CODE
           A function to generate the value to store for each SV. Is invoked with each SV in the
           SV list, and should return the value to set in the column.

              $value = $from->( $sv )

   provides_sv_detail
         Devel::MAT::UI->provides_sv_detail( type => $type, title => $title, render => $render )

       A tool may call this to declare that it provides a section of detail about an SV.

       type => STRING
           The type of the column. This may be "widget", "text" or "icon".

       title => STRING
           The title to display alongside the detail cell on the main SV display pane.

       render => CODE
           A function to generate the display for a given SV address. It is invoked with an SV to
           display, and should a value whose meaning depends on the type. If it returns undef
           then the row is not displayed for this SV.

            $value = $render->( $sv )

       If the type is "widget", any of the following "make_*" methods can be used by the render
       function to generate a widget to display.

   make_widget_text
         $widget = Devel::MAT::UI->make_widget_text( $text )

       Constructs a widget displaying a fixed text string.

   make_widget_text_icon
         $widget = Devel::MAT::UI->make_widget_text_icon( $text, $icon )

       Constructs a widget displaying a fixed text string next to an icon.

   make_table
         $widget = Devel::MAT::UI->make_table( $label => $widget, $label => $widget, ... )

       Constructs a widget displaying a labeled table of other widgets.

   current_sv
         $sv = Devel::MAT::UI->current_sv

       If the UI has a concept of the "current" SV that the user is viewing, this method returns
       it. This may be used by tools to pick a default SV on which to operate, in case one was
       not supplied on the commandline.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>