.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "Wx::Loader 3pm"
.TH Wx::Loader 3pm 2024-05-24 "perl v5.38.2" "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 (PAR, 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