danger.ui
Class FolderView

java.lang.Object
  danger.app.Listener
      danger.ui.View
          danger.ui.Container
              danger.ui.FolderView

All Implemented Interfaces:

ToolTipOwner

Direct Known Subclasses:

MultiFolderView

public class FolderView
extends Container
implements ToolTipOwner

This class is a UI object that manages and draws a one-deep list of folders and their contents.

Folders can be referenced by their numerical index or name (case-insensitive). As such, there can be only one folder with a given name.

This handles all expected HI. The arrow keys and the wheel can be used to navigate up and down through the list. The return key and the wheel button can be used to open and close folders.

If you want customized drawing to take place you will need to subclass and override drawFolderLine(danger.ui.Pen, java.lang.Object, danger.ui.Rect, boolean) and drawItemLine(danger.ui.Pen, java.lang.Object, danger.ui.Rect, boolean).

If you want this object to actually do something when a folder item is selected and the wheel button or return key is hit then you will need to subclass and override eventKeyDown(char, danger.app.Event) and eventWidgetDown(int, danger.app.Event).

If you want to have something happen when the selection switches between a folder and one of its items (for instance, changing the contents of the action menu), then again, you'll need to override eventWidgetUp(int, danger.app.Event) and eventWidgetDown(int, danger.app.Event).

NOTE: You will note that several of the methods in here are public even though it seems like they shouldn't be. This is so that classes in other packages which subclass from FolderView can override these methods. XXX--why aren't these declared protected?

Field Summary

static int	COLUMN_GAP Deprecated. For internal use only.
int	mAscent Deprecated. For internal use only.
protected int	mCurrentFolder Deprecated. For internal use only.
protected int	mCurrentItem Deprecated. Use getSelection() instead.
protected Vector	mFolders Deprecated. Use setFolders(java.util.Vector) and addFolder(danger.util.Folder) instead.
Font	mFontBold Deprecated. For internal use only.
Font	mFontPlain Deprecated. For internal use only.
protected boolean	mHasBorder Deprecated. Use setHasBorder(boolean) and getHasBorder() instead.
protected int	mLineHeight Deprecated. For internal use only.
protected int	mNumDisplayLines Deprecated. For internal use only.

Fields inherited from class danger.ui.View

DEFAULT_SCROLL_FOCUS_MARGIN, FOCUS_DEFAULT, FOCUS_DOWNWARD, FOCUS_LEFTWARD, FOCUS_NONE, FOCUS_RIGHTWARD, FOCUS_UPWARD, mOriginX, mOriginY, mStyle, POSITION_ABOVE, POSITION_ALIGN_BASELINE, POSITION_ALIGN_BOTTOM, POSITION_ALIGN_HORIZONTALLY, POSITION_ALIGN_LEFT, POSITION_ALIGN_PARENT_BOTTOM, POSITION_ALIGN_PARENT_RIGHT, POSITION_ALIGN_RIGHT, POSITION_ALIGN_TOP, POSITION_ALIGN_VERTICALLY, POSITION_BELOW, POSITION_CENTER_HORIZONTALLY, POSITION_CENTER_VERTICALLY, POSITION_TO_LEFT, POSITION_TO_RIGHT, PREFER_DIRECTION_NONE, PREFER_HORIZONTAL_DIRECTION, PREFER_VERTICAL_DIRECTION, STATE_AT_AND_SPACE_PAGE, STATE_CAN_FOCUS, STATE_DEBUG_BOUNDS, STATE_ENABLED, STATE_FOCUSED, STATE_MAKE_DING, STATE_PARTIAL_FOCUS_OK, STATE_TRANSPARENT, STATE_VISIBLE, WIDTH_FILL_TO_RIGHT

Constructor Summary

FolderView()

FolderView(int inLeft, int inTop, int inRight, int inBottom)

FolderView(Rect inSize)

Method Summary

Folder	addFolder(Folder inFolder) Add a folder.
protected void	adjustActionMenuState()
void	adjustSelection()
protected boolean	advanceHilite(int delta)
Folder	createFolder(String inFolderName)
void	drawBackground(Pen p, Rect r)
void	drawBackground(Pen p, Rect r, boolean more_above, boolean more_below)
protected void	drawEmptyList(Pen p)
protected void	drawFolderLine(Pen p, Object inEntry, Rect r, boolean inSelected)
protected void	drawFolderLine(Pen p, Object inEntry, Rect r, boolean inSelected, Object above, Object below)
protected void	drawItemLine(Pen p, Object inEntry, Rect r, boolean inSelected)
protected void	drawItemLine(Pen p, Object inEntry, Rect r, boolean inSelected, Object above, Object below)
boolean	eventKeyDown(char inChar, Event event) This method is called when the user presses a key.
boolean	eventKeyRepeat(char inChar, Event event) This method is called when the user holds a key long enough for it to repeat.
boolean	eventKeyUp(char inChar, Event event) Standard UI method to handle the RETURN and DEL keys.
boolean	eventShortcut(char c, Event e) Handle a shortcut key.
boolean	eventWidgetDown(int inWhichWidget, Event event) Handle the pressing of a device widget
boolean	eventWidgetUp(int inWhichWidget, Event event) Handle the release of a device widget
int	folderCount()
int	getContentWidth()
int	getCurrentFolderIndex()
int	getCurrentItemIndex()
protected int	getEntryNumOfItem(int inFolderNum, int inItemNum)
Folder	getFolder(int inFolderNum)
Folder	getFolder(String inFolderName)
int	getFolderIndex(Folder inFolder)
int	getFolderIndex(String inFolderName)
Vector	getFolders()
boolean	getHasBorder()
boolean	getHasScrollbar()
CharSequence	getItemTitle(Object item) Get the title of the given item.
Object	getSelection()
CharSequence	getToolTip(int inFolderIndex, int inItemIndex)
protected int	getVisibleItemCount()
protected void	invalidateEntry(int inFolderNum, int inItemNum)
void	loseFocus() This method is called when this view loses its previous status as the focused child of a container.
protected int	matchFolderItemPrefix(String inPrefix, int currItem)
void	onSelectionChanged()
void	paint(Pen p) Draw the contents of this View.
protected void	recalcMetrics()
protected void	recordSelection()
void	removeAll()
void	removeAllFolderItems(String inFolderName)
Folder	removeFolder(int inFolderNum)
Folder	removeFolder(String inFolderName)
Object	removeFolderItem(int inFolder, int inItem)
Object	removeFolderItem(String inFolderName, int inItem)
Object	removeFolderItem(String inFolderName, Object inItem)
void	renameFolder(String inOldName, String inNewName)
protected void	restoreSelection()
protected boolean	reverseHilite(int delta)
protected void	selectItem(Object inItem)
void	setFolders(Vector folders) Use the specified Vector of Folder objects.
void	setHasBorder(boolean inHasBorder)
void	setHasScrollbar(boolean inHasScrollbar)
void	setMaxToolTipLines(int maxLines) Set the maximum number of lines to show in a tool tip.
void	setSelection(int inFolderNum, int inItemNum)
void	setSize(int inWidth, int inHeight) Simultaneously set the width and height of this View.
void	showToolTip() This method should be implemented to actually display the tool tip, probably via a call to ToolTipWindow.showToolTip(danger.ui.MenuItem, int, int, int, danger.ui.Window).
void	sortAllFolderItems(Comparator inComparator)
void	sortFolders(Comparator inComparator)
void	takeFocus(boolean inFromAbove) Focus this container.
protected void	toggleFolder(Folder inFolder)

Methods inherited from class danger.ui.Container

addChild, addChild, addChildAt, addChildAt, addFromContainerResource, addFromContainerResource, addFromContainerResource, addFromDialogResource, addFromDialogResource, advanceFocus, advanceFocusInWindow, childCount, childIsOnScreen, disable, enable, eventKeyHeld, eventPeriodicPulse, eventRawKeyDown, eventRawKeyHeld, eventRawKeyRepeat, eventRawKeyUp, eventWidgetHeld, focusedDescendantIsValid, getBottomChild, getBottomChild, getChildAt, getChildIndex, getChildWithID, getControlWithID, getDescendantWithID, getFirstChild, getFirstFocusableChild, getFocusableChildInWindow, getFocusedChild, getFocusedLeaf, getInterestingRect, getLastChild, getLastFocusableChild, getLeftMostChild, getNextFocusableChild, getNextFocusableChild, getPageHeight, getPrevFocusableChild, getPrevFocusableChild, getRightMostChild, getRightMostChild, handleButtonShortcut, hideAllChildren, isDescendant, keepRectInView, moveChildToIndex, onChildPositionChanged, onChildSizeChanged, onChildVisibilityChanged, pageToEnd, pageToHome, paintChildren, receiveEvent, reflowChildren, removeAllChildren, removeChild, reverseFocus, setFocusedChild, setFocusedChild, setFocusedChild, setFocusedDescendant, setFocusedDescendant, setFocusedDescendant, setFocusToFirstDescendant, setFormatDateForControlWithID, setFormatDateForTextControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setFormatTextForTextControlWithID, setListenerForAllControls, setReflowAdjustHeight, setWindow, showAllChildren, snapHeightToChildren, snapHeightToChildren, snapToChildren, snapWidthToChildren, snapWidthToChildren, willFocusWithin, willFocusWithin

Methods inherited from class danger.ui.View

boundsIntersect, boundsIntersect, canLoseFocus, clear, clear, copyStyle, getAcceptFocus, getBackgroundColor, getBottom, getBounds, getBounds, getFocusTraversalDirection, getFocusTraversalFrom, getFocusTraversalPolicy, getFrame, getFrame, getGlobalBottom, getGlobalLeft, getGlobalRight, getGlobalTop, getHeight, getID, getInterestingRect, getLabelFont, getLabelFont, getLeft, getOrigin, getOrigin, getOriginX, getOriginY, getParent, getParentContainer, getPartialFocusOK, getRight, getScrollFocusMargin, getSibling, getState, getStyle, getStyleColor, getStyleFont, getTop, getWidth, getWindow, globalToLocal, globalToLocalH, globalToLocalV, hide, invalidate, invalidate, invalidate, invalidateIndependentOfOrigin, invalidateIndependentOfOrigin, isEnabled, isFocusable, isFocused, isOnScreen, isTransparent, isVisible, isVisibleInHierarchy, isVisibleOnScreen, justSetVisible, localToGlobal, localToGlobal, localToGlobalH, localToGlobalV, localToWindow, moveBy, notifyWhenParentSizeChanges, notifyWhenPositionChanges, notifyWhenSizeChanges, offsetOrigin, offsetOrigin, onAddedToParent, onDecoded, onEnabledStateChanged, onHide, onPeriodicPulse, onPositionChanged, onRemovedFromParent, onShortcut, onShortcut, onShortcutConsumed, onShow, onSizeChanged, onStyleChanged, onViewPositionChanged, onViewSizeChanged, onWindowPaint, playLimitSound, receiveEventInternal, resetOrigin, sendEventToWindow, setAcceptFocus, setAtAndSpacePage, setBackground, setBackgroundColor, setBottom, setDebugBounds, setDynamicPosition, setDynamicWidth, setEnabled, setFocusTraversalDirection, setFocusTraversalFrom, setFocusTraversalPolicy, setFrame, setHeight, setKeyedValue, setLabelFont, setLeft, setMakeLimitNoise, setOrigin, setOrigin, setPartialFocusOK, setPosition, setPreferredDirection, setRight, setScrollFocusMargin, setStyle, setStyleColor, setStyleFont, setStyleFrameColor, setTop, setTransparent, setVisible, setWidth, shouldDropEvent, show, showContextMenu, styleIsDefault, swapStyleColors, windowToLocal

Methods inherited from class danger.app.Listener

cancelEvents, childEventPump, childEventPumpDone, eventProblem, isDispatchingThread, sendEvent, sendEvent, sendEvent, sendEvent, sendEvent, sendLowPriorityEvent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mFolders

protected Vector mFolders

Deprecated. Use setFolders(java.util.Vector) and addFolder(danger.util.Folder) instead.

mLineHeight

protected int mLineHeight

Deprecated. For internal use only.

mNumDisplayLines

protected int mNumDisplayLines

Deprecated. For internal use only.

mHasBorder

protected boolean mHasBorder

Deprecated. Use setHasBorder(boolean) and getHasBorder() instead.

mFontPlain

public Font mFontPlain

Deprecated. For internal use only.

mFontBold

public Font mFontBold

Deprecated. For internal use only.

mAscent

public int mAscent

Deprecated. For internal use only.

mCurrentFolder

protected int mCurrentFolder

Deprecated. For internal use only.

mCurrentItem

protected int mCurrentItem

Deprecated. Use getSelection() instead.

COLUMN_GAP

public static final int COLUMN_GAP

Deprecated. For internal use only.

See Also:

Constant Field Values

Constructor Detail

FolderView

public FolderView()

