/ 
Gtk2-Ex-QuadButton-1
River stage zero No dependents
/ Gtk2::Ex::QuadButton

NAME

Gtk2::Ex::QuadButton -- button for up, down, left or right

SYNOPSIS

use Gtk2::Ex::QuadButton;
my $qb = Gtk2::Ex::QuadButton->new;

WIDGET HIERARCHY

Gtk2::Ex::QuadButton is a subclass of Gtk2::DrawingArea, but don't rely on more than Gtk2::Widget for now.

Gtk2::Widget
  Gtk2::DrawingArea
    Gtk2::Ex::QuadButton

DESCRIPTION

A QuadButton button presents up, down, left and right arrows for the user to click within a single button,

+-------------------+
|         /\        |
|        /  \       |
|         ||        |
|  / -----  ----- \ |
|  \ -----  ----- / |
|         ||        |
|        \  /       |
|         \/        |
+-------------------+

A clicked signal is emitted with a Gtk2::ScrollType like step-up, page-right etc. A normal click is a "step" and if the control key is held down then a "page".

ScrollType is oriented towards stepping or paging something in the display. See Gtk2::Ex::QuadButton::Scroll to act on Gtk2::Adjustment objects. The ScrollType reaches a Perl code signal handler as a string, so it's easy to strip the step- or page- part if only interested in the direction.

Moving the mouse pointer across the QuadButton shows the prospective direction as "prelight". In the Gtk default "Raleigh" theme prelight foreground colour is the same as normal foreground, so only the background is highlighted. This can make it a little hard to see, but doesn't affect clicking of course.

Key Bindings

The following mouse buttons and keystrokes are recognised

Button1             step-up,down,left,right per arrow
<Ctrl>Button1       page-up,down,left,right per arrow
Mouse-Wheel         step-up,down,left,right 
<Ctrl>Mouse-Wheel   page-up,down,left,right 

Up              step-up
Down            step-down
Left            step-left
Right           step-right
<Ctrl>Up        page-up
<Ctrl>Down      page-down
<Ctrl>Left      page-left
<Ctrl>Right     page-right
Page_Up         page-up
Page_Down       page-down

Other key bindings can be set to emit clicked in the usual ways, eg. per Gtk2::Rc. The mouse buttons are hard-coded. The mouse wheel is from the usual widget scroll-event and can go left and right too if you have a second wheel or setup for that.

The QuadButton is focusable by default. If you don't want keyboard operation then turn off can_focus in the usual way (see Gtk2::Widget) to be mouse-only,

$qb->can_focus(0);

Size Request

The default size request is small but enough to be visible and to click on. Currently it's based on the font size, but that might change.

If the QuadButton is to go somewhere like the lower right corner of an application between vertical and horizontal scroll bars then the default might be bigger than the space normally there. To have it use only that space, ie. not have the container widen the scrollbars just for the button, then apply a set_size_request() to something small, perhaps just 1x1. The usual width-request and height-request properties can do that in the creation,

my $qb = Gtk2::Ex::QuadButton->new
           (width_request  => 1,    # 1x1 no minimum size
            height_request => 1);

In all cases the QuadButton uses whatever space is provided by the parent and centres itself in a square area within that allocation. See the xalign and yalign properties below to control the positioning.

FUNCTIONS

$qb = Gtk2::Ex::QuadButton->new (key=>value,...)

Create and return a new QuadButton widget. Optional key/value pairs set initial properties per Glib::Object->new.

my $qb = Gtk2::Ex::QuadButton->new;

SIGNALS

clicked action signal (parameters: Gtk2::ScrollType)

Emitted when the user clicks on the button with the mouse pointer or presses a key.

This is an "action signal" and can be emitted both from Gtk2::Rc key bindings and from program code.

PROPERTIES

xalign (float, default 0.5)
yalign (float, default 0.5)

The positioning of the quad arrow within the allocated area.

If the allocated area is wider than needed then the arrow is positioned according to xalign. 0.0 is the left edge, 1.0 the right edge. The default 0.5 means centre it. Similarly yalign if the allocated area is higher than needed, with 0.0 for the top, 1.0 for the bottom.

If the widget text direction (see set_direction in Gtk2::Widget) is "rtl" then the sense of xalign is reversed, so 0.0 is the right edge and 1.0 is the left edge.

These properties are the same as the Gtk2::Misc, but QuadButton doesn't inherit from that class (currently).

SEE ALSO

Gtk2::Ex::QuadButton::Scroll, Gtk2::Button

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-quadbutton/index.html

LICENSE

Copyright 2010, 2011 Kevin Ryde

Gtk2-Ex-QuadButton is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Gtk2-Ex-QuadButton is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gtk2-Ex-QuadButton. If not, see http://www.gnu.org/licenses/.