John W. Campbell
DocExtractor Icon
JWC
The program 'DocExtractor' is used to prepare documentation files from
a special pre-xhtml format devised for use with this program or by extracting
documentation sections from Java code source files. When used with Java
source code files, the source code documentation must follow a
particular convention; this is compatible with the requirements for
Java's own 'javadoc' documentation tool. All documents produced have
a similar overall layout. The output files will normally be in XHTML
format, though there is an option for plain text format output files.
The program enables this process to be taken further to create
a whole set of linked documents. In this case the program will also
automatically generate a contents list of sections, subsections and
figures and, when XHTML output is requested, this will contain links
to the various sections, sub-sections and figures. In addition, back
links to the higher level documents in the set will be output
automatically at the end of each document.
An option exists to enable additional information, defined in a footer file, to
be output at the end of each document if required.
List of sections:
General Layout of a Document
Running the Program
Pre-xhtml Documents
Documentation in Java Source Code
The general layout of a document is as follows:
CHAPTER 1 Title
1.1 Introduction
1.2 Section
1.2.1 Introduction
1.2.2 Sub-section
1.2.3 Sub-section
...
1.3 Section
1.3.1 Introduction
1.3.2 Sub-section
1.3.3 Sub-section
...
etc.
The chapter (or overall section) number is supplied when the program is run
and may be omitted if the document stands on its own. For documentation from
Java source code, the sections are typically something like the
following:
CHAPTER 1 Title
Author
1.1 Introduction
1.2 Class Details
1.3 Accessible Fields
1.4 Constructors
1.5 Section
1.5.1 Method
1.5.2 Method
...
1.6 Section
1.6.1 Method
1.6.2 Method
...
etc.
This section describes how the program is run and the program options
available. The options may either be given in the command line or, if
no such options are given, a question and answer sequence is started
in command window from which the program is started.
There are three basic options for document processing:-
- Process a single document (pre-xhtml file or Java source code.
file)
- Process a document set with linked documents (top level document
is a pre-xhtml file).
- Process (re-process) a single document in the context of a
document set to which it belongs.
List of subsections in this section:
Program Command Line
Program Option Switches
Interactive Option
If the program is run using the command line options, then there are
three choices available depending on the nature of the documents to be
processed as noted above.
- Single (standalone) pre-xthml or Java source code file:
java DocExtractor [-root rootdir] [-out outdir]
[-link lfile]
[-chapname chnam] [-secnum secn/no]
[-footer footfil] [-text] [-num] [-list] filename
- Document set (top level file is a pre-xthml file):
java DocExtractor -set [-root rootdir] [-out outdir]
[-link lfile]
[-chapname chnam] [-secnum secn/no]
[-nocontents] [-footer footfil] [-text] [-num] [-list]
filename
- Single document as part of a document set:
java DocExtractor -sel setname [-root rootdir]
[-out outdir] [-link lfile]
[-chapname chnam] [-secnum secn/no]
[-footer footfil] [-text] [-num] [-list] filename
Note: The above examples assume that the Java class path has been set
so that it includes the paths of the DocExtractor.class file and the
Jdl class libraries. If this is not the case then the java command must
be followed immediately by the -classpath option giving the required
additions to the current Java class path.
The command option switches and other items are as follows:
- -set
- The input file is the top level pre-xhtml file for a linked document
set. All the files of the set will be processed.
- -sel setname
- The input file is a single file (pre-xhtml or Java source file) which is
to be processed (or re-processed) within the context of a document set
to which it is linked. setname is the name of the top-level pre-xhtml
file for the document set. To provide the correct context, the
-outdir, -chapname, -secnum and -footer options given should be the same
as those used when the document set is processed as a whole.
- -root rootdir
- This is the root directory for the input files. All the files to be
processed must be in this directory or, for files specified by links
in a document set, relative to it as specified by the relative
paths in the <.doclink> tagged data. If omitted, the current directory
is assumed.
- -out outdir
- This is the top level directory for the output .xhtml or .txt
files. This is the directory for a single document or the top level document
for a document set. If omitted, the current directory is assumed.
The file names will remain the same as those of the input files except
for the file extension. Note that for linked files, the output files for
the individual documents will be in the same directories relative to 'outdir'
as the input files were relative to 'rootdir'.
- -link lfile
- This enables the specification of a links file to resolve external links
within the document when a link name is given rather than explicit
file reference. The file name is given relative to the root directory
as input above. If this is omitted and any such links are present in the
file, such links will be listed when DocExtractor is run; similarly, if
the file is given, but a link is not resolved, then the unresolved link
will be listed.
- -text
- If this option is specified, then the output file will be a plain
text file. If it is not given, then an XHTML file will be
output.
- -chapname chnam
- This specifies a chapter or equivalent name if required. If this is
present, then the document title will be prefixed by this word. If
given, then the following -secnum option should also be given. Thus
if, for example the title is 'Text Processing Programs' and chnam
is 'Appendix' and secn is '2', then the document title line
will be 'Appendix 2 - Text Processing Programs'.
- -secnum secn
- This enables a section number (or string) to be defined for the
document and the document sections will then be numbered based on the
given value of secn. Thus, for example, if secn is 'A2.1',
the document will be numbered as section A2 and sections/subsections
within the document will be labelled as A2.1.1, A2.1.1.1, A2.1.1.2 ..., A2.1.2
etc.
- -num
- For a single document when secn is not given, the
sections will be un-numbered unless this option is specified in
which case the sections/sub-sections will be numbered as 1, 1.1, 1.2
..., 2, 2.1, 2.2 etc. For document sets, sections are always numbered
either using the default numbering scheme or secn if this
was given.
- -nocontents
- Normally for a document set, a table of contents is generated
with links (if XHTML output) to all the sections and sub-sections (and
figures defined via <.figure> tagged items). This follows the
text of the top level document. If no such contents are required, then
the -nocontents option may be specified. The option does not apply to
single documents.
- -footer footfil
- If required this option enables the contents of a file
(containing XHTML coded data) to be appended (within the document
body) to the document or each individual document within a set of
documents. The file path for this file must be given relative to
rootdir.
- -list
- This enables additional output to pinpoint the context of a
document processing problem. If the switch is present then
document file names will be listed as they are read and, if an error
was encountered processing the document source, a context string
is printed from the document source from about 20 characters before to 40
characters after the point at which the problem was encountered.
- filename
- The name of the single document file or, for a document set, the
top level document file. The file path for this file must be given relative to
rootdir.
This option enables the input of the required options via a series of
questions and answers instead of command line options as described
above. The question and answer sequence will be entered if no command
line options are specified. The exact details vary slightly depending
on the replies to the earlier questions. In this section, references
are made to the descriptions of the equivalent command line
options given above.
- Document set (y/n) [y]:
- A reply of 'y' (the default reply) indicates that a document set
is to be processed. A reply of 'n' indicates that a single document (or
a single document selected from a document set) is to be processed.
- Select from a document set (y/n) [n]:
- This question is omitted if a document set is being processed
(reply of 'y' to the first question). The reply is 'y' if a single
document from a document set is to be processed (re-processed) or 'n'
(the default) if a single standalone document is to be processed.
- Name of input root directory:
- The reply is the name of the root directory for the input
files. The default (blank) reply indicates that the root directory
is the current directory. (See also -root option above).
- Name of input set 'pxh' file:
- This question is asked if a document set or a selected file from
a document set is to be processed. The reply is the name of the top
level document file ('pre-xhtml file) for the document set.
- Name of selected 'pxh' or 'java' file:
- This question is only asked when processing a selected file from
a document set. The reply is the name of the selected document file
relative to the specified root directory.
- Name of input 'pxh' or 'java' file:
- This question is only asked when processing a single standalone
document. The reply is the name of the document file
relative to the specified root directory.
- Name of output directory:
- The reply is the name of the top level directory for the processed output
files. The default (blank) reply indicates that the output top level directory
is the current directory. (See also -out option above).
- Name of link file if required:
- The name of a file (relative to the root directory) containing the data
to resolve external links specified in the document by link names. If this
is omitted and any such links are present in the file, such links will
be listed when DocExtractor is run; similarly, if the file is given, but
a link is not resolved, then the unresolved link will be listed.
- Output type XHTML or TXT (x/t) [x]:
- The default (blank) reply or a reply of 'x' indicates that the output
file(s) are to be in XHTML format. A reply of 't' indicates that the
output file(s) are to be in plain text format.
- Chapter name if required:
- The reply is a 'Chapter' or equivalent name if required (See -chapname
option above for details).
- Section number if required:
- Section number:
- This question has one of the two forms shown, the latter being output
if a chapter name was specified above indicating that a section number
ought to be given in this case. The reply is a section number/string for
the top level of the document (set) (See -secnum option above for
details).
- Number sections (y/n) [y]:
- This question is only asked if a single standalone document is being
processed and no section number string was given. The default (blank)
reply or a reply of 'y' indicates that the sections are to be numbered
from 1 upwards (See -num option above). A reply of 'n' indicates that
the sections of the document are to remain un-numbered.
- Print contents (y/n) [y]:
- This question is only asked if a document set is being processed. A
default (blank) reply or a reply of 'y' indicates that a contents
table is to be generated. A reply of 'n' indicates that such a
contents table is not required. (See also -nocontents option above).
- Footer filename if required:
- The reply is the name of a footer file (if required) to enable some
additional XHTML code to be included at the end of the single
document or all documents of a document set. (See also -footer option
above).
- List context (y/n) [n]:
- This enables additional output to pinpoint the context of a
document processing problem. If the reply is 'yes' then
document file names will be listed as they are read and, if an error
was encountered processing the document source, a context string
is printed from the document source from about 20 characters before to 40
characters after the point at which the problem was encountered.
The pre-xhtml file used as input to the 'DocExtractor' program
has a set of 'xml' type structural tags enabling a simple, if somewhat
restricted, layout for the document but with the bonus that the
program will automatically generate lists, in appropriate places, of
the sections/sub-sections present and, when used with the normal
XHTML output option will automatically generate a set of links to
these sections/sub-sections. It also enables the output of documents
compatible in format with those extracted from Java source code files.
The pre-xhtml format enables figure handing to be defined for both XHTML
and plain-text output cases.
When required, the sections of text may contain a subset of the
allowable XHTML tags. These comprise the Core modules including the
Text, Hypertext and List modules. The only restriction on their use is that the
Structure and Heading tags should not be used as those required are
generated by the program. The Presentation module and Image module
tags may also be given.
A few additional tags are defined for use in the document. These are
for the output of single lines, new pages, inclusion of additional
links and inclusion of figures.
List of subsections in this section:
Layout of a Pre-xhtml Document
Markers in a Pre-xhtml Document
Handling of Figures
Links
Document Sets
Special Characters
The document is layed out using the following items tagged as shown with
items enclosed in ellipses indicating user supplied material which may
contain various XHTML tags and other items as indicated above and
described in more detail in the following section:
<.title> ...title-string... </.title>
<.author>
...text...
</.author>
<.intro>
...text...
</.intro>
<.sect ...section-header...>
...text...
</.sect>
<.subsect ...subsection-header...>
...text...
</.subsect>
<.subsect>
...text...
</.subsect>
...
<.sect>
...text...
</.sect>
...
etc.
The items are as follows:
- Title
- This item must be present. It defines a title string which will appear
at the top of the document. In XHTML it is used as both the title and
level 1 header.
- Author
- This item is optional. It is a section of text giving details
of the document author(s). The section will be output after the title
and before the introduction section.
- Introduction
- This item must be present. It is a section of text giving a general
description of the subject matter of the document. The program will
automatically append a list of the sections present in the document to
this item and these will have links to the relevant sections when the output
file is in XHTML format.
- Section
- One or more sections must be described. The section item consists of
two parts, a short section header string within the tag and a body of
text. The section header string is used both as a section
header in the output file (usually appended to a section number) and
in the list of sections automatically generated at the end of the
Introduction section. It will also be used in the contents section when
present. If there are no sub-sections for this section, then the text body
will just be the text for the section. When the section has
sub-sections, the text body is used to provide an introductory
sub-section for the section in question and the program will automatically
append a list of the sub-sections present in the section to which this
item belongs. These will have links to the relevant sub-sections when the
output file is in XHTML format.
- Sub-section
- Zero or more sub-sections for the section. The sub-section
item consists of two parts, a short sub-section header string within the
tag and a body of text. The sub-section header string is used both as a
sub-section header in the output file (usually appended to a sub-section
number) and in the list of subsections automatically generated at the end of
the introductory sub-section for the current section. It will also be used
in the contents list if requested. Note that the sub-sections need not
nested within the <.sect> </.sect>tags though they may be.
The pre-xhtml file used as input to the 'DocExtractor' program allows for
the inclusion of a subset of XHTML tags with a few additional special
tags designed for use in pre-xhtml files. The pre-xhtml special
tag names start with a dot e.g. <.title>. All tags are treated in
a case insensitive manner though lower case is recommended as all
valid XHTML tags are lower case. All XHTML tags will, of course,
be output by the program in lower case.
- Tags defining the basic items/section of the document:
- <.title>
- This is followed by the title string for the document.
- </.title>
- Terminates the title string.
- <.author>
- The author section (if present) follows this tag.
- </.author>
- Terminates the author section.
- <.intro>
- The introduction text body follows this tag.
- </.intro>
- Terminates the introduction.
- <.sect ...section-header...>
- A section text body or description follows this tag.
- </.sect>
- Terminates the section description.
- <.subsect ...subsection-header...>
- A sub-section text body follows this tag.
- </.subsect>
- Terminates the sub-section text body.
- Standard XHTML tags allowed within a text body:
- A text body is the text within the author item, the introduction item,
a section item or a sub-section item. No tags are processed outside such
items.
- Block module tags
- <p> <pre> <blockquote> <div> <address>
- Inline module tags
- <br/> <em> <strong> <q> <kbd>
<samp> <span> <var> <abbr> <acronym>
<cite> <code> <dfn> <samp> <span>
<var>
Note that <br/> must be given as an empty tag.
- List module tags
- <ol> <ul> <dl> <dt> <dd>
<li>
- Hypertext module tags
- <a>
- Image module tags
- <img>
- Presentation module tags
- <b> <i> <hr/><big> <small>
<tt> <sub> <sup>
Note that <hr/> must be given as an empty tag.
- Special 'DocExtractor' tags
- A number of additional tags specific to the program 'DocExtractor' may
also be used within the text body. These are the following:
- <.al>
- This is equivalent for XHTML output to <.ol> for an ordered list
and items are introduced in the same manner using the <li> tag. For
plain text output, the items list will be tagged with letters rather than
numbers.
- <.singles>
- This tag is used to enclose a section of text for which each line in
the input file is to be output to a single line. For XHTML output, the
normal font is used for each line and each line will be terminated by a
<br/> tag. For plain text output, it will be equivalent to a
pre-formatted section.
- <.xhtml> or <.html>
- This tag is used to enclose a section which is in XHTML
format. This section will be included without modification in a XHTML
output file (and can include any valid XHTML tags) but will be ignored
for a plain text output file.
- <.ascii>
- This tag is used to enclose a section which is to be output
without modification for a plain text output file but will be ignored
for an XHTML output file.
- <.newpage/>
- This tag is used to indicate a page break for a plain text output
file. It will be ignored for an XHTML output file.
- <.figure>
- This tag is used to enclose a special section which gives details
for a figure to be included in the document. Details are given in
a separate section below.
- <.link>
- This tag allows additional links to be introduced into the
document. Details are given in a separate section below.
- <.doclink>
- This tag allows additional documents to be linked together to
form a document set for which a single set of contents (with links
to each individual document, section and subsection) may be generated
if required. Details are given in a separate section below.
Documention in plain text format has no direct provision for
the inclusion of figures and one of the advantages of XHTML is the
possibility of including figures directly or via links. The special figures
section, enclosed with the tags:
<.figure ...figure_name... > and </.figure>
enables the definition of figures in a pre-xhtml document. Two formats of
line are recognised within the section; these describe how a figure is to be
handled for each of the possible output file types. Normally both should be
given.
For XHTML the format of the line is as follows:
XHTML: ...image_file_name... code
The name of the required image file is given followed by a code wich is
either INTERNAL or EXTERNAL (the latter assumed by default). If INTERNAL
is given, then the image will be included in-line when an XHTML output
document is prepared. When EXTERNAL, a link to the figure will be included
instead. A figure string includes the word 'Figure', a figure number
(appended to the chapter/section no. string if defined in the program
command line) and the figure name from within the <.figure> tag.
There will be an anchor point to this Figure number string. When the figure
is external, the figure name string will be highlighted as the hypertext link.
For plain text output, the format of the line is as follows:
TEXT: ...image_file_name... number/code
The name of a file containing the figure is followed either by an integer
giving the number of blank lines to be left in the document for the figure
to be added later or the code END indicating that the figure is to be added
at the end of the document. In both cases a figure string will be written
(made up as in the XHTML case.). If the END code option is used, then
a line of the form '(at end of chapter)' is also output (the word chapter
will be replaced by a lower case version of any chapname string
passed to the program). For figures at the end of the document,
new pages will be added and these will be annotated with the figure strings.
All figures are numbered in the sequence they are defined in the document.
A list of figures is extracted for the contents figures section if this is
generated.
The <.link "url" ...text... /> tag allows additional links to be
introduced into the document. The quotes around the URL are optional.
The user supplied text is used as the reference for the link. For plain
text output, only the reference text is output. For XHTML output,
an entry of the form <a href = "url">...text...</a> is
created. Alternatively, if any external links required may vary because, for
example, the document is to be used in different situations, the URL
entry may be replaced by a link name starting with a ? character (this
must not be surrounded by quotes) e.g.
<.link ?DDM Data Diffraction Module/>
When the DocExtractor program is run, a links file may be specified;
this has a list of pairs of items consisting of the link name and the
URL with which it is to be replaced to form the link in the output file e.g.
?DDM docs/ddm_main.html
?CCP4 http://www.ccp4.ac.uk/index.html
In the links file the ? characters may be omitted. The link names are
case insensitive.
As well as processing single documents with sections and subsections,
it is possible to create document sets with links to other documents which
may be other pre-xhtml or marked up Java source code files. The
documents are linked using the <doclink> </.doclink> tags.
The link may be specified at the end of a section or a sub-section
just prior to the </.sect> or </.subsect> tag. The standard
format of the document link is as follows:
<doclink> ...file_name... </.doclink>
where 'file_name' is the name of a marked up Java source code file (file
extension .java) or a pre-xhtml document (any other file extension e.g.
.pxh). All filenames must be relative to the directory where the top
level document of the set is held. Normally the link should be made
from a section without sub-sections or from a sub-section.
In these cases, a link to the requested document
(of the form Document Link: ...title...) will be shown following
the text for the section or sub-section containing the link.
Only one link is allowed in each main section or in each sub-section.
All the sections of any linked documents will be listed in the contents
section for the document set. The numbering scheme may be illustrated by the
following two examples:
- Link from a section: For a section 'Coordinate Axes' (numbered '2')
with no sub-sections but with a link to a document entitled
'Coordinate Systems' with two sections headed 'Detector axes'
(sub-sections 'Laboratory Axes' and 'Setting parameters') and 'Image Axes'
(sub-sections 'Flat Detector axes', 'Cylindrical Detector Axes' and
'Distortion Corrections'). Let the next section of the main document be
headed 'Synchrotron Parameters'.
2 Coordinate Axes
Document Link: 2 Coordinate Systems
2.1 Introduction
2.2 Detector Axes
2.2.1 Introduction
2.2.2 Laboratory Axes
2.2.3 Setting Parameters
2.3 Image Axes
2.3.1 Introduction
2.3.2 Flat Detector Axes
2.3.3 Cylindrical Detector
2.3.4 Distortion Corrections
3 Synchrotron Parameters
- Link from a sub-section: For a section 'Diffraction Parameters'
(numbered '4.1') with sub-sections 'Detector Parameters' and
'Crystal Parameters' and with a link from the first of these sub-sections
to a document entitled 'Coordinate Systems' with two sections headed
'Detector axes' (sub-sections 'Laboratory Axes' and 'Setting parameters')
and 'Image Axes' (sub-sections 'Flat Detector axes', 'Cylindrical Detector
Axes' and 'Distortion Corrections'). Let the next section of the main document
be headed 'Predicting Images'.
4.1 Diffraction Parameters
4.1.1 Introduction
4.1.2 Detector Parameters
Document Link: 4.1.2
Coordinate Systems
4.1.2.1 Introduction
4.1.2.2 Detector Axes
4.1.2.2.1 Introduction
4.1.2.2.2 Laboratory Axes
4.1.2.2.3 Setting Parameters
4.1.2.3 Image Axes
4.1.2.3.1 Introduction
4.1.2.3.2 Flat Detector Axes
4.1.2.3.3 Cylindrical Detector
4.1.2.3.4 Distortion Corrections
4.1.3 Crystal Parameters
4.2 Predicting Images
It is permissable to include a link in a section which has got
sub-sections. In this case, the link will be included at the end of
the automatically generated 'Introduction' sub-section. It is also
permissable to include a link in any of the sub-sections.
A document link with optional additional items may also be given. This
has the following form:
<doclink> ...file_name... [secnum] [chap_name] </.doclink>
The 'secnum' entry is a starting section number for the linked document
which will override the automatically generated document numbering scheme.
In addition, the 'chap_name' entry, if present, will be used with the
'secnum' entry to give a heading for the linked document of the form:
chap_name secnum ...document title... . In the contents section of the
top level document, the sections and sub-section numbering of the linked
document will also be that based on the requested 'secnum'.
For a linked document with figures, a Figure List for that document
will be included in the contents section of the top-level document at
the end of the sections/sub-sections listed for that document.
Some special characters in XHTML have to be represented by escape sequences.
This practice is followed in a pre-xhtml file with a limited number of such
characters/escape-sequences being allowed. (Note that, in contrast, the
characters are used directly when input is from program source code
documentation and not their corresponding escape sequences). In pre-xhtml,
the following escape sequences are recognised:
< <
> >
& & (need not use escape sequence in pre-xhtml)
" " (need not use escape sequence in pre-xhtml)
' ' (need not use escape sequence in pre-xhtml)
Non-breaking space
The program 'DocExtractor' may be used to extract documentation from Java
code source files. As there is an official Java documentation tool available,
'javadoc', the required markup has been made compatible with the
requirements for this tool although only the @author, @param and
@return 'javadoc' tags are recognised by the DocExtractor program and
hence only those 'javadoc' tags should be used. The use of XHTML
tags in the source code documentation should also be restricted to the set
used in pre-xhtml files as listed above.
In the descriptions below, items surrounded by ellipses e.g. ...title...
represent text supplied by the user.
List of subsections in this section:
Documentation Layout in a Java Source Code File
Summary of Java Documentation Item Codes
Example of Documented Java Source Code
The documentation layout in a Java source code file are as follows:
Title (special pre-xhtml code)
Author (special pre-xhtml code)
Section order list (special pre-xhtml code - optional)
Actions (special pre-xhtml tag)
Introduction (special pre-xhtml code followed by 'javadoc' class
definition. If the @author tag is found in that definition, the line
containing it will be ignored. The DocExtractor program uses its own
author tagging to determine the document author)
Public/package fields for the class - 'javadoc' documentation
Section description for constructors (special pre-xhtml code)
Documentation of constructors ('javadoc' documentation of constructors
with @param tags recognised)
Section of methods header (special pre-xhtml code)
Method documentation - 'javadoc' (@param and @return tags recognised)
Method documentation - 'javadoc' (@param and @return tags recognised)
...
Section of methods header (special pre-xhtml code)
Method documentation - 'javadoc' (@param and @return tags recognised)
Method documentation - 'javadoc' (@param and @return tags recognised)
...
etc.
There may be several sections of methods classified to the programmer's
own requirements.
The following gives a summary of the codes which are used to introduce and/or
terminate the special pre-xhtml documentation items. They are
generally analogous to the pre-xhtml tags described above but converted into
a form which is treated as comment text in the Java source code file.
Item-type Java source file
Title /*-Title:
...title...
-end*/
Author /*-Author:
...author...
-end*/
Section order /*-Section_order:
...list-of-section-numbers...
-end*/
Actions /*-Actions:
...description-of-actions...
-end*/
Introduction /*-Intro: ...section-list-header... */
(Followed by 'javadoc' class documentation)
Section description /*-Section: ...section-header...
...section-description...
-end ...list-heading... */
(Followed by 'javadoc' documented methods)
Exclude following /*-Exclude*/
source code
Include following /*-Include*/
source code
The following pre-xhtml documented Java source code extract may help to clarify
the above description.
package Jdl.JdlView;
/*-Title:
Button - JdlButton
-end*/
/*-Author:
John W. Campbell
-end*/
/*-Actions:
An action event will be generated when the button is pressed. The associated
action command string is "button pressed".
-end*/
/*-Intro: Class, fields, constructors and methods: */
/**
This class provides a press button with a three dimensional look.
The button may contain a user supplied string.
@author John W. Campbell
*/
public class JdlButton extends JPanel implements MouseListener
{
/**
Border type option: Solid.
*/
public final static int SOLID = 0;
/**
Border type option: Three dimensional (raised/inset).
*/
public final static int INOUT = 1;
/**
Label alignment: centred.
*/
public final static int CENTER = 0;
/**
Label alignment: left justified.
*/
public final static int LEFT = 1;
/**
Label alignment: right justified.
*/
public final static int RIGHT = 2;
/*-Section: Constructors
Two constructors are available, one for a blank button and one for a button
with an initial label string.
-end Constructors: */
/**
Default constructor
Constructs a blank button with default resources.
*/
public JdlButton()
{
...
}
/**
Constructor 2
Constructs a button with a requested label string.
@param str The label string.
*/
public JdlButton(String str)
{
...
}
/*-Section: Set Label Details
This section has methods to set a new label string and define its
characteristics.
-end Methods: */
/**
Set label string
This method sets the label string resource.
@param str The label string (default = null).
*/
public void setLabelString(String str)
{
...
}
/**
Get label string
This method returns the current label string.
@return Returns the label string.
*/
public String getLabelString()
{
...
}
/**
Set label font
This method sets the label font resource.
@param font The font for a button label.
*/
public void setLabelFont (Font font)
{
...
}
/**
Set label alignment
This method sets the label alignment resource.
@param align A flag indicating the required label alignment: <br/>
= 0, to centre <br/>
= 1, for left justification <br/>
= 2, for right justification <br/>
(May use the variables CENTER, LEFT, RIGHT)
*/
public void setLabelAlignment (int align)
{
...
}
/*-Section: Set Button Borders
This section has methods to set the width and type of border to be
used for the button.
-end Methods: */
/**
Set border width
This method sets the button border width resource.
@param thickness This is the required Button border thickness in pixels.
*/
public void setButtonBorder(int thickness)
{
...
}
/**
Set border type
This method sets the border type resource.
@param type Border type flag: <br/>
= 0, solid <br/>
= 1, in/out (3-dimensional) (the default) <br/>
(May use variables SOLID, INOUT)
*/
public void setBorderType (int type)
{
...
}
/*Exclude*/
...
}