BaseOptionTemplateSection


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.pde.ui.templates;
12  import java.util.Hashtable  ;
13  
14  import org.eclipse.core.resources.IProject;
15  import org.eclipse.core.runtime.CoreException;
16  import org.eclipse.core.runtime.IProgressMonitor;
17  import org.eclipse.pde.core.plugin.IPluginModelBase;
18  import org.eclipse.pde.ui.IFieldData;
19  
20  /**
21   * This class adds a notion of options to the default template section
22   * implementation. Options have values and visual presence that allows users to
23   * change them. When a section is configured with a number of options, they
24   * become available to the code generator and can take part in conditional code
25   * emitting.
26   * <p>
27   * This class is typically used in conjunction with
28   * <samp>OptionTemplateWizardPage </samp>. The later is capable of creating UI
29   * based on the list of options it was given, thus simplifying new template
30   * section creation.
31   * 
32   * @since 2.0
33   */
34  
35  public abstract class BaseOptionTemplateSection extends AbstractTemplateSection {
36      private Hashtable   options = new Hashtable  ();
37  
38      /**
39       * Adds a boolean option with a provided name, label and initial value.
40       * 
41       * @param name
42       *            the unique name of the option (can be used as a variable in
43       *            conditional code emitting and variable substitution)
44       * @param label
45       *            presentable name of the option
46       * @param value
47       *            initial value of the option
48       * @param pageIndex
49       *            a zero-based index of a page where this option should appear
50       * @return the newly created option
51       */
52      protected TemplateOption addOption(String   name, String   label,
53              boolean value, int pageIndex) {
54          BooleanOption option = new BooleanOption(this, name, label);
55          registerOption(option, value ? Boolean.TRUE : Boolean.FALSE, pageIndex);
56          return option;
57      }
58  
59      /**
60       * Adds a string option with a provided name, label and initial value.
61       * 
62       * @param name
63       *            the unique name of the option (can be used as a variable in
64       *            conditional code emitting and variable substitution)
65       * @param label
66       *            presentable name of the option
67       * @param value
68       *            initial value of the option
69       * @param pageIndex
70       *            a zero-based index of a page where this option should appear
71       * @return the newly created option
72       */
73      protected TemplateOption addOption(String   name, String   label, String   value,
74              int pageIndex) {
75          StringOption option = new StringOption(this, name, label);
76          registerOption(option, value, pageIndex);
77          return option;
78      }
79      /**
80       * Adds a choice option with a provided name, label, list of choices and the
81       * initial value (choice).
82       * 
83       * @param name
84       *            the unique name of the option (can be used as a variable in
85       *            conditional code emitting and variable substitution)
86       * @param label
87       *            presentable name of the option
88       * @param choices
89       *            an array of choices that the user will have when setting the
90       *            value of the option. Each array position should accept an
91       *            array of String objects of size 2, the first being the unique
92       *            name and the second the presentable label of the choice.
93       * @param value
94       *            initial value (choice) of the option
95       * @param pageIndex
96       *            a zero-based index of a page where this option should appear
97       * @return the newly created option
98       */
99      protected TemplateOption addOption(String   name, String   label,
100             String  [][] choices, String   value, int pageIndex) {
101         AbstractChoiceOption option;
102         if (choices.length == 2)
103             option = new RadioChoiceOption(this, name, label, choices);
104         else
105             option = new ComboChoiceOption(this, name, label, choices);         
106         registerOption(option, value, pageIndex);
107         return option;
108     }
109     
110     /**
111      * Force a combo choice representation.
112      * Radio buttons look bad - even if only two options specified.
113      * @param name
114      * @param label
115      * @param choices
116      * @param value
117      * @param pageIndex
118      * @return the newly created option
119      */
120     protected ComboChoiceOption addComboChoiceOption(String   name, String   label,
121             String  [][] choices, String   value, int pageIndex) {
122         ComboChoiceOption option = new ComboChoiceOption(this, name, label, choices);
123         registerOption(option, value, pageIndex);
124         return option;
125     }
126     
127     /**
128      * Adds a blank field with a default height to provide spacing.
129      * 
130      * @param pageIndex
131      *            a zero-based index of a page where this option should appear
132      * @return the newly created option
133      */
134     protected TemplateOption addBlankField(int pageIndex) {
135         BlankField field = new BlankField(this);    
136         registerOption(field, "", pageIndex); //$NON-NLS-1$
137         return field;
138     }
139     /**
140      * Adds a blank field with a specific height to provide spacing.
141      * 
142      * @param height
143      *            specifies the height of the blank field in pixels            
144      * @param pageIndex
145      *            a zero-based index of a page where this option should appear
146      * @return the newly created option
147      */
148     protected TemplateOption addBlankField(int height, int pageIndex) {
149         BlankField field = new BlankField(this, height);    
150         registerOption(field, "", pageIndex); //$NON-NLS-1$
151         return field;
152     }
153     /**
154      * Initializes the option with a given unique name with the provided value.
155      * The value will be set only if the option has not yet been initialized.
156      * 
157      * @param name
158      *            option unique name
159      * @param value
160      *            the initial value of the option
161      */
162     protected void initializeOption(String   name, Object   value) {
163         TemplateOption option = getOption(name);
164         if (option != null) {
165             // Only initialize options that have no value set
166             if (option.getValue() == null)
167                 option.setValue(value);
168         }
169     }
170     /**
171      * Returns a string value of the option with a given name. The option with
172      * that name must exist and must be registered as a string option to begin
173      * with.
174      * 
175      * @param name
176      *            the unique name of the option
177      * @return the string value of the option with a given name or <samp>null
178      *         </samp> if not found.
179      */
180     public String   getStringOption(String   name) {
181         TemplateOption option = (TemplateOption) options.get(name);
182         if (option != null) {
183             if (option instanceof StringOption)
184                 return ((StringOption) option).getText();
185             else if (option instanceof ComboChoiceOption) {
186                 // Added by DG: selection of the choice option
187                 // should also be considered if the selected
188                 // value is a String.
189                 ComboChoiceOption ccoption = (ComboChoiceOption)option;
190                 Object   value = ccoption.getValue();
191                 if (value!=null && value instanceof String  )
192                     return (String  )value;
193             }
194         }
195         return null;
196     }
197     /**
198      * Returns a boolean value of the option with a given name. The option with
199      * that name must exist and must be registered as a boolean option to begin
200      * with.
201      * 
202      * @param key
203      *            the unique name of the option
204      * @return the boolean value of the option with a given name or <samp>null
205      *         </samp> if not found.
206      */
207     public boolean getBooleanOption(String   key) {
208         TemplateOption option = (TemplateOption) options.get(key);
209         if (option != null && option instanceof BooleanOption) {
210             return ((BooleanOption) option).isSelected();
211         }
212         return false;
213     }
214     /**
215      * Enables the option with a given name. The exact effect of the method
216      * depends on the option type, but the end-result should always be the same -
217      * users should not be able to modify values of disabled options. This
218      * method has no effect if the option with a given name is not found.
219      * 
220      * @param name
221      *            the unique name of the option
222      * @param enabled
223      *            the enable state that the option should have
224      */
225     public void setOptionEnabled(String   name, boolean enabled) {
226         TemplateOption option = (TemplateOption) options.get(name);
227         if (option != null)
228             option.setEnabled(enabled);
229     }
230     /**
231      * Returns the value of the option with a given name. The actual type of the
232      * returned object depends on the option type.
233      * 
234      * @param name
235      *            the name of the option
236      * @return the current value of the option with a specified name or
237      *         <samp>null </samp> if not found or not applicable.
238      */
239     public Object   getValue(String   name) {
240         TemplateOption option = (TemplateOption) options.get(name);
241         if (option != null)
242             return option.getValue();
243         return super.getValue(name);
244     }
245     /**
246      * Returns true if this template depends on values set in the parent wizard.
247      * Values in the parent wizard include plug-in id, plug-in name, plug-in
248      * class name, plug-in provider etc. If the template does depend on these
249      * values, <samp>initializeFields </samp> will be called when the page is
250      * made visible in the forward direction (going from the first page to the
251      * pages owned by this template). If the page is never shown (Finish is
252      * pressed before the page is made visible at least once),
253      * <samp>initializeFields </samp> will be called with the model object
254      * instead during template execution. The same method will also be called
255      * when the template is created within the context of the plug-in manifest
256      * editor, because plug-in model already exists at that time.
257      * 
258      * @return <code>true</code> if this template depends on the data set in
259      *         the parent wizard, <code>false</code> otherwise.
260      */
261     public boolean isDependentOnParentWizard() {
262         return false;
263     }
264     /**
265      * Initializes options in the wizard page using the data provided by the
266      * method parameters. Some options may depend on the user selection in the
267      * common wizard pages before template page has been shown (for example,
268      * plug-in ID, plug-in name etc.). This method allows options to initialize
269      * in respect to these values.
270      * <p>
271      * The method is called before the actual plug-in has been built.
272      * </p>
273      * 
274      * @param data
275      *            plug-in data as defined in the common plug-in project wizard
276      *            pages
277      */
278     protected void initializeFields(IFieldData data) {
279     }
280     /**
281      * Initializes options in the wizard page using the data provided by the
282      * method parameters. Some options may depend on the user selection in the
283      * common wizard pages before template page has been shown (for example,
284      * plug-in ID, plug-in name etc.). This method allows options to initialize
285      * in respect to these values.
286      * <p>
287      * This method is called after the plug-in has already been created or as
288      * part of new extension creation (inside the manifest editor). Either way,
289      * the plug-in properties in the model have been fully set and the model can
290      * be used to initialize options that cannot be initialized independently.
291      * 
292      * @param model
293      *            the model of the plug-in manifest file.
294      */
295     public void initializeFields(IPluginModelBase model) {
296     }
297     /**
298      * Subclasses must implement this method in order to validate options whose
299      * value have been changed by the user. The subclass can elect to validate
300      * the option on its own, or to also check validity of other options in
301      * relation to the new value of this one.
302      * 
303      * @param changed
304      *            the option whose value has been changed by the user
305      */
306     public abstract void validateOptions(TemplateOption changed);
307     /**
308      * Expands variable substitution to include all string options defined in
309      * this template.
310      * 
311      * @see AbstractTemplateSection#getReplacementString(String, String)
312      */
313     public String   getReplacementString(String   fileName, String   key) {
314         String   value = getStringOption(key);
315         if (value != null)
316             return value;
317         return super.getReplacementString(fileName, key);
318     }
319     /**
320      * Modifies the superclass implementation by adding the initialization step
321      * before commencing execution. This is important because some options may
322      * not be initialized and users may choose to press 'Finish' before the
323      * wizard page where the options are were shown for the first time.
324      */
325     public void execute(IProject project, IPluginModelBase model,
326             IProgressMonitor monitor) throws CoreException {
327         initializeFields(model);
328         super.execute(project, model, monitor);
329     }
330     /**
331      * Registers the provided option and sets the initial value.
332      * 
333      * @param option
334      *            the option to register
335      * @param value
336      *            the initial value
337      * @param pageIndex
338      *            the page index to which this option belongs
339      */
340     protected void registerOption(TemplateOption option, Object   value,
341             int pageIndex) {
342         option.setValue(value);
343         options.put(option.getName(), option);
344     }
345 
346     private TemplateOption getOption(String   key) {
347         return (TemplateOption) options.get(key);
348     }
349 }
350
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags