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.

   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.