/Users/richardallenbair/Documents/Source/Projects/swingx-work/jxtitledseparator/swingx/src/java/org/jdesktop/swingx/JXTitledSeparator_API.java
/*
 * $Id: JXTitledSeparator_API3.html 1411 2006-09-20 22:15:12Z rbair $
 *
 * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle,
 * Santa Clara, California 95054, U.S.A. All rights reserved.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

package org.jdesktop.swingx;

import java.awt.Color;
import java.awt.Dimension;
import java.awt.Font;
import java.awt.GridBagConstraints;
import java.awt.GridBagLayout;
import java.awt.Insets;
import javax.swing.Box;
import javax.swing.Icon;
import javax.swing.JLabel;
import javax.swing.JSeparator;
import javax.swing.SwingConstants;
import javax.swing.UIManager;

/**
 * <p>A simple horizontal separator that contains a title.<br/>
 *
 * <p>JXTitledSeparator allows you to specify the title via the {@link #setTitle} method.
 * The title alignment may be specified by using the {@link #setHorizontalAlignment}
 * method, and accepts all the same arguments as the {@link javax.swing.JLabel#setHorizontalAlignment}
 * method.</p>
 *
 * <p>In addition, you may specify an Icon to use with this separator. The icon
 * will appear "leading" the title (on the left in left-to-right languages,
 * on the right in right-to-left languages). To change the position of the
 * title with respect to the icon, call {@link #setHorizontalTextPosition}.</p>
 *
 * <p>The default font and color of the title comes from the <code>LookAndFeel</code>, mimicking
 * the font and color of the {@link javax.swing.TitledBorder}</p>
 *
 * <p>Here are a few example code snippets:
 * <pre><code>
 *  //create a plain separator
 *  JXTitledSeparator sep = new JXTitledSeparator();
 *  sep.setText("Customer Info");
 *
 *  //create a separator with an icon
 *  sep = new JXTitledSeparator();
 *  sep.setText("Customer Info");
 *  sep.setIcon(new ImageIcon("myimage.png"));
 *
 *  //create a separator with an icon to the right of the title,
 *  //center justified
 *  sep = new JXTitledSeparator();
 *  sep.setText("Customer Info");
 *  sep.setIcon(new ImageIcon("myimage.png"));
 *  sep.setHorizontalAlignment(SwingConstants.CENTER);
 *  sep.setHorizontalTextPosition(SwingConstants.TRAILING);
 * </code></pre>
 *
 * @author rbair
 */
public class JXTitledSeparator extends JXPanel {
    /** 
     * Creates a new instance of <code>JXTitledSeparator</code>. The default title is simply
     * an empty string. Default justification is <code>LEADING</code>, and the default
     * horizontal text position is <code>TRAILING</code> (title follows icon)
     */
    public JXTitledSeparator();
    
    /** 
     * Creates a new instance of <code>JXTitledSeparator</code> with the specified
     * title. Default horizontal alignment is <code>LEADING</code>, and the default
     * horizontal text position is <code>TRAILING</code> (title follows icon)
     */
    public JXTitledSeparator(String title);
    
    /** 
     * Creates a new instance of <code>JXTitledSeparator</code> with the specified
     * title, icon, and horizontal alignment. The default
     * horizontal text position is <code>TRAILING</code> (title follows icon)
     */
    public JXTitledSeparator(String title, Icon icon, int horizontalAlignment);
    
    /**
     * Sets the title for the separator. This may be simple html, or plain
     * text.
     *
     * @param title the new title. Any string input is acceptable
     */
    public void setTitle(String title);
    
    /**
     * Gets the title.
     * 
     * @return the title being used for this <code>JXTitledSeparator</code>. 
     *         This will be the raw title text, and so may include html tags etc 
     *         if they were so specified in #setTitle.
     */
    public String getTitle();
    
    /**
     * <p>Sets the alignment of the title along the X axis. If leading, then
     * the title will lead the separator (in left-to-right languages,
     * the title will be to the left and the separator to the right). If centered,
     * then a separator will be to the left, followed by the title (centered),
     * followed by a separator to the right. Trailing will have the title
     * on the right with a separator to its left, in left-to-right languages.</p>
     * 
     * <p>LEFT and RIGHT always position the text left or right of the separator,
     * respectively, regardless of the language orientation.</p>
     *
     * @param alignment  One of the following constants
     *           defined in <code>SwingConstants</code>:
     *           <code>LEFT</code>,
     *           <code>CENTER</code>,
     *           <code>RIGHT</code>,
     *           <code>LEADING</code> (the default) or
     *           <code>TRAILING</code>.
     *
     * @throws IllegalArgumentException if the alignment does not match one of
     *         the accepted inputs.
     * @see SwingConstants
     * @see #getHorizontalAlignment
     */
    public void setHorizontalAlignment(int alignment);
    
    /**
     * Returns the alignment of the title contents along the X axis.
     *
     * @return   The value of the horizontalAlignment property, one of the 
     *           following constants defined in <code>SwingConstants</code>:
     *           <code>LEFT</code>,
     *           <code>CENTER</code>, 
     *           <code>RIGHT</code>,
     *           <code>LEADING</code> or
     *           <code>TRAILING</code>.
     *
     * @see #setHorizontalAlignment
     * @see SwingConstants
     */
    public int getHorizontalAlignment();

    /**
     * Sets the horizontal position of the title's text,
     * relative to the icon.
     *
     * @param position  One of the following constants
     *           defined in <code>SwingConstants</code>:
     *           <code>LEFT</code>,
     *           <code>CENTER</code>,
     *           <code>RIGHT</code>,
     *           <code>LEADING</code>, or
     *           <code>TRAILING</code> (the default).
     * @throws IllegalArgumentException if the position does not match one of
     *         the accepted inputs.
     */
    public void setHorizontalTextPosition(int position);
    
    /**
     * Returns the horizontal position of the title's text,
     * relative to the icon.
     *
     * @return   One of the following constants
     *           defined in <code>SwingConstants</code>:
     *           <code>LEFT</code>,
     *           <code>CENTER</code>, 
     *           <code>RIGHT</code>,
     *           <code>LEADING</code> or
     *           <code>TRAILING</code>.
     *
     * @see SwingConstants
     */
    public int getHorizontalTextPosition();
    
    /**
     * Defines the icon this component will display.  If
     * the value of icon is null, nothing is displayed.
     * <p>
     * The default value of this property is null.
     * 
     * @see #setHorizontalTextPosition
     * @see #getIcon
     */
    public void setIcon(Icon icon);
    
    /**
     * Returns the graphic image (glyph, icon) that the 
     * <code>JXTitledSeparator</code> displays.
     *
     * @return an Icon
     * @see #setIcon
     */
    public Icon getIcon();

    /**
     * @inheritDoc
     */
    @Override
    public void setForeground(Color foreground);
    
    /**
     * @inheritDoc
     */
    @Override
    public void setFont(Font font);
}