001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.pde.ui.templates;
011:
012: import java.util.Hashtable;
013:
014: import org.eclipse.core.resources.IProject;
015: import org.eclipse.core.runtime.CoreException;
016: import org.eclipse.core.runtime.IProgressMonitor;
017: import org.eclipse.pde.core.plugin.IPluginModelBase;
018: import org.eclipse.pde.ui.IFieldData;
019:
020: /**
021: * This class adds a notion of options to the default template section
022: * implementation. Options have values and visual presence that allows users to
023: * change them. When a section is configured with a number of options, they
024: * become available to the code generator and can take part in conditional code
025: * emitting.
026: * <p>
027: * This class is typically used in conjunction with
028: * <samp>OptionTemplateWizardPage </samp>. The later is capable of creating UI
029: * based on the list of options it was given, thus simplifying new template
030: * section creation.
031: *
032: * @since 2.0
033: */
034:
035: public abstract class BaseOptionTemplateSection extends
036: AbstractTemplateSection {
037: private Hashtable options = new Hashtable();
038:
039: /**
040: * Adds a boolean option with a provided name, label and initial value.
041: *
042: * @param name
043: * the unique name of the option (can be used as a variable in
044: * conditional code emitting and variable substitution)
045: * @param label
046: * presentable name of the option
047: * @param value
048: * initial value of the option
049: * @param pageIndex
050: * a zero-based index of a page where this option should appear
051: * @return the newly created option
052: */
053: protected TemplateOption addOption(String name, String label,
054: boolean value, int pageIndex) {
055: BooleanOption option = new BooleanOption(this , name, label);
056: registerOption(option, value ? Boolean.TRUE : Boolean.FALSE,
057: pageIndex);
058: return option;
059: }
060:
061: /**
062: * Adds a string option with a provided name, label and initial value.
063: *
064: * @param name
065: * the unique name of the option (can be used as a variable in
066: * conditional code emitting and variable substitution)
067: * @param label
068: * presentable name of the option
069: * @param value
070: * initial value of the option
071: * @param pageIndex
072: * a zero-based index of a page where this option should appear
073: * @return the newly created option
074: */
075: protected TemplateOption addOption(String name, String label,
076: String value, int pageIndex) {
077: StringOption option = new StringOption(this , name, label);
078: registerOption(option, value, pageIndex);
079: return option;
080: }
081:
082: /**
083: * Adds a choice option with a provided name, label, list of choices and the
084: * initial value (choice).
085: *
086: * @param name
087: * the unique name of the option (can be used as a variable in
088: * conditional code emitting and variable substitution)
089: * @param label
090: * presentable name of the option
091: * @param choices
092: * an array of choices that the user will have when setting the
093: * value of the option. Each array position should accept an
094: * array of String objects of size 2, the first being the unique
095: * name and the second the presentable label of the choice.
096: * @param value
097: * initial value (choice) of the option
098: * @param pageIndex
099: * a zero-based index of a page where this option should appear
100: * @return the newly created option
101: */
102: protected TemplateOption addOption(String name, String label,
103: String[][] choices, String value, int pageIndex) {
104: AbstractChoiceOption option;
105: if (choices.length == 2)
106: option = new RadioChoiceOption(this , name, label, choices);
107: else
108: option = new ComboChoiceOption(this , name, label, choices);
109: registerOption(option, value, pageIndex);
110: return option;
111: }
112:
113: /**
114: * Force a combo choice representation.
115: * Radio buttons look bad - even if only two options specified.
116: * @param name
117: * @param label
118: * @param choices
119: * @param value
120: * @param pageIndex
121: * @return the newly created option
122: */
123: protected ComboChoiceOption addComboChoiceOption(String name,
124: String label, String[][] choices, String value,
125: int pageIndex) {
126: ComboChoiceOption option = new ComboChoiceOption(this , name,
127: label, choices);
128: registerOption(option, value, pageIndex);
129: return option;
130: }
131:
132: /**
133: * Adds a blank field with a default height to provide spacing.
134: *
135: * @param pageIndex
136: * a zero-based index of a page where this option should appear
137: * @return the newly created option
138: */
139: protected TemplateOption addBlankField(int pageIndex) {
140: BlankField field = new BlankField(this );
141: registerOption(field, "", pageIndex); //$NON-NLS-1$
142: return field;
143: }
144:
145: /**
146: * Adds a blank field with a specific height to provide spacing.
147: *
148: * @param height
149: * specifies the height of the blank field in pixels
150: * @param pageIndex
151: * a zero-based index of a page where this option should appear
152: * @return the newly created option
153: */
154: protected TemplateOption addBlankField(int height, int pageIndex) {
155: BlankField field = new BlankField(this , height);
156: registerOption(field, "", pageIndex); //$NON-NLS-1$
157: return field;
158: }
159:
160: /**
161: * Initializes the option with a given unique name with the provided value.
162: * The value will be set only if the option has not yet been initialized.
163: *
164: * @param name
165: * option unique name
166: * @param value
167: * the initial value of the option
168: */
169: protected void initializeOption(String name, Object value) {
170: TemplateOption option = getOption(name);
171: if (option != null) {
172: // Only initialize options that have no value set
173: if (option.getValue() == null)
174: option.setValue(value);
175: }
176: }
177:
178: /**
179: * Returns a string value of the option with a given name. The option with
180: * that name must exist and must be registered as a string option to begin
181: * with.
182: *
183: * @param name
184: * the unique name of the option
185: * @return the string value of the option with a given name or <samp>null
186: * </samp> if not found.
187: */
188: public String getStringOption(String name) {
189: TemplateOption option = (TemplateOption) options.get(name);
190: if (option != null) {
191: if (option instanceof StringOption)
192: return ((StringOption) option).getText();
193: else if (option instanceof ComboChoiceOption) {
194: // Added by DG: selection of the choice option
195: // should also be considered if the selected
196: // value is a String.
197: ComboChoiceOption ccoption = (ComboChoiceOption) option;
198: Object value = ccoption.getValue();
199: if (value != null && value instanceof String)
200: return (String) value;
201: }
202: }
203: return null;
204: }
205:
206: /**
207: * Returns a boolean value of the option with a given name. The option with
208: * that name must exist and must be registered as a boolean option to begin
209: * with.
210: *
211: * @param key
212: * the unique name of the option
213: * @return the boolean value of the option with a given name or <samp>null
214: * </samp> if not found.
215: */
216: public boolean getBooleanOption(String key) {
217: TemplateOption option = (TemplateOption) options.get(key);
218: if (option != null && option instanceof BooleanOption) {
219: return ((BooleanOption) option).isSelected();
220: }
221: return false;
222: }
223:
224: /**
225: * Enables the option with a given name. The exact effect of the method
226: * depends on the option type, but the end-result should always be the same -
227: * users should not be able to modify values of disabled options. This
228: * method has no effect if the option with a given name is not found.
229: *
230: * @param name
231: * the unique name of the option
232: * @param enabled
233: * the enable state that the option should have
234: */
235: public void setOptionEnabled(String name, boolean enabled) {
236: TemplateOption option = (TemplateOption) options.get(name);
237: if (option != null)
238: option.setEnabled(enabled);
239: }
240:
241: /**
242: * Returns the value of the option with a given name. The actual type of the
243: * returned object depends on the option type.
244: *
245: * @param name
246: * the name of the option
247: * @return the current value of the option with a specified name or
248: * <samp>null </samp> if not found or not applicable.
249: */
250: public Object getValue(String name) {
251: TemplateOption option = (TemplateOption) options.get(name);
252: if (option != null)
253: return option.getValue();
254: return super .getValue(name);
255: }
256:
257: /**
258: * Returns true if this template depends on values set in the parent wizard.
259: * Values in the parent wizard include plug-in id, plug-in name, plug-in
260: * class name, plug-in provider etc. If the template does depend on these
261: * values, <samp>initializeFields </samp> will be called when the page is
262: * made visible in the forward direction (going from the first page to the
263: * pages owned by this template). If the page is never shown (Finish is
264: * pressed before the page is made visible at least once),
265: * <samp>initializeFields </samp> will be called with the model object
266: * instead during template execution. The same method will also be called
267: * when the template is created within the context of the plug-in manifest
268: * editor, because plug-in model already exists at that time.
269: *
270: * @return <code>true</code> if this template depends on the data set in
271: * the parent wizard, <code>false</code> otherwise.
272: */
273: public boolean isDependentOnParentWizard() {
274: return false;
275: }
276:
277: /**
278: * Initializes options in the wizard page using the data provided by the
279: * method parameters. Some options may depend on the user selection in the
280: * common wizard pages before template page has been shown (for example,
281: * plug-in ID, plug-in name etc.). This method allows options to initialize
282: * in respect to these values.
283: * <p>
284: * The method is called before the actual plug-in has been built.
285: * </p>
286: *
287: * @param data
288: * plug-in data as defined in the common plug-in project wizard
289: * pages
290: */
291: protected void initializeFields(IFieldData data) {
292: }
293:
294: /**
295: * Initializes options in the wizard page using the data provided by the
296: * method parameters. Some options may depend on the user selection in the
297: * common wizard pages before template page has been shown (for example,
298: * plug-in ID, plug-in name etc.). This method allows options to initialize
299: * in respect to these values.
300: * <p>
301: * This method is called after the plug-in has already been created or as
302: * part of new extension creation (inside the manifest editor). Either way,
303: * the plug-in properties in the model have been fully set and the model can
304: * be used to initialize options that cannot be initialized independently.
305: *
306: * @param model
307: * the model of the plug-in manifest file.
308: */
309: public void initializeFields(IPluginModelBase model) {
310: }
311:
312: /**
313: * Subclasses must implement this method in order to validate options whose
314: * value have been changed by the user. The subclass can elect to validate
315: * the option on its own, or to also check validity of other options in
316: * relation to the new value of this one.
317: *
318: * @param changed
319: * the option whose value has been changed by the user
320: */
321: public abstract void validateOptions(TemplateOption changed);
322:
323: /**
324: * Expands variable substitution to include all string options defined in
325: * this template.
326: *
327: * @see AbstractTemplateSection#getReplacementString(String, String)
328: */
329: public String getReplacementString(String fileName, String key) {
330: String value = getStringOption(key);
331: if (value != null)
332: return value;
333: return super .getReplacementString(fileName, key);
334: }
335:
336: /**
337: * Modifies the superclass implementation by adding the initialization step
338: * before commencing execution. This is important because some options may
339: * not be initialized and users may choose to press 'Finish' before the
340: * wizard page where the options are were shown for the first time.
341: */
342: public void execute(IProject project, IPluginModelBase model,
343: IProgressMonitor monitor) throws CoreException {
344: initializeFields(model);
345: super .execute(project, model, monitor);
346: }
347:
348: /**
349: * Registers the provided option and sets the initial value.
350: *
351: * @param option
352: * the option to register
353: * @param value
354: * the initial value
355: * @param pageIndex
356: * the page index to which this option belongs
357: */
358: protected void registerOption(TemplateOption option, Object value,
359: int pageIndex) {
360: option.setValue(value);
361: options.put(option.getName(), option);
362: }
363:
364: private TemplateOption getOption(String key) {
365: return (TemplateOption) options.get(key);
366: }
367: }
|