view release on metacpan or  search on metacpan

lib/Gtk2/Ex/WidgetCursor.pm  view on Meta::CPAN

                   Glib::G_PARAM_READWRITE),
                  #
                  # when glib 1.240 has fix for this pspec/get/set style
                  # {
                  #  pspec => ...,
                  #  get => \&cursor,
                  #  set => \&cursor,
                  # }

                  Glib::ParamSpec->string
                  ('cursor-name',
                   'Cursor name',
                   'Cursor to use while dragging, as cursor type enum nick plus "invisible".',
                   (eval {Glib->VERSION(1.240);1}
                    ? undef # default
                    : ''),  # no undef/NULL before Perl-Glib 1.240
                   Glib::G_PARAM_READWRITE),

                  Glib::ParamSpec->boxed
                  ('cursor-object',
                   'Cursor object',
                   'Cursor to use while dragging, as cursor object.',
                   'Gtk2::Gdk::Cursor',
                   Glib::G_PARAM_READWRITE),

                  Glib::ParamSpec->boolean
                  ('active',
                   'Active',
                   'Whether to show this cursor.',
                   0, # default no
                   Glib::G_PARAM_READWRITE),
                  # when glib 1.240 has fix for this pspec/get/set style
                  # {
                  #  pspec => '',
                  #  get => \&active,
                  #  set => \&active,
                  # }

                  Glib::ParamSpec->double
                  ('priority',
                   'Priority',
                   'The priority of this cursor among multiple WidgetCursors on a given widget.  Higher numbers are higher priority.',
                   - POSIX::DBL_MAX(), # min
                   POSIX::DBL_MAX(),   # max
                   0,                  # default
                   Glib::G_PARAM_READWRITE),

                  Glib::ParamSpec->boolean
                  ('include-children',
                   'Include children',
                   'Whether to apply the cursor to child widgets too.',
                   0, # default no
                   Glib::G_PARAM_READWRITE),

                ];

# @wobjs is all the WidgetCursor objects which currently exist, sorted from
# highest to lowest priority, and from newest to oldest among those of equal
# priority
#
# Elements are weakened so they don't keep the objects alive.  The DESTROY
# method strips elements and undefs from here, but not sure if undef could
# still be seen in here by certain funcs at certain times.
#
my @wobjs = ();

sub INIT_INSTANCE {
  my ($self) = @_;
  ### WidgetCursor INIT_INSTANCE: "$self"

  $self->{'installed_widgets'} = [];
  _wobjs_insert ($self);
}

sub FINALIZE_INSTANCE {
  my ($self) = @_;
  ### WidgetCursor FINALIZE_INSTANCE: "$self"
  ### installed_widgets: join(' ',@{$self->{'installed_widgets'}})

  _splice_out (\@wobjs, $self);
  if (delete $self->{'active'}) {
    _wobj_deactivated ($self);
  }
}

sub GET_PROPERTY {
  my ($self, $pspec) = @_;
  ### WidgetCursor GET_PROPERTY(): $pspec->get_name
  my $pname = $pspec->get_name;

  if ($pname eq 'cursor_name') {
    my $cursor = $self->{'cursor'};
    if (Scalar::Util::blessed($cursor)) {
      $cursor = $cursor->type;
      # think prefer undef over cursor-is-pixmap for the get()
      if ($cursor eq 'cursor-is-pixmap') {
        undef $cursor;
      }
    }
    return $cursor;
  }
  if ($pname eq 'cursor_object') {
    my $cursor = $self->{'cursor'};
    return (Scalar::Util::blessed($cursor)
            && $cursor->isa('Gtk2::Gdk::Cursor')
            && $cursor);
  }

  return $self->{$pname};
}

