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' 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 needs to overload one of borderWidth, hScroll, and vScroll 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 horizontall scroll bar
     {vScrollBar}   - pointer to the vertical scroll bar
     {bone}         - rectangular widget between the scrollbars

  The reserved method names:

     set_h_scroll
     set_v_scroll
     insert_bone
     setup_indents
     borderWidth
     hScroll
     vScroll

  The reserved widget names:

     HScroll
     VScroll
     Bone

Properties

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.

AUTHOR

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

SEE ALSO

Prima, Prima::Widget, Prima::InputLine, Prima::Lists, Prima::Edit, Prima::Outlines, Prima::ScrollBar.