OptionTemplateSection


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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.net.MalformedURLException  ;
13  import java.net.URL  ;
14  import java.util.ArrayList  ;
15  
16  import org.eclipse.jface.wizard.IWizardContainer;
17  import org.eclipse.jface.wizard.WizardPage;
18  import org.eclipse.osgi.util.NLS;
19  import org.eclipse.pde.internal.ui.PDEUIMessages;
20  
21  /**
22   * This class adds some conventions to the class it is based on. For example, it
23   * expects to find the template content in the following location:
24   * 
25   * <pre>
26   * 
27   *     [install location]/[templateDirectory]/[sectionId]
28   *  
29   * </pre>
30   * 
31   * where <code>templateDirectory</code> is expected to be 'templates_3.0' (to
32   * distinguish from template designed for earlier Eclipse versions), and
33   * <code>sectionId</code> is the unique identifier as reported by the template
34   * section.
35   * <p>
36   * It also assumes that all wizard pages associated with this template will be
37   * based on <code>OptionTemplateWizardPage</code>.
38   * 
39   * 
40   * @since 2.0
41   */
42  
43  public abstract class OptionTemplateSection extends BaseOptionTemplateSection {
44      private ArrayList   pages = new ArrayList  ();
45  
46      private static class TemplatePage {
47          WizardPage page;
48          ArrayList   options;
49          public TemplatePage() {
50              options = new ArrayList  ();
51          }
52      }
53  
54      /**
55       * The default constructor.
56       */
57      public OptionTemplateSection() {
58      }
59  
60      /**
61       * Returns the unique name of this section. This name will be used to
62       * construct name and description lookup keys, as well as the template file
63       * location in the contributing plug-in.
64       * 
65       * @return the unique section Id
66       * @see #getLabel()
67       * @see #getDescription()
68       * @see #getTemplateLocation()
69       */
70      public abstract String   getSectionId();
71  
72      /**
73       * Returns the directory where all the templates are located in the
74       * contributing plug-in.
75       * 
76       * @return "templates_[schemaVersion]" for code since Eclipse 3.0, or
77       *         "templates" for pre-3.0 code.
78       */
79      protected String   getTemplateDirectory() {
80          String   schemaVersion = model.getPluginBase().getSchemaVersion();
81          if (schemaVersion != null)
82              return "templates_" + schemaVersion; //$NON-NLS-1$
83          return "templates"; //$NON-NLS-1$
84      }
85      /**
86       * Returns the install URL of the plug-in that contributes this template.
87       * 
88       * @return the install URL of the contributing plug-in
89       */
90      protected abstract URL   getInstallURL();
91  
92      /**
93       * Implements the abstract method by looking for templates using the
94       * following path:
95       * <p>
96       * [install location]/[templateDirectory]/[sectionId]
97       * 
98       * @return the URL of the location where files to be emitted by this
99       *         template are located.
100      */
101     public URL   getTemplateLocation() {
102         URL   url = getInstallURL();
103         try {
104             String   location = getTemplateDirectory() + "/" //$NON-NLS-1$
105             + getSectionId() + "/"; //$NON-NLS-1$
106             return new URL  (url, location);
107         } catch (MalformedURLException   e) {
108             return null;
109         }
110     }
111     /**
112      * Returns the wizard page at the specified index. Pages must be created
113      * prior to calling this method.
114      * 
115      * @return the wizard page at the specified index or <samp>null </samp> if
116      *         invalid index.
117      * @see #createPage(int)
118      */
119     public WizardPage getPage(int pageIndex) {
120         if (pageIndex < 0 || pageIndex >= pages.size())
121             return null;
122         TemplatePage tpage = (TemplatePage) pages.get(pageIndex);
123         return tpage.page;
124     }
125 
126     /**
127      * Creates the wizard page for the specified page index. This method cannot
128      * be called before setPageCount(int). The page will be created with all the
129      * options registered for that page index. Therefore, make all the calls to
130      * addOption() before calling this method.
131      * 
132      * @param pageIndex
133      *            a zero-based index of the page relative to this template. For
134      *            example, if a template needs to have two pages, you have to
135      *            call this method twice (once with index 0 and again with index
136      *            1).
137      * @see #setPageCount(int)
138      * @see BaseOptionTemplateSection#addOption
139      */
140     public WizardPage createPage(int pageIndex) {
141         if (pageIndex < 0 || pageIndex >= pages.size())
142             return null;
143         TemplatePage tpage = (TemplatePage) pages.get(pageIndex);
144         tpage.page = new OptionTemplateWizardPage(this, tpage.options, null);
145         return tpage.page;
146     }
147     /**
148      * Creates the wizard page for the specified page index. This method cannot
149      * be called before setPageCount(int). The page will be created with all the
150      * options registered for that page index. Therefore, make all the calls to
151      * addOption() before calling this method.
152      * 
153      * @param pageIndex
154      *            a zero-based index of the page relative to this template. For
155      *            example, if a template need to have two pages, you have to
156      *            call this method twice (once with index 0 and again with index
157      *            1).
158      * @param helpContextId
159      *            the Id of the help context defined in the contributing plug-in
160      *            that will be used to locate content of the info-pop displayed
161      *            when F1 is pressed.
162      * @see #setPageCount(int)
163      * @see BaseOptionTemplateSection#addOption
164      */
165     public WizardPage createPage(int pageIndex, String   helpContextId) {
166         if (pageIndex < 0 || pageIndex >= pages.size())
167             return null;
168         TemplatePage tpage = (TemplatePage) pages.get(pageIndex);
169         tpage.page = new OptionTemplateWizardPage(this, tpage.options,
170                 helpContextId);
171         return tpage.page;
172     }
173     /**
174      * Returns a number of pages that this template contributes to the wizard.
175      * 
176      * @return the number of pages
177      * @see #setPageCount(int)
178      */
179     public int getPageCount() {
180         return pages.size();
181     }
182 
183     /**
184      * Sets the number of pages this template will manage. This method must be
185      * called prior to adding pages and options in order to initialize the
186      * template. Once the method has been called, you can call methods that
187      * accept page index in the range [0..count-1].
188      * 
189      * @param count
190      *            number of pages that this template will contribute to the
191      *            template wizard
192      */
193     public void setPageCount(int count) {
194         pages.clear();
195         for (int i = 0; i < count; i++) {
196             pages.add(new TemplatePage());
197         }
198     }
199 
200     /**
201      * Returns options that belong to the page with the given index.
202      * 
203      * @param pageIndex
204      *            0-based index of the template page
205      * @return @see #setPageCount(int)
206      */
207 
208     public TemplateOption[] getOptions(int pageIndex) {
209         if (pageIndex < 0 || pageIndex >= pages.size())
210             return new TemplateOption[0];
211         TemplatePage page = (TemplatePage) pages.get(pageIndex);
212         return (TemplateOption[]) page.options
213         .toArray(new TemplateOption[page.options.size()]);
214     }
215 
216     /**
217      * Returns options that are added to the provided wizard page.
218      * 
219      * @param page
220      *            wizard page that hosts required options
221      * @return array of options added to the provided wizard page
222      */
223 
224     public TemplateOption[] getOptions(WizardPage page) {
225         for (int i = 0; i < pages.size(); i++) {
226             TemplatePage tpage = (TemplatePage) pages.get(i);
227             if (tpage.page.equals(page))
228                 return getOptions(i);
229         }
230         return new TemplateOption[0];
231     }
232 
233     /**
234      * Returns the zero-based index of a page that hosts the the given option.
235      * 
236      * @param option
237      *            template option for which a page index is being requested
238      * @return zero-based index of a page that hosts the option or -1 if none of
239      *         the pages contain the option.
240      */
241     public int getPageIndex(TemplateOption option) {
242         for (int i = 0; i < pages.size(); i++) {
243             TemplatePage tpage = (TemplatePage) pages.get(i);
244             if (tpage.options.contains(option))
245                 return i;
246         }
247         return -1;
248     }
249 
250     /**
251      * Returns the label of this template to be used in the UI. The label is
252      * obtained by creating a lookup key using the following rule:
253      * "template.[section-id].name". This key is used to locate the label in the
254      * plugin.properties file of the plug-in that contributed this template.
255      * 
256      * @return the translated label of this template
257      */
258     public String   getLabel() {
259         String   key = "template." + getSectionId() + ".name"; //$NON-NLS-1$ //$NON-NLS-2$
260         return getPluginResourceString(key);
261     }
262     /**
263      * Returns the description of this template to be used in the UI. The
264      * description is obtained by creating a lookup key using the following
265      * rule: "template.[section-id].desc". This key is used to locate the label
266      * in the plugin.properties file of the plug-in that contributed this
267      * template.
268      * 
269      * @return the translated description of this template
270      */
271     public String   getDescription() {
272         String   key = "template." + getSectionId() + ".desc"; //$NON-NLS-1$ //$NON-NLS-2$
273         return getPluginResourceString(key);
274     }
275     /**
276      * Locates the page that this option is presented in and flags that the
277      * option is required and is currently not set. The flagging is done by
278      * setting the page incomplete and setting the error message that uses
279      * option's message label.
280      * 
281      * @param option
282      *            the option that is required and currently not set
283      */
284     protected void flagMissingRequiredOption(TemplateOption option) {
285         WizardPage page = null;
286         for (int i = 0; i < pages.size(); i++) {
287             TemplatePage tpage = (TemplatePage) pages.get(i);
288             ArrayList   list = tpage.options;
289             if (list.contains(option)) {
290                 page = tpage.page;
291                 break;
292             }
293         }
294         if (page != null) {
295             page.setPageComplete(false);
296             String   message = NLS.bind(PDEUIMessages.OptionTemplateSection_mustBeSet, option.getMessageLabel());
297             page.setErrorMessage(message);
298         }
299     }
300 
301     /**
302      * Resets the current page state by clearing the error message and making
303      * the page complete, thereby allowing users to flip to the next page.
304      */
305     protected void resetPageState() {
306         if (pages.size() == 0)
307             return;
308         WizardPage firstPage = ((TemplatePage) pages.get(0)).page;
309         IWizardContainer container = firstPage.getWizard().getContainer();
310         WizardPage currentPage = (WizardPage) container.getCurrentPage();
311         currentPage.setErrorMessage(null);
312         currentPage.setPageComplete(true);
313     }
314 
315     protected void registerOption(TemplateOption option, Object   value,
316             int pageIndex) {
317         super.registerOption(option, value, pageIndex);
318         if (pageIndex >= 0 && pageIndex < pages.size()) {
319             TemplatePage tpage = (TemplatePage) pages.get(pageIndex);
320             tpage.options.add(option);
321         }
322     }
323 
324     /**
325      * Validate options given a template option
326      */
327     public void validateOptions(TemplateOption source) {
328         if (source.isRequired() && source.isEmpty()) {
329             flagMissingRequiredOption(source);
330         }
331         validateContainerPage(source);
332     }
333 
334     private void validateContainerPage(TemplateOption source) {
335         TemplateOption[] allPageOptions = getOptions(0);
336         for (int i = 0; i < allPageOptions.length; i++) {
337             TemplateOption nextOption = allPageOptions[i];
338             if (nextOption.isRequired() && nextOption.isEmpty()) {
339                 flagMissingRequiredOption(nextOption);
340                 return;
341             }
342         }
343         resetPageState();
344     }
345     
346 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags