=head1	NAME

jlayout - A Java code generator to create GUI elements

=head1	SYNOPSYS

  jlayout <inputfile> [<java-source>]

=head1	DESCRIPTION

The jlayout program reads a GUI description from the input file.
The structure of the input file is explained below.
The output operation is to modify a Java source code file. Regions
of this file -- marked up by special comments -- are replaced by new
code to create the GUI.

=head1	OPTIONS

=over	4

=item	B<-h>

issues a help text.

=item	B<-v>

prints version information.

=back

=head1	RETURN VALUE

The program returns 0 on success, a positive value on exit.

=head1	ERRORS

There are two classes of errors: Syntax errors in the input file
and processing errors while the program is running (i.e. not
enought memory...)

Whenever applicable jlayout includes file name and line number
of the object to which the error is related.

=head1	DIAGNOSTICS

Errors are reported to standard output or standard error output depending
on the dklibs preferences set for logging.

=head1	FILES

=head2	Input file

=head3	General input file structure

The input file consists of a list of sections. Each section describes one
GUI object. All sections -- except the first section -- are started
by a section header. The section header contains the GUI objects
class and variable name in square brackets. The first section is for the
object class defined in the Java source code file, so it does not need
a section header.

The remainder is a list of key/value pairs to set object attributes.
Key and value are separated by ``=''.

In addition to normal lines there are control lines. Control
lines are started by a dot. The can be used to set options for the
jlayout program or to establish default values for some attributes.

=head3	Control lines

=head4	Option lines

=over	4

=item	B<.option use tool tip text as accessible description> = I<boolean>

For objects with no accessible description set we can choose whether or not
to use the tool tip text as accessible description.

=back

=head4	Default lines

=over	4

=item	B<.default fill> = I<fill>

This is the default fill style used when no fill style is attached
to an object. For fill styles see ``fill'' below.

=item	B<.default border> = I<border>

This is the default for the space between objects in a container if not
border attribute is attached to the container. For more information
see ``border'' below.

=item	B<.default anchor> = I<anchor>

This is the default anchor if no anchor attribute is attached to an
object. For details see ``anchor'' below.

=back

=head3	attributes

=over	4

=item	B<enabled> = I<boolean>

enables or disables an object.

=item	B<layout> = I<layout>

chooses a layout manager for the current object. Use one of the
following: ``GridBag'', ``Card'', ``Border'', ``Box.X_AXIS'',
``Box.Y_AXIS'', ``Box.PAGE_AXIS'', ``Box.LINE_AXIS'', ``Flow''
or ``Grid''.

SpringLayout and GroupLayout can not be used.

=item	B<border> = I<border>

specifies the space between objects in a container.

NOTE: This is not the space around the current component but the
space between contents objects in the current object (the current
object is a container).

The I<border> must be a Java-int-expression.

=item	B<use content pane> = I<boolean>

specifies whether to add contents objects directly to the current
object (I<false>) or to the content pane returned by getContentPane()
(I<true>).

=item	B<contents> = I<object and placement>

adds a contents object to the current object (the current object is
a container). Some layout managers require placement information
after the object name. Placement information format depends on the
layout manager used by the current object:

=over	8

=item	GridBag

start column, start row, width, height, anchor and fill.
Anchor and fill information is optional, see below for an explaination.
Start column and row can be specified directly (numeric values) or
relative to the previous object:

=over	12

=item	B<.>

Use the same column/row number as for the previous object.

=item	B<+>I<n>

From the start position of the previous object move
I<n> columns to the right / rows downwards.

=item	B<->I<n>

From the start position of the previous object move
I<n> columns to the left / rows upwards.

=back

=item	Card

A Java-String-expression returning a string which can be used
to activate a card. If the placement information is ommited, jlayout
creates a string from the number of the current object.

=item	Border

One of the anchors: ``PAGE_START'', ``LINE_START'', ``CENTER'',
``LINE_END'' or ``PAGE_END''.

=item	Box..., Flow and Grid

No placement information is necessary. Objects are added to the
container in order of appearance in the input file.

=back

