dtRdr::HTMLWidget - Generic HTML widget interface

  use dtRdr::HTMLWidget;

  my @wx_args = (
    # from http://www.wxwindows.org/manuals/2.6.3/wx_wxhtmlwindow.html
    $parent, # wxWindow *parent,
    $id,     # wxWindowID id = -1,
    $pos,    # const wxPoint& pos = wxDefaultPosition,
    $size,   # const wxSize& size = wxDefaultSize,
    $style,  # long style = wxHW_DEFAULT_STYLE,
    $name,   # const wxString& name = "htmlWindow"
    );
  $widget = dtRdr::HTMLWidget->new(\@wx_args, \%opts);

  $widget = dtRdr::HTMLWidget->new($parent, $id, $position, $size, $style)

  $widget->base;

  $widget->init($parent, url_handler => $handler);

  $bool = $widget->render_HTML($html, $data_handle);

  $data_handle->get_member_string($relative_uri)

  $hw->reset_wrap($subref);

  $html = $hw->filter_HTML($html, $datahandle);

  $widget->allow_copy($bool)

  $old_callback = $widget->register_get_file(&callback)

  This is the function called when the widget needs to fetch a file
  that's embedded within a webpage. (This is for E<lt>imgE<gt> tag
  fetches and suchlike things)

  $bool = $widget->load_in_progress;

  callback implement in html shim
  $position = $widget->get_cursor_pos();
  Returns the current vertical scroll bar position for the HTML widget

  callback implement in html shim
  $widget->set_scroll_pos(200);

  Sets the current vertical scroll bar position for the HTML widget

  callback implement in html shim
  scroll_page_down();
  scrolls the browser widget down 1 page.
  equivilent to [Page Down]
  Returns 1 if successfull or 0 if it can't scroll

  callback implement in html shim
  scroll_page_up();
  scrolls the browser widget down 1 page.
  equivilent to [Page Up]
  Returns 1 if successfull or 0 if it can't scroll

  callback implement in html shim
  scroll_page_bottom
  scrolls the browser to the bottom of the page

  $old_callback = $widget->register_url_changed(&callback)

  This is the callback that's called when the browser pane is about to
  change to a new page because someone clicked on a link.

  $old_callback = $widget->register_form_post(&callback)

  This is the callback that's called when the browser pane does a form
  POST request.

  $old_callback = $widget->register_form_get(&callback)

  This is the callback that's called when the browser pane does a form
  GET request.

  Navigates to the next state in history

  Navigates to the previous state in history

  Print the current page

  Returns selected text

  my $string = $hw->get_selection;

  my $html = $hw->get_selection_as_html;

  Returns ($pre, $str, $post)
  where pre and post text are $context_length or less if the selected
  text is near the begining or end of the document

  my ($pre, $str, $post) = $hw->get_selection_context($context_length);

package dtRdr::HTMLWidget;
$VERSION = eval{require version}?version::qv($_):$_ for(0.10.1);

use warnings;
use strict;

use Carp;


use dtRdr::Traits::Class qw(
  NOT_IMPLEMENTED
  WARN_NOT_IMPLEMENTED
  );

my $delegate_class;

use Wx qw(
  wxHW_NO_SELECTION
  );

use dtRdr::Logger;

use Class::Accessor::Classy;
rw qw(
  load_in_progress
  zoom
);
ro qw(
  parent
  url_handler
);
rs html_source => \ (my $set_html_source);
no  Class::Accessor::Classy;