FolderView

public FolderView(Rect inSize)

FolderView

public FolderView(int inLeft,
                  int inTop,
                  int inRight,
                  int inBottom)

Method Detail

createFolder

public Folder createFolder(String inFolderName)

addFolder

public Folder addFolder(Folder inFolder)

Add a folder.

This checks to see if you are adding a duplicate folder (one with the same name). If so, this method does nothing. This check has the downside of degrading performance. If you are adding many folders at once, you may want to use the more efficient setFolders(java.util.Vector) method instead.

removeAll

public void removeAll()

removeFolder

public Folder removeFolder(String inFolderName)

removeFolder

public Folder removeFolder(int inFolderNum)

removeFolderItem

public Object removeFolderItem(int inFolder,
                               int inItem)

removeFolderItem

public Object removeFolderItem(String inFolderName,
                               Object inItem)

removeFolderItem

public Object removeFolderItem(String inFolderName,
                               int inItem)

removeAllFolderItems

public void removeAllFolderItems(String inFolderName)

sortFolders

public void sortFolders(Comparator inComparator)

sortAllFolderItems

public void sortAllFolderItems(Comparator inComparator)

folderCount

public int folderCount()

getFolder

public Folder getFolder(String inFolderName)

getFolder

public Folder getFolder(int inFolderNum)

getFolderIndex

public int getFolderIndex(Folder inFolder)

getFolderIndex

public int getFolderIndex(String inFolderName)

setFolders

public void setFolders(Vector folders)

Use the specified Vector of Folder objects.