For Box... and Flow one can add the special object B<$glue> to add
horizontal or vertical glue (depending on the direction of the
BoxLayout.

=item	B<fill> = I<fill>

specifies how an object can grow if there is more room available
than needed. Use ``none'', ``horizontal'', ``vertical'' or ``both''
for ``The object is not allowed to grow.'', ``The object is allowed
to grow horizontally.'', ``...vertically.'' or ``... in both directions.''.

=item	B<anchor> = I<anchor>

specifies where to place in object if there is more room available than
used by the object. Use one of the following directions:
``NORTH'', ``NORTHWEST'', ``WEST'', ``SOUTHWEST'', ``SOUTH'',
``SOUTHEAST'', ``EAST'', ``NORTHEAST'' or ``CENTER''.

=item	B<text> = I<text>

specifies the text for all GUI elements showing text
(i.e. labels, buttons...).

=item	B<icon file name> = I<name>

specifies the file name of an icon to show.

=item	B<tool tip text> = I<text>

specifies the tool tip text.

=item	B<accessible description> = I<text>

specifies the text for the accessible description.

=item	B<title> = I<text>

specifies the title for the JFrame, JDialog or JApplet).

=item	B<constructor> = I<arg(s)>

specifies the function arguments passed to the objects constructor.
For some objects jlayout automatically chooses one of the appropriate
attributes as constructor if the constructor attribute is not specified.

=item	B<width> = I<width>

specifies the width of a text field in characters.

=item	B<horizontal alignment> = I<alignment>

specifies the horizontal text alignment, one of:
``leading'', ``left'', ``center'', ``right'' or ``trailing''.

=item	B<vertical alignment> = I<alignment>

specifies the vertical text alignment, on of:
``top'', ``center'' or ``bottom''.

=item	B<size group> = I<identifier>

specifies the name of a size group. Specify the same name here for all
objects which must have the same size.

=item	B<button group> = I<identifier>

specifies the ButtonGroup for radio buttons.

=item	B<component border> = I<border>

specifies how to render the border of a component:

=over	8

=item	empty

Draw an empty border.

=item	etched I<subtype>

Draw an etched border, either ``lowered'' or ``raised''.

=item	bevel I<subtype>

Draw a bevel border, either ``lowered'' or ``raised''.

=item	line

Draw a line.

=item	matte I<matte-type>

Draw either a solid color (``color:I<color>'') or a tile pattern
using an icon (``icon:I<filename>'').

=item	titled I<text>

Draw a border and place a text label.

=back

=item	B<minimum size> = I<w h>

specifies the minimum size (numeric values).

=item	B<preferred size> = I<w h>

specifies the preferred size (numeric values)

=item	B<maximum size> = I<w h>

specifies the maximum size (numeric values).

=item	B<action command> = I<text>

specifies the additional information text for the action event.

=item	B<action listener> = I<listener>

B<item listener> = I<listener>

B<window listener> = I<listener>

B<caret listener> = I<listener>

B<change listener> = I<listener>

B<component listener> = I<listener>

B<container listener> = I<listener>

B<document listener> = I<listener>

B<focus listener> = I<listener>

B<internal frame listener> = I<listener>

B<key listener> = I<listener>

B<list data listener> = I<listener>

B<list selection listener> = I<listener>

B<mouse listener> = I<listener>

B<mouse motion listener> = I<listener>

B<mouse wheel listener> = I<listener>

B<property change listener> = I<listener>

B<table model listener> = I<listener>

B<tree expansion listener> = I<listener>

B<tree model listener> = I<listener>

B<tree selection listener> = I<listener>

B<tree will expand listener> = I<listener>

B<undoable edit listener> = I<listener>

specify event listeners for various event types. Use a variable name
for a variable containg an object which already exists.

This name is used twice, once in jLayoutSetup() and once in
jLayoutCleanup().

=item	B<transfer handler> = I<handler>

specifies the transfer handler.

=item	B<default close operation> = I<operation>

specifies how to hande a window closing event. Use one of
``nothing'', ``hide'', ``dispose'' or ``exit''.

=item	B<contents border> = I<border>

