Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

com.eliad.model
Interface RulerModel

All Known Implementing Classes:
AbstractRulerModel
public interface RulerModel
extends Intervals, GridModelListener, java.beans.PropertyChangeListener, RulerConstants, java.lang.Cloneable

This interface captures the model for handling a component that can be segmented along the horizontal or vertical axis, with each segment size being separately tunable.

This is meant for Scrollable components with a large number of segments, in which it would be necessary to move quickly and easily from pixel to logical units (segments).

The API is an extension of the Intervals API, adding preferred, minimum, and maximum sizes for each item, a hidden/visible attribute, and global orientation, margin, and resizing behavior.

Version:
1.0 00/05/20
Author:
Patrick Mérissert-Coffinières

Inner Class Summary
static class RulerModel.Factory
          A factory to clone ruler model objects and create default ones
 
Inner classes inherited from class com.eliad.util.Intervals
Intervals.Factory
 
Fields inherited from class com.eliad.util.RulerConstants
AUTO_RESIZE_ALL, AUTO_RESIZE_LAST, AUTO_RESIZE_NEXT, AUTO_RESIZE_OFF, AUTO_RESIZE_SUBSEQUENT, HORIZONTAL, VERTICAL
 
Method Summary
 void addRulerModelListener(RulerModelListener l)
          Adds a listener to the list that's notified each time a change to the data model occurs.
 java.lang.Object clone()
          Necessary to allow public access to the clone method.
 int getAutoResizeMode()
          Returns the resizing mode of the ruler.
 int getDraggingDistance()
          Returns the distance that the "dragged" items are from their normal position.
 int getFirstDraggingItem()
          Returns the first of a continuous range of items that should be considered "dragged" out of its normal position.
 int getIndex(int position)
          Returns the index of the entry that corresponds to the specified position.
 int getLastDraggingItem()
          Returns the last of a continuous range of items that should be considered "dragged" out of its normal position.
 int getMargin()
          Returns the global margin value
 int getMaxSize(int index)
          Returns the maximum size of a specific entry.
 int getMinSize(int index)
          Returns the minimum size of a specific entry.
 int getOrientation()
          Returns the orientation of the ruler.
 int getPreferredSize(int index)
          Returns the preferred size of a specific entry.
 int getScrollableBlockIncrement(int start, int length, int direction)
          Returns the scroll increment (in pixels) that completely exposes one new "page".
 int getScrollableUnitIncrement(int start, int length, int direction)
          Returns the scroll increment (in pixels) that completely exposes one new item.
 int getSize(int i)
          Returns the size of the specified entry.
 int getTotalMaxSize()
          Returns the total maximum size of the items in the most optimized way
 int getTotalMinSize()
          Returns the total minimum size of the items in the most optimized way
 int getTotalPreferredSize()
          Returns the total preferred size of the items in the most optimized way
 int getTotalSize()
          Returns the total size of the items in the most optimized way
 void insertEntries(int start, int count, int value)
          Adds a continuous group of entries to this Intervals.
 void insertEntries(int start, int count, int value, boolean visible)
          Adds a continuous group of entries to this Intervals.
 boolean isResizable(int index)
          Returns the resizable attribute for a specific item.
 boolean isVisible(int index)
          Returns true if the item with the given index is visible.
 void removeRulerModelListener(RulerModelListener l)
          Removes a listener from the list that's notified each time a change to the data model occurs.
 void resetDragging()
          Resets all dragging parameters.
 void setActiveRange(int start, int count)
          For an implementation about the area of interest, where subsequent queries should be answered very efficiently Invoke this method each time the bounds of the component change.
 void setAutoResizeMode(int mode)
          Sets the resizing mode of the ruler.
 void setDraggingDistance(int d)
          Sets the distance the "dragged" items are from their normal position.
 void setFirstDraggingItem(int index)
          Sets the first of a continuous range of items that have been "dragged" out of its normal position.
 void setLastDraggingItem(int index)
          Sets the last of a continuous range of items that have been "dragged" out of its normal position.
 void setMargin(int m)
          Sets the global margin value
 int setMaxSize(int index, int maxSize)
          Sets the maximum size of a specific entry but must leave all sizes consistent.
 int setMinSize(int index, int minSize)
          Sets the minimum size of a specific entry but must leave all sizes consistent.
 int setPreferredSize(int index, int size)
          Sets the preferred size of a specific entry which must be constrained between the minimum and maximum sizes.
 void setResizable(int index, boolean flag)
          Allows to interactively change the resizable attribute for a specific item.
 void setSize(int i, int size)
          Sets the size of the specified entry.
 void setUniformMaxSize(int maxSize)
          Sets a uniform maximum size for all entries.
 void setUniformMinSize(int minSize)
          Sets a uniform minimum size for all entries.
 void setVisible(int index, boolean flag)
          Set the visible property of an item.
 void sizeToFit(int totalSize)
          Handles global resizing
 
