view release on metacpan or  search on metacpan

lib/AntTweakBar.pm  view on Meta::CPAN

=cut

require XSLoader;
XSLoader::load('AntTweakBar', $VERSION);


=head1 METHODS

=head2 new

  my $bar = AntTweakBar->new(
    "TweakBar & Perl",
    size  => '200 400',
    color => '96 216 224'
  );

  my $another_bar = AntTweakBar->new(
    "Misc.",
  );


Creates new AntTweakBar instance. Optionally the list of strings of
bar-related parameters can be provided. See the list of available
at L<http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:twbarparamsyntax>.

=cut

sub new {
    my ($class, $name, %bar_params) = @_;
    croak "AntTweakBar name should be specified"
        unless defined $name;
    my $self = {
        _name    => $name,
        _bar_ptr => _create( $name ),
    };
    bless $self => $class;
    $self->set_bar_params(%bar_params);
    return $self;
}

sub DESTROY {
    my $self = shift;
    _destroy($self->{_bar_ptr});
}


sub _as_definition_string {
    my $d = shift;
    return join(' ', map {
        my $key = $_;
        my $value = $d->{$key};
        $value =~ s/'/\\'/g;
        "$key='$value'";
    } sort keys %$d);
}

=head2 add_button

  $bar->add_button(
    name       => 'my_btn',
    cb         => sub { say "clicked!" },
    definition => "label='Click me!'",    # optional
  );

  $bar->add_button(
    name       => 'my_btn',
    cb         => sub { say "clicked!" },
    definition => { # optional
      label => 'Click me!'
    }
  );


The definition parameters are the same as for variable. See
L<http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:varparamsyntax#parameters>.

=cut


sub add_button {
    my ($self, %args) = @_;

    my $name        = $args{name      };
    my $cb          = $args{cb        };
    my $definition  = $args{definition} // "";

    croak "Button name should be specified"
        unless defined $name;
    croak "Button callback should be specified"
        if(!defined($cb) || ref($cb) ne 'CODE');
    $definition = _as_definition_string($definition)
        if ($definition && ref($definition) eq 'HASH');

    _add_button($self->{_bar_ptr}, $name, $cb, $definition);
}


=head2 add_separator

  $bar->add_separator('separator-name');

=cut

sub add_separator {
    my ($self, $name, $definition) = @_;
    croak "Separator name should be specified"
        unless defined $name;

    $definition //= "";
    $definition = _as_definition_string($definition)
        if ($definition && ref($definition) eq 'HASH');

    _add_separator($self->{_bar_ptr}, $name, $definition);
}


=head2 add_variable

  my $zoom = 1.0;
  $bar->add_variable(
    mode       => 'rw',
    name       => "Zoom",
    type       => 'number',
    value      => \$zoom,
    definition => " min=0.01 max=2.5 step=0.01 help='Bla-bla-bla.' ",
  );

  # the same, but with more perlish style in definition
  $bar->add_variable(
    mode       => 'rw',
    name       => "Zoom",
    type       => 'number',
    value      => \$zoom,
    definition => {
        min     => "0.01",
        max     => "2.5",
        step    => "0.01",
        keyIncr => 'z',
        keyDecr => 'Z',
        help    => 'Scale the object (1=original size).'
    },
  );

  my $bool = undef;
  $bar->add_variable(
    mode       => 'rw',
    name       => "bool_rw_cb",
    type       => 'bool',
    cb_read    => sub { $bool; },
    cb_write   => sub {
        $bool = shift;
        say "writing value $bool";
    }
  );

C<mode>, C<name>, C<type> are mandatory. Either C<value> or C<cb_read>
should be specified. The C<definition> and C<cb_write> are optional.

=head3 mode

The B<mode> can be C<rw> (read/write) or C<ro> (read only). The mode
specified whether the variable value could be modified via AntTweakBar.

=head3 name

Defines the unique variable name at tweakbar. Unless C<label> is
specified via C<defintion>, then C<name> also defines the visual label.
for the variable.

=head3 type

Defines the type of variable. Original types L<http://anttweakbar.sourceforge.net/doc/tools:anttweakbar:twtype>
were reduced to:

=over

=item bool

=item integer

=item number (float)

=item string

=item color3f

variable must be reference to array, consisted of 3 float values: rgb.

=item color4f

variable must be reference to array, consisted of 4 float values: rgba.

=item direction

3D-vector (direction). The variable must be reference to array, consisted of 3 float values.

=item quaternion

4D-vector (3D-object rotation). The variable must be reference to array, consisted of 4 float values.

=item custom type of L<Anttweakbar::Type>

=back

=head3 value

The B<reference> to the variable value. For complex types (e.g. quaternion) it must
also be an B<reference> to array of 3 numbers.

=head3 cb_read

Closure, that returns the actual value of variable.