This is more efficient than making many calls to addFolder(danger.util.Folder), since {#link #addFolder} checks to see if you are adding a duplicate folder.

Since:

3.0

getFolders

public Vector getFolders()

getSelection

public Object getSelection()

setSize

public void setSize(int inWidth,
                    int inHeight)

Description copied from class: View

Simultaneously set the width and height of this View.

Overrides:

setSize in class View

recalcMetrics

protected void recalcMetrics()

setHasScrollbar

public void setHasScrollbar(boolean inHasScrollbar)

getHasScrollbar

public boolean getHasScrollbar()

getContentWidth

public int getContentWidth()

paint

public void paint(Pen p)

Description copied from class: View

Draw the contents of this View. This method is called by the graphics system when the View needs to be repainted. A Pen will be provided which is appropriately clipped and translated for drawing on this View.

The implementation of this method in this class will merely call clear() pen, if this View is opaque (not transparent), and will do nothing otherwise. If you don't need this behavior, then there is no point in calling super.paint() in an overriding method.

Overrides:

paint in class Container

Parameters:

p - non-null; the pen to use for drawing operations

drawFolderLine

protected void drawFolderLine(Pen p,
                              Object inEntry,
                              Rect r,
                              boolean inSelected)

drawFolderLine

protected void drawFolderLine(Pen p,
                              Object inEntry,
                              Rect r,
                              boolean inSelected,
                              Object above,
                              Object below)

drawItemLine

protected void drawItemLine(Pen p,
                            Object inEntry,
                            Rect r,
                            boolean inSelected)

drawItemLine

protected void drawItemLine(Pen p,
                            Object inEntry,
                            Rect r,
                            boolean inSelected,
                            Object above,
                            Object below)

drawEmptyList

protected void drawEmptyList(Pen p)

getItemTitle

public CharSequence getItemTitle(Object item)

Get the title of the given item. The result is used in the default implementations of drawItemLine(danger.ui.Pen, java.lang.Object, danger.ui.Rect, boolean) and matchFolderItemPrefix(java.lang.String, int). This default implementation returns the result of calling toString on the object. Override this method if necessary to provide information used for prefix matching in open folders.

Parameters:

item - the item to get the title of

Returns:

the item title, or "null" if the item is null

toggleFolder

protected void toggleFolder(Folder inFolder)

selectItem

protected void selectItem(Object inItem)

eventWidgetDown

public boolean eventWidgetDown(int inWhichWidget,
                               Event event)

Description copied from class: Container

Handle the pressing of a device widget

Overrides:

eventWidgetDown in class Container

Parameters:

inWhichWidget - the widget that went up

Returns:

whether or not the event was consumed

eventWidgetUp

public boolean eventWidgetUp(int inWhichWidget,
                             Event event)

Description copied from class: Container

Handle the release of a device widget

Overrides:

eventWidgetUp in class Container

Parameters:

inWhichWidget - the widget that went down

Returns:

whether or not the event was consumed

eventShortcut

public boolean eventShortcut(char c,
                             Event e)

Description copied from class: View

Handle a shortcut key. Returns true if the shortcut was handled. Override this method if you want to handle this event yourself. event is currently always null. However, in a future release the actual event will be included so you can determine which modifier keys were held. The default View.eventShortcut handles the MENU+WHEEL shortcut for context menus. See ScreenWindow, DialogWindow, BaseMenuWindow.

Overrides:

eventShortcut in class Container

Parameters:

c - the key that was pressed

e - the event associated with the key press

Returns:

true if the shortcut was handled

eventKeyRepeat

public boolean eventKeyRepeat(char inChar,
                              Event event)

Description copied from class: View

This method is called when the user holds a key long enough for it to repeat. The default implementation turns space and @ into page-down and page-up events if you have View.setAtAndSpacePage(boolean).

Overrides:

eventKeyRepeat in class Container

eventKeyDown

public boolean eventKeyDown(char inChar,
                            Event event)

Description copied from class: View

This method is called when the user presses a key. The default implementation turns space and @ into page-down and page-up events if you have View.setAtAndSpacePage(boolean).

Overrides:

eventKeyDown in class Container

eventKeyUp

public boolean eventKeyUp(char inChar,
                          Event event)

Standard UI method to handle the RETURN and DEL keys. Please be aware that this method has a default handler for the DEL key that calls removeFolderItem(int, int) on the currently-selected item, which in practice no application really seems to want. If you do not want the user to remove items from the folder directly, you *must* override this method to catch DEL keyreleases.

Overrides:

eventKeyUp in class Container

Parameters:

inChar - the character being released.

matchFolderItemPrefix

protected int matchFolderItemPrefix(String inPrefix,
                                    int currItem)

advanceHilite

protected boolean advanceHilite(int delta)

reverseHilite

protected boolean reverseHilite(int delta)

onSelectionChanged

public void onSelectionChanged()

setSelection

public void setSelection(int inFolderNum,
                         int inItemNum)

takeFocus

public void takeFocus(boolean inFromAbove)

Description copied from class: Container

Focus this container. Returns the focus to whatever the focused child was. If there was no focused child, then if the focus is coming from above the focus is set to the first focusable child; otherwise, it is set to the last focusable child.

Overrides:

takeFocus in class Container

Parameters:

inFromAbove - whether the focus was entered into this view from above

loseFocus

public void loseFocus()

Description copied from class: View

This method is called when this view loses its previous status as the focused child of a container.

You generally wouldn't call this method yourself, but instead would override it if you wanted to know when the view is losing focus.

If you don't want this view to have focus anymore, you should use Container.setFocusedChild(View) or Container.setFocusedDescendant(View).

Overrides:

loseFocus in class Container

invalidateEntry

protected void invalidateEntry(int inFolderNum,
                               int inItemNum)

adjustSelection

public void adjustSelection()

getEntryNumOfItem

protected int getEntryNumOfItem(int inFolderNum,
                                int inItemNum)

adjustActionMenuState

protected void adjustActionMenuState()

drawBackground

public void drawBackground(Pen p,
                           Rect r)

drawBackground

public void drawBackground(Pen p,
                           Rect r,
                           boolean more_above,
                           boolean more_below)

setHasBorder

public void setHasBorder(boolean inHasBorder)

getHasBorder

public boolean getHasBorder()

getCurrentFolderIndex

public int getCurrentFolderIndex()

getCurrentItemIndex

public int getCurrentItemIndex()

renameFolder

public void renameFolder(String inOldName,
                         String inNewName)

recordSelection

protected final void recordSelection()

restoreSelection

protected final void restoreSelection()

getVisibleItemCount

protected final int getVisibleItemCount()

showToolTip

public void showToolTip()

Description copied from interface: ToolTipOwner

This method should be implemented to actually display the tool tip, probably via a call to ToolTipWindow.showToolTip(danger.ui.MenuItem, int, int, int, danger.ui.Window).

Specified by:

showToolTip in interface ToolTipOwner

setMaxToolTipLines

public void setMaxToolTipLines(int maxLines)

Set the maximum number of lines to show in a tool tip. A value of 0 means there is no maximum.

getToolTip

public CharSequence getToolTip(int inFolderIndex,
                               int inItemIndex)