/ 
IUP-0.304
River stage zero No dependents
/ IUP::Dial

NAME

IUP::Dial - [GUI element] dial for regulating a given angular variable

DESCRIPTION

Creates a dial for regulating a given angular variable.

USAGE

CREATION - new() method

$dial = IUP::Dial->new( ORIENTATION=>"VERTICAL" );

Returns: the identifier of the created element, or undef if an error occurs.

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.

ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:

DENSITY

Number of lines per pixel in the handle of the dial. Default is "0.2".

EXPAND

The default is "NO".

FGCOLOR

Foreground color. The default value is "64 64 64". Not used for the circular dial.

SIZE

(non inheritable)

The initial size is "16x80", "80x16" or "40x35" according to the dial orientation. Set to undef to allow the automatic layout use smaller values.

ORIENTATION

(creation only) (non inheritable)

Dial layout configuration "VERTICAL", "HORIZONTAL" or "CIRCULAR". Default: "HORIZONTAL".

UNIT

Unit of the angle. Can be "DEGREES" or "RADIANS". Default is "RADIANS". Used only in the callbacks.

VALUE

(non inheritable)

The dial angular value in radians. The value is reset to zero when the interaction is started, except for ORIENTATION="CIRCULAR". When orientation is vertical or horizontal, the dial measures relative angles. When orientation is circular the dial measure absolute angles, where the origin is at 3 o'clock.

The following common attributes are also accepted:

CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:

BUTTON_PRESS_CB

Called when the user presses the left mouse button over the dial. The angle here is always zero, except for the circular dial.

Callback handler prototype:

sub button_press_cb_handler {
  my ($self, $angle) = @_;
  #...
}

    $self: reference to the element (IUP::Dial) that activated the event

    $angle: the dial value converted according to UNIT.

BUTTON_RELEASE_CB

Called when the user releases the left mouse button after pressing it over the dial.

Callback handler prototype:

sub button_release_cb_handler {
  my ($self, $angle) = @_;
  #...
}

    $self: reference to the element (IUP::Dial) that activated the event

    $angle: the dial value converted according to UNIT.

MOUSEMOVE_CB

Called each time the user moves the dial with the mouse button pressed. The angle the dial rotated since it was initialized is passed as a parameter.

Callback handler prototype:

sub mousemove_cb_handler {
  my ($self, $angle) = @_;
  #...
}

    $self: reference to the element (IUP::Dial) that activated the event

    $angle: the dial value converted according to UNIT.

VALUECHANGED_CB

Called after the value was interactively changed by the user. It is called whenever a BUTTON_PRESS_CB, a BUTTON_RELEASE_CB or a MOUSEMOVE_CB would also be called, but if defined those callbacks will not be called.

Callback handler prototype:

sub valuechanged_cb_handler {
  my ($self) = @_;
  #...
}

    $self: reference to the element (IUP::Dial) that activated the event

The following common callbacks are also accepted:

NOTES

When the keyboard arrows are pressed and released the mouse press and the mouse release callbacks are called in this order. If you hold the key down the mouse move callback is also called for every repetition.

When the wheel is rotated only the mouse move callback is called, and it increments the last angle the dial was rotated.

In all cases the value is incremented or decremented by PI/10 (18 degrees).

If you press Shift while using the arrow keys the increment is reduced to PI/100 (1.8 degrees). Press the Home key in the circular dial to reset to 0.

EXAMPLES

The element IUP::Dial is used in the following sample scripts:

SEE ALSO

IUP::Canvas

The original doc: iupdial.html