001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.lib.editor.codetemplates.spi;
043:
044: import java.util.Collection;
045: import java.util.Map;
046: import org.netbeans.lib.editor.codetemplates.CodeTemplateParameterImpl;
047:
048: /**
049: * Code template parameter describes parsed parameter in the template's text.
050: * <br>
051: * A first occurrence of the parameter in the parametrized text of the code template
052: * define a master parameter. All other occurrences of the parameter
053: * with the same name will become slave parameters.
054: * <br/>
055: * The value of the master parameter
056: * will be used for the slaves as well automatically and document modifications
057: * to master parameter's value will be propagated to slaves as well.
058: *
059: * <p>
060: * Master parameters can have additional hints in the form
061: * <pre>
062: * ${param hint=value [hint2=value2] ... }
063: * ${param hint="string-literal" ... }
064: * ${param hint ... }
065: * </pre>
066: * The hints give additional specification of what the parameter's value should be.
067: * <br/>
068: * The slave parameters inherit their value from their master so it has no sense
069: * to define any hints for slave parameters.
070: * <br/>
071: * The hints without explicit <code>=value</code> are assigned with string value "true".
072: *
073: * @author Miloslav Metelka
074: */
075: public final class CodeTemplateParameter {
076:
077: /**
078: * Name of the parameter corresponding to the caret position parameter.
079: */
080: public static final String CURSOR_PARAMETER_NAME = "cursor"; // NOI18N
081:
082: public static final String COMPLETION_INVOKE_HINT_NAME = "completionInvoke"; // NOI18N
083:
084: public static final String SELECTION_PARAMETER_NAME = "selection"; // NOI18N
085:
086: public static final String LINE_HINT_NAME = "line"; // NOI18N
087:
088: /**
089: * Name of the hint that defines an explicit default value of a parameter.
090: */
091: public static final String DEFAULT_VALUE_HINT_NAME = "default"; // NOI18N
092:
093: /**
094: * Name of the hint that defines whether the given parameter is editable
095: * by the user or not.
096: * <br/>
097: * If the parameter is not editable the user cannot jump to it by <i>TAB</i>
098: * key during the post-insert editing. The value however can be changed
099: * by the code template processor(s).
100: * <br/>
101: * Example of non-editable parameter:
102: * <pre>
103: * ${param editable=false}
104: * </pre>
105: */
106: public static final String EDITABLE_HINT_NAME = "editable"; // NOI18N
107:
108: private final CodeTemplateParameterImpl impl;
109:
110: CodeTemplateParameter(CodeTemplateParameterImpl impl) {
111: this .impl = impl;
112: }
113:
114: /**
115: * Get name of this parameter as parsed from the code template description's text.
116: */
117: public String getName() {
118: return impl.getName();
119: }
120:
121: /**
122: * Get the present value of this parameter.
123: *
124: * @return non-null text value of this parameter.
125: * <br/>
126: * The default value of the parameter is set to the name of the parameter.
127: * <br/>
128: * If the parameter has hint of name
129: * {@link #DEFAULT_VALUE_HINT_NAME} then the default value
130: * is taken from the hint.
131: *
132: * <p>
133: * Once the code template gets inserted into the document
134: * (can be checked by {@link CodeTemplateInsertRequest#isInserted()})
135: * then the user may modify the parameter's value explicitly and this method
136: * will reflect these changes.
137: */
138: public String getValue() {
139: return impl.getValue();
140: }
141:
142: /**
143: * Set a new value for this parameter.
144: * <br/>
145: * The value can only be set to the master parameters
146: * because slave parameters will inherit values from their masters.
147: * <br/>
148: * If the code template was not yet inserted into the text the value
149: * will be remembered and used as a default value during insertion.
150: * <br/>
151: * If the code template was already inserted and it's still actively
152: * being changed then the value is propagated directly to the document's text.
153: *
154: * @see CodeTemplateInsertRequest#isInserted()
155: */
156: public void setValue(String newValue) {
157: impl.setValue(newValue, true);
158: }
159:
160: /**
161: * Check whether this parameter is editable by the user.
162: *
163: * @return true if this parameter is editable or false if it will
164: * be skipped during parameters user's editing.
165: */
166: public boolean isEditable() {
167: return impl.isEditable();
168: }
169:
170: /**
171: * Check whether the value of this parameter was modified by the user.
172: *
173: * @return true if the user has explicitly modify value of this parameter
174: * by typing or false if not.
175: */
176: public boolean isUserModified() {
177: return impl.isUserModified();
178: }
179:
180: /**
181: * Get starting offset of this parameter
182: * in the {@link CodeTemplateInsertRequest#getInsertText()}.
183: *
184: * @return >=0 starting offset of this parameter in the text being
185: * inserted into the document.
186: * <br/>
187: * After the code template gets inserted into the document
188: * the value continues to be updated if the user changes the value
189: * by typing until the code template gets released which can be
190: * determined by {@link CodeTemplateInsertRequest#isReleased()}.
191: */
192: public int getInsertTextOffset() {
193: return impl.getInsertTextOffset();
194: }
195:
196: /**
197: * Get starting offset of this parameter in the parametrized text.
198: * <br/>
199: * The parametrized text can be obtained
200: * by {@link CodeTemplateInsertRequest#getParametrizedText()}.
201: *
202: * @return >=0 index of the '${' in the parametrized text.
203: * @see #getParametrizedTextEndOffset()
204: */
205: public int getParametrizedTextStartOffset() {
206: return impl.getParametrizedTextStartOffset();
207: }
208:
209: /**
210: * Get the ending offset of this parameter in the parametrized text.
211: * <br/>
212: * The parametrized text can be obtained
213: * by {@link CodeTemplateInsertRequest#getParametrizedText()}.
214: *
215: * @return >=0 end offset of the parameter in the parametrized text
216: * pointing right after the closing '}' of the parameter.
217: * @see #getParametrizedTextStartOffset()
218: */
219: public int getParametrizedTextEndOffset() {
220: return impl.getParametrizedTextEndOffset();
221: }
222:
223: /**
224: * Get map of the [String,String] hints in the parameter.
225: * <br/>
226: * For example the hints map for <code>${param hint1 hint2="defaultValue"}</code>
227: * will contain ["hint1","true"] and ["hint2","defaultValue"].
228: */
229: public Map<String, String> getHints() {
230: return impl.getHints();
231: }
232:
233: /**
234: * Get the master parameter of this parameter.
235: *
236: * @return master parameter for this parameter or null if this parameter
237: * is master parameter.
238: */
239: public CodeTemplateParameter getMaster() {
240: return impl.getMaster();
241: }
242:
243: /**
244: * Get unmodifiable collection of the slave parameters.
245: *
246: * @return non-null collection of the slave parameters for this parameter.
247: * <br/>
248: * The collection will be empty if this is a slave parameter
249: * or a master with no slaves.
250: */
251: public Collection<? extends CodeTemplateParameter> getSlaves() {
252: return impl.getSlaves();
253: }
254:
255: /**
256: * Check whether this parameter is slave or not.
257: */
258: public boolean isSlave() {
259: return impl.isSlave();
260: }
261:
262: CodeTemplateParameterImpl getImpl() {
263: return impl;
264: }
265:
266: }
|