Sfairadora

  • Reference Guide

Mouse Handling

Dispels displaying a picture, that is, the image editor and the image label, allow you to define a function responding to mouse events. This chapter explains the underlying functionality.
The mouse handling function receives, as a parameter, a structure of the Mouse_info type. The parameter name is mouse_info. There are two types of information in this structure – information on the event calling the mouse handling function (pressing or releasing a button, change of position, etc.) and information on the state of the mouse (mouse position, pressed buttons – for example, the user may have pressed the left button while holding the right button pressed all the time. In this case the event was “mouse left button pressed” while the right button state was “pressed”).
The mouse can be in two modes with respect to a dispel: normally, it is in the free mode, where a dispel receives information about mouse events only when the mouse is above the dispel; or it can be in the bound mode, where the mouse is bound to a particular dispel and information about the mouse is received only by that dispel regardless of whether the mouse is above it or not. The bound mode can be enforced by a dispel in reaction to pressing a mouse button. When the mouse button is released, the mouse is automatically switched to the free mode (i.e. if no button is pressed, the mouse is always in the free mode). The bound mode ensures, among others, that after you press a mouse button, the dispel always receives also information about the button being released.

Mouse_info

Component type
Component name
Description
Int
event
Mouse event invoking the mouse handler. One of the following constants:
MOUSE_LBUTTON_PRESSED (0)
MOUSE_MBUTTON_PRESSED (1)
MOUSE_RBUTTON_PRESSED (2)
MOUSE_LBUTTON_RELEASED (3)
MOUSE_MBUTTON_RELEASED (4)
MOUSE_RBUTTON_RELEASED (5)
MOUSE_CTRL_PRESSED (6)
MOUSE_ALT_PRESSED (7)
MOUSE_SHIFT_PRESSED (8)
MOUSE_CTRL_RELEASED (9)
MOUSE_ALT_RELEASED (10)
MOUSE_SHIFT_RELEASED (11)
MOUSE_MOVE (12)
MOUSE_LOST (13)
Numerical values of the constants enclosed in parentheses are listed only for debugging purposes. You should use the symbolic names when writing a function.
Constants ending with _PRESSED indicate that a button/key was pressed whereas constants ending with _RELEASED indicate that a button/key was released. Constants containing L/M/RBBUTTON apply to the left/middle/right mouse button. Constants containing CTRL, ALT, or SHIFT apply to the respective key on the keyboard.
When a button is pressed, the respective item below reflects the state resulting from the event (i.e. when MOUSE_LBUTTON_PRESSED occurs, the value of the lbutton_pressed item is always TRUE).
The MOUSE_MOVE constant indicates a change of the mouse position. The MOUSE_LOST constant is set when the mouse had been bound to a dispel (MOUSE_MODE_BOUND mode) and this mode has been terminated from the outside.
Int
mode
Current mouse mode:
MOUSE_MODE_FREE (0) free mode
MOUSE_MODE_BOUND (1) bound mode
Bool
lbutton_pressed
Left mouse button is pressed.
Bool
mbutton_pressed
Middle mouse button is pressed.
Bool
rbutton_presed
Right mouse button is pressed.
Bool
ctrl_pressed
The Ctrl key is pressed.
Bool
alt_pressed
The Alt key is pressed.
Bool
shift_pressed
The Shift key is pressed.
Bool
out
The mouse is outside the picture area. This item can be TRUE only in the bound mode.
Int
x
Horizontal coordinate of the mouse position. It is derived from the image coordinates. The left boundary has a value of 0.
Int
y
Vertical coordinate of the mouse position. It is derived from the image coordinates. The top boundary has a value of 0.
Int
boundary_crossing
Applies to the MOUSE_MOVE event – specifies whether the image boundary has been crossed by the move:
MBC_ENTERED (1)
the mouse has just entered the image area.
MBC_NONE (0)
the state has not changed (the mouse either was and still is outside or it was and still is inside; the state can be established from the out item).
MBC_LEFT (–1)
the mouse has left the image area. If the mouse is in the free mode, the item is set to this value when the mouse leaves the image area. Information about its position and state of the buttons is empty.
Int
click_count
This value is set upon any of the events involving pressing a mouse button. If the function requested a double click (the returned value was EVENT_SEND_DOUBLE_CLICK) in reaction to the last mouse click, the sequential number of the mouse click is contained herein. The value is 1 upon a single click, 2 upon a double click, etc.

Returned Values

The function must return one of the following values in reaction to an event involving pressing a mouse button. It must return the EVENT_ACCEPTED value in reaction to all other events (other values have no effect).
EVENT_REJECTED
the mouse click has not been processed; it will be passed to parent dispels for processing.
EVENT_ACCEPTED
the mouse event has been processed.
EVENT_SEND_DOUBLE_CLICK
the mouse click has been processed, and the function requests that a double click is sent, if applicable. A double click is a click following the preceding click within a short time interval without moving the mouse (the speed and relocation tolerance are set in Windows). The mouse remains in the free mode.
EVENT_BIND_MOUSE
the mouse click has been processed and the mouse is to be switched to the bound mode. From now on, all mouse events will be passed exclusively to this dispel. The bound mode is automatically canceled when all mouse buttons are released.