CodeTemplateParameter


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.lib.editor.codetemplates.spi;
21  
22  import java.util.Collection  ;
23  import java.util.Map  ;
24  import org.netbeans.lib.editor.codetemplates.CodeTemplateParameterImpl;
25  
26  /**
27   * Code template parameter describes parsed parameter in the template's text.
28   * <br>
29   * A first occurrence of the parameter in the parametrized text of the code template
30   * define a master parameter. All other occurrences of the parameter
31   * with the same name will become slave parameters.
32   * <br/>
33   * The value of the master parameter
34   * will be used for the slaves as well automatically and document modifications
35   * to master parameter's value will be propagated to slaves as well.
36   *
37   * <p>
38   * Master parameters can have additional hints in the form
39   * <pre>
40   * ${param hint=value [hint2=value2] ... }
41   * ${param hint="string-literal" ... }
42   * ${param hint ... }
43   * </pre>
44   * The hints give additional specification of what the parameter's value should be.
45   * <br/>
46   * The slave parameters inherit their value from their master so it has no sense
47   * to define any hints for slave parameters.
48   * <br/>
49   * The hints without explicit <code>=value</code> are assigned with string value "true".
50   * 
51   * @author Miloslav Metelka
52   */
53  public final class CodeTemplateParameter {
54      
55      /**
56       * Name of the parameter corresponding to the caret position parameter.
57       */
58      public static final String   CURSOR_PARAMETER_NAME = "cursor"; // NOI18N
59      
60      public static final String   SELECTION_PARAMETER_NAME = "selection"; // NOI18N
61  
62      public static final String   LINE_HINT_NAME = "line"; // NOI18N
63  
64      /**
65       * Name of the hint that defines an explicit default value of a parameter.
66       */
67      public static final String   DEFAULT_VALUE_HINT_NAME = "default"; // NOI18N
68      
69      /**
70       * Name of the hint that defines whether the given parameter is editable
71       * by the user or not.
72       * <br/>
73       * If the parameter is not editable the user cannot jump to it by <i>TAB</i>
74       * key during the post-insert editing. The value however can be changed
75       * by the code template processor(s).
76       * <br/>
77       * Example of non-editable parameter:
78       * <pre>
79       * ${param editable=false}
80       * </pre>
81       */
82      public static final String   EDITABLE_HINT_NAME = "editable"; // NOI18N
83      
84      
85      private final CodeTemplateParameterImpl impl;
86      
87      CodeTemplateParameter(CodeTemplateParameterImpl impl) {
88          this.impl = impl;
89      }
90      
91      /**
92       * Get name of this parameter as parsed from the code template description's text.
93       */
94      public String   getName() {
95          return impl.getName();
96      }
97      
98      /**
99       * Get the present value of this parameter.
100      * 
101      * @return non-null text value of this parameter.
102      *  <br/>
103      *  The default value of the parameter is set to the name of the parameter.
104      *  <br/>
105      *  If the parameter has hint of name
106      *  {@link #DEFAULT_VALUE_HINT_NAME} then the default value
107      *  is taken from the hint.
108      *
109      *  <p>
110      *  Once the code template gets inserted into the document
111      *  (can be checked by {@link CodeTemplateInsertRequest#isInserted()})
112      *  then the user may modify the parameter's value explicitly and this method
113      *  will reflect these changes.
114      */
115     public String   getValue() {
116         return impl.getValue();
117     }
118     
119     /**
120      * Set a new value for this parameter.
121      * <br/>
122      * The value can only be set to the master parameters
123      * because slave parameters will inherit values from their masters.
124      * <br/>
125      * If the code template was not yet inserted into the text the value
126      * will be remembered and used as a default value during insertion.
127      * <br/>
128      * If the code template was already inserted and it's still actively
129      * being changed then the value is propagated directly to the document's text.
130      * 
131      * @see CodeTemplateInsertRequest#isInserted()
132      */
133     public void setValue(String   newValue) {
134         impl.setValue(newValue, true);
135     }
136     
137     /**
138      * Check whether this parameter is editable by the user.
139      *
140      * @return true if this parameter is editable or false if it will
141      *  be skipped during parameters user's editing.
142      */
143     public boolean isEditable() {
144         return impl.isEditable();
145     }
146 
147     /**
148      * Check whether the value of this parameter was modified by the user.
149      *
150      * @return true if the user has explicitly modify value of this parameter
151      *  by typing or false if not.
152      */
153     public boolean isUserModified() {
154         return impl.isUserModified();
155     }
156     
157     /**
158      * Get starting offset of this parameter
159      * in the {@link CodeTemplateInsertRequest#getInsertText()}.
160      * 
161      * @return &gt;=0 starting offset of this parameter in the text being
162      *  inserted into the document.
163      *  <br/>
164      *  After the code template gets inserted into the document
165      *  the value continues to be updated if the user changes the value
166      *  by typing until the code template gets released which can be
167      *  determined by {@link CodeTemplateInsertRequest#isReleased()}.
168      */
169     public int getInsertTextOffset() {
170         return impl.getInsertTextOffset();
171     }
172     
173     /**
174      * Get starting offset of this parameter in the parametrized text.
175      * <br/>
176      * The parametrized text can be obtained
177      * by {@link CodeTemplateInsertRequest#getParametrizedText()}.
178      *
179      * @return &gt;=0 index of the '${' in the parametrized text.
180      * @see #getParametrizedTextEndOffset()
181      */
182     public int getParametrizedTextStartOffset() {
183         return impl.getParametrizedTextStartOffset();
184     }
185     
186     /**
187      * Get the ending offset of this parameter in the parametrized text.
188      * <br/>
189      * The parametrized text can be obtained
190      * by {@link CodeTemplateInsertRequest#getParametrizedText()}.
191      *
192      * @return &gt;=0 end offset of the parameter in the parametrized text
193      *  pointing right after the closing '}' of the parameter.
194      * @see #getParametrizedTextStartOffset()
195      */
196     public int getParametrizedTextEndOffset() {
197         return impl.getParametrizedTextEndOffset();
198     }
199 
200     /**
201      * Get map of the [String,String] hints in the parameter.
202      * <br/>
203      * For example the hints map for <code>${param hint1 hint2="defaultValue"}</code>
204      * will contain ["hint1","true"] and ["hint2","defaultValue"].
205      */
206     public Map   getHints() {
207         return impl.getHints();
208     }
209     
210     /**
211      * Get the master parameter of this parameter.
212      *
213      * @return master parameter for this parameter or null if this parameter
214      *  is master parameter.
215      */
216     public CodeTemplateParameter getMaster() {
217         return impl.getMaster();
218     }
219     
220     /**
221      * Get unmodifiable collection of the slave parameters.
222      *
223      * @return non-null collection of the slave parameters for this parameter.
224      *  <br/>
225      *  The collection will be empty if this is a slave parameter
226      *  or a master with no slaves.
227      */
228     public Collection   getSlaves() {
229         return impl.getSlaves();
230     }
231     
232     /**
233      * Check whether this parameter is slave or not.
234      */
235     public boolean isSlave() {
236         return impl.isSlave();
237     }
238     
239     CodeTemplateParameterImpl getImpl() {
240         return impl;
241     }
242 
243 }
244
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags