=head1 NAME

C<Devel::MAT::UI> - extend the user interface of a C<Devel::MAT> explorer

=head1 DESCRIPTION

This virtual package provides methods that L<Devel::MAT::Tool> classes can use
to extend the user interface provided by a L<Devel::MAT> explorer program.
This package does not exist in a real F<.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
C<use Devel::MAT::UI>.

=head1 METHODS

=head2 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
C<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 C<type> is
C<icon>. The value set gives the name the icon was registered with.

=over 4

=item svg => PATH (GTK)

Gives a path name to an F<SVG> file containing image data. This path is
relative to the share directory of the package, managed by L<File::ShareDir>.

=back

=head2 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 C<@buttons> list
containing the following keys:

=over 4

=item text => STRING

The text to display on the button

=item icon => STRING

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

=item tooltip => STRING

Descriptive text to associate with the button to further explain it

=item code => CODE

A code reference to invoke when the button is activated.

=back

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

=head2 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 C<set_svlist_column_values> to provide data for
the column.

=over 4

=item type => STRING

The type of the column. This may be C<int>, C<text> or C<icon>.

=item title => STRING

The title to display in the column header.

=back

=head2 COLUMN_TYPE

=head2 COLUMN_ADDR

=head2 COLUMN_DESC

=head2 COLUMN_SIZE

=head2 COLUMN_BLESSED

=head2 COLUMN_OUTREFS

=head2 COLUMN_INREFS

Opaque column values to represent the predefined SV list columns.

=head2 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 C<provides_svlist_column>, or to replace the values
in any of the predefined columns.

=over 4

=item column => SCALAR

The value returned from C<provides_svlist_column>.

=item 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 )

=back

=head2 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.

=over 4

=item type => STRING

The type of the column. This may be C<widget>, C<text> or C<icon>.

=item title => STRING

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

=item 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 )

=back

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

=cut

=head2 make_widget_text

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

Constructs a widget displaying a fixed text string.

=head2 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.

=head2 make_table

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

Constructs a widget displaying a labeled table of other widgets.

=head2 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.

=head1 AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

=cut