sub SET_PROPERTY {
  my ($self, $pspec, $newval) = @_;
  ### WidgetCursor SET_PROPERTY(): $pspec->get_name
  my $pname = $pspec->get_name;

  if ($pname eq 'active') {
    $self->active($newval);
    return;
  }
  if ($pname =~ /^cursor/) {

lib/Gtk2/Ex/WidgetCursor.pm  view on Meta::CPAN

L<Glib::Object>).

    $wc = Gtk2::Ex::WidgetCursor->new (widget => $mywidget,
                                       cursor => 'fleur',
                                       active => 1);

Note that C<active> is false by default and the WidgetCursor does nothing to
the widgets until made C<active> by the property or the method call below.

WidgetCursor objects can be applied to unrealized widgets.  The cursor
settings take effect if/when the widgets are realized.

=back

=head2 Methods

=over

=item C<< $bool = $wc->active () >>

=item C<< $wc->active ($newval) >>

Get or set the "active" state of C<$wc>.  This is the C<active> property.

=item C<< $cursor = $wc->cursor () >>

=item C<< $wc->cursor ($cursor) >>

Get or set the cursor of C<$wc>.  This is the C<cursor> property, see
L</PROPERTIES> below for possible values.  Eg.

    $wc->cursor ('umbrella');

=item C<< @widgets = $wc->widgets () >>

Return a list of the widgets currently in C<$wc>.  Eg.

    my @array = $wc->widgets;

or if you know you're only acting on one widget then say

    my ($widget) = $wc->widgets;

=item C<< $wc->add_widgets ($widget, $widget, ...) >>

Add widgets to C<$wc>.  Those not already in C<$wc> are added.

=back

=head1 PROPERTIES

=over 4

=item C<widget> (C<Gtk2::Widget>, default C<undef>)

=item C<widgets> (scalar arrayref of C<Gtk2::Widget>, default C<undef>)

The widget or widgets to act on.

A WidgetCursor object only keeps weak references to its widget(s), so the
mere fact there's a desired cursor won't keep a widget alive forever.
Garbage collected widgets drop out of the widgets list.  In particular this
means it's safe to hold a WidgetCursor within a widget's own hash without
creating a circular reference.  Eg.

    my $widget = Gtk2::DrawingArea->new;
    $widget->{'base_cursor'} = Gtk2::Ex::WidgetCursor->new
                                 (widget => $widget,
                                  cursor => 'hand1',
                                  active => 1,
                                  priority => -10);

=item C<add-widget> (C<Gtk2::Widget>, write-only)

Add a widget to those to act on.  This is a write-only pseudo-property
calling C<add_widget> above.  It's good for C<Gtk2::Builder> where the
C<widgets> property can't be used since it's a Perl scalar type.

=item C<cursor> (scalar string name or C<Gtk2::Gdk::Cursor> object)

The cursor to show in the widgets.  This can be

=over

=item *

A string cursor type nick from the C<Gtk2::Gdk::CursorType> enum, such as
C<"hand1">.  See L<Gtk2::Gdk::Cursor> for the full list of cursor types.

=item *

Special string name C<"invisible"> to have no cursor at all.  In Gtk 2.16 up
this is the same as "blank-cursor", or in earlier versions gives a "no
pixels set" pixmap cursor.

=item *

A C<Gtk2::Gdk::Cursor> object.

If your program uses multiple displays then remember the cursor object must
be on the same display (ie. C<Gtk2::Gdk::Display>) as the widget(s).  If you
have more than one widget then they must be all on the same display in this
case.  (For a named cursor they don't have to be.)

=item *

C<undef> to inherit the parent window's cursor, which may be the default
little pointing arrow or whatever from the root window.

=back

=item C<cursor-name> (string, default C<undef>)

=item C<cursor-object> (C<Gtk2::Gdk::Cursor>, default C<undef>)

The cursor to show in the widgets, as a plain Glib string or object
property.  These are designed for use from C<Gtk2::Builder> where the scalar
type C<cursor> property can't be set.

Reading from C<cursor-name> when a cursor object has been set gives the type
nick if it has one, or if it's a pixmap then currently C<undef>.