.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Wx::Loader 3pm"
.TH Wx::Loader 3pm "2014-03-08" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Wx::Loader \- using custom dll loaders with Wx
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  # For Packagers
\&  #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  
\&  # the order of these use()s is important
\&  use MyCustomWxLoader;
\&  use Wx;
\&  
\&  or .....
\&  
\&  use threads;
\&  use threads::shared;
\&  use MyCustomLoader;
\&  use Wx;
\&  
\&  or \- Wx::Perl::Splashfast special case
\&    
\&  use MyCustomWxLoader;
\&  use Wx::Perl::SplashFast ("./logo.jpg",5000);
\&  use Wx;
\&  
\&  ............. meanwhile in MyCustomWxLoader.pm
\&  
\&  package MyCustomWxLoader;
\&  require Wx::Mini;
\&  our @ISA = qw( Wx::Loader::Standard );
\&    
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_;
\&  ...... or
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_\->new;
\&  
\&  #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  # For binary distributions
\&  #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  
\&  # Provide a custom Wx::Loader::Custom
\&  # to be loaded by Wx::Mini
\&  
\&  package Wx::Loader::Custom
\&  our @ISA = qw( Wx::Loader::Standard );
\&  
\&  # be polite if another loader is already in place
\&  
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_ if !$Wx::wx_binary_loader;
\&  ...... or
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_\->new() if !$Wx::wx_binary_loader;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If you are providing binary distributions of Wx or packaging Wx
applications to run on machines without Perl (\s-1PAR,\s0 PerlApp),you
may need to override dll loading methods. Providing a custom
wx_binary_loader package allows you to do this.
.SH "Binary Distributions"
.IX Header "Binary Distributions"
A binary distribution my provide alternative sources and loading
methods for the wxWidgets dlls. It achieves this by providing a
Wx::Loader::Custom module in the distribution
.PP
.Vb 2
\&  package Wx::Loader::Custom
\&  our @ISA = qw( Wx::Loader::Standard );
\&  
\&  # be polite if another loader is already in place
\&  
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_ if !$Wx::wx_binary_loader;
\&  ...... or
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_\->new() if !$Wx::wx_binary_loader;
\&  
\&  # remember that Wx.pm has not necessarily been loaded so only
\&  # Wx::Mini is available
.Ve
.SH "Perl Application Packagers"
.IX Header "Perl Application Packagers"
.Vb 3
\&  Applications that package perl scripts to run on machines without
\&  Perl (PAR, PerlApp etc) can override dll loading methods if necessary
\&  by loading a custom package before wx
\&  
\&  package MyCustomWxLoader;
\&  require Wx::Mini;
\&  our @ISA = qw( Wx::Loader::Standard );
\&    
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_;
\&  ...... or
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_\->new;
\&  
\&  # remember that Wx.pm has not necessarily been loaded so only
\&  # Wx::Mini is available
.Ve
.SH "METHODS"
.IX Header "METHODS"
.Vb 2
\&  The following methods may be provided by custom loaders to override the
\&  default behaviour
.Ve
.SS "loader_info"
.IX Subsection "loader_info"
.Vb 2
\&  should return an information string about the loader and MUST be provided.
\&  The default loader has
\&  
\&  sub loader_info { \*(AqStandard Distribution\*(Aq; }
\&  
\&  so any custom loader should return something different
\&  
\&  e.g.
\&  
\&  sub loader_info { "Mark\*(Aqs Broken Distribution \- it\*(Aqs all my fault"; }
.Ve
.SS "set_binary_path"
.IX Subsection "set_binary_path"
.Vb 1
\&  allows setting a custom path for the wxWidgets libraries.
\&  
\&  sub set_binary_path {
\&    my $class_or_object = shift;
\&    
\&    ... work out binary path
\&    
\&    return $newbinarypath; # method MUST return a path
\&  }
.Ve
.SS "load_dll"
.IX Subsection "load_dll"
.Vb 2
\&  Is called to load wxWidgets plugin dlls using a key for the $Wx::dlls hash
\&  ( see Wx::Mini )
\&  
\&  sub load_dll {
\&    my ($class_or_object, $dllkey) = @_;
\&    ..... load dll \- or maybe not
\&  }
\&  
\&  the default loader does nothing \- dependencies are loaded automatically
\&  and determined by the standard methods of the os:
\&  
\&  an example of pre loading a known dependency 
\&  
\&  sub load_dll {
\&    return if $^O !~ /^(mswin|linux)/i;
\&    local $ENV{PATH} = $Wx::wx_path . \*(Aq;\*(Aq . $ENV{PATH} if $Wx::wx_path;
\&    return unless exists $Wx::dlls\->{$_[1]} && $Wx::dlls\->{$_[1]};
\&    my $dll = $Wx::dlls\->{$_[1]};
\&    $dll = $Wx::wx_path . \*(Aq/\*(Aq . $dll if $Wx::wx_path;
\&    Wx::_load_plugin( $dll );
\&  }
.Ve
.SS "unload_dll"
.IX Subsection "unload_dll"
.Vb 2
\&  Is called ONCE from within an END block
\&  A custom loader may choose, for example to unload any dlls it has loaded
\&  
\&  sub unload_dll {
\&    my $class_or_object = shift;
\&    
\&    ... carry out END actions
\&  }
\&  
\&  The default unload_dll is a noop ( sub unload_dll {} )
.Ve
.SS "external_set_load"
.IX Subsection "external_set_load"
.Vb 3
\&  A deprecated method of replacing the load function for plugins
\&  A custom loader may override this to prevent a legacy loader replacing
\&  the loading methods.
.Ve
.SS "external_set_unload"
.IX Subsection "external_set_unload"
.Vb 3
\&  A deprecated method of replacing the unload function for plugins
\&  A custom loader may override this to prevent a legacy loader replacing
\&  the unloading methods.
.Ve
.SS "boot_overload"
.IX Subsection "boot_overload"
.Vb 4
\&  For binary distributions and packaged applications, normal shared
\&  library loading semantics may not work. A custom loader may provide
\&  this method to use in place of, or to supplement the standard XS load
\&  of Wx.dll (Wx.so).
\&  
\&  The method MUST return true or false, depending on whether it has
\&  loaded Wx.dll (Wx.so).
\&  
\&  For example, to load the core wxWidgets dlls before Wx is loaded
\&  
\&  sub boot_overload {
\&    shift; 
\&    require DynaLoader;
\&    for my $dll ( qw( base core adv ) ) {
\&      next unless exists $Wx::dlls\->{$dll} && $Wx::dlls\->{$dll};
\&      my $file = ( $Wx::wx_path ) ? $Wx::wx_path . \*(Aq/\*(Aq . $Wx::dlls\->{$dll} : $Wx::dlls\->{$dll};
\&      my $libref = DynaLoader::dl_load_file($file, 0);
\&      push(@DynaLoader::dl_librefs,$libref) if $libref;
\&      
\&      # Dynaloader should take care of unloading
\&    
\&    }
\&   
\&    #\-\-\-\-\-\-\-\-\-\-\-\- IMPORTANT \-\-\-\-\-\-\-\-\-\-
\&    return 0; # we have not loaded Wx
\&    #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  }
\&  
\&  
\&  Some packagers extract dlls at runtime, and then may attempt to remove them
\&  at application close. This may fail for Wx. For example, on MSWin the directory
\&  cleanup fails whilst on Linux the application will seg\-fault on exit.
\&  Packagers may avoid this by loading Wx.dll( Wx.so) from a non standard location
\&  ( perhaps a separate binary distribution of wx dlls ) that is not removed at
\&  application exit.
\&  
\&  For example
\&  
\&  sub boot_overload {
\&    my $class = shift 
\&    require DynaLoader;
\&    for my $dll ( qw( base core adv ) ) {
\&      next unless exists $Wx::dlls\->{$dll} && $Wx::dlls\->{$dll};
\&      my $file = ( $Wx::wx_path ) ? $Wx::wx_path . \*(Aq/\*(Aq . $Wx::dlls\->{$dll} : $Wx::dlls\->{$dll};
\&      my $libref = DynaLoader::dl_load_file($file, 0);
\&      push(@DynaLoader::dl_librefs,$libref) if $libref;
\&      
\&      # Dynaloader should take care of unloading
\&    
\&    }
\&    
\&    package
\&       DynaLoader;
\&    
\&    my $file = $class\->get_the_location_to_wx_xs_module;
\&    
\&    #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    # From XSLoader
\&    #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    
\&    my $module  = \*(AqWx\*(Aq;
\&    
\&    my $boots = "$module\e::bootstrap";
\&    my $bootname = "boot_$module";
\&    $bootname =~ s/\eW/_/g;
\&    @DynaLoader::dl_require_symbols = ($bootname);
\&    my $boot_symbol_ref;
\&    
\&    my $libref = dl_load_file($file, 0) or do {
\&        require Carp;
\&        Carp::croak("Can\*(Aqt load \*(Aq$file\*(Aq for module $module: " . dl_error());
\&    };
\&    push(@DynaLoader::dl_librefs,$libref);  # record loaded object
\&
\&    my @unresolved = dl_undef_symbols();
\&    if (@unresolved) {
\&        require Carp;
\&        Carp::carp("Undefined symbols present after loading $file: @unresolved\en");
\&    }
\&
\&    $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do {
\&        require Carp;
\&        Carp::croak("Can\*(Aqt find \*(Aq$bootname\*(Aq symbol in $file\en");
\&    };
\&
\&    push(@DynaLoader::dl_modules, $module); # record loaded module
\&
\&    my $xs = dl_install_xsub($boots, $boot_symbol_ref, $file);
\&
\&    push(@DynaLoader::dl_shared_objects, $file); # record files loaded
\&        
\&    #\-\-\-\-\-\-\-\-\-\-\-\- IMPORTANT \-\-\-\-\-\-\-\-\-\-
\&    return 1; # we have loaded Wx
\&    #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&}
.Ve
.SH "Full Custom Loader Example"
.IX Header "Full Custom Loader Example"
.Vb 5
\&  ################################################
\&  # Custom loader for Wx distribution from
\&  # http://www.wxperl.co.uk/repository
\&  #
\&  ################################################
\&  
\&  package Wx::Loader::Custom;
\&  use strict;
\&  use warnings;
\&  
\&  our @ISA = qw( Wx::Loader::Standard );
\&  
\&  $Wx::wx_binary_loader = _\|_PACKAGE_\|_ if !$Wx::wx_binary_loader;
\&  
\&  sub loader_info { \*(AqLinux PPM Distribution from http://www.wxperl.co.uk/repository\*(Aq; }
\&  
\&  sub boot_overload {
\&      shift; 
\&      require DynaLoader;
\&      for my $dll ( qw( base core adv ) ) {
\&        next unless exists $Wx::dlls\->{$dll} && $Wx::dlls\->{$dll};
\&        my $file = ( $Wx::wx_path ) ? $Wx::wx_path . \*(Aq/\*(Aq . $Wx::dlls\->{$dll} : $Wx::dlls\->{$dll};
\&        my $libref = DynaLoader::dl_load_file($file, 0);
\&        push(@DynaLoader::dl_librefs,$libref) if $libref;
\&        
\&        # Dynaloader should take care of unloading
\&      }
\&     return 0;
\&  }
\&  
\&  # Allow legacy packaging call to override our load method
\&  
\&  my( $load_fun ) = ( \e&_load_dll );
\&  
\&  sub _load_dll {
\&      return unless exists $Wx::dlls\->{$_[0]} && $Wx::dlls\->{$_[0]};
\&      my $dll = $Wx::dlls\->{$_[0]};
\&      $dll = $Wx::wx_path . \*(Aq/\*(Aq . $dll if $Wx::wx_path;
\&      return Wx::_load_plugin( $dll );  
\&  }
\&  
\&  sub external_set_load { $load_fun = $_[1] }
\&  
\&  sub load_dll {
\&    shift;
\&    goto &$load_fun;
\&  }
.Ve