Package org.faceless.pdf2.viewer2

Class ViewerWidget

  • Direct Known Subclasses:
    About, Close, Coordinates, FullScreenMode, Info, InvisiblySignDocument, ManageIdentities, NavigationWidget, NetworkSave, Open, OpenSystem, Print, PrintSystem, Quit, RotateClockwise, Save, SaveAs, SearchField, ShowConsole, ToggleViewerWidget, XFA, ZoomIn, ZoomLevel, ZoomOut
    public class ViewerWidget
extends ViewerFeature

    A type of ViewerFeature that adds a "widget" to a PDFViewer. Widgets are typically buttons on the toolbar, menu items and so on.

    Internals (the old way)

    Prior to 2.13.1, Widgets would need to specify details for a button (by calling setButton() and/or a menu item (by calling setMenu()). This would create a JButton that would run the ActionListener returned by createActionListener() when clicked - for most widgets this would simply call action. Likewise a JMenuItem would also be created the same way.

    The two component were independent, and had to be enabled or disabled independently. Retrieving the components could be done by calling getViewer.getNamedCompoment(name), where name was ButtonNNN or MenuNNN (NNN being the name of the feature).

    If the widget left the documentRequired field to the default value of true, then both the button and menu components would be added to a list of JComponents which would have their enabled state updated depending on whether the PDFViewer had an active document panel. Here's a typical example. 

     public class MyWidget extends ViewerWidget {
    public MyWidget() {
        super("MyWidgetName");
        setButton("ToolbarName", "resources/icons/myicon.png", "Tooltip text");
        setMenu("MenuName\tMenuItemName", 'z');
    }
    public void action(ViewerEvent event) {
        DocumentPanel panel = event.getViewer().getActiveDocumntPanel();
        // Run action here
    }
 }

    This approach has proved inflexible as the viewer has grown more capable, in particular since the arrival of the permission framework, which implies that features are no longer enabled based solely on whether a PDF is available. It is no long recommended for new Widgets, although it will continue to work as described above. For new Widgets and those with more complex requirements for enablement, we recommend the approach described below.

    Internals (the new way)

    The recommended approach for more complex Widgets is to override createActionListener() to return an Action instead of a simple ActionListener. One of both of setButton() or setMenu() must still be called to add the action to the toolbar or menu (but any Icon, Name, Tooltip or Accelerator key set on the Action will override values specified in these calls).

    This is a much more Swing-like approach: there is one Action shared by the button, menu (or any other components you may create that trigger it), and you manage the enabled status of the Action, rather than the components. The Action will be disabled by default if the documentRequired field is left at the default value of true, but other than that you must manage when the Action is enabled by reacting to DocumentPanelEvents. Here's an example which is functionally identical to the above example. 

     public class MyWidget extends ViewerWidget {
    private AbstractAction action;

    public MyWidget() {
        super("MyWidgetName");
        setButton("ToolbarName", "resources/icons/myicon.png", "Tooltip text");
        setMenu("MenuName\tMenuItemName", 'z');
        action = new AbstractAction() {
            public void actionPerformed(ActionEvent event) {
                action(new ViewerEvent(event, getViewer()));
            }
        };
    }
    public ActionListener createActionListener() {
        return action;
    }
    public void action(ViewerEvent event) {
        DocumentPanel panel = event.getViewer().getActiveDocumentPanel();
        // Run action here
    }
 }

    If the action is only to be enabled when a PDF is available and (for example) the Assemble permission is set, then you could augment the above code with the following. 

     public void initialize(final PDFViewer viewer) {
     super.initialize(viewer);
     viewer.addDocumentPanelListener(new DocumentPanelListener() {
         public void documentUpdated(DocumentPanelEvent event) {
             String type = event.getType();
             if (type.equals("activated") || (type.equals("permissionChanged") && event.getDocumentPanel() == viewer.getActiveDocumentPanel())) {
                 action.setEnabled(event.getDocumentPanel().hasPermission("Assemble"));
             } else if (type.equals("deactivated")) {
                 action.setEnabled(false);
             }
         }
     });
 }

    Of course other designs for this widget are possible, including skipping action() and running the code directly from Action.actionPerformed(), or having the widget itself implement Action and DocumentPanelListener to remove the anonymous inner classes.

    This code is copyright the Big Faceless Organization. You're welcome to use, modify and distribute it in any form in your own projects, provided those projects continue to make use of the Big Faceless PDF library.

    Since:
    2.8
    See Also:
    ToggleViewerWidget

    • Field Detail

      • propertyChangeSupport

        protected WeakPropertyChangeSupport propertyChangeSupport

    • Constructor Detail

      • ViewerWidget

        public ViewerWidget​(String name)
        Create a new Widget

    • Method Detail

      • createActionListener

        protected ActionListener createActionListener()
        Return an ActionListener that will be called when this Widget is activated. Subclasses will typically not need to override this method except in special cases.
        Returns:
        ActionListener the ActionListener to be notified when an event fires
        See Also:
        Quit.createActionListener()

      • getIcon

        protected ImageIcon getIcon​(String path)
        Return the icon specified by the supplied path, or null if no such icon exists

      • getViewer

        public final PDFViewer getViewer()
        Get the Viewer this Feature has been added to.

      • setDocumentRequired

        protected final void setDocumentRequired​(boolean required)
        Set whether this feature requires a PDF to be loaded. Most features except for the "Open" widget do, so the default is "true"

      • isDocumentRequired

        public boolean isDocumentRequired()
        Return whether this widget should be inactive if no Document is selected.
        Since:
        2.11.7
        See Also:
        setDocumentRequired(boolean)

      • setComponent

        protected final void setComponent​(String toolbar,
                                  JComponent component)
        Set a custom component to be displayed in the ToolBar for this feature.
        Parameters:
        toolbar - the name of the toolbar to put the component in
        component - the component

      • getComponent

        public JComponent getComponent()
        Return the component representing this Widget.
        Since:
        2.8.5

      • isButtonEnabledByDefault

        public boolean isButtonEnabledByDefault()
        Return true if the button component for this widget is enabled by default. The default is "true"
        Since:
        2.10.3

      • isMenuEnabledByDefault

        public boolean isMenuEnabledByDefault()
        Return true if the menu component for this widget is enabled by default. The default is "true"
        Since:
        2.10.3

      • setButton

        public void setButton​(String toolbar,
                      String icon,
                      String tooltip)
        Set this feature to use a regular button in the toolbar. The button will be created using the specified icon and with the specified tooltip.
        Parameters:
        toolbar - the name of the toolbar to put the component in
        icon - the URL of the icon to use. If the return value of createActionListener() is an Action that specifies an icon already, this will be ignored.
        tooltip - the tooltip to display for this button. If the return value of createActionListener() is an Action that specifies a tooltip value already, this will be ignored.
        Since:
        2.8, changed from protected to public in 2.17.1

      • setToolBarEnabled

        public void setToolBarEnabled​(boolean enabled)
        Set whether the toolbar this feature is stored in is enabled by default
        Since:
        2.8, changed from protected to public in 2.17.1

      • setToolBarEnabledAlways

        public void setToolBarEnabledAlways​(boolean always)
        Set whether the toolbar this feature is stored in can be enabled or disabled
        Since:
        2.8, changed from protected to public in 2.17.1
        See Also:
        ToolbarDisabling

      • setToolBarFloatable

        public void setToolBarFloatable​(boolean floatable)
        Set whether the toolbar this feature is stored in can be floated
        Since:
        2.8, changed from protected to public in 2.17.1

      • setToolBarFloating

        public void setToolBarFloating​(boolean floating)
        Set whether this toolbar is always floating or not. Toolbars with this set are implemented as JInternalFrame objects, and are never attached to the regular tool bar
        Since:
        2.8.3, changed from protected to public in 2.17.1

      • setMenu

        public void setMenu​(String menu)
        Set a menu item for this feature. Activating the menu item is the same as pressing the button.
        Parameters:
        menu - the menu hierarchy to use, separated with tabs - eg "File\tOpen". If the return value of createActionListener() is an Action that specifies a Name already, the last part of this menu will be ignored and that name used instead.
        Since:
        2.8, changed from protected to public in 2.17.1

      • setMenu

        public void setMenu​(String menu,
                    char mnemonic)
        Set a menu item for this feature, with an optional keyboard shortcut.
        Parameters:
        menu - the menu hierarchy to use, separated with tabs - eg "File\tOpen". If the return value of createActionListener() is an Action that specifies a Name already, the last part of this menu will be ignored and that name used instead.
        mnemonic - the keyboard shortcut to activate the menu - a lowercase or uppercase character to activate the menu. If the return value of createActionListener() is an Action that specifies an Accelerator key already, this will be ignored.
        Since:
        2.10.2, changed from protected to public in 2.17.1

      • action

        public void action​(ViewerEvent event)
        The method that's run when this feature is activated. This method is called by the ActionListener returned by the default implementation of createActionListener(), and by default is a no-op.

      • addPropertyChangeListener

        public void addPropertyChangeListener​(PropertyChangeListener listener)
        Add a Listener for changes to this object. By default only the "enabled" property change is fired when the widget's action is enabled or disabled; subclasses may expand on this list. Duplicate PropertyChangeListeners are ignored and listeners are held in this class with a weak-reference and so will be removed automatically on garbage collection.
        Parameters:
        listener - the Listener.
        Since:
        2.24.2

      • firePropertyChange

        protected void firePropertyChange​(String name,
                                  Object oldValue,
                                  Object newValue)
        Fire a property change event on this object
        Since:
        2.24.2