package TUI::Dialogs::HistoryWindow;
# ABSTRACT: Window component showing and managing history list items

use 5.010;
use strict;
use warnings;

our $VERSION = '2.000_001';
$VERSION =~ tr/_//d;
our $AUTHORITY = 'cpan:BRICKPOOL';

use Exporter 'import';
our @EXPORT = qw(
  THistoryWindow
  new_THistoryWindow
);

use Carp ();
use TUI::toolkit;
use TUI::toolkit::Types  qw(
  :is
  :types
);

use TUI::Dialogs::Const qw( cpHistoryWindow );
use TUI::Dialogs::HistInit;
use TUI::Dialogs::HistoryViewer;
use TUI::Views::Const qw(
  sbHandleKeyboard
  sbHorizontal
  sbVertical
  wfClose
  wnNoNumber
);
use TUI::Views::Palette;
use TUI::Views::Window;

sub THistoryWindow() { __PACKAGE__ }
sub new_THistoryWindow { __PACKAGE__->from(@_) }

extends ( TWindow, THistInit );

# protected attributes
has viewer => ( is => 'ro' );

sub BUILDARGS {    # \%args (%args)
  state $sig = signature(
    method => 1,
    named  => [
      bounds    => Object,
      historyId => PositiveOrZeroInt,
    ],
    caller_level => +1,
  );
  my ( $class, $args1 ) = $sig->( @_ );
  local $Carp::CarpLevel = $Carp::CarpLevel + 1;
  my $args2 = TWindow->BUILDARGS(
    bounds => $args1->{bounds},
    title  => '',
    number => wnNoNumber,
  );
  my $args3 = THistInit->BUILDARGS(
    cListViewer => $class->can( 'initViewer' )
  );
  return { %$args1, %$args2, %$args3 };
}

sub BUILD {    # void (\%args)
  my ( $self, $args ) = @_;
  assert ( @_ == 2 );
  assert ( is_Object $self );
  assert ( is_HashRef $args );
  $self->{flags} = wfClose;
  if ( $self->{createListViewer} ) {
    $self->{viewer} = $self->createListViewer( $self->getExtent(), $self, 
      $args->{historyId} );
    $self->insert( $self->{viewer} ) if $self->{viewer};
  }
  return;
}

sub from {    # $obj ($bounds, $historyId)
  state $sig = signature(
    method => 1,
    pos    => [Object, PositiveOrZeroInt],
  );
  my ( $class, @args ) = $sig->( @_ );
  return $class->new( bounds => $args[0], historyId => $args[1] );
}

sub getPalette {    # $palette ()
  state $sig = signature(
    method => Object,
    pos    => [],
  );
  my ( $self ) = $sig->( @_ );
  state $palette = TPalette->new(
    data => cpHistoryWindow, 
    size => length( cpHistoryWindow ),
  );
  return $palette->clone();
}

sub getSelection {    # void (\$dest)
  state $sig = signature(
    method => Object,
    pos    => [ScalarRef],
  );
  my ( $self, $dest ) = @_;
  $self->{viewer}->getText( $dest, $self->{viewer}{focused}, 255 );
  return;
}

sub initViewer {    # $listViewer ($r, $win, $historyId)
  state $sig = signature(
    method => 1,
    pos    => [Object, Object, PositiveOrZeroInt],
  );
  my ( $class, $r, $win, $historyId ) = $sig->( @_ );
  $r->grow( -1, -1 );
  return THistoryViewer->new(
    bounds     => $r,
    hScrollBar => $win->standardScrollBar( sbHorizontal | sbHandleKeyboard ),
    vScrollBar => $win->standardScrollBar( sbVertical | sbHandleKeyboard ),
    historyId  => $historyId,
  );
} #/ sub initViewer

1

__END__

=pod

=head1 NAME

TUI::Dialogs::HistoryWindow - window displaying input history entries

=head1 HIERARCHY

  TObject
    TView
      TGroup
        TWindow
          THistoryWindow

=head1 SYNOPSIS

  use TUI::Dialogs;

  my $window = TUI::Dialogs::HistoryWindow->new(
    bounds    => $bounds,
    historyId => 1
  );

=head1 DESCRIPTION

C<THistoryWindow> implements the window used to display the history list managed
by C<THistory>. When the history icon is activated, a history window is created
and populated with a list viewer showing previously entered values.

This class primarily exists to support the internal operation of history lists
and is not commonly instantiated directly by application code. The window owns
a C<THistoryViewer> instance that handles rendering and selection of history
entries.

=head1 ATTRIBUTES

The following attributes are managed internally and exposed as read-only
accessors.

=over

=item viewer

Reference to the history list viewer (I<THistoryViewer>) contained within this
window.

=back

=head1 CONSTRUCTOR

=head2 new

  my $window = THistoryWindow->new(
    bounds    => $bounds,
    historyId => $historyId
  );

Creates a new history window and initializes its internal list viewer.

=over

=item bounds

Bounding rectangle of the history window (I<TRect>).

=item historyId

Numeric identifier selecting which history list is displayed.

=back

=head2 new_THistoryWindow

  my $window = new_THistoryWindow($bounds, $historyId);

Factory-style constructor using positional arguments.

This constructor is equivalent to calling C<new> with named parameters and is
provided for compatibility with traditional Turbo Vision construction patterns.

=head1 METHODS

=head2 getPalette

  my $palette = $window->getPalette();

Returns the color palette used to draw the history window.

=head2 getSelection

  $window->getSelection(\$dest);

Copies the currently selected history entry into C<$dest>.

=head2 initViewer

  my $viewer = $window->initViewer($rect, $window, $historyId);

Creates and initializes the internal history list viewer.

=head1 SEE ALSO

L<TUI::Dialogs::History>,
L<TUI::Dialogs::HistoryViewer>,
L<TUI::Dialogs::InputLine>

=head1 AUTHORS

=over

=item Borland International (original Turbo Vision design)

=item J. Schneider <brickpool@cpan.org> (Perl implementation and maintenance)

=back

=head1 COPYRIGHT AND LICENSE

Copyright (c) 1990-1994, 1997 by Borland International

Copyright (c) 2026 the L</AUTHORS> as listed above.

This software is licensed under the MIT license (see the LICENSE file, which is
part of the distribution). This documentation is provided under the same terms
as the Turbo Vision library itself.

=cut
