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.

Prima::MouseScroller

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.

Prima::GroupScroller

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.
scrollBarClass STRING = Prima::ScrollBar: Create-only property that allows to change scrollbar class
hScrollBarProfile, vScrollBarProfile HASH: Create-only property that allows to change scrollbar parameters when it is being created

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.

Prima::UndoActions

Used for classes that can edit and undo and redo its content.

Properties

undoLimit INTEGER: Sets limit on number of stored atomic undo operations. If 0, undo is disabled.

Methods

begin_undo_group: Opens bracket for group of actions, undone as single operation. The bracket is closed by calling "end_undo_group".
end_undo_group: Closes bracket for group of actions, opened by "begin_undo_group".
redo: Re-applies changes, formerly rolled back by "undo".
undo: Rolls back changes into internal array, which size cannot extend "undoLimit" value. In case "undoLimit" is 0, no undo actions can be made.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.