NAME

IUP::Manual::04_Callbacks - Callbacks concept, using callbacks, common + global callbacks

IUP MANUAL

IUP::Manual::01_Introduction
IUP::Manual::02_Elements
IUP::Manual::03_Attributes
IUP::Manual::04_Callbacks <<< this document
IUP::Manual::06_HandlingKeyboard
IUP::Manual::05_DialogLayout
IUP::Manual::07_UsingImageLibrary
IUP::Manual::08_DragAndDrop

INTRODUCTION

This document is intended as a reference list for common callbacks used by several or all GUI elements + global IDLE_ACTION callback.

For more information about using callbacks see Callbacks Concept in IUP::Manual::01_Introduction.

Callbacks described in this document:

ACTION, BUTTON_CB, CLOSE_CB, DESTROY_CB, DROPFILES_CB, ENTERWINDOW_CB, GETFOCUS_CB, HELP_CB, HIGHLIGHT_CB, IDLE_ACTION, KEYPRESS_CB, KILLFOCUS_CB, K_ANY, LEAVEWINDOW_CB, MAP_CB, MENUCLOSE_CB, MOTION_CB, OPEN_CB, RESIZE_CB, SCROLL_CB, SHOW_CB, UNMAP_CB, WHEEL_CB, WOM_CB

CALLBACKS

ACTION

Action generated when the element is activated. Affects each element differently.

Callback handler prototype:

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

$self: reference to the element that activated the event.

In some elements, this callback may receive more parameters, apart from $self. Please refer to each element's documentation.

Affects: IUP::Button, IUP::Item, IUP::List, IUP::Text, IUP::Canvas, IUP::Multiline, IUP::Toggle

BUTTON_CB

Action generated when a mouse button is pressed or released.

Callback handler prototype:

sub button_cb_handler {
  my ($self, $button, $pressed, $x, $y, $status) = @_;
  #...
}

$self: reference to the element that activated the event.

$button: identifies the activated mouse button:

IUP_BUTTON1 or "1" ... left mouse button (button 1)
IUP_BUTTON2 or "2" ... middle mouse button (button 2)
IUP_BUTTON3 or "3" ... right mouse button (button 3)

Note: IUP_BUTTON? constants are defined in IUP::Constants.

$pressed: boolean that indicates the state of the button:

0 ... mouse button was released;
1 ... mouse button was pressed.

$x, $y: position in the canvas where the event has occurred, in pixels.

$status: status of the mouse buttons and some keyboard keys at the moment the event is generated. The following macros must be used for verification:

IUP->isshift($status)
IUP->iscontrol($status)
IUP->isbutton1($status)
IUP->isbutton2($status)
IUP->isbutton3($status)
IUP->isbutton4($status)
IUP->isbutton5($status)
IUP->isdouble($status)
IUP->isalt($status)
IUP->issys($status)

They return 1 if the respective key or button is pressed, and 0 otherwise.

Returns: IUP_CLOSE will be processed. On some controls if IUP_IGNORE is returned the action is ignored (this is system dependent).

Notes:

This callback can be used to customize a button behavior. For a standard button behavior use the ACTION callback of the IUP::Button.

A double click is preceded by two single clicks, one for pressed=1 and one for pressed=0, and followed by a press=0, all three without the double click flag set. In GTK, it is preceded by an additional two single clicks sequence. For example, for one double click all the following calls to BUTTON_CB callback handler are made:

BUTTON_CB($but=1, $pressed=1, $x=154, $y=83, $status='[  1       ]')
BUTTON_CB($but=1, $pressed=0, $x=154, $y=83, $status='[  1       ]')
BUTTON_CB($but=1, $pressed=1, $x=154, $y=83, $status='[  1       ]') (in GTK only)
BUTTON_CB($but=1, $pressed=0, $x=154, $y=83, $status='[  1       ]') (in GTK only)
BUTTON_CB($but=1, $pressed=1, $x=154, $y=83, $status='[  1  D    ]')
BUTTON_CB($but=1, $pressed=0, $x=154, $y=83, $status='[  1       ]')