Methods inherited from interface com.eliad.util.Intervals
getCount, getDefaultSize, getPosition, getSizes, hasFixedSize, removeEntries, setFixedSize, setSizes
 
Methods inherited from interface com.eliad.model.GridModelListener
gridDataChanged, gridModelChanged, gridStructureChanged
 
Methods inherited from interface java.beans.PropertyChangeListener
propertyChange
 

Method Detail

getSize

public int getSize(int i)
Returns the size of the specified entry. This method already belongs to the Intervals API, but with slightly different post-conditions.
Specified by:
getSize in interface Intervals
Parameters:
i - the index corresponding to the entry
Returns:
the size of the entry
Preconditions:
index >= 0 && i < getCount()
Postconditions:
return >= 0
return == getPosition(i+1) - getPosition(i)
!isVisible(i) implies return == 0
isVisible(i) implies getMinSize(i) <= return && return <= getMaxSize(index);

setSize

public void setSize(int i,
                    int size)
Sets the size of the specified entry. This method already belongs to the Intervals API, but with slightly different post-conditions. Implementation must coerce the value between the minimum and maximum sizes to preserve the invariants.

If the item is not visible, it stays that way, the method call only affects the size that it will be once it is made visible again.

Specified by:
setSize in interface Intervals
Parameters:
i - the index corresponding to the entry
size - the size of the entry
Preconditions:
i >= 0 && i < getCount()
getAutoResizeMode() == AUTO_RESIZE_OFF || getAutoResizeMode() == AUTO_RESIZE_LAST || i < getCount()-1
size > 0
Postconditions:
!isVisible(i) implies forall int j in [0, getCount()[ | getSize(j) == getSize(j)@pre
getAutoResizeMode() != getAutoResizeMode()@pre implies isVisible(i) && getAutoResizeModel() == AUTO_RESIZE_OFF
isVisible(i) && getAutoResizeMode()@pre == AUTO_RESIZE_OFF implies getSize(i) == Math.min(Math.max(size,getMinSize(i)),getMaxSize(i))
isVisible(i) && getAutoResizeMode() == getAutoResizeMode()@pre && getAutoResizeMode() != AUTO_RESIZE_OFF && getAutoResizeMode() != AUTO_RESIZE_ALL implies getSize(i) == Math.min(Math.max(size,getMinSize(i)),getMaxSize(i))
isVisible(i) && getAutoResizeMode() == getAutoResizeMode()@pre && getAutoResizeMode() != AUTO_RESIZE_OFF implies getTotalSize() == getTotalSize()@pre

getIndex

public int getIndex(int position)
Returns the index of the entry that corresponds to the specified position. This method already belongs to the Intervals API, but with slightly enhanced post-conditions.
Specified by:
getIndex in interface Intervals
Parameters:
position - the position of the entry
Returns:
the index of the entry that occupies the specified position
Postconditions:
position < 0 implies return == -1
position >=0 && position < getTotalSize() implies return >= 0 && return < getCount() && isVisible(return)
position >= getTotalSize() implies return == getCount()
See Also:
Intervals.getIndex(int)

getOrientation

public int getOrientation()
Returns the orientation of the ruler. This is a read-only property, which must be set at instantiation time.
Returns:
whether the axis is horizontal or vertical.
Postconditions:
return == RulerConstants.HORIZONTAL || return == RulerConstants.VERTICAL
See Also:
RulerConstants

getScrollableUnitIncrement

public int getScrollableUnitIncrement(int start,
                                      int length,
                                      int direction)
Returns the scroll increment (in pixels) that completely exposes one new item.

This method is called each time the user requests a unit scroll.

Parameters:
start - the start of the view area visible within the viewport
length - the length of the view area visible within the viewport
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
the "unit" increment for scrolling in the specified direction
Preconditions:
direction == -1 || direction == 1
start >=0 && start <= getPosition(getCount())
Postconditions:
return >= 0
start + direction*return >=0 && start + direction*return <= getPosition(getCount())
getPosition(getIndex(start + direction*return)) == start + direction*return
direction > 0 && start == getPosition(getCount()) implies return == 0
direction > 0 && start < getPosition(getCount()) implies return > 0 && forall i in [getIndex(start), getIndex(start + return)[ | getPosition(i) <= start
direction < 0 && start == 0 implies return == 0
direction < 0 && start > 0 implies return > 0 && forall i in [getIndex(start - return)+1, getIndex(start)[ | getPosition(i) >= start
See Also:
Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(int start,
                                       int length,
                                       int direction)
Returns the scroll increment (in pixels) that completely exposes one new "page".

This method is called each time the user requests a page scroll.

Parameters:
start - the start of the view area visible within the viewport
length - the length of the view area visible within the viewport
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
the "block" increment for scrolling in the specified direction
Preconditions:
direction == -1 || direction == 1
start >=0 && start < getPosition(getCount())
Postconditions:
return >= 0
start + direction*return >=0 && start + direction*return <= getPosition(getCount())
getPosition(getIndex(start + direction*return)) == start + direction*return
direction > 0 implies forall i in [getIndex(start)+1, getIndex(start + return)[ | getPosition(i) < Math.min(getPosition(getIndex(start))+count, getPosition(getCount()))
direction < 0 implies forall i in [getIndex(start - return)+1, getIndex(start)[ | getPosition(i) > Math.max(getPosition(getIndex(start))-count, 0)
See Also:
Scrollable.getScrollableBlockIncrement(java.awt.Rectangle, int, int)

getAutoResizeMode

public int getAutoResizeMode()
Returns the resizing mode of the ruler.
Returns:
The resize mode. May be one of those values:

setAutoResizeMode

public void setAutoResizeMode(int mode)
Sets the resizing mode of the ruler.
Parameters:
mode - The resize mode. May be one of those values:
Preconditions:
mode == AUTO_RESIZE_OFF || mode == AUTO_RESIZE_NEXT || mode == AUTO_RESIZE_SUBSEQUENT || mode == AUTO_RESIZE_LAST || mode == AUTO_RESIZE_ALL

getPreferredSize

public int getPreferredSize(int index)
Returns the preferred size of a specific entry.
Parameters:
index - the index of the entry.
Returns:
the preferred size of the entry
Preconditions:
index >= 0 && index < getCount()
Postconditions:
getMinSize(index) <= return && return <= getMaxSize(index);
See Also:
Intervals.getIndex(int)

setPreferredSize

public int setPreferredSize(int index,
                            int size)
Sets the preferred size of a specific entry which must be constrained between the minimum and maximum sizes. An implementation may choose to ignore this.
Parameters:
index - the index of the entry. Should be non-negative.
size - the preferred size of the entry
Returns:
The size actually set, or -1 if no change was made.
Throws:
java.lang.IllegalArgumentException -  
Preconditions:
index >= 0 && index < getCount()
size > 0
See Also:
Intervals.getIndex(int)

getMinSize

public int getMinSize(int index)
Returns the minimum size of a specific entry.
Parameters:
index - the index of the entry. Should be non-negative.
Returns:
the minimum size of the entry
Preconditions:
index >= 0 && index < getCount()

setMinSize

public int setMinSize(int index,
                      int minSize)
Sets the minimum size of a specific entry but must leave all sizes consistent. An implementation may choose to ignore it.
Parameters:
index - the index of the entry.
minSize - the minimum size of the entry
Returns:
The size actually set, or -1 if no change was made.
Throws:
java.lang.IllegalArgumentException -  
Preconditions:
index >= 0 && index < getCount()
minSize > 0
See Also:
Intervals.getIndex(int)

setUniformMinSize

public void setUniformMinSize(int minSize)
Sets a uniform minimum size for all entries.
Parameters:
minSize - the uniform minimum size
Throws:
java.lang.IllegalArgumentException -  
Preconditions:
minSize > 0

getMaxSize

public int getMaxSize(int index)
Returns the maximum size of a specific entry.
Parameters:
index - the index of the entry.
Returns:
the maximum size of the entry
Preconditions:
index >= 0 && index < getCount()

setMaxSize

public int setMaxSize(int index,
                      int maxSize)
Sets the maximum size of a specific entry but must leave all sizes consistent. An implementation may choose to ignore it.
Parameters:
index - the index of the entry.
maxSize - the maximum size of the entry
Returns:
The size actually set, or -1 if no change was made.
Throws:
java.lang.IllegalArgumentException -  
Preconditions:
index >= 0 && index < getCount()
maxSize > 0
See Also:
Intervals.getIndex(int)

setUniformMaxSize

public void setUniformMaxSize(int maxSize)
Sets a uniform maximum size for all entries.
Parameters:
maxSize - the uniform maximum size
Throws:
java.lang.IllegalArgumentException -  
Preconditions:
maxSize > 0

isResizable

public boolean isResizable(int index)
Returns the resizable attribute for a specific item.
Parameters:
index - the index of the item
Returns:
whether the user will be allowed to resize this item, subject to the overall resizing strategy and the minimum and maximum size constraints
Preconditions:
index >= 0 && index < getCount()

setResizable

public void setResizable(int index,
                         boolean flag)
Allows to interactively change the resizable attribute for a specific item.
Parameters:
index - the index of the item
flag - whether the user will be allowed to resize this item, subject to the overall resizing strategy and the minimum and maximum size constraints
Preconditions:
index >= 0 && index < getCount()

getMargin

public int getMargin()
Returns the global margin value
Returns:
the number of empty pixels between any two items This will be subtracted from the item sizes, so it should be nonnegative, but smaller than the least of the minimum sizes

setMargin

public void setMargin(int m)
Sets the global margin value
Parameters:
m - the number of empty pixels between any two items This will be subtracted from the item sizes, so it should be nonnegative, but smaller than the least of the minimum sizes

getTotalSize

public int getTotalSize()
Returns the total size of the items in the most optimized way
Returns:
the total size of the items
Postconditions:
return == getPosition(getCount())

getTotalMinSize

public int getTotalMinSize()
Returns the total minimum size of the items in the most optimized way
Returns:
the total minimum size of the items
Postconditions:
return > 0

getTotalPreferredSize

public int getTotalPreferredSize()
Returns the total preferred size of the items in the most optimized way
Returns:
the total preferred size of the items
Postconditions:
return > 0

getTotalMaxSize

public int getTotalMaxSize()
Returns the total maximum size of the items in the most optimized way
Returns:
the total maximum size of the items
Postconditions:
return > 0

setActiveRange

public void setActiveRange(int start,
                           int count)
For an implementation about the area of interest, where subsequent queries should be answered very efficiently

Invoke this method each time the bounds of the component change.

Parameters:
start - the start of the range where we want subsequent queries
count - the length of the range where we want subsequent queries

isVisible

public boolean isVisible(int index)
Returns true if the item with the given index is visible. Useful in hiding a column/row in a grid or table.
Parameters:
index - the index where we want to know the visible property
Returns:
true if the index is visible
Preconditions:
index >= 0 && index < getCount()

setVisible

public void setVisible(int index,
                       boolean flag)
Set the visible property of an item. This will send a "visibility change event", not a "size change event".
Parameters:
index - the index where we want to set the visible property
flag - the visible property for the index
Preconditions:
index >= 0 && index < getCount()

sizeToFit

public void sizeToFit(int totalSize)
Handles global resizing
Parameters:
totalSize - The size we want to fit into
See Also:
RulerSizeManager.sizeToFit(int), Container.doLayout()

getFirstDraggingItem

public int getFirstDraggingItem()
Returns the first of a continuous range of items that should be considered "dragged" out of its normal position.
Returns:
the index of the first dragged item, -1 if none.
Postconditions:
return == -1 || return >= 0 && return < getCount()

getLastDraggingItem

public int getLastDraggingItem()
Returns the last of a continuous range of items that should be considered "dragged" out of its normal position.
Returns:
the index of the first dragged item, -1 if none.
Preconditions:
getFirstDraggingItem() >= 0
Postconditions:
return >= getFirstDraggingItem && return < getCount()

getDraggingDistance

public int getDraggingDistance()
Returns the distance that the "dragged" items are from their normal position.
Returns:
the number of size units (presumably pixels) between the actual position of the dragged items and their normal position such as given by getPosition

setFirstDraggingItem

public void setFirstDraggingItem(int index)
Sets the first of a continuous range of items that have been "dragged" out of its normal position.
Parameters:
index - the index of the first dragged item
Preconditions:
index >= 0 && index < getCount()
Postconditions:
getFirstDraggingItem() == index && getLastDraggingItem() == index

setLastDraggingItem

public void setLastDraggingItem(int index)
Sets the last of a continuous range of items that have been "dragged" out of its normal position.
Parameters:
index - the index of the last dragged item
Preconditions:
getFirstDraggingItem() >= 0
index >= getFirstDraggingItem() && index < getCount()
Postconditions:
getLastDraggingItem() == index

setDraggingDistance

public void setDraggingDistance(int d)
Sets the distance the "dragged" items are from their normal position.
Parameters:
d - the number of size units (presumably pixels) between the actual position of the dragged items and their normal position as given by getPosition
Preconditions:
getFirstDraggingItem() >= 0

resetDragging

public void resetDragging()
Resets all dragging parameters.
Postconditions:
getFirstDraggingItem() == -1

insertEntries

public void insertEntries(int start,
                          int count,
                          int value,
                          boolean visible)
Adds a continuous group of entries to this Intervals.
Parameters:
start - the index to be assigned to the first entry in the group
count - the number of entries in the group
value - the size to be assigned to each new entry
visible - whether the new entries are initially visible
Preconditions:
start >= 0
count > 0
Postconditions:
getCount() == getCount()@pre + count

insertEntries

public void insertEntries(int start,
                          int count,
                          int value)
Adds a continuous group of entries to this Intervals. This method is a part of the Intervals interface. It should be equivalent to:
  insertEntries(start,count,value,true);


Specified by: 
insertEntries in interface Intervals
Parameters:
start - the index to be assigned to the first entry
                       in the group
count - the number of entries in the group
value - the size to be assigned to each new entry
Preconditions:
start >= 0
count > 0
Postconditions:
getCount() == getCount()@pre + count
forall i in [start, start+count[ | !isVisible(i)

addRulerModelListener

public void addRulerModelListener(RulerModelListener l)
Adds a listener to the list that's notified each time a change to the data model occurs.
Parameters:
l - the RulerModelListener
See Also:
RulerModelEvent, RulerModelListener

removeRulerModelListener

public void removeRulerModelListener(RulerModelListener l)
Removes a listener from the list that's notified each time a change to the data model occurs. This is part of the RulerModelEventSource contract, and should respect an obvious relation with the addXXX function.
Parameters:
l - the RulerModelListener
See Also:
RulerModelEvent, RulerModelListener

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Necessary to allow public access to the clone method.
Specified by:
clone in interface Intervals
Overrides:
clone in class java.lang.Object
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD