001/* ----------------------------------------------------------------------------
002   The Kiwi Toolkit - A Java Class Library
003   Copyright (C) 1998-2004 Mark A. Lindner
004
005   This library is free software; you can redistribute it and/or
006   modify it under the terms of the GNU General Public License as
007   published by the Free Software Foundation; either version 2 of the
008   License, or (at your option) any later version.
009
010   This library is distributed in the hope that it will be useful,
011   but WITHOUT ANY WARRANTY; without even the implied warranty of
012   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013   General Public License for more details.
014
015   You should have received a copy of the GNU General Public License
016   along with this library; if not, write to the Free Software
017   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
018   02111-1307, USA.
019 
020   The author may be contacted at: mark_a_lindner@yahoo.com
021   ----------------------------------------------------------------------------
022   $Log: ContentPanel.java,v $
023   Revision 1.7  2004/05/12 19:11:04  markl
024   comment block updates
025
026   Revision 1.6  2003/01/19 09:50:53  markl
027   Javadoc & comment header updates.
028
029   Revision 1.5  2001/03/12 09:27:53  markl
030   Source code and Javadoc cleanup.
031
032   Revision 1.4  1999/10/05 02:50:51  markl
033   Javadoc fix for constructor.
034
035   Revision 1.3  1999/08/13 07:10:49  markl
036   Implemented some of the abstract methods.
037
038   Revision 1.2  1999/05/10 09:24:09  markl
039   Added methods.
040
041   Revision 1.1  1999/02/28 00:26:24  markl
042   Initial revision
043   ----------------------------------------------------------------------------
044*/
045
046package kiwi.ui;
047
048import kiwi.db.*;
049
050/** This class defines methods common to components that display (and allow
051  * the editing of) a piece of data, which is represented by a
052  * <code>DomainObject</code>. Typically, the component is filled with
053  * editing fields and other input components that correspond to fields in
054  * the domain object. Data is synchronized between the domain object and these
055  * fields via calls to the methods <code>setData()</code> and
056  * <code>syncData()</code>.
057  *
058  * @author Mark Lindner
059  */
060
061public abstract class ContentPanel extends KPanel
062  {
063  /** Construct a new <code>ContentPanel</code>.
064   */
065  
066  public void ContentPanel()
067    {
068    }
069  
070  /** Synchronize a <code>DomainObject</code> with the
071   *  <code>ContentPanel</code>. Subclassers should define this method to
072   *  copy the appropriate values from the domain object to the corresponding
073   *  input elements in the interface. The reference to the domain object must
074   *  also be saved so that its state may be updated in the
075   *  <code>syncData()</code> method.
076   *
077   * @param data The <code>DomainObject</code> to associate with this
078   * <code>ContentPanel</code>.
079   */
080  
081  public abstract void setData(DomainObject data);
082
083  /** Synchronize data entered into the <code>ContentPanel</code> with the
084   * <code>DomainObject</code> that was provided with the most recent call
085   * to <code>setData()</code>. Subclassers should define this method to
086   * copy the appropriate values from the input elements in the interface to
087   * the corresponding fields in the domain object.
088   * <p>
089   * Data validation is performed by a <code>DomainObject</code>'s
090   * <i>setter</i> methods. Invalid input is flagged by raising a
091   * <code>AccessorException</code>, which must be caught by the
092   * <code>syncData()</code> method. The message in the exception is a human-
093   * readable phrase that describes the problem with the input; this message
094   * may be displayed in a warning dialog box to notify the user of the
095   * erroneous input.
096   *
097   * @return <code>true</code> if no data validation errors occurred, and
098   * <code>false</code> otherwise.
099   */
100  
101  public abstract boolean syncData();
102
103  /** Set the editable property for this <code>ContentPanel</code>. Some
104   * interfaces have both an editable (<i>edit</i>) and a non-editable
105   * (<i>view</i>) mode, but some subclasses may not implement both; in this
106   * case the method will be a <i>no-op</i>.
107   *
108   * @param editable A flag specifying whether the component will be editable.
109   */
110  
111  public abstract void setEditable(boolean editable);
112
113  /** Activate this content panel. The meaning of <i>activate</i> is
114   * context-specific. If this is one of a sequence of panels in a tabbed
115   * pane, for example, this method might be called when the user selects the
116   * corresponding tab to make this panel visible.
117   *
118   * @return A flag specifying whether this panel may be activated. The default
119   * implementation returns <code>true</code>.
120   */
121  
122  public boolean activate()
123    {
124    return(true);
125    }
126
127  /** Deactivate this content panel. The meaning of <i>deactivate</i> is
128   * context-specific. If this is one of a sequence of panels in a tabbed
129   * pane,  for example, this method might be called when the user selects
130   * another tab to make this panel invisible.
131   *
132   * @return A flag specifying whether this panel may be deactivated. The
133   * default implementation returns <code>true</code>.
134   */
135  
136  public boolean deactivate()
137    {
138    return(true);
139    }
140
141  /** Get the title for this panel. The usage of this method will vary; if this
142   * is one of a sequence of panels in a tabbed pane, for example, this method
143   * might return the string that should appear in the tab corresponding to
144   * this panel.
145   *
146   * @return The title for the panel. The default implementation returns an
147   * empty string.
148   */
149  
150  public String getTitle()
151    {
152    return("");
153    }
154
155  }
156
157/* end of source file */