org.tullmann.taglets
Class ListTag

java.lang.Object
  |
  +--org.tullmann.taglets.ListTag

All Implemented Interfaces:

com.sun.tools.doclets.Taglet

Direct Known Subclasses:

Issue, ReviewedBy, ToDo

public abstract class ListTag

extends java.lang.Object

implements com.sun.tools.doclets.Taglet

A generic Taglet implementation that provides "list-like" default behavior for handling multiple instances of the tag which occur in a single block. This class does not actually provide any tags, but instead provides infrastructure for tags. See ToDo and Issue for tags that are built from this tag.

Customization of the tag is through user Preferences. The preferences are all stored in the 'ListTag.class' user node (maps to something like 'org/tullmann/taglets' in the per-user repository). In that node, the preferences are prefixed with the tag-name plus "." (e.g., For an '@todo' tag the prefix is 'todo'). The following suffixes are used to customize how the tag shows up:

Suffix	Meaning	Default
listtype	The type of HTML list (currently just 'ordered' or 'unordered')	Passed to ListTag constructor
header.text	The header text to prefix the list (e.g., 'To Do:')	Passed to ListTag constructor
header.color.fg	Foreground color of the header text, any legal HTML color spec is valid.	- (no color)
header.color.bg	Background color of the header text, any legal HTML color spec is valid.	- (no color)
header.relsize	Relative size of the header text (e.g., +1, -1, etc.)	- (no change)
text.color.fg	Foreground color of the text body, any legal HTML color spec is valid.	- (no color)
text.color.bg	Background color of the text body, any legal HTML color spec is valid.	- (no color)
text.relsize	Relative size of the text body (e.g., +1, -1, etc.)	- (no change)

See PrefHack for a simple mechanism to set these preferences.

To Do:

• Support for supressing a tag (e.g., @todo -> @done).

• Support customization of the list bullets.

• Add comments to the methods customization of the list bullets.

• Add other list types? (e.g., the comma-delimited list?).

• Support plural/singular labels.

Issue(s):

• Just move the whole tag definition into preferences?

Since:

January, 2002

Author:

Patrick Tullmann <taglets@tullmann.org>

Field Summary

static org.tullmann.taglets.ListTag.ListType	ORDERED_LIST
static org.tullmann.taglets.ListTag.ListType	TABLE_LIST
protected org.tullmann.taglets.TagPrefs	tagPrefs
static org.tullmann.taglets.ListTag.ListType	UNORDERED_LIST
static org.tullmann.taglets.ListTag.ListType	VISIBLETABLE_LIST

Constructor Summary

ListTag(java.lang.String tagName, java.lang.String tagHeader, org.tullmann.taglets.ListTag.ListType listType)
Create a new list-behaviour tag.

ListTag(java.lang.String tagName, java.lang.String prefsName, java.lang.String tagHeader, org.tullmann.taglets.ListTag.ListType listType)

Method Summary

protected void	emitCustomFooter(java.lang.StringBuffer sbuf, boolean multi) Override to insert custom text after the list is complete, but before the list closing tags
protected void	emitCustomHeader(java.lang.StringBuffer sbuf, boolean multi) Override to insert custom text after the list start, but before the first bit of tag text
protected void	emitFooter(java.lang.StringBuffer sbuf, boolean multi) Emit footer for HTML version of tag.
protected void	emitHeader(java.lang.StringBuffer sbuf, boolean multi) Emit header for HTML version of tag.
protected void	emitTag(com.sun.javadoc.Tag tag, java.lang.StringBuffer sbuf, boolean multi)
protected void	endingTags(java.lang.StringBuffer sbuf)
protected void	forceColorPrefs(org.tullmann.taglets.TagPrefs tagPrefs, java.lang.String tagPrefix)
protected void	forceCustomDefaultPrefs(org.tullmann.taglets.TagPrefs tagPrefs)
protected void	formatText(java.lang.StringBuffer sbuf, java.lang.String text, java.lang.String propName) Format the given text using the properties under the givne propName into the given StringBuffer.
java.lang.String	getName()
boolean	inConstructor()
boolean	inField()
boolean	inMethod()
boolean	inOverview()
boolean	inPackage()
boolean	inType()
boolean	isInlineTag()
protected void	parseTagText(java.lang.StringBuffer sbuf, java.lang.String text, boolean multi) Generate formatted HTML for the given tag text.
static void	register(java.util.Map tagletMap, org.tullmann.taglets.ListTag lt) Register the given taglet in the given map.
protected void	startingTags()
java.lang.String	toString(com.sun.javadoc.Tag tag)
java.lang.String	toString(com.sun.javadoc.Tag[] tags)

