org.faceless.pdf2.viewer2

## Class ViewerWidget

- java.lang.Object
- - org.faceless.pdf2.viewer2.ViewerFeature
  - - org.faceless.pdf2.viewer2.ViewerWidget

- Direct Known Subclasses:
    About, Close, Coordinates, FullScreenMode, Info, InvisiblySignDocument, ManageIdentities, NavigationWidget, NetworkSave, Open, Print, 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`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ViewerWidget(String name)` Create a new Widget

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `action(ViewerEvent event)` The method that's run when this feature is activated.
    `protected ActionListener` | `createActionListener()` Return an ActionListener that will be called when this Widget is activated.
    `JComponent` | `getComponent()` Return the component representing this Widget.
    `protected ImageIcon` | `getIcon(String path)` Return the icon specified by the supplied path, or null if no such icon exists
    `PDFViewer` | `getViewer()` Get the Viewer this Feature has been added to.
    `void` | `initialize(PDFViewer viewer)` Called when the feature is first added to a viewer
    `boolean` | `isButtonEnabledByDefault()` Return true if the button component for this widget is enabled by default.
    `boolean` | `isDocumentRequired()` Return whether this widget should be inactive if no Document is selected.
    `boolean` | `isMenuEnabledByDefault()` Return true if the menu component for this widget is enabled by default.
    `void` | `setButton(String toolbar, String icon, String tooltip)` Set this feature to use a regular button in the toolbar.
    `protected void` | `setComponent(String toolbar, JComponent component)` Set a custom component to be displayed in the ToolBar for this feature.
    `protected void` | `setDocumentRequired(boolean required)` Set whether this feature requires a PDF to be loaded.
    `void` | `setMenu(String menu)` Set a menu item for this feature.
    `void` | `setMenu(String menu, char mnemonic)` Set a menu item for this feature, with an optional keyboard shortcut.
    `void` | `setToolBarEnabled(boolean enabled)` Set whether the toolbar this feature is stored in is enabled by default
    `void` | `setToolBarEnabledAlways(boolean always)` Set whether the toolbar this feature is stored in can be enabled or disabled
    `void` | `setToolBarFloatable(boolean floatable)` Set whether the toolbar this feature is stored in can be floated
    `void` | `setToolBarFloating(boolean floating)` Set whether this toolbar is always floating or not.
    `String` | `toString()`

    - ### Methods inherited from class org.faceless.pdf2.viewer2.ViewerFeature

      `getAllEnabledFeatures, getAllFeatures, getCustomJavaScript, getFeatureProperty, getFeatureURLProperty, getName, isEnabledByDefault, setFeatureName, teardown`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ViewerWidget

          public ViewerWidget(String name)

      Create a new Widget

  - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `ViewerFeature`

    - #### 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

    - #### initialize

          public void initialize(PDFViewer viewer)

      Description copied from class: `ViewerFeature`
      Called when the feature is first added to a viewer
      Overrides:
        `initialize` in class `ViewerFeature`

    - #### 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.

Copyright © 2001-2015 Big Faceless Organization