our @ISA;
BEGIN {
  $delegate_class = 0;
  my %dispatch = (
    darwin   => 'dtRdr::HTMLShim::WebKit',
    MSWin32  => 'dtRdr::HTMLShim::ActiveXIE',
    linux    => 'dtRdr::HTMLShim::WxMozilla',
    # linux    => 'dtRdr::HTMLShim::WxHTML',
    fallback => 'dtRdr::HTMLShim::WxHTML',
    );

  # override
  my $force = $ENV{THOUT_WIDGET} ?
    'dtRdr::HTMLShim::' . $ENV{THOUT_WIDGET} :
    undef;
  # pick one
  if(my $backend = $force || $dispatch{$^O}) {
    eval "use $backend";
    if($@) {
      die "$force not working ($@)" if($force);
      warn "could not use $backend -- try fallback ($@)";
    }
    else {
      $delegate_class = $backend;
    }
  }
  else {
    warn "'$^O' backend not specified";
  }

  # If something went wrong, go to the fallback
  unless($delegate_class) {
    eval "use $dispatch{fallback}";
    $@ and die "even the fallback failed! $@";
    $delegate_class = $dispatch{fallback};
  }

  # If we can't use the fallback, then punt
  our @ISA;
  # we're basically inserting ourselves between the platform-specific
  # widget and the class that it wants to inherit from
  # e.g. we inherit from the widget's chosen base class on its behalf
  push(@ISA, $delegate_class->base);
} # end BEGIN

sub new {
  my $package = shift;
  my $caller = caller;
  my ($b_args, $w_args) = @_;
  # allow duality of API
  if((ref($b_args) || '') ne 'ARRAY') {
    eval {$b_args->isa('Wx::Window')} or croak("bad arguments @_");
    $b_args = [@_];
  }
  $w_args ||= {};

  if(defined($caller) and $caller->isa(__PACKAGE__)) {
    # being inherited => be a base class
    0 and warn "base class for $caller";
    my $class = ref($package) || $package;
    0 and warn "b_args: ", join("|", @$b_args);
    my $self = $class->base->new(@$b_args);
    bless($self, $class);
    return($self);
  }
  else {
    # being called => be a factory
    0 and warn "factory" . ($caller ? " (for $caller)" : '');
    return($delegate_class->new($b_args, $w_args));
  }
} # end subroutine new definition
########################################################################

sub base { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub init {
  my $self = shift;
  my $parent = shift;
  (@_ % 2) and croak('odd number of elements in argument list');
  my %args = @_;
  $self->{parent} = $parent;
  my @attribs = qw(
    url_handler
  );
  foreach my $arg (@attribs) {
    $self->{$arg} = $args{$arg} if(exists($args{$arg}));
  }
} # end subroutine init definition
########################################################################

sub render_HTML {
  my $self = shift;
  my ($html, $dh) = @_;

  $self->{load_in_progress} = 1;
  # XXX shouldn't need this filtering anymore
  # $html = $self->filter_HTML($html, $dh);
  DBG_DUMP('FILTERED', 'filtered.html', sub {$html});
  my $status = $self->SetPage($html);
  $self->$set_html_source($html);
  $self->{load_in_progress} = 0;
  return $status;
} # end subroutine render_HTML definition
########################################################################

sub reset_wrap {
  my $self = shift;
  my ($subref) = @_;
  my $yscroll = $self->get_scroll_pos();
  #L->debug("scroll pos $yscroll");
  my $zoom = $self->get_zoom;
  #L->debug("zoom $zoom");
  $subref->();
  my $new_pos = $self->set_scroll_pos($yscroll);
  #L->debug("set scroll pos to $new_pos");
  $self->set_zoom($zoom);
} # end subroutine reset_wrap definition
########################################################################

sub filter_HTML {
  my $self = shift;
  my ($html, $dh) = @_;
  return($html);
} # end subroutine filter_HTML definition
########################################################################

sub allow_copy {
  my ($self, $allow) = @_;
  my $style = $self->GetWindowStyleFlag();
  if (!$allow) {
    $style = $style | wxHW_NO_SELECTION;
    $self->SetWindowStyleFlag($style);
  } else {
    $style = $style & (~wxHW_NO_SELECTION);
    $self->SetWindowStyleFlag($style);
  }
} # end subroutine allow_copy definition
########################################################################

sub register_get_file { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

# accessor
########################################################################

sub get_scroll_pos { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub set_scroll_pos { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub scroll_page_down { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub scroll_page_up { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub scroll_page_bottom { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub increase_font {  my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub decrease_font {  my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub register_url_changed { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub register_form_post { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub register_form_get { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub history_next { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub history_back { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub print_page { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub get_selection { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub get_selection_as_html { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

sub get_selection_context { my $self = shift; $self->NOT_IMPLEMENTED; }
########################################################################

1;
# vim:ts=2:sw=2:et:sta