Methods inherited from class java.lang.Object

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

Field Detail

tagPrefs

protected final org.tullmann.taglets.TagPrefs tagPrefs

ORDERED_LIST

public static final org.tullmann.taglets.ListTag.ListType ORDERED_LIST

UNORDERED_LIST

public static final org.tullmann.taglets.ListTag.ListType UNORDERED_LIST

TABLE_LIST

public static final org.tullmann.taglets.ListTag.ListType TABLE_LIST

VISIBLETABLE_LIST

public static final org.tullmann.taglets.ListTag.ListType VISIBLETABLE_LIST

Constructor Detail

ListTag

public ListTag(java.lang.String tagName,
               java.lang.String tagHeader,
               org.tullmann.taglets.ListTag.ListType listType)

Create a new list-behaviour tag. The tagHeader and listType parameters can be overridden in properties.

ListTag

public ListTag(java.lang.String tagName,
               java.lang.String prefsName,
               java.lang.String tagHeader,
               org.tullmann.taglets.ListTag.ListType listType)

Method Detail

forceCustomDefaultPrefs

protected void forceCustomDefaultPrefs(org.tullmann.taglets.TagPrefs tagPrefs)
                                throws java.lang.Exception

java.lang.Exception

forceColorPrefs

protected void forceColorPrefs(org.tullmann.taglets.TagPrefs tagPrefs,
                               java.lang.String tagPrefix)

register

public static void register(java.util.Map tagletMap,
                            org.tullmann.taglets.ListTag lt)

Register the given taglet in the given map. Uses the ListTag.name() to get the name of the tag.

getName

public java.lang.String getName()

Specified by:

getName in interface com.sun.tools.doclets.Taglet

isInlineTag

public boolean isInlineTag()

Specified by:

isInlineTag in interface com.sun.tools.doclets.Taglet

inField

public boolean inField()

Specified by:

inField in interface com.sun.tools.doclets.Taglet

inConstructor

public boolean inConstructor()

Specified by:

inConstructor in interface com.sun.tools.doclets.Taglet

inMethod

public boolean inMethod()

Specified by:

inMethod in interface com.sun.tools.doclets.Taglet

inType

public boolean inType()

Specified by:

inType in interface com.sun.tools.doclets.Taglet

inPackage

public boolean inPackage()

Specified by:

inPackage in interface com.sun.tools.doclets.Taglet

inOverview

public boolean inOverview()

Specified by:

inOverview in interface com.sun.tools.doclets.Taglet

formatText

protected void formatText(java.lang.StringBuffer sbuf,
                          java.lang.String text,
                          java.lang.String propName)

Format the given text using the properties under the givne propName into the given StringBuffer.

parseTagText

protected void parseTagText(java.lang.StringBuffer sbuf,
                            java.lang.String text,
                            boolean multi)

Generate formatted HTML for the given tag text. Put the HTML in the given StringBuffer.

Returns:

the given StringBuffer.

emitCustomHeader

protected void emitCustomHeader(java.lang.StringBuffer sbuf,
                                boolean multi)

Override to insert custom text after the list start, but before the first bit of tag text

emitCustomFooter

protected void emitCustomFooter(java.lang.StringBuffer sbuf,
                                boolean multi)

Override to insert custom text after the list is complete, but before the list closing tags

emitHeader

protected void emitHeader(java.lang.StringBuffer sbuf,
                          boolean multi)

Emit header for HTML version of tag. All generated text is put in the given sbuf. The multi parameter indicates if this header is for more than one element.

emitTag

protected void emitTag(com.sun.javadoc.Tag tag,
                       java.lang.StringBuffer sbuf,
                       boolean multi)

emitFooter

protected void emitFooter(java.lang.StringBuffer sbuf,
                          boolean multi)

Emit footer for HTML version of tag. All generated text is put in the given sbuf. The multi parameter indicates if this header is for more than one element.

startingTags

protected void startingTags()

endingTags

protected void endingTags(java.lang.StringBuffer sbuf)

toString

public java.lang.String toString(com.sun.javadoc.Tag tag)

Specified by:

toString in interface com.sun.tools.doclets.Taglet

toString

public java.lang.String toString(com.sun.javadoc.Tag[] tags)

Specified by:

toString in interface com.sun.tools.doclets.Taglet