ChangeableLookProvider


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.spi.looks;
21  
22  import java.util.Enumeration  ;
23  import java.util.TooManyListenersException  ;
24  import javax.swing.event.ChangeListener  ;
25  
26  /** Interface for finding a Looks for given represented object. To create
27   * a {@link LookSelector} implement this interface and call
28   * {@link Selectors#selector( ChangeableLookProvider )}. LookSelectors created
29   * from this interface are allowed to change the content. To do so you have
30   * to implement the {@link #addChangeListener} method and fire the changes
31   * on the registered listener. Typical implementation of the method
32   * would look like:<P>
33   * <CODE>
34   *  if ( this.listener != null ) {
35          throw new TooManyListenersException();
36      }
37      else {
38          this.listener = listener;
39          }
40   * </CODE>
41   * <P>
42   * and fire method would look like:<P>
43   * <CODE>
44   * listener.stateChanged( new ChangeEvent( this ) );
45   * </CODE>
46   * <P>
47   * Notice that it is usually not necessary to create a list of listeners and
48   * rather throw TooManyListeners exception if there would be more than one
49   * listener registered. The reason is that reusing one instance of
50   * ChangeableLookProvider would result in two LookSelectors with the same
51   * behavior i.e. you may rather want to reuse the LookSelector than the
52   * Provider.
53   *
54   *
55   * @see LookProvider for creating LooksSelectors which have fixed content
56   *
57   * @author Petr Hrebejk
58   */
59  public interface ChangeableLookProvider {
60      
61      /** Finds all suitable Looks for given key. The key for a representedObject
62       * is obtained by call to the (@link #getKey} method.
63       * @param key The key we want to find available looks for.
64       * @return Enumeration of available Looks
65       */
66      public Enumeration   getLooksForKey( Object   key );
67      
68      /** Returns key for given object. Make sure you return the same key for
69       * given object during whole lifecycle of the LookSelector. This means
70       * that changes in the content are changes in the enumerations of Looks
71       * for given key not a change in a key which is returned for given object.
72       * (It also means that it is not good idea to base the implementation
73       * of this method on an attribute of an object which can change. Changes
74       * in representation of such attributes should generally be handled by Looks
75       * rather than LookSelectors/Providers)
76       * @param representedObject The represented object we want to find key for.
77       * @return Key for given represented object. Returning <CODE>null</CODE>
78       *         instead of a key will result in returning empty Enumeration 
79       *         from the LookSelector.
80       */
81      public Object   getKeyForObject( Object   representedObject );
82      
83      /** Registers listener for changes in the Provider's content. Call
84       * stateChanged on the registered listener to notify it about change in
85       * the Look enumerations returned for keys.
86       *
87       * @see #getKeyForObject for info about correct behavior of the Provider
88       * @param listener The listenet which should be notified when change in
89       *        the Provider's content occurs.
90       * @throws TooManyListenersException May be thrown when more than one
91       *         listener is registered.
92       */
93      public void addChangeListener( ChangeListener   listener ) throws TooManyListenersException  ;
94              
95              
96  }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags