org.havi.ui.HListGroupLook Maven / Gradle / Ivy
package org.havi.ui;
import java.awt.Image;
import java.awt.Point;
import java.awt.Dimension;
import java.awt.Graphics;
/*
* Copyright 2000-2003 by HAVi, Inc. Java is a trademark of Sun
* Microsystems, Inc. All rights reserved.
*/
/**
The {@link org.havi.ui.HListGroupLook HListGroupLook} class is used by the {@link
org.havi.ui.HListGroup HListGroup} component to display both the
{@link org.havi.ui.HListGroup HListGroup} itself (potentially
including a scrollbar component) and graphical or textual list
content held on the {@link org.havi.ui.HListGroup HListGroup}. This
look will be provided by the platform and the exact way in which it
is rendered will be platform dependent.
The {@link org.havi.ui.HListGroupLook HListGroupLook} class draws the HListGroup
and any look-specific borders around the component, and then
renders the content set on the {@link org.havi.ui.HListGroup
HListGroup}. It uses the {@link
org.havi.ui.HListGroup#getListContent getListContent} method to
determine the content to render. The content of the HListGroup does
not depend on the interaction state.
{@link org.havi.ui.HListGroupLook HListGroupLook} should use the
following properties of {@link org.havi.ui.HListGroup HListGroup}
to lay out and render the {@link org.havi.ui.HListElement
HListElement} content:
Item Method Purpose Orientation {@link
org.havi.ui.HListGroup#getOrientation
getOrientation} direction to lay out elements Content {@link
org.havi.ui.HListGroup#getListContent
getListContent} elements to display Scroll position {@link
org.havi.ui.HListGroup#getScrollPosition
getScrollPosition} first element to draw Selection {@link
org.havi.ui.HListGroup#isItemSelected isItemSelected} mark
an element as selected Current item {@link
org.havi.ui.HListGroup#getCurrentItem
getCurrentItem} highlight an element
{@link org.havi.ui.HListGroupLook HListGroupLook}
should draw a scrollbar as necessary when there are more {@link
org.havi.ui.HListElement HListElements} than can be displayed. It
is an implementation option to leave border space between each
element. The insets used for the element borders can be retrieved
using {@link org.havi.ui.HListGroupLook#getElementInsets
getElementInsets}
Implementations of {@link org.havi.ui.HListGroupLook HListGroupLook}
should use the appropriate methods on {@link org.havi.ui.HListGroup
HListGroup} to determine which scaling and alignment modes to use
when rendering content. See the class description for {@link
org.havi.ui.HLook HLook} for more details.
{@link org.havi.ui.HListGroupLook HListGroupLook} may support scalable graphical
content. As a minimum, all implementations must support the {@link
org.havi.ui.HVisible#RESIZE_NONE RESIZE_NONE} scaling mode for
graphical content, and all alignment modes for text content.
However, Note that {@link org.havi.ui.HListGroupLook HListGroupLook} behaves
slightly differently from other HAVi {@link org.havi.ui.HLook
HLook} classes, as follows.
- Where supported, scaling applies to the icon (graphical
content) of each {@link org.havi.ui.HListElement HListElement},
based on the area allocated to that {@link org.havi.ui.HListElement
HListElement} rather than the entire area of the {@link
org.havi.ui.HListGroup HListGroup}.
- Alignment mode applies to the content of the {@link
org.havi.ui.HListElement HListElement} within the area allocated to
that {@link org.havi.ui.HListElement HListElement} rather than the
entire area of the {@link org.havi.ui.HListGroup HListGroup}.
Note that the results of applying the {@link
org.havi.ui.HVisible#VALIGN_JUSTIFY VALIGN_JUSTIFY} and {@link
org.havi.ui.HVisible#HALIGN_JUSTIFY HALIGN_JUSTIFY} alignment modes
to graphical content are defined to identical to {@link
org.havi.ui.HVisible#VALIGN_CENTER VALIGN_CENTER} and {@link
org.havi.ui.HVisible#HALIGN_CENTER HALIGN_CENTER} modes
respectively, as justification is meaningless in this context.
This is the default look that is used by {@link
org.havi.ui.HListGroup HListGroup}.
The parameters to the constructors are as follows, in cases where
parameters are not used, then the constructor should use the default
values.
Default parameter values exposed in the constructors
Parameter Description Default value
Set method Get method None.
Default parameter values not exposed in the constructors
Description Default value Set method
Get method
Element insets
null
{@link org.havi.ui.HListGroupLook#getElementInsets
getElementInsets}
---
@see org.havi.ui.HListGroup
@see org.havi.ui.HListElement
@see org.havi.ui.HVisible
@see org.havi.ui.HLook
@see org.havi.ui.HDefaultTextLayoutManager
*/
public class HListGroupLook
implements HExtendedLook, HAdjustableLook
{
/**
* Creates a {@link org.havi.ui.HListGroupLook HListGroupLook} object. See the
* class description for details of constructor parameters and
* default values.
*/
public HListGroupLook()
{
}
/**
* The {@link org.havi.ui.HExtendedLook#showLook showLook} method is
* the entry point for repainting the entire {@link
* org.havi.ui.HVisible} component. This method delegates the
* responsibility of drawing the component background, borders and any
* HVisible related data or content to the
* fillBackground,
* renderVisible and renderBorders methods
* respectively, subject to the clipping rectangle of the Graphics object
* passed to it. This method shall call the methods
* fillBackground,
* renderVisible, and renderBorders in that order
* and shall not do any rendering itself.
*
* The {@link org.havi.ui.HExtendedLook#showLook showLook} method should
* not modify the clipRect (clipping rectangle) of the
* Graphics object that is passed to it in a way
* which includes any area not part of that original clipRect. If any
* modifications are made, the original clipRect shall be restored.
*
* Any resources explicitly associated with an {@link
* org.havi.ui.HExtendedLook} should be loaded by the {@link
* org.havi.ui.HExtendedLook} during its creation, etc.
* Note that the "standard" looks don't load content by default.
*
* This method is called from the {@link
* org.havi.ui.HVisible#paint} method of {@link
* org.havi.ui.HVisible} and must never be called from
* elsewhere. Components wishing to redraw themselves should call
* their repaint method in the usual way.
*
* @param g the graphics context.
* @param visible the visible.
* @param state the state parameter indicates the state of the
* visible, allowing the look to render the appropriate content
* for that state. Note that some components (e.g. HStaticRange,
* HRange, HRangeValue) do not use state-based content.
*/
public void showLook(java.awt.Graphics g, HVisible visible, int state)
{
return;
}
/**
* The {@link org.havi.ui.HExtendedLook#fillBackground} method
* paints the component with its current background Color
* according to the {@link org.havi.ui.HVisible#setBackgroundMode}
* method of {@link org.havi.ui.HVisible}.
*
* This method is only called from showLook within this
* HExtendedLook implementation. It's not the intention to call
* this method directly from outside of the HExtendedLook.
*
* Regardless of the background mode, it is an implementation option for
* this method to render added decorations which may affect the look's
* transparency. This method shall not be used to render any HVisible related
* data or content associated with the HVisible. It is purely for background
* and decoration only.
*
* The fillBackground method should not modify the clipRect
* (clipping rectangle) of the Graphics object that is passed
* to it in a way which includes any area not part of that original
* clipRect. If any modifications are made, the original clipRect shall be
* restored.
*
* @param g the graphics context.
* @param visible the visible.
* @param state the state parameter indicates the state of the visible
* @see HLook#isOpaque
* @since MHP 1.0.3/1.1.1
*/
public void fillBackground(java.awt.Graphics g, HVisible visible, int state)
{
return;
}
/**
* The {@link org.havi.ui.HExtendedLook#renderBorders} method
* paints any implementation specific borders according to
* the {@link org.havi.ui.HVisible#setBordersEnabled} method of
* {@link org.havi.ui.HVisible}. If borders are drawn, the border
* decoration shall be rendered within the border area as returned by
* getInsets. The behavior of this method, when a subclass
* overrides the method getInsets is undefined, except
* that it will never draw outside the border area as returned by
* getInsets.
*
* This method is only called from showLook within this
* HExtendedLook implementation. It's not the intention to call
* this method directly from outside of the HExtendedLook.
*
* The {@link org.havi.ui.HExtendedLook#renderBorders}
* method should not modify the clipRect (clipping rectangle) of the
* Graphics object that is passed to it in a way
* which includes any area not part of that original clipRect. If any
* modifications are made, the original clipRect shall be restored.
*
* @param g the graphics context.
* @param visible the visible.
* @param state the state parameter indicates the state of the visible
* @since MHP 1.0.3/1.1.1
*/
public void renderBorders(java.awt.Graphics g, HVisible visible, int state)
{
return;
}
/**
* The {@link org.havi.ui.HExtendedLook#renderVisible} method
* paints any content or other data associated with the look's HVisible. This
* method shall not be used to render a background nor any other decoration.
* Its purpose is purely to render content or other value data stored on
* the HVisible.
* This may be set via HVisible methods such as setTextContent
* and setGraphicContent. Rendering shall take place within the
* bounds returned by the getInsets method.
*
* This method is only called from showLook within this
* HExtendedLook implementation. It's not the intention to call
* this method directly from outside of the HExtendedLook.
*
* For looks which draw content (e.g. {@link org.havi.ui.HTextLook}, {@link
* org.havi.ui.HGraphicLook} and {@link org.havi.ui.HAnimateLook}),
* if no content is associated with the component, this method does nothing.
*
* The {@link org.havi.ui.HExtendedLook#renderVisible}
* method should not modify the clipRect (clipping rectangle) of the
* Graphics object that is passed to it in a way
* which includes any area not part of that original clipRect. If any
* modifications are made, the original clipRect shall be restored.
*
* The labels of the associated HListElements shall
* be rendered by using the current text layout manager of the
* HListGroup. For each visible label is the
* render() method of HTextLayoutManager
* called. The position and size per label are specified as insets
* relatively to the bounds of HListGroup. Note that
* the bounds are independent of any borders of the
* HListGroup, but the insets have to include the
* borders per element, if any. The look shall use the method
* getLabelSize() of HListGroup to
* determine the size for each label. If the returned dimension
* object has DEFAULT_LABEL_WIDTH for the width and/or
* DEFAULT_LABEL_HEIGHT for the height as values, then
* this method shall use implementation specific value(s) as default(s)
* for the missing dimension(s) instead. If
* getTextLayoutManager() returns null,
* then labels shall not be rendered.
*
* If supported, scaling of icons shall reflect the resize mode of the
* visible within the area of the respective list element. The look
* shall use the method getIconSize() of
* HListGroup to determine the size for each icon. If
* the returned dimension object has DEFAULT_ICON_WIDTH
* for the width and/or DEFAULT_ICON_HEIGHT for the
* height as values, then this method shall use implementation specific
* value(s) as default(s) for the missing dimension(s) instead.
*
* Except for the alignment of labels and sizes of labels and icons, it
* is explicitly not defined, how this look arranges icons and labels
* within the elements' areas. Additionally, it is an implementation
* option to render labels and icons in other sizes than specified, if
* the available size per element is smaller or larger than label and
* icon size. It is also not defined, how the look presents the current
* item and selected items, or the current selection mode. The
* elements shall be layed out as specified by
* getOrientation() of the associated HListGroup.
*
* When the associated HListGroup contains more elements than
* presentable, the look shall make the user aware of that condition,
* e.g. by displaying an additional scrollbar reflecting the current
* scroll position. Again, the visible means by which this information
* is conveyed is not defined and implementation dependent. It is an
* implementation option for HListGroupLook to draw
* elements before the scroll position, in order to fill the
* available space.
*
* The behavior of this method, when a subclass overrides the methods
* getInsets() or getElementInsets(), is
* not defined. Application developers shall not assume that the
* corresponding borders will appear as specified.
*
* The {@link org.havi.ui.HExtendedLook#renderVisible} method is
* responsible for painting any implementation specific borders for
* each HListElement as well as drawing of an additional scrollbar
* if required.
*
* @param g the graphics context.
* @param visible the visible.
* @param state the state parameter indicates the state of the visible
* @since MHP 1.0.3/1.1.1
*/
public void renderVisible(java.awt.Graphics g, HVisible visible, int state)
{
return;
}
/**
* Called by the {@link org.havi.ui.HVisible HVisible} whenever
* its content, state, or any other data changes. See the class
* description of {@link org.havi.ui.HVisible HVisible} for more
* information about the changes parameter.
*
* The implementation of this method should work out which
* graphical areas of the {@link org.havi.ui.HVisible HVisible}
* have changed and make any relevant calls to trigger the
* repainting of those areas.
*
* A minimum implementation of this method could simply call
*
* visible.repaint()
*
*
* @param visible the {@link org.havi.ui.HVisible HVisible} which
* has changed
* @param changes an array containing hint data and associated hint
* objects. If this argument is null a full repaint
* will be triggered.
*/
public void widgetChanged (HVisible visible, HChangeData[] changes)
{
return;
}
/**
* Returns the size to present one element of the specified
* HVisible plus any additional dimensions that the
* HListGroupLook requires for border decoration etc.
*
* The extra space required for border decoration can be determined
* from the getInsets() and
* getElementInsets() methods. The behavior is
* not defined for the case, when a subclass overrides these methods.
* Application developers shall not assume any influence on the
* returned dimensions.
*
* The size per element shall be determined by calls to
* getIconSize() and getLabelSize() of
* HListGroup. If any of the dimensions requests a
* default as specified by DEFAULT_ICON_WIDTH,
* DEFAULT_ICON_HEIGHT, DEFAULT_LABEL_WIDTH and
* DEFAULT_LABEL_HEIGHT, then an implementation specific
* default is used for the corresponding value(s).
*
* @param visible HVisible to which this
* HLook is attached.
* @return A dimension object indicating this HLook's
* minimum size.
* @see HListGroup#setIconSize
* @see HListGroup#setLabelSize
* @see HVisible#getMinimumSize
*/
public Dimension getMinimumSize(HVisible visible)
{
return(null);
}
/**
* Gets the preferred size of the HVisible component
* when drawn with this HListGroupLook.
*
* If a default size for width and height was set with
* HVisible.setDefaultSize(), then the dimensions are
* rounded down to the nearest element (minimum of one) according
* to the orientation of the associated HListGroup, and
* any dimensions for border decorations etc. are added.
*
* If no default size was set or only for one dimension (i.e. height is
* NO_DEFAULT_HEIGHT or width is
* NO_DEFAULT_WIDTH), then the unset dimension(s) shall
* be sufficiently large to present five elements according to the
* HListGroup's orientation. Any dimensions for border
* decoration etc. are added.
*
* The extra space required for border decoration can be determined
* from the getInsets() and
* getElementInsets() methods. The behavior is not
* defined for the case, when a subclass overrides these methods.
* Application developers shall not assume any influence on the
* returned dimensions.
*
* The size per element shall be determined by calls to
* getIconSize() and getLabelSize() of
* HListGroup. If any of the values requests a
* default as specified by DEFAULT_ICON_WIDTH,
* DEFAULT_ICON_HEIGHT,
* DEFAULT_LABEL_WIDTH and
* DEFAULT_LABEL_HEIGHT, then an implementation
* specific default is used for the corresponding value(s).
*
* @param visible HVisible to which this
* HLook is attached.
* @return A dimension object indicating the preferred size of the
* HVisible when drawn with this
* HListGroupLook.
* @see HListGroup#setIconSize
* @see HListGroup#setLabelSize
* @see HVisible#getPreferredSize
* @see HVisible#setDefaultSize
*/
public Dimension getPreferredSize(HVisible visible)
{
return(null);
}
/**
* Returns the size to present all elements of the specified
* HVisible plus any additional dimensions that the
* HListGroupLook requires for border decoration
* etc. If no elements are present, a dimension object is returned
* with width and height set to java.lang.Short.MAX_VALUE.
*
* The extra space required for border decoration can be determined
* from the getInsets() and
* getElementInsets() methods. The behavior is not
* defined for the case, when a subclass overrides these methods.
* Application developers shall not assume any influence on the
* returned dimensions.
*
* The size per element shall be determined by calls to
* getIconSize() and getLabelSize() of
* HListGroup. If any of the values
* requests a default as specified by DEFAULT_ICON_WIDTH,
* DEFAULT_ICON_HEIGHT,
* DEFAULT_LABEL_WIDTH and
* DEFAULT_LABEL_HEIGHT,
* then an implementation specific default is used for the
* corresponding value(s).
*
* @param visible HVisible to which this
* HLook is attached.
* @return A dimension object indicating this
* HListGroupLook's maximum size.
* @see HListGroup#setIconSize
* @see HListGroup#setLabelSize
* @see HVisible#getMaximumSize
*/
public Dimension getMaximumSize(HVisible visible)
{
return(null);
}
/**
* Returns true if the entire painted area of the {@link
* org.havi.ui.HVisible HVisible} when using this look is fully opaque,
* i.e. the {@link org.havi.ui.HLook#showLook showLook} method
* guarantees that all pixels are painted in an opaque Color.
*
* The default value is implementation specific and depends on the
* background painting mode of the given {@link
* org.havi.ui.HVisible HVisible}. The consequences of an invalid
* overridden value are implementation specific.
*
* @param visible the visible to test
* @return true if all the pixels with the
* java.awt.Component#getBounds method of an {@link
* org.havi.ui.HVisible HVisible} using this look are fully
* opaque, i.e. the {@link org.havi.ui.HLook#showLook showLook}
* method guarantees that all pixels are painted in an opaque
* Color, otherwise false.
*/
public boolean isOpaque(HVisible visible)
{
return(false);
}
/**
* Determines the insets of this {@link org.havi.ui.HLook HLook},
* which indicate the size of the border. This area is
* reserved for the {@link org.havi.ui.HLook HLook} to use for
* drawing borders around the associated {@link
* org.havi.ui.HVisible HVisible}.
*
* @param hvisible {@link org.havi.ui.HVisible HVisible} to which
* this {@link org.havi.ui.HLook HLook} is attached.
* @return the insets of this {@link org.havi.ui.HLook HLook}.
*/
public java.awt.Insets getInsets(HVisible hvisible)
{
return(null);
}
/**
* Returns a value which indicates the pointer click position in the
* on-screen representation of the orientable component.
* The behavior of this method in {@link org.havi.ui.HListGroupLook
* HListGroupLook} differs from the behavior of {@link
* org.havi.ui.HAdjustableLook#hitTest HAdjustableLook.hitTest()} in
* that if the position belongs to an {@link org.havi.ui.HListElement
* HListElement} of the associated {@link org.havi.ui.HListGroup
* HListGroup}, then this method will return the index of that
* element. The HListGroup shall interpret this index
* as current item. If the value is ADJUST_THUMB, then
* the caller shall use getValue() to retrieve the
* actual scroll position corresponding to the specified pointer
* position. The look will not change the appearance of that element
* (eg. by highlighting it). Such a change may only occur due to a
* call to {@link #widgetChanged}.
* Note that it is a valid implementation option to always return
* {@link org.havi.ui.HAdjustableLook#ADJUST_NONE ADJUST_NONE}.
* @param component - the HOrientable component for which the hit
* position should be calculated
* @param pt - the pointer click point relative to the upper-left corner
* of the specified component.
* @return one of {@link org.havi.ui.HAdjustableLook#ADJUST_NONE
* ADJUST_NONE}, {@link
* org.havi.ui.HAdjustableLook#ADJUST_BUTTON_LESS
* ADJUST_BUTTON_LESS}, {@link
* org.havi.ui.HAdjustableLook#ADJUST_PAGE_LESS ADJUST_PAGE_LESS},
* {@link org.havi.ui.HAdjustableLook#ADJUST_THUMB ADJUST_THUMB},
* {@link org.havi.ui.HAdjustableLook#ADJUST_PAGE_MORE
* ADJUST_PAGE_MORE} or {@link
* org.havi.ui.HAdjustableLook#ADJUST_BUTTON_MORE
* ADJUST_BUTTON_MORE}, or a non-negative element index.
*/
public int hitTest(HOrientable component, java.awt.Point pt)
{
return(0);
}
/**
* Returns the value of the component which corresponds to the pointer
* position specified by pt. If the position does not map to a value
* (eg. the mouse is outside the active area of the component), this
* method returns null. A non-null value
* represents the scroll position of the associated
* HListGroup. The value shall never be less than
* zero.
*
* The look shall not reflect the value returned by this method visibly.
* If the component uses the returned value, it will inform the look
* by calling {@link #widgetChanged widgetChanged()}.
* @param component an {@link org.havi.ui.HOrientable HOrientable}
* implemented by an {@link org.havi.ui.HVisible HVisible}
* @param pt the position of the mouse-cursor relative to the
* upper-left corner of the associated component
* @return the non-negative scroll position associated with the specified
* pointer position or null
* @see #hitTest
*/
public java.lang.Integer getValue(HOrientable component, java.awt.Point pt)
{
return(null);
}
/**
* Retrieve the element insets for this instance of {@link
* org.havi.ui.HListGroupLook HListGroupLook}. The element insets control the
* amount of empty space left between the elements and the border
* of the HListGroup component.
*
* @return the element insets, or null if insets are
* not used by this implementation of {@link org.havi.ui.HListGroupLook
* HListGroupLook}.
*/
public java.awt.Insets getElementInsets()
{
return (null);
}
/**
* Retrieve the number of visible elements for the specified
* component.
*
* This method should determine the number of list elements that
* would be completely visible should the specified component be
* drawn using this look.
*
* @param visible the {@link org.havi.ui.HVisible HVisible} to
* obtain the number of visible elements for.
* @return the number of visible elements.
*/
public int getNumVisible(HVisible visible)
{
return (0);
}
}