replaced <code></code> with more concise {@code}
[idea/community.git] / plugins / ui-designer / src / com / intellij / uiDesigner / propertyInspector / PropertyEditor.java
1 /*
2  * Copyright 2000-2009 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.uiDesigner.propertyInspector;
17
18 import com.intellij.uiDesigner.radComponents.RadComponent;
19 import org.jetbrains.annotations.NotNull;
20 import org.jetbrains.annotations.Nullable;
21
22 import javax.swing.*;
23 import javax.swing.event.EventListenerList;
24
25 /**
26  * @author Anton Katilin
27  * @author Vladimir Kondratyev
28  */
29 public abstract class PropertyEditor<V> {
30   private final EventListenerList myListenerList;
31
32   protected PropertyEditor(){
33     myListenerList=new EventListenerList();
34   }
35
36   /**
37    * @return edited value. Note that {@code null} is the legal.
38    *
39    * @exception java.lang.Exception the method throws exception
40    * if user enters wrong value and it cannot be applied. Note, that
41    * exception's message will be shown to the user.
42    */
43   @Nullable
44   public abstract V getValue() throws Exception;
45
46   /**
47    * @param component this component can be used to prepare editor UI
48    * component
49    *
50    * @param value value to be edited. The editor should not
51    * directly edit the passed object. Instead of this it must edit some
52    * internal data and return the edited value by {@code getValue}
53    * method.
54    *
55    * @param inplaceContext this is hint for the editor. This parameter is not {@code null}
56    * in case if the editor is used for inplace editing. This hint is very useful.
57    * For example string editor doesn't have a border when it is used
58    * inside property inspector and has border when it is used for inspace editing.
59    *
60    * @return the component which is used to edit the property in UI.
61    * The method must always return not {@code null} component.
62    */
63   public abstract JComponent getComponent(
64     RadComponent component,
65     V value,
66     InplaceContext inplaceContext);
67
68   /**
69    * Property editor can return preferred focused component (if any) inside the component
70    * which is returned by the {@link #getComponent(com.intellij.uiDesigner.radComponents.RadComponent,V,InplaceContext) } method.
71    * This method is used as a hint to implement better focus handling.
72    * {@code null} values means that editor relies on the UI editor in
73    * determing preferred focused component.
74    *
75    * @param component cannot be null
76    */
77   public JComponent getPreferredFocusedComponent(@NotNull final JComponent component){
78     return null;
79   }
80
81   /**
82    * Editor should update UI of all its internal components to fit current
83    * IDEA Look And Feel. We cannot directly update UI of the component
84    * that is returned by {@link #getComponent(com.intellij.uiDesigner.radComponents.RadComponent,V,InplaceContext) } method
85    * because hidden components that are not in the Swing tree can exist.
86    */
87   public abstract void updateUI();
88
89   /**
90    * Adds specified listener
91    */
92   public final void addPropertyEditorListener(final PropertyEditorListener l){
93     myListenerList.add(PropertyEditorListener.class,l);
94   }
95
96   /**
97    * Removes specified listener
98    */
99   public final void removePropertyEditorListener(final PropertyEditorListener l){
100     myListenerList.remove(PropertyEditorListener.class,l);
101   }
102
103   protected final void fireEditingCancelled(){
104     final PropertyEditorListener[] listeners=myListenerList.getListeners(PropertyEditorListener.class);
105     for (PropertyEditorListener listener : listeners) {
106       listener.editingCanceled(this);
107     }
108   }
109
110   protected final void fireValueCommitted(final boolean continueEditing, final boolean closeEditorOnError) {
111     final PropertyEditorListener[] listeners=myListenerList.getListeners(PropertyEditorListener.class);
112     for (PropertyEditorListener listener : listeners) {
113       listener.valueCommitted(this, continueEditing, closeEditorOnError);
114     }
115   }
116
117   protected final void preferredSizeChanged(){
118     final PropertyEditorListener[] listeners=myListenerList.getListeners(PropertyEditorListener.class);
119     for (PropertyEditorListener listener : listeners) {
120       listener.preferredSizeChanged(this);
121     }
122   }
123 }