Prima::IntUtils(3)

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 the get_scroll_rate entry in the Prima::Application manpage ).

  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 the Prima::IntIndents manpage, and adjusts the the indents manpage property when scrollbars are shown or hidden, or the borderWidth manpage 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
the Prima manpage, the Prima::Widget manpage, the Prima::InputLine manpage, the Prima::Lists manpage, the Prima::Edit manpage, the Prima::Outlines manpage, the Prima::ScrollBar manpage.