specifies the space between objects in sub-containers of the current container.

=item	B<contents fill> = I<fill>

specifies how to fill objects in sub-containers of the current container.

=item	B<contents anchor> = I<anchor>

specifies the anchor position for objets in sub-containers of the
current container.

=back

=head2	Java source file

The Java source code file must contain special comments to mark the
regions to be replaced by jlayout.

=over	4

=item	Variables

Use
  // jlayout.variables.begin
  ...
  // jlayout.variables.end
to mark the region for variables.

=item	Setup function

Use
  // jlayout.setup.begin
  ...
  // jlayout.setup.end
to mark the region for the jLayoutSetup() function.

=item	Cleanup function

Use
  // jlayout.cleanup.begin
  ...
  // jlayout.cleanup.end
to mark the region for the jLayoutCleanup() function.

=back

=head1	EXAMPLES

=head2	Input file example inputjl

  .default border =	2
  .default fill =	none
  .default anchor =	west
  
  border =			2
  fill =			none
  title =			"jlayout"
  layout =			border
  menu bar =			mb
  default close operation =	dispose
  contents =			pa	center
  
  [JPanel pa]
  component border =	titled	"Panel"
  layout =		gridbag
  contents =		la1	0 0 1 1 west
  contents =		cb1	1 0 1 1 west
  contents =		paBu	0 1 2 1 center
  
  [JLabel la1]
  text =		"Label"
  
  [JCheckBox cb1]
  text =		"Checkbox"
  
  [JPanel paBu]
  layout =		box.line_axis
  contents =		bu1
  contents =		bu2
  
  [JButton bu1]
  text =		"Button 1"
  action listener =	this
  tool tip text =	"Exit this application"
  size group =		sg1
  
  [JButton bu2]
  text =		"Button 2"
  action listener =	this
  tool tip text =	"Exit this application"
  size group =		sg1
  
  [JMenuBar mb]
  contents =		mMenu
  
  [JMenu mMenu]
  text =		"Menu"
  contents =		miItem
  
  [JMenuItem miItem]
  text =		"Item"
  action listener =	this
  tool tip text =	"Exit this application"

=head2	Java source code file example LogoWindowMain.java

  import java.awt.event.ActionEvent;
  import java.awt.event.ActionListener;
  import java.awt.event.WindowEvent;
  import java.awt.Container;
  import java.awt.BorderLayout;
  import java.awt.GridBagLayout;
  import java.awt.GridBagConstraints;
  import java.awt.Color;
  import java.awt.Dimension;
  import javax.swing.WindowConstants;
  
  import javax.swing.BorderFactory;
  import javax.swing.Box;
  import javax.swing.BoxLayout;
  import javax.swing.ImageIcon;
  import javax.swing.JPanel;
  import javax.swing.JMenu;
  import javax.swing.JMenuBar;
  import javax.swing.JMenuItem;
  import javax.swing.JFrame;
  import javax.swing.JLabel;
  import javax.swing.JButton;
  import javax.swing.JCheckBox;
  
  public class LogoMainWindow extends JFrame
    implements ActionListener
  {
  
  // jlayout.variables.begin
  // jlayout.variables.end
  
  // jlayout.setup.begin
  // jlayout.setup.end
  
  // jlayout.cleanup.begin
  // jlayout.cleanup.end
  
    public LogoMainWindow()
    {
      super("");
      jLayoutSetup();
    }
  
    public void actionPerformed(ActionEvent e)
    {
      WindowEvent we = new WindowEvent(
        this, WindowEvent.WINDOW_CLOSING
      );
      processWindowEvent(we);
    }
  }

=head2	How to run jlayout

  jlayout input.jl MyFrame.java

=head1	ENVIRONMENT

There are no special environment for jlayout. Like other dklibs-based
applications jlayout uses the LANG environment variable to find the
language for log messages.

=head1	RESTRICTIONS

The SpringLayout and GroupLayout layout managers are not supported.

=head1	SEE ALSO

http://dktools.sourceforge.net/jlayout.html

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (C) - 2008, Dirk Krause
All rights resrved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

