home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgLangD.iso / VCAFE.3.0A / Main.bin / VisualCafe.java < prev    next >
Text File  |  1998-10-25  |  31KB  |  862 lines
  1. /*
  2.  * Copyright 1998 Symantec Corporation, All Rights Reserved.
  3.  */
  4.  
  5. package com.symantec.itools.vcafe.openapi;
  6.  
  7. import java.awt.Rectangle;
  8. import java.awt.MenuBar;
  9. import java.awt.Menu;
  10. import java.awt.event.ActionListener;
  11. import java.beans.PropertyChangeListener;
  12. import java.util.Vector;
  13. import java.util.Enumeration;
  14. import java.io.File;
  15. import com.sun.java.swing.LookAndFeel;
  16. import com.sun.java.swing.JComponent;
  17. import com.symantec.itools.vcafe.openapi.datatransfer.VisualCafeClipboard;
  18. import com.symantec.itools.vcafe.openapi.options.EnvironmentOptionSet;
  19. import com.symantec.itools.vcafe.openapi.pluginapi.OptionsWindow;
  20. import com.symantec.itools.vcafe.openapi.dtreflect.DTListener;
  21.  
  22. /**
  23.  * The <code>VisualCafe</code> class provides the initial and primary interface used by Visual Cafe
  24.  * plug-ins.  Using this class a plug-in can obtain access to Visual Cafe projects,
  25.  * project files, source files, environment options, the clipboard, component library
  26.  * and more.
  27.  * Use the <code>getVisualCafe()</code> method to access the one-and-only instance of this class.
  28.  * @see VisualCafe#getVisualCafe
  29.  *
  30.  * @author Symantec Internet Tools Division
  31.  * @version 1.0
  32.  * @since VCafe 3.0
  33.  */
  34. public abstract class VisualCafe
  35. {
  36.     /**
  37.      * Project options
  38.      * @see    VisualCafe#getOptionsWindow
  39.      */
  40.     public static final int PROJECT_OPTIONS                        = 4;
  41.  
  42.     /**
  43.      * Environment options
  44.      * @see    VisualCafe#getOptionsWindow
  45.      */
  46.     public static final int ENVIRONMENT_OPTIONS                    = 5;
  47.  
  48.     /**
  49.      * The popup menu that appears upon right-mouse click in objects tab of project window
  50.      * @see    VisualCafe#getContextualMenu
  51.      */
  52.     public static final int OBJECT_VIEW_TAB_POPUP                = 6;
  53.  
  54.     /**
  55.      * The popup menu that appears upon right-mouse click in packages tab of project window
  56.      * @see    VisualCafe#getContextualMenu
  57.      */
  58.     public static final int PACKAGE_VIEW_TAB_POPUP                = 7;
  59.  
  60.     /**
  61.      * The popup menu that appears upon right-mouse click in files tab of project window
  62.      * @see    VisualCafe#getContextualMenu
  63.      */
  64.     public static final int FILE_VIEW_TAB_POPUP                    = 8;
  65.  
  66.     /**
  67.      * The popup menu that appears upon right-mouse click in source code editor window
  68.      * @see    VisualCafe#getContextualMenu
  69.      */
  70.     public static final int SOURCE_EDITOR_POPUP                    = 9;
  71.  
  72.     /**
  73.      * The popup menu that appears upon right-mouse click in form editor window
  74.      * @see    VisualCafe#getContextualMenu
  75.      */
  76.     public static final int FORM_EDITOR_POPUP                    = 10;
  77.  
  78.     /**
  79.      * The popup menu that appears upon right-mouse click in component library window
  80.      * @see    VisualCafe#getContextualMenu
  81.      */
  82.     public static final int COMP_LIBRARY_POPUP                    = 11;
  83.  
  84.     /**
  85.      * The popup menu that appears upon right-mouse click in classes pane of class browser
  86.      * @see    VisualCafe#getContextualMenu
  87.      */
  88.     public static final int CLASS_BROWSER_CLASSES_PANE_POPUP    = 12;
  89.  
  90.     /**
  91.      * The popup menu that appears upon right-mouse click in members pane of class browser
  92.      * @see    VisualCafe#getContextualMenu
  93.      */
  94.     public static final int CLASS_BROWSER_MEMBERS_PANE_POPUP    = 13;
  95.  
  96.     /**
  97.      * The popup menu that appears upon right-mouse click in editor pane of class browser
  98.      * @see    VisualCafe#getContextualMenu
  99.      */
  100.     public static final int CLASS_BROWSER_EDITOR_PANE_POPUP        = 14;
  101.  
  102.     /**
  103.      * The menu text for undoing a cut operation.
  104.      * @see VisualCafe#beginUndo
  105.      * @see    VisualCafe#setUndoCommandName
  106.      */
  107.     public static String UNDOCUT;
  108.  
  109.     /**
  110.      * The menu text for undoing a paste operation.
  111.      * @see VisualCafe#beginUndo
  112.      * @see    VisualCafe#setUndoCommandName
  113.      */
  114.     public static String UNDOPASTE;
  115.  
  116.     /**
  117.      * The menu text for undoing a delete operation.
  118.      * @see VisualCafe#beginUndo
  119.      * @see    VisualCafe#setUndoCommandName
  120.      */
  121.     public static String UNDODELETE;
  122.  
  123.     /**
  124.      * The menu text for undoing a drag-n-drop operation.
  125.      * @see VisualCafe#beginUndo
  126.      * @see    VisualCafe#setUndoCommandName
  127.      */
  128.     public static String UNDODRAGDROP;
  129.  
  130.     /**
  131.      * The menu text for undoing a property edit operation.
  132.      * @see VisualCafe#beginUndo
  133.      * @see    VisualCafe#setUndoCommandName
  134.      */
  135.     public static String UNDOPROPERTYEDIT;
  136.  
  137.     /**
  138.      * The menu text for undoing an insert operation.
  139.      * @see VisualCafe#beginUndo
  140.      * @see    VisualCafe#setUndoCommandName
  141.      */
  142.     public static String UNDOINSERT;
  143.  
  144.  
  145.     /**
  146.      * Gets the object that implements the <code>VisualCafe</code> API.  There is only one instance of this
  147.      * class.  This method <b>never</b> returns <code>null</code>.
  148.      * @return the <code>VisualCafe</code> object.
  149.      */
  150.     public static VisualCafe getVisualCafe()
  151.     {
  152.         return visualCafe;
  153.     }
  154.  
  155.     /**
  156.      * Gets the top level menubar in Visual Cafe.
  157.      * @return a <code>MenuBar</code> object that represents the menu bar in Visual Cafe.
  158.      */
  159.     public abstract MenuBar getMenuBar();
  160.  
  161.     /**
  162.      * Returns an array of all of the open projects in Visual Cafe.
  163.      * If no projects are open, a zero-length array is returned.
  164.      * @return an array of <code>VisualProjects</code>
  165.      * @see #getProject
  166.      * @see #getTargetProject
  167.      */
  168.     public abstract VisualProject[] getProjects();
  169.  
  170.     /**
  171.      * Gets the target or current project in Visual Cafe.
  172.      * @return the current <code>VisualProject</code>, or <code>null</code> if no projects are open.
  173.      * @see #getProject
  174.      * @see #getProjects
  175.      */
  176.     public abstract VisualProject getTargetProject();
  177.  
  178.     /**
  179.      * Gets the open project with the given name in Visual Cafe.
  180.      * @param projectName the name of the open project.
  181.      * @return the named project, or <code>null</code> if it cannot be found.
  182.      * @see #getTargetProject
  183.      * @see #getProjects
  184.      */
  185.     public abstract VisualProject getProject(String projectName);
  186.  
  187.     /**
  188.      * Opens the project with the given name in Visual Cafe.
  189.      * The project becomes the target project.
  190.      * @param projectName the name of the project to open.
  191.      * @return the newly opened project, or <code>null</code> if it cannot be found.
  192.      * @see #getTargetProject
  193.      */
  194.     public abstract VisualProject openProject(String projectName);
  195.  
  196.     /**
  197.      * Creates a new project in Visual Cafe, using the specified <code>projectTemplate</code>.
  198.      * The project becomes the target project.
  199.      * @param projectTemplate a Project Template describing the initial state of the project.
  200.      * @return the new project, or <code>null</code> if it cannot be created.
  201.      * @see #getProjectTemplates
  202.      * @see #createEmptyProject
  203.      * @see #createDefaultProject
  204.      * @see #getTargetProject
  205.      */
  206.     public abstract VisualProject createProject(VisualObject projectTemplate);
  207.  
  208.     /**
  209.      * Creates a new project in Visual Cafe, using the Empty Project Template.
  210.      * The project becomes the target project.
  211.      * @return the new project, or <code>null</code> if it cannot be created.
  212.      * @see #getProjectTemplates
  213.      * @see #createProject
  214.      * @see #createDefaultProject
  215.      * @see #getTargetProject
  216.      */
  217.     public abstract VisualProject createEmptyProject();
  218.  
  219.     /**
  220.      * Creates a new project in Visual Cafe, using the default Project Template.
  221.      * The project becomes the target project.
  222.      * @return the new project, or <code>null</code> if it cannot be created.
  223.      * @see #getProjectTemplates
  224.      * @see #createProject
  225.      * @see #createEmptyProject
  226.      * @see #getTargetProject
  227.      */
  228.     public abstract VisualProject createDefaultProject();
  229.  
  230.     /**
  231.      * Returns an array of all of the installed Project Templates (as appearing
  232.      * in the Project Templates group of the Component Library).
  233.      * @return array of <code>VisualObjects</code> representing the installed Project Templates.
  234.      * @see #createProject
  235.      * @see #createEmptyProject
  236.      * @see #createDefaultProject
  237.      */
  238.     public abstract VisualObject[] getProjectTemplates();
  239.  
  240.     /**
  241.      * Returns an array of all of the open source files in Visual Cafe.
  242.      * If no source files are open, a zero-length array is returned.
  243.      * @return an array of open source files.
  244.      * @see #getSourceFile(String)
  245.      * @see #getSourceFile(File)
  246.      */
  247.     public abstract SourceFile[] getSourceFiles();
  248.  
  249.     /**
  250.      * Gets the <code>SourceFile</code> with the specified name.
  251.      * Note: unlike <code>getSourceFiles()</code>, this method will return a <code>SourceFile</code>
  252.      * even if it isn't currently open in Visual Cafe.
  253.      * @param filename name of the file to get.
  254.      * @return the named <code>SourceFile</code>, or <code>null</code> if not found.
  255.      * @see #getSourceFiles
  256.      * @see #getSourceFile(File)
  257.      */
  258.     public abstract SourceFile getSourceFile(String filename);
  259.  
  260.     /**
  261.      * Returns a <code>SourceFile</code> for the given <code>File</code>.
  262.      * Note: unlike <code>getSourceFiles()</code>, this method will return a <code>SourceFile</code>
  263.      * even if it isn't currently open in Visual Cafe.
  264.      * @param file the file to get.
  265.      * @return the <code>SourceFile</code>, or <code>null</code> if not found.
  266.      * @see #getSourceFiles
  267.      * @see #getSourceFile(String)
  268.      */
  269.     public abstract SourceFile getSourceFile(File file);
  270.  
  271.     /**
  272.      * Gets the Visual Repository object that allows access to Visual Cafe's Component Library.
  273.      * @return the <code>ComponentLibrary</code>.
  274.      * @see VisualRepository
  275.      * @see ComponentLibrary
  276.      */
  277.     public abstract ComponentLibrary getComponentLibrary();
  278.  
  279.     /**
  280.      * Get the <code>Attributes</code> object that global (program-wide) named value storage.
  281.      *
  282.      * The values stored in the returned <code>Attributes</code> object are associated with the Visual Cafe
  283.      * program (are global), not with a specific project.  To associate named values with a
  284.      * specific project, use that <code>VisualProject</code>'s <code>getAttributes()</code> method.
  285.      * @return the global <code>Attributes</code> storage object.
  286.      * @see VisualProject#getAttributes
  287.      */
  288.     public abstract Attributes getAttributes();
  289.  
  290.     /**
  291.      * Gets the <code>EnvironmentOptionSet</code> object which allows access to Visual Cafe's environment options.
  292.      *
  293.      * @return        the environment's options access API object.
  294.      */
  295.     public abstract EnvironmentOptionSet getEnvironmentOptionSet();
  296.  
  297.     /**
  298.      * Creates a new <code>VisualObject</code> that represents an object of the given class. The <code>Class</code> must
  299.      * already have an entry in the <code>ComponentLibrary</code>.
  300.      * @param clazz the <code>Class</code> of the new <code>VisualObject</code>.
  301.      * @return a new <code>VisualObject</code>.
  302.      * @see #createVisualObjectByName
  303.      */
  304.     public abstract VisualObject createVisualObject(Class clazz);
  305.  
  306.     /**
  307.      * Create a new <code>VisualObject</code> that represents an object of the given class. The class must
  308.      * already have an entry in the <code>ComponentLibrary</code>.
  309.      * @param className the class name of the new <code>VisualObject</code>.
  310.      * @return a new <code>VisualObject</code>.
  311.      * @see #createVisualObject
  312.      */
  313.     public abstract VisualObject createVisualObjectByName(String className);
  314.  
  315.     /**
  316.      * Adds a jar file to the Component Library in Visual Cafe.
  317.      * This performs the same action as using the Visual Cafe menus to insert a Component into
  318.      * the library (Insert -> Component into Library).
  319.      * Errors are reported in Visual Cafe's message window.
  320.      *
  321.      * @param jarFile       the full path of the jar file to be added.
  322.      */
  323.     public abstract void addJarToLibrary(String jarFile);
  324.  
  325.     //
  326.     // Object Editor Support
  327.     //
  328.     /**
  329.      * Register an editor to edit an object of type class. After this call, the listener will be
  330.      * notified when the user chooses to edit an object of the given class, from anywhere in the
  331.      * environment.
  332.      * @param targetClassNames array of strings denoting the type of objects for editing
  333.      * @param listener the object that receives notifications.
  334.      * example usage:<code>
  335.      *        // Register an object editor for SoftBevelBorder
  336.      *        String[] objectType = { "com.symantec.itools.swing.borders.SoftBevelBorder" };
  337.      *        VisualCafe.getVisualCafe().registerEditor(objectType, new SymObjectEditorAction());
  338.      *</code>
  339.      */
  340.     public abstract void registerEditor(String[] targetClassNames, ActionListener l);
  341.  
  342.     //
  343.     // Environment/Project Options Window Extension Support
  344.     //
  345.     /**
  346.      * Adds an <code>ActionListener</code>.  After this call, the listener will be notified
  347.      * when the user chooses to open Environment Options or Project Options window.
  348.      * @param optionType the type of options window. One of:<ul type=circle>
  349.      * <li>PROJECT_OPTIONS - the project options window
  350.      * <li>ENVIRONMENT_OPTIONS - the environment options window
  351.      * </ul>
  352.      * @param listener the object that receives notifications.
  353.      */
  354.     public abstract void addOptionsMenuItemListener(int optionType, ActionListener l);
  355.  
  356.     /**
  357.      * Removes a <code>ActionListener</code>. After this call, the listener will not
  358.      * be notified when the user chooses to open Environment Options or Project Options window.
  359.      * @param optionType the type of options window. One of:<ul type=circle>
  360.      * <li>PROJECT_OPTIONS - the project options window
  361.      * <li>ENVIRONMENT_OPTIONS - the environment options window
  362.      * </ul>
  363.      * @param listener the object that was receiving notifications.
  364.      */
  365.     public abstract void removeOptionsMenuItemListener(int optionType, ActionListener l);
  366.  
  367.     /**
  368.      * Returns the options window being opened in Visual Cafe.
  369.      * One of:<ul type=circle>
  370.      * <li>PROJECT_OPTIONS - the project options window
  371.      * <li>ENVIRONMENT_OPTIONS - the environment options window
  372.      * </ul>
  373.      * @return        the environment/project Options window
  374.      * @see OptionsWindow
  375.      */
  376.     public abstract OptionsWindow getOptionsWindow();
  377.  
  378.     //
  379.     // Contextual Menu Support
  380.     //
  381.     /**
  382.      * Returns a popup menu in Visual Cafe
  383.      * @param popupType the type of popup menu, one of:<ul type=circle>
  384.      * <li>OBJECT_VIEW_TAB_POPUP - popup menu in objects tab of project window,
  385.      * <li>PACKAGE_VIEW_TAB_POPUP - popup menu in packages tab of project window,
  386.      * <li>FILE_VIEW_TAB_POPUP - popup menu in files tab of project window,
  387.      * <li>SOURCE_EDITOR_POPUP - popup menu in source code editor window,
  388.      * <li>FORM_EDITOR_POPUP - popup menu in form editor window,
  389.      * <li>COMP_LIBRARY_POPUP - popup menu in component library window
  390.      * <li>CLASS_BROWSER_CLASSES_PANE_POPUP - popup menu in classes pane of class browser
  391.      * <li>CLASS_BROWSER_MEMBERS_PANE_POPUP - popup menu in members pane of class browser
  392.      * <li>CLASS_BROWSER_EDITOR_PANE_POPUP - popup menu in editor pane of class browser
  393.      * </ul>
  394.      * @return    the requested menu
  395.      * @see VisualMenu
  396.      */
  397.     public abstract VisualMenu getContextualMenu(int popupType);
  398.  
  399.     /**
  400.      * Sets an array of <code>VisualObjects</code> as active in the Property List of Visual Cafe.  The
  401.      * previously selected property remains selected if it exists for the list of objects.
  402.      *
  403.      * @param visualObjects an array containing objects of type <code>VisualObject</code>.
  404.      * @see #setActiveObjects(VisualObject[], boolean)
  405.      */
  406.     public void setActiveObjects(VisualObject[] visualObjects) {
  407.         setActiveObjects(visualObjects, false /*!forceDefaultProperty*/);
  408.     }
  409.  
  410.     /**
  411.      * Sets an array of <code>VisualObjects</code> as active in the Property List of Visual Cafe.
  412.      *
  413.      * @param visualObjects            an array containing objects of type <code>VisualObject</code>.
  414.      * @param forceDefaultProperty    if true, forces the default property for the object[s] to be selected.
  415.      *                                if false, the previously selected property remains selected (if it exists).
  416.      * @see #setActiveObjects(VisualObject[])
  417.      */
  418.     public abstract void setActiveObjects(VisualObject[] visualObjects, boolean forceDefaultProperty);
  419.  
  420.  
  421.     /**
  422.      * Gets an array of <code>VisualObjects</code> that are active in the Property List of Visual Cafe.
  423.      * If there are no active <code>VisualObjects</code>, a zero-length array is returned.
  424.      *
  425.      * @return      an array containing objects of type <code>VisualObject</code>.
  426.      */
  427.     public abstract VisualObject[] getActiveObjects();
  428.  
  429.  
  430.     /**
  431.      * Activates the Property List, showing it as needed.
  432.      * @see #activatePropertySheet(char)
  433.      */
  434.     public abstract void activatePropertySheet();
  435.  
  436.     /**
  437.      * Activates the Property List, showing it as needed, and sends the typed character to it.
  438.      * @param typedCharacter the character to send to the property sheet.
  439.      * @see #activatePropertySheet()
  440.      */
  441.     public abstract void activatePropertySheet(char typedCharacter);
  442.  
  443.  
  444.     /**
  445.      * Removes a <code>VisualObjectListener</code> from all <code>VisualObjects</code>.  After this call, the listener will
  446.      * not be listening to changes to <i>any</i> <code>VisualObject</code>.
  447.      *
  448.      * A <code>VisualObjectListener</code> can stop listening to a specific <code>VisualObject</code> by calling that
  449.      * <code>VisualObject</code>'s <code>removeVisualObjectListener()</code> method.
  450.      *
  451.      * @param listener the object that was receiving notifications
  452.      * @see VisualObject#addVisualObjectListener
  453.      * @see VisualObject#removeVisualObjectListener
  454.      */
  455.     public abstract void removeVisualObjectListener(VisualObjectListener listener);
  456.  
  457.  
  458.     /**
  459.      * Adds an <code>ActiveVisualObjectListener</code>.  After this call, the listener will be notified
  460.      * when a <code>VisualObject</code> is selected into the Property List.
  461.      *
  462.      * @param listener the object that receives notifications.
  463.      * @see #removeActiveVisualObjectListener()
  464.      * @see #setActiveObjects(VisualObject[])
  465.      */
  466.     public abstract void addActiveVisualObjectListener(ActiveVisualObjectListener listener);
  467.  
  468.     /**
  469.      * Removes an <code>ActiveVisualObjectListener</code>.  After this call, the listener will no longer be notified
  470.      * when a <code>VisualObject</code> is selected into the Property List.
  471.      *
  472.      * @param listener the object that was receiving notifications.
  473.      * @see VisualCafe#addActiveVisualObjectListener
  474.      * @see #setActiveObjects(VisualObject[])
  475.      */
  476.     public abstract void removeActiveVisualObjectListener(ActiveVisualObjectListener listener);
  477.  
  478.     /**
  479.      * Adds a <code>SourceFileListener</code> to all <code>SourceFiles</code>.  After this call, the listener will be
  480.      * listening to changes to <i>any</i> <code>SourceFile</code>.
  481.      *
  482.      * A <code>SourceFileListener</code> can listen to a specific <code>SourceFile</code> by calling that <code>SourceFile</code>'s
  483.      * <code>addSourceFileListener()</code> method.
  484.      *
  485.      * @param listener the object that receives notifications
  486.      * @see #removeSourceFileListener
  487.      * @see SourceFile#addSourceFileListener
  488.      */
  489.     public abstract void addSourceFileListener(SourceFileListener listener);
  490.  
  491.     /**
  492.      * Removes a <code>SourceFileListener</code> from all <code>SourceFiles</code>.  After this call, the listener will not
  493.      * be listening to changes to <i>any</i> <code>SourceFile</code>.
  494.      *
  495.      * A <code>SourceFileListener</code> can stop listenening to a specific <code>SourceFile</code> by calling that <code>SourceFile</code>'s
  496.      * <code>removeSourceFileListener()</code> method.
  497.      *
  498.      * @param listener the object that was receiving notifications.
  499.      * @see VisualCafe#addSourceFileListener
  500.      * @see SourceFile#removeSourceFileListener
  501.      */
  502.     public abstract void removeSourceFileListener(SourceFileListener listener);
  503.  
  504.  
  505.     /**
  506.      * Start listening to changes to Visual Cafe's project system.
  507.      *
  508.      * @param listener the object that receives notifications.
  509.      * @see VisualCafe#removeProjectSystemListener
  510.      */
  511.     public abstract void addProjectSystemListener(ProjectSystemListener listener);
  512.  
  513.     /**
  514.      * Stop listening to changes to Visual Cafe's project system.
  515.      *
  516.      * @param listener the object that was receiving notifications.
  517.      * @see VisualCafe#addProjectSystemListener
  518.      */
  519.     public abstract void removeProjectSystemListener(ProjectSystemListener listener);
  520.  
  521.  
  522.     /**
  523.      * Start listening to when classes' design time information is reparsed.
  524.      *
  525.      * @param listener the object that receives notifications.
  526.      * @see #removeDTListener
  527.      * @see VisualProject#addDTListener
  528.      * @see com.symantec.itools.vcafe.openapi.dtreflect.DTListener
  529.      */
  530.     public abstract void addDTListener(DTListener listener);
  531.  
  532.     /**
  533.      * Stop listening to when classes' design time information is reparsed.
  534.      *.
  535.      * @param listener the object that was receiving notifications.
  536.      * @see #addDTListener
  537.      * @see VisualProject#removeDTListener
  538.      * @see com.symantec.itools.vcafe.openapi.dtreflect.DTListener
  539.      */
  540.     public abstract void removeDTListener(DTListener listener);
  541.  
  542.  
  543.     //
  544.     // Online Help Support
  545.     //
  546.     /**
  547.      * Activates online help displaying the link specified by the given help id.
  548.      *
  549.      * @param helpId the help id to use. (Note: HID_BASE_RESOURCE is added before WinHelp() is invoked).
  550.      */
  551.     public abstract void invokeHelp(int helpId);
  552.  
  553.     /**
  554.      * Activates online help displaying the link specified by the given help id, in
  555.      * the specified help file.
  556.      *
  557.      * @param helpFile the (WinHelp) help file to use.
  558.      * @param helpId the help id to use. (Note: HID_BASE_RESOURCE is added before WinHelp() is invoked).
  559.      */
  560.     public abstract void invokeHelp(File helpFile, int helpId);
  561.  
  562.     /**
  563.      * Activates online help displaying the link specified by the given help id, in
  564.      * the help file with the specified name.  If the <code>helpFileName</code> doesn't contain
  565.      * a path, the "help" directory is assumed.
  566.      *
  567.      * @param helpFileName the name of the help file to use.
  568.      * @param helpId the help id to use. (Note: HID_BASE_RESOURCE is added before WinHelp() is invoked).
  569.      */
  570.     public abstract void invokeHelp(String helpFileName, int helpId);
  571.  
  572.  
  573.     /**
  574.      * Gets Visual Cafe's clipboard object.
  575.      *
  576.      * @return      the clipboard object that allows datatransfer between
  577.      *                Java and Visual Cafe.
  578.      */
  579.     public abstract VisualCafeClipboard getClipboard();
  580.  
  581.     //
  582.     // Undo Support
  583.     //
  584.  
  585.     /**
  586.      * Call before starting an undoable operation.
  587.      * @param commandName the command text for the undo menu, one of:<ul type=circle>
  588.      * <li>UNDOCUT - menu text for undoing a cut,
  589.      * <li>UNDOPASTE - menu text for undoing a paste,
  590.      * <li>UNDODELETE - menu text for undoing a delete,
  591.      * <li>UNDODRAGDROP - menu text for undoing a drag-n-drop,
  592.      * <li>UNDOPROPERTYEDIT - menu text for undoing a property edit,
  593.      * <li>UNDOINSERT - menu text for undoing an insert, or
  594.      * <li>any other text that specifies a different action.
  595.      * </ul>
  596.      */
  597.     public abstract void beginUndo(String commandName);
  598.  
  599.     /**
  600.      * Call when done with an undoable operation.
  601.      */
  602.     public abstract void endUndo();
  603.  
  604.     /**
  605.      * Call when starting an operation that can't be undone.
  606.      * Disables the "undo" menu selection.
  607.      */
  608.     public abstract void clearUndo();
  609.  
  610.     /**
  611.      * Sets the undo menu item to the specified text.
  612.      * @param commandName the command text for the undo menu, one of:<ul type=circle>
  613.      * <li>UNDOCUT - menu text for undoing a cut,
  614.      * <li>UNDOPASTE - menu text for undoing a paste,
  615.      * <li>UNDODELETE - menu text for undoing a delete,
  616.      * <li>UNDODRAGDROP - menu text for undoing a drag-n-drop,
  617.      * <li>UNDOPROPERTYEDIT - menu text for undoing a property edit,
  618.      * <li>UNDOINSERT - menu text for undoing an insert, or
  619.      * <li>any other text that specifies a different action.
  620.      * </ul>
  621.      */
  622.     public abstract void setUndoCommandName(String commandName);
  623.  
  624.     /**
  625.      * Returns an object that provides information about which edition of Visual Cafe is running.
  626.      * @return the object providing edition information.
  627.      * @see ProductEdition
  628.      */
  629.     public abstract ProductEdition getProductEdition();
  630.  
  631.     //
  632.     // Window Information
  633.     //
  634.  
  635.     /**
  636.      * Returns an object that represents the frontmost window.
  637.      * Currently, can return objects of type:
  638.      *        <code>VisualProject</code> (for active project windows), <code>SourceFile</code> (for active source editor windows),
  639.      *        and <code>VisualRepository</code> (for the Component Library).
  640.      * If the frontmost window is not one of these, <code>null</code> is returned.
  641.      * @return the topmost window object.
  642.      */
  643.     public abstract Object getFrontmostWindow();
  644.  
  645.     /**
  646.      * Returns an object that represents the frontmost SourceFile window.
  647.      * @return the topmost SourceFile object.
  648.      */
  649.     public abstract SourceFile getFrontmostSourceFile();
  650.  
  651.     /**
  652.      * Determines the current environment mode (MDI/SDI) of Visual Cafe.
  653.      *
  654.      * This method is valid only on the Windows platform. On the Macintosh
  655.      * platform, it returns false.
  656.      *
  657.      * @return      <code>true</code> for MDI, <code>false</code> for SDI.
  658.      */
  659.     public abstract boolean isMDIEnabled();
  660.  
  661.     /**
  662.      * Returns the dimensions of Visual Cafe's main frame window.
  663.      *
  664.      * @return      the bounds of the main frame window.
  665.      */
  666.     public abstract Rectangle getMainFrameBounds();
  667.  
  668.     /**
  669.      * Returns the dimensions of the client area of Visual Cafe's main frame window.
  670.      *
  671.      * @return      the bounds of the client area of the main frame window.
  672.      */
  673.     public abstract Rectangle getClientAreaBounds();
  674.  
  675.     /**
  676.      * Displays a message on Visual Cafe status bar.
  677.      *
  678.      * @param        the text to display.
  679.      */
  680.     public abstract void setMessageText(String message);
  681.  
  682.  
  683.     /**
  684.      * Indicate to the user that a lengthy operation is starting.  The Wait cursor is
  685.      * displayed until a matching call to <code>stopWaitCursor()</code>.
  686.      * This method <b>must</b> be matched by a call to <code>stopWaitCursor()</code>.
  687.      * example usage:<code>
  688.      *        VisualCafe.getVisualCafe().startWaitCursor();
  689.      *        try {
  690.      *            ...
  691.      *            ... lots of time consuming processing here ...
  692.      *            ...
  693.      *        } finally {
  694.      *            VisualCafe.getVisualCafe().stopWaitCursor();
  695.      *        }</code>
  696.      *
  697.      * @see #stopWaitCursor()
  698.      */
  699.     public abstract void startWaitCursor();
  700.  
  701.     /**
  702.      * Indicate that a lengthy operation has ended.  The cursor is restored to
  703.      * its appearance before <code>startWaitCursor()</code> was called.
  704.      *
  705.      * @see #startWaitCursor();
  706.      */
  707.     public abstract void stopWaitCursor();
  708.  
  709.  
  710.     //
  711.     // DesignTime LookAndFeel Support
  712.     //
  713.  
  714.     /**
  715.      * Gets the current design time look-and-feel.
  716.      *
  717.      * @return the current design time look-and-feel.
  718.      * @see #setDesignTimeLookAndFeel(LookAndFeel)
  719.      * @see #setDesignTimeLookAndFeel(String)
  720.      * @see #updateDesignTimeLookAndFeelUI
  721.      */
  722.     public abstract LookAndFeel getDesignTimeLookAndFeel();
  723.  
  724.     /**
  725.      * Set the current design time look-and-feel.
  726.      * The new look-and-feel is applied to both new and existing Components.
  727.      * <p>
  728.      * This is a JavaBeans bound property.
  729.      *
  730.      * @param newDesignTimeLookAndFeel an object defining the UI's new look-and-feel.
  731.      * @see #setDesignTimeLookAndFeel(String)
  732.      * @see #getDesignTimeLookAndFeel
  733.      * @see #updateDesignTimeLookAndFeelUI
  734.      */
  735.     public abstract void setDesignTimeLookAndFeel(LookAndFeel newDesignTimeLookAndFeel);
  736.  
  737.     /**
  738.      * Set the current design time look-and-feel.
  739.      * The new look-and-feel is applied to both new and existing Components.
  740.      * <p>
  741.      * This is a JavaBeans bound property.
  742.      *
  743.      * @param newDesignTimeLookAndFeelClassName class name of an object defining the UI's new look-and-feel.
  744.      * @exception ClassNotFoundException if the specified class cannot be located.
  745.      * @exception InstantiationException if the specified class could not be constructed.
  746.      * @exception IllegalAccessException if the specified class definition cannot be
  747.      * accessed (it's not public).
  748.      * @see #setDesignTimeLookAndFeel(LookAndFeel)
  749.      * @see #getDesignTimeLookAndFeel
  750.      * @see #updateDesignTimeLookAndFeelUI
  751.      */
  752.     public abstract void setDesignTimeLookAndFeel(String newDesignTimeLookAndFeelClassName)
  753.     throws ClassNotFoundException,
  754.             InstantiationException,
  755.             IllegalAccessException;
  756.  
  757.     /**
  758.      * Changes the look-and-feel of a JComponent to match the current design time look-and-feel.
  759.      * @param component the component whose look-and-feel needs updating.
  760.      * @see #setDesignTimeLookAndFeel(LookAndFeel)
  761.      * @see #setDesignTimeLookAndFeel(String)
  762.      * @see #getDesignTimeLookAndFeel
  763.      */
  764.     public abstract void updateDesignTimeLookAndFeelUI(java.awt.Component component);
  765.  
  766.     //
  767.     // Property Changed Support
  768.     //
  769.  
  770.     /**
  771.      * Starts listening for <code>PropertyChangeEvents</code> generated by Visual Cafe.  These occur when the
  772.      * bound property "design time look-and-feel" is changed.
  773.      * @param listener the object that receives notifications.
  774.      * @see #removePropertyChangeListener
  775.      * @see #setDesignTimeLookAndFeel(LookAndFeel)
  776.      * @see #setDesignTimeLookAndFeel(String)
  777.      */
  778.     public abstract void addPropertyChangeListener(PropertyChangeListener listener);
  779.  
  780.     /**
  781.      * Stops the specified listener from listening for <code>PropertyChangeEvents</code> generated by Visual Cafe.
  782.      * @param listener the object that was receiving notifications.
  783.      * @see #addPropertyChangeListener
  784.      */
  785.     public abstract void removePropertyChangeListener(PropertyChangeListener listener);
  786.  
  787.  
  788.     //
  789.     // Directory Information
  790.     //
  791.     /**
  792.      * Gets the installation (bin) directory of Visual Cafe.
  793.      *
  794.      * @return    path to the install directory.
  795.      */
  796.     public abstract String getInstallDirectory();
  797.  
  798.     /**
  799.      * Gets Visual Cafe's "current directory".  This is the directory that would be displayed in
  800.      * the open file dialog.
  801.      *
  802.      * @return    path to the current directory.
  803.      * @see #setDirectory
  804.      */
  805.     public abstract String getDirectory();
  806.  
  807.     /**
  808.      * Sets Visual Cafe's "current directory".  This is the directory that would be displayed in
  809.      * the open file dialog.
  810.      *
  811.      * @param    path to the new directory.
  812.      * @return    true if success, false otherwise.
  813.      */
  814.     public abstract boolean setDirectory(String newDirectory);
  815.  
  816.  
  817.     //
  818.     // Threading helpers
  819.     //
  820.  
  821.     /**
  822.      * Executes a <code>Runnable</code> object in Visual Cafe's main UI thread.
  823.      * <p>
  824.      * If the caller is already running in the main UI thread,
  825.      * the Runnable's <code>run()</code> method is invoked immediately and
  826.      * <code>runInMainUIThread()</code> does not return until the <code>run()</code>
  827.      * method returns. If the caller is running in any other
  828.      * thread, the runnable is queued for later execution in
  829.      * the main UI thread and the caller returns immediately.
  830.      *
  831.      * This method can help performance when calling several
  832.      * openapi methods that individually execute in the main UI thread (for
  833.      *    example, most of the <code>com.symantec.itools.vcafe.openapi.dtreflect</code>
  834.      *  methods)
  835.      */
  836.     public abstract void runInMainUIThread(Runnable runnable);
  837.  
  838.  
  839.     /**
  840.      * Executes a <code>Runnable</code> object in Visual Cafe's main UI thread and wait for completion.
  841.      * <p>
  842.      * <code>runInMainUIThreadAndWait()</code> does not return
  843.      * until the runnable's <code>run()</code> method has completed.
  844.      *
  845.      * This method can help performance when calling several
  846.      * openapi methods that individually execute in the main UI thread (for
  847.      *    example, most of the <code>com.symantec.itools.vcafe.openapi.dtreflect</code>
  848.      *  methods)
  849.      */
  850.     public abstract void runInMainUIThreadAndWait(final Runnable runnable);
  851.  
  852.  
  853.     //
  854.     // Implementation
  855.     //
  856.  
  857.     /**
  858.      * Instance of a <code>VisualCafe</code> object, created at startup and always available.
  859.      */
  860.     protected static VisualCafe visualCafe;
  861. }
  862.