NAME¶
Prima::IntUtils - internal functions
DESCRIPTION¶
The module provides packages, containing common functionality for some standard
classes. The packages are designed as a code containers, not as widget
classes, and are to be used as secondary ascendants in the widget inheritance
declaration.
Implements routines for emulation of auto repeating mouse events. A code inside
"MouseMove" callback can be implemented by the following scheme:
if ( mouse_pointer_inside_the_scrollable_area) {
$self-> scroll_timer_stop;
} else {
$self-> scroll_timer_start unless $self-> scroll_timer_active;
return unless $self-> scroll_timer_semaphore;
$self-> scroll_timer_semaphore( 0);
}
The class uses a semaphore "{mouseTransaction}", which should be set
to non-zero if a widget is in mouse capture state, and set to zero or
"undef" otherwise.
The class starts an internal timer, which sets a semaphore and calls
"MouseMove" notification when triggered. The timer is assigned the
timeouts, returned by "Prima::Application::get_scroll_rate" ( see
"get_scroll_rate" in Prima::Application ).
Methods¶
- scroll_timer_active
- Returns a boolean value indicating if the internal timer is
started.
- scroll_timer_semaphore [ VALUE ]
- A semaphore, set to 1 when the internal timer was
triggered. It is advisable to check the semaphore state to discern a
timer-generated event from the real mouse movement. If VALUE is specified,
it is assigned to the semaphore.
- scroll_timer_start
- Starts the internal timer.
- scroll_timer_stop
- Stops the internal timer.
Prima::IntIndents¶
Provides the common functionality for the widgets that delegate part of their
surface to the border elements. A list box can be of an example, where its
scroll bars and 3-d borders are such elements.
Properties¶
- indents ARRAY
- Contains four integers, specifying the breadth of
decoration elements for each side. The first integer is width of the left
element, the second - height of the lower element, the third - width of
the right element, the fourth - height of the upper element.
The property can accept and return the array either as a four scalars, or as
an anonymous array of four scalars.
Methods¶
- get_active_area [ TYPE = 0, WIDTH, HEIGHT ]
- Calculates and returns the extension of the area without
the border elements, or the active area. The extension are related to the
current size of a widget, however, can be overridden by specifying WIDTH
and HEIGHT. TYPE is an integer, indicating the type of calculation:
- TYPE = 0
- Returns four integers, defining the area in the
inclusive-exclusive coordinates.
- TYPE = 1
- Returns four integers, defining the area in the
inclusive-inclusive coordinates.
- TYPE = 2
- Returns two integers, the size of the area.
The class is used for widgets that contain optional scroll bars, and provides
means for their maintenance. The class is the descendant of Prima::IntIndents,
and adjusts the indents property when scrollbars are shown or hidden, or
borderWidth is changed.
The class does not provide range selection for the scrollbars; the descentant
classes must implement that.
The descendant classes must follow the guidelines:
- •
- A class must provide "borderWidth",
"hScroll", and "vScroll" property keys in
profile_default() . A class may provide "autoHScroll" and
"autoVScroll" property keys in profile_default() .
- •
- A class' init() method must set
"{borderWidth}", "{hScroll}", and
"{vScroll}" variables to 0 before the initialization, call
"setup_indents" method, and then assign the properties from the
object profile.
If a class provides "autoHScroll" and "autoVScroll"
properties, these must be set to 0 before the initialization.
- •
- If a class needs to overload one of
"borderWidth", "hScroll", "vScroll",
"autoHScroll", and "autoVScroll" properties, it is
mandatory to call the inherited properties.
- •
- A class must implement the scroll bar notification
callbacks: "HScroll_Change" and "VScroll_Change".
- •
- A class must not use the reserved variable names, which
are:
{borderWidth} - internal borderWidth storage
{hScroll} - internal hScroll value storage
{vScroll} - internal vScroll value storage
{hScrollBar} - pointer to the horizontal scroll bar
{vScrollBar} - pointer to the vertical scroll bar
{bone} - rectangular widget between the scrollbars
{autoHScroll} - internal autoHScroll value storage
{autoVScroll} - internal autoVScroll value storage
The reserved method names:
set_h_scroll
set_v_scroll
insert_bone
setup_indents
reset_indents
borderWidth
autoHScroll
autoVScroll
hScroll
vScroll
The reserved widget names:
HScroll
VScroll
Bone
Properties¶
- autoHScroll BOOLEAN
- Selects if the horizontal scrollbar is to be shown and
hidden dynamically, depending on the widget layout.
- autoVScroll BOOLEAN
- Selects if the vertical scrollbar is to be shown and hidden
dynamically, depending on the widget layout.
- borderWidth INTEGER
- Width of 3d-shade border around the widget.
Recommended default value: 2
- hScroll BOOLEAN
- Selects if the horizontal scrollbar is visible. If it is,
"{hScrollBar}" points to it.
- vScroll BOOLEAN
- Selects if the vertical scrollbar is visible. If it is,
"{vScrollBar}" points to it.
Properties¶
- setup_indents
- The method is never called directly; it should be called
whenever widget layout is changed so that indents are affected. The method
is a request to recalculate indents, depending on the widget layout.
The method is not reentrant; to receive this callback and update the widget
layout, that in turn can result in more "setup_indents" calls,
overload "reset_indents" .
- reset_indents
- Called after "setup_indents" is called and
internal widget layout is updated, to give a chance to follow-up the
layout changes.
AUTHOR¶
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO¶
Prima, Prima::Widget, Prima::InputLine, Prima::Lists, Prima::Edit,
Prima::Outlines, Prima::ScrollBar.