Desktop: Add a button in dockbar to get the help about the component
[scilab.git] / scilab / modules / gui / src / java / org / scilab / modules / gui / helpbrowser / ScilabHelpBrowser.java
1 /*
2  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
3  * Copyright (C) 2008 - INRIA - Vincent Couvert
4  * Copyright (C) 2011 - Calixte DENIZET
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  */
13
14 package org.scilab.modules.gui.helpbrowser;
15
16 import java.awt.Component;
17 import java.awt.Container;
18 import java.awt.KeyEventDispatcher;
19 import java.awt.KeyboardFocusManager;
20 import java.awt.Toolkit;
21 import java.awt.event.KeyEvent;
22
23 import javax.swing.SwingUtilities;
24
25 import org.scilab.modules.commons.ScilabCommons;
26 import org.scilab.modules.commons.ScilabConstants;
27 import org.scilab.modules.commons.gui.ScilabGUIUtilities;
28 import org.scilab.modules.gui.bridge.ScilabBridge;
29 import org.scilab.modules.gui.bridge.helpbrowser.SwingScilabHelpBrowser;
30 import org.scilab.modules.gui.bridge.tab.SwingScilabTab;
31 import org.scilab.modules.gui.bridge.window.SwingScilabWindow;
32 import org.scilab.modules.gui.console.ScilabConsole;
33 import org.scilab.modules.gui.dockable.ScilabDockable;
34 import org.scilab.modules.gui.events.callback.ScilabCallBack;
35 import org.scilab.modules.gui.menubar.MenuBar;
36 import org.scilab.modules.gui.tab.ScilabTab;
37 import org.scilab.modules.gui.tab.Tab;
38 import org.scilab.modules.gui.tabfactory.HelpBrowserTab;
39 import org.scilab.modules.gui.tabfactory.HelpBrowserTabFactory;
40 import org.scilab.modules.gui.tabfactory.ScilabTabFactory;
41 import org.scilab.modules.gui.textbox.ScilabTextBox;
42 import org.scilab.modules.gui.textbox.TextBox;
43 import org.scilab.modules.gui.utils.ClosingOperationsManager;
44 import org.scilab.modules.gui.utils.ConfigManager;
45 import org.scilab.modules.gui.utils.MenuBarBuilder;
46 import org.scilab.modules.gui.utils.Position;
47 import org.scilab.modules.gui.utils.Size;
48 import org.scilab.modules.gui.utils.WindowsConfigurationManager;
49 import org.scilab.modules.gui.window.ScilabWindow;
50 import org.scilab.modules.gui.window.Window;
51 import org.scilab.modules.localization.Messages;
52
53 /**
54  * Class for Scilab Help Browser in GUIs
55  * @author Vincent COUVERT
56  * @author Calixte DENIZET
57  */
58 public class ScilabHelpBrowser extends ScilabDockable implements HelpBrowser {
59
60     public static final String HELPUUID = "d1ef5062-533e-4aee-b12a-66740820d6d1";
61
62     private static final String SCI = ScilabConstants.SCI.getPath();
63     private static final String MENUBARXMLFILE = SCI + "/modules/gui/etc/helpbrowser_menubar.xml";
64     private static final boolean isMac = System.getProperty("os.name").toLowerCase().indexOf("mac") != -1;
65
66     private static HelpBrowser instance;
67     private static Tab helpTab;
68
69     private static String language;
70     private static String[] helps;
71
72     static {
73         ScilabTabFactory.getInstance().addTabFactory(HelpBrowserTabFactory.getInstance());
74     }
75
76     private SimpleHelpBrowser component;
77     private Window parentWindow;
78
79     /**
80      * Constructor
81      * @param helps help chapters and directories
82      * @param language Scilab current language
83      */
84     protected ScilabHelpBrowser(String[] helps, String language) {
85         if (language == null) {
86             language = ScilabCommons.getlanguage();
87         }
88         component = ScilabBridge.createHelpBrowser(helps, language);
89     }
90
91     /**
92      * Creates a SwingScilabTab containing the help browser
93      * @return the corresponding SwingScilabTab
94      */
95     public static SwingScilabTab createHelpBrowserTab() {
96         helpTab = ScilabTab.createTab(Messages.gettext("Help Browser"), HELPUUID);
97         String lastID = restoreHelpBrowserState();
98
99         instance = new ScilabHelpBrowser(helps, language);
100         helpTab.addMember(instance);
101
102         MenuBar menubar = MenuBarBuilder.buildMenuBar(MENUBARXMLFILE);
103         helpTab.addMenuBar(menubar);
104
105         TextBox infobar = ScilabTextBox.createTextBox();
106         helpTab.addInfoBar(infobar);
107
108         KeyboardFocusManager manager = KeyboardFocusManager.getCurrentKeyboardFocusManager();
109         manager.addKeyEventDispatcher(new KeyEventDispatcher() {
110                 // This is a workaround for Mac OS X where e.getKeyCode() sometimes returns a bad value
111                 public boolean dispatchKeyEvent(KeyEvent e) {
112                     if (e.getID() == KeyEvent.KEY_PRESSED) {
113                         Container c = SwingUtilities.getAncestorOfClass(SwingScilabWindow.class, (SwingScilabTab) helpTab.getAsSimpleTab());
114                         if (e.getSource() instanceof Component) {
115                             Container cs = SwingUtilities.getAncestorOfClass(SwingScilabWindow.class, (Component) e.getSource());
116                             char chr = e.getKeyChar();
117
118                             if (cs == c && ((chr == '-' || chr == '_' || chr == '=' || chr == '+')
119                                             && (e.getModifiers() & Toolkit.getDefaultToolkit().getMenuShortcutKeyMask()) != 0)) {
120                                 if (chr == '-' || chr == '_') {
121                                     ((SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component).decreaseFont();
122                                 } else {
123                                     ((SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component).increaseFont();
124                                 }
125                                 return true;
126                             }
127                         }
128                     }
129                     return false;
130                 }
131             });
132
133         SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
134         browser.setCurrentID(lastID);
135         ((SwingScilabTab) helpTab.getAsSimpleTab()).setAssociatedXMLIDForHelp("helpbrowser");
136         WindowsConfigurationManager.restorationFinished((SwingScilabTab) helpTab.getAsSimpleTab());
137
138         return (SwingScilabTab) helpTab.getAsSimpleTab();
139     }
140
141     /**
142      * Creates a Scilab Help Browser
143      * @param helps help chapters and directories
144      * @param language Scilab current language
145      * @return the created Help Browser
146      */
147     public static HelpBrowser createHelpBrowser(String[] helps, String language) {
148         if (instance == null) {
149             ScilabHelpBrowser.language = language;
150             ScilabHelpBrowser.helps = helps;
151             boolean success = WindowsConfigurationManager.restoreUUID(HELPUUID);
152             if (!success) {
153                 HelpBrowserTabFactory.getInstance().getTab(HELPUUID);
154                 ((ScilabHelpBrowser) instance).setParentWindow();
155                 ((ScilabHelpBrowser) instance).parentWindow.addTab(helpTab);
156                 ((ScilabHelpBrowser) instance).parentWindow.setVisible(true);
157             }
158
159             if (ScilabConsole.isExistingConsole() && ScilabConsole.getConsole().getInfoBar() != null) {
160                 if (ScilabConsole.getConsole().getInfoBar().getText().equals(Messages.gettext("Loading help browser..."))) {
161                     // An error occured
162                     ScilabConsole.getConsole().getInfoBar().setText("");
163                     return null;
164                 }
165             }
166         }
167
168         SwingScilabWindow window = (SwingScilabWindow) SwingUtilities.getAncestorOfClass(SwingScilabWindow.class, (SwingScilabTab) helpTab.getAsSimpleTab());
169         ScilabGUIUtilities.toFront(window);
170
171         return instance;
172     }
173
174     /**
175      * Set a default parent window
176      */
177     public void setParentWindow() {
178         this.parentWindow = ScilabWindow.createWindow();
179         SwingScilabWindow window = (SwingScilabWindow) parentWindow.getAsSimpleWindow();
180         window.setLocation(0, 0);
181         window.setSize(500, 500);
182     }
183
184     /**
185      * Display the home page
186      */
187     public static void startHomePage() {
188         if (instance != null) {
189             SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
190             try {
191                 browser.displayHomePage();
192             } catch (Exception e) {
193                 System.err.println("This error should not occured, please report it at bugzilla.scilab.org\n" + e);
194             }
195         }
196     }
197
198     /**
199      * @return the current displayed url as String
200      */
201     public String getCurrentURL() {
202         SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
203         return browser.getCurrentURL();
204     }
205
206     /**
207      * @return the current displayed url as String
208      */
209     public String getCurrentID() {
210         SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
211         return browser.getCurrentID();
212     }
213
214     /**
215      * Increase the font of the help viewer
216      */
217     public void increaseFont() {
218         SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
219         browser.increaseFont();
220     }
221
222     /**
223      * Decrease the font of the help viewer
224      */
225     public void decreaseFont() {
226         SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
227         browser.decreaseFont();
228     }
229
230     /**
231      * Display the home page
232      */
233     public void showSearchField() {
234         SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
235         browser.showSearchField();
236     }
237
238     /**
239      * Display the home page
240      */
241     public void hideSearchField() {
242         SwingScilabHelpBrowser browser = (SwingScilabHelpBrowser) ((ScilabHelpBrowser) instance).component;
243         browser.hideSearchField();
244     }
245
246     /**
247      * Get the Scilab Help Browser
248      * @return the console
249      */
250     public static HelpBrowser getHelpBrowser() {
251         if (instance == null) {
252             instance = new ScilabHelpBrowser(null, "en_US");
253         }
254         return instance;
255     }
256
257     /**
258      * Get the Scilab Help Browser (does not create it is not existing)
259      * @return the console
260      */
261     public static HelpBrowser getHelpBrowserWithoutCreation() {
262         return instance;
263     }
264
265     /**
266      * Display the Help Browser
267      */
268     public void display() {
269         ScilabBridge.display(this);
270     }
271
272     /**
273      * Display the help page for a specified keyword
274      * @param keyword the keyword
275      */
276     public void searchKeywork(String keyword) {
277         ScilabBridge.searchKeywork(this, keyword);
278     }
279
280     /**
281      * Display the result of a full-text search for a specified word
282      * @param keyword the keyword
283      */
284     public void fullTextSearch(String keyword) {
285         ScilabBridge.fullTextSearch(this, keyword);
286     }
287
288     /**
289      * Close the HelpBrowser
290      */
291     public void closeHelpBrowser() {
292         saveHelpBrowserState();
293         instance = null;
294     }
295
296     /**
297      * Close the HelpBrowser
298      */
299     public static void closeHB() {
300         ((ScilabHelpBrowser) instance).closeHelpBrowser();
301     }
302
303     /**
304      * Close the HelpBrowser
305      */
306     public void close() {
307         ClosingOperationsManager.startClosingOperation((SwingScilabTab) helpTab.getAsSimpleTab());
308     }
309
310     /**
311      * Not used
312      */
313     public void draw() {
314         throw new UnsupportedOperationException();
315     }
316
317     /**
318      * Gets this Bridge component object
319      * @return this Bridge component object
320      */
321     public SimpleHelpBrowser getAsSimpleHelpBrowser() {
322         return component;
323     }
324
325     /**
326      * Not used
327      * @return nothing
328      */
329     public Size getDims() {
330         throw new UnsupportedOperationException();
331     }
332
333     /**
334      * Not used
335      * @return nothing
336      */
337     public Position getPosition() {
338         throw new UnsupportedOperationException();
339     }
340
341     /**
342      * Not used
343      * @return nothing
344      */
345     public boolean isVisible() {
346         throw new UnsupportedOperationException();
347     }
348
349     /**
350      * Not used
351      * @param newSize not used
352      */
353     public void setDims(Size newSize) {
354         throw new UnsupportedOperationException();
355     }
356
357     /**
358      * Not used
359      * @param newPosition not used
360      */
361     public void setPosition(Position newPosition) {
362         throw new UnsupportedOperationException();
363     }
364
365     /**
366      * Not used
367      * @param newVisibleState not used
368      */
369     public void setVisible(boolean newVisibleState) {
370         throw new UnsupportedOperationException();
371     }
372
373     /**
374      * Get associated InfoBar
375      * @return the infobar of the parent tab
376      * @see org.scilab.modules.gui.uielement.ScilabUIElement#getInfoBar()
377      */
378     public TextBox getInfoBar() {
379         return helpTab.getInfoBar();
380     }
381
382
383     /**
384      * Save the state of this help browser
385      */
386     public void saveHelpBrowserState() {
387         ConfigManager.saveHelpBrowserState(getCurrentID());
388     }
389
390     /**
391      * Restore the state of this help browser
392      * @return the last id displayed in the browser
393      */
394     public static String restoreHelpBrowserState() {
395         return ConfigManager.getHelpBrowserState();
396     }
397 }