Affects: IUP::Canvas, IUP::Button, IUP::Text, IUP::List, IUP::CanvasGL

CLOSE_CB

Called just before a dialog is closed when the user clicks the close button of the title bar or an equivalent action.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Returns: if IUP_IGNORE, it prevents the dialog from being closed. If you destroy the dialog in this callback, you must return IUP_IGNORE. IUP_CLOSE will be processed.

Affects: IUP::Dialog

DESTROY_CB

Called right before an element is destroyed.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: All.

DROPFILES_CB

Action called when a file is "dragged" to the application. When several files are dragged, the callback is called several times, once for each file.

If defined after the element is mapped then the attribute DRAGDROP must be set to YES.

[Windows and GTK Only] (GTK 2.6)

Callback handler prototype:

sub dropfiles_cb_handler {
  my ($self, $filename, $num, $x, $y) = @_;
  #...
}

$self: reference to the element that activated the event.

$filename: Name of the dragged file.

$num: Number of the dragged file. If several files are dragged, num counts the number of dragged files starting from "total-1" to "0".

$x: X coordinate of the point where the user released the mouse button.

$y: Y coordinate of the point where the user released the mouse button.

Returns: If IUP_IGNORE is returned the callback will NOT be called for the next dropped files, and processing of dropped files will be interrupted.

Affects: IUP::Dialog, IUP::Canvas, IUP::CanvasGL, IUP::Text, IUP::List

ENTERWINDOW_CB

Action generated when the mouse enters the canvas or button.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: All controls with user interaction.

GETFOCUS_CB

Action generated when an element is given keyboard focus. This callback is called after the KILLFOCUS_CB of the element that loosed the focus. The IUP::GetFocus function during the callback returns the element that loosed the focus.

Callback handler prototype:

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

$self: reference to the the element that received keyboard focus.

Affects: All elements with user interaction, except menus.

See Also: KILLFOCUS_CB, GetFocus, SetFocus

HELP_CB

Action generated when the user press F1 at a control. In Motif is also activated by the Help button in some workstations keyboard.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Returns: IUP_CLOSE will be processed.

Affects: All elements with user interaction.

HIGHLIGHT_CB

Callback triggered every time the user selects an IUP::Item or IUP::Submenu.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: IUP::Item, IUP::Submenu

IDLE_ACTION

Predefined IUP action, generated when there are no events or messages to be processed. Often used to perform background operations.

Callback handler prototype:

sub idle_handler() {
  # no parameters
  #...
}
int function(void); [in C]

Returns: if IUP_CLOSE is returned the current loop will be closed and the callback will be removed. If IUP_IGNORE is returned the callback is removed and normal processing continues.

Notes:

The Idle callback will be called whenever there are no messages left to be processed. But this occurs more frequent than expected, for example if you move the mouse over the application the idle callback will be called many times because the mouse move message is processed so fast that the Idle will be called before another mouse move message is schedule to processing.

So this callback changes the message loop to a more CPU consuming one. It is important that you set it to undef when not using it. Or the application will be consuming CPU even if the callback is doing nothing.

To set this action use the function IUP->SetIdle(\&myfunction). Using undef as a parameter to remove the association.

Long Time Operations: If you create a loop or an operation that takes a long time to complete inside a callback of your application then the user interface message loop processing is interrupted until the callback returns, so the user can not click on any control of the application. But there are ways to handle that:

call IUP->LoopStep or IUP->Flush inside the application callback when it is performing long time operations. This will allow the user to click on a cancel button for instance, because the user interface message loop will be processed.
split the operation in several parts that are processed by the IUP->Idle XXX-CHECKTHIS function when no messages are left to be processed for the user interface message loop. This will make a heavy use of the CPU, even if the callback is doing nothing.
split the operation in several parts but use a IUP::Timer to process each part.

If you just want to do something simple as a background redraw of an IUP::Canvas, then a better idea is to handle the "idle" state yourself. For example, register a timer for a small time like 500ms, and reset the timer in all the mouse and keyboard callbacks of the IUP::Canvas. If the timer is trigged then you are in idle state. If the IUP::Canvas loses its focus then stop the timer.

See Also: SetFunction, IUP::Timer.

KEYPRESS_CB

Action generated when a key is pressed or released. If the key is pressed and held several calls will occur. It is called after the callback K_ANY is processed.

Callback handler prototype:

sub keypress_cb_handler {
  my ($self, $c, $press) = @_;
  #...
}

$self: reference to the element that activated the event.

$c: identifier of typed key. Please refer to the Keyboard Codes table for a list of possible values.

$press: 1 is the user pressed the key or 0 otherwise.

Returns: If IUP_IGNORE is returned the key is ignored by the system. IUP_CLOSE will be processed.

Affects: IUP::Canvas

KILLFOCUS_CB

Action generated when an element loses keyboard focus. This callback is called before the GETFOCUS_CB of the element that gets the focus.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: All elements with user interaction, except menus.

See Also: GETFOCUS_CB, IUP-GetFocus|IUP/GetFocus>, IUP-SetFocus|IUP/SetFocus>

K_ANY

Action generated when a keyboard event occurs.

Callback handler prototype:

sub k_any_handler {
  my ($self, $c) = @_;
  #...
}

$self: reference to the element that activated the event.

$c: identifier of typed key. Please refer to the Keyboard Codes table for a list of possible values.

Returns: If IUP_IGNORE is returned the key is ignored and not processed by the control and not propagated. If returns IUP_CONTINUE, the key will be processed and the event will be propagated to the parent of the element receiving it, this is the default behavior. If returns IUP_DEFAULT the key is processed but it is not propagated. IUP_CLOSE will be processed.

Notes:

Keyboard callbacks depend on the keyboard usage of the control with the focus. So if you return IUP_IGNORE the control will usually not process the key. But be aware that sometimes the control process the key in another event so even returning IUP_IGNORE the key can get processed. Although it will not be propagated.

IMPORTANT: The callbacks "K_*" of the dialog or native containers depend on the IUP_CONTINUE return value to work while the control is in focus.

If the callback does not exists it is automatically propagated to the parent of the element.

Affects: All elements with keyboard interaction.

LEAVEWINDOW_CB

Action generated when the mouse leaves a canvas or button.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: All controls with user interaction.

MAP_CB

Called right after an element is mapped and its layout updated.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: All that have a native representation.

MENUCLOSE_CB

Called just after the menu is closed.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: IUP::Menu

MOTION_CB

Action generated when the mouse moves.

Callback handler prototype:

int function(Ihandle *ih, int x, int y, char *status); [in C]
elem:motion_cb(x, y: number, status: string) -> (ret: number) [in Lua]
sub motion_cb_handler {
  my ($self, $x, $y, $number, $status) = @_;
  #...
}

$self: reference to the element that activated the event.

$x, $y: position in the canvas where the event has occurred, in pixels.

$status: status of mouse buttons and certain keyboard keys at the moment the event was generated. The same macros used for BUTTON_CB can be used for this status.

Affects: IUP::Canvas, IUP::CanvasGL

OPEN_CB

Called just before the menu is opened.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: IUP::Menu

RESIZE_CB

Action generated when the element size is changed.

Callback handler prototype:

sub resize_cb_handler {
  my ($self, $width, $height) = @_;
  #...
}

$self: reference to the element that activated the event.

$width: the width of the internal element size in pixels not considering the decorations (client size) XXX-ADD-LINK description in layout.pod

$height: the height of the internal element size in pixels not considering the decorations (client size) XXX-ADD-LINK description in layout.pod

Notes:

This action is also generated when the dialog is mapped, after the map and before the show.

Affects: IUP::Canvas, IUP::CanvasGL, IUP::Dialog

SCROLL_CB

Called when some manipulation is made to the scrollbar. The canvas is automatically redrawn only if this callback is NOT defined.

(GTK 2.8)

Callback handler prototype:

sub scroll_cb_handler {
  my ($self, $op, $posx, $posy) = @_;
  #...
}

$self: reference to the element that activated the event.

$op: indicates the operation performed on the scrollbar.

If the manipulation was made on the vertical scrollbar, it can have the following values:

IUP_SBUP    ... line up
IUP_SBDN    ... line down
IUP_SBPGUP  ... page up
IUP_SBPGDN  ... page down
IUP_SBPOSV  ... vertical positioning
IUP_SBDRAGV ... vertical drag

If it was on the horizontal scrollbar, the following values are valid:

IUP_SBLEFT    ... column left
IUP_SBRIGHT   ... column right
IUP_SBPGLEFT  ... page left
IUP_SBPGRIGHT ... page right
IUP_SBPOSH    ... horizontal positioning
IUP_SBDRAGH - horizontal drag

$posx, posy: the same as the ACTION canvas callback (corresponding to the values of attributes POSX and POSY).

Notes:

IUP_SBDRAGH and IUP_SBDRAGV are not supported in GTK.

Affects: IUP::Canvas, IUP::CanvasGL, SCROLLBAR

SHOW_CB

Called right after the dialog is opened, minimized or restored from a minimization. This callback is called when those actions were performed by the user or programmatically by the application.

Callback handler prototype:

sub show_cb_handler {
  my ($self, $state) = @_;
  #...
}

$self: reference to the element that activated the event.

$state: indicates which of the following situations generated the event:

IUP_HIDE
IUP_SHOW
IUP_RESTORE  (was minimized or maximized)
IUP_MINIMIZE
IUP_MAXIMIZE

Note: IUP_MAXIMIZE is not received in Motif when activated from the maximize button.

Returns: IUP_CLOSE will be processed.

Affects: IUP::Dialog

UNMAP_CB

Called right before an element is unmapped.

Callback handler prototype:

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

$self: reference to the element that activated the event.

Affects: All that have a native representation.

WHEEL_CB

Action generated when the mouse wheel is rotated. If this callback is not defined the wheel will automatically scroll the canvas in the vertical direction by some lines, the SCROLL_CB callback if defined will be called with the IUP_SBDRAGV operation.

Callback handler prototype:

sub wheel_cb_handler {
  my ($self, $delta, $x, $y, $status) = @_;
  #...
}

$self: reference to the element that activated the event.

$delta: the amount the wheel was rotated in notches.

$x, $y: position in the canvas where the event has occurred, in pixels.

$status: status of mouse buttons and certain keyboard keys at the moment the event was generated. The same macros used for BUTTON_CB can be used for this status.

Notes:

In Motif and GTK delta is always 1 or -1. In Windows is some situations delta can reach the value of two. In the future with more precise wheels this increment can be changed.

The wheel will only work if the focus is at the canvas.

Affects: IUP::Canvas, IUP::CanvasGL

WOM_CB

Action generated when an audio device receives an event.

[Windows Only]

Callback handler prototype:

sub wom_cb_handler {
  my ($self, $state) = @_;
  #...
}

$self: reference to the element that activated the event.

$state: can be opening=1, done=0, or closing=-1.

Notes:

This callback is used to syncronize video playback with audio. It is sent when the audio device:

MESSAGE     DESCRIPTION
opening     is opened by using the waveOutOpen function.
done        is finished with a data block sent by using the waveOutWrite function.
closing     is closed by using the B<waveOutClose> function.

You must use the HWND attribute when calling waveOutOpen in the dwCallback parameter and set fdwOpen to CALLBACK_WINDOW.

Affects: IUP::Dialog, IUP::Canvas, IUP::CanvasGL

To install IUP, copy and paste the appropriate command in to your terminal.

cpanm

cpanm IUP

CPAN shell

perl -MCPAN -e shell
install IUP

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

IUP MANUAL

INTRODUCTION

CALLBACKS

Module Install Instructions