package nxm.sys.inc;

import java.awt.Component;
import java.util.EventListener;
import java.util.EventObject;

/** Defines a generic widget that can be used in a GUI. This allows customization of the widgets
    supported by nxm.sys.libg WidgetWrapper and allows creation of new widgets that
    nxm.sys.libg WidgetWrapper will recognize.

    @author  J. Czechowski IV
    @since   NeXtMidas 2.7.0
 */
public interface Widget {
  /** Sets the value of the widget.
      @param value The value of the widget.
   */
  void setWidgetValue (Object value);

  /** Gets the value of the widget.
      @return The value of the widget.
   */
  Object getWidgetValue ();

  /** Simulate a user's interaction in setting the value of the widget. Unlike {@link #setWidgetValue},
      which simply sets the value of the widget (with no notification of the event listeners), this
      is a programatic way of simulating user interaction. Most implementations look similar to this:
      <pre>
        public void setWidgetAction (Object value) {
          setWidgetValue(value);
          // notify listeners
        }
      </pre>
      @param value The value of the widget.
   */
  void setWidgetAction (Object value);

  /** Sets the title (or name) of the widget.
      @param title The title of the widget.
   */
  void setWidgetTitle (Object title);

  /** Gets the title (or name) of the widget.
      @return The title of the widget.
   */
  Object getWidgetTitle ();

  /** Gets the widget's primary component. This component will be used for refreshes, getting the
      widget's bounds, visibility, etc. In 90% of cases this will simply be:
      <pre>
        public Component getWidgetComponent () { return this; }
      </pre>
      @return The widget's primary component.
   */
  Component getWidgetComponent ();

  /** Returns the class of the event listener to use when listening for events from this object.
      This can be one of the following standard Java listeners:
      <pre>
        {@link java.awt.event.ActionListener}
        {@link java.awt.event.AdjustmentListener}
        {@link java.awt.event.ItemListener}
        {@link java.awt.event.TextListener}
        {@link javax.swing.event.ChangeListener}
      </pre>
      or one of the following special options:
      <pre>
        {@link Widget.WidgetListener} -- Allows customization for use with NeXtMidas.
        <code>null</code>                -- Says that no listener is required.
      </pre>
      If this is non-null nxm.sys.libg WidgetWrapper class uses the specified listener class
      when listening to events from the widget. The widget wrapper assumes that the widget follows
      the standard Java naming convention for the add and remove methods:
      <pre>
        public void add&lt;type&gt;(&lt;type&gt; listener) { ... }
        public void remove&lt;type&gt;(&lt;type&gt; listener) { ... }
      </pre>
      For example, one that uses a {@link Widget.WidgetListener} should have the methods:
      <pre>
        public void addWidgetListener(WidgetListener listener) { ... }
        public void removeWidgetListener(WidgetListener listener) { ... }
      </pre>
      It should be noted that the default handling of the standard Java listeners is very basic
      and that users should consider using {@link Widget.WidgetListener} whenever they want more
      control over what constitutes an event for the macro.

      @return One of the standard listeners, {@link Widget.WidgetListener} or <code>null</code>.
   */
  Class<? extends EventListener> getWidgetEventListener ();

  /** This is an optional event listener interface that can be used by a Widget where it wishes
      to have custom control over events. See {@link Widget#getWidgetEventListener} for details.
   */
  public static interface WidgetListener extends EventListener {
    /** event handler triggered when a widget has been updated
        @param e Event Object returned from GUI
     */
    void widgetUpdated (EventObject e);
  }
}
