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.
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.
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.
ToggleViewerWidget
Constructor and Description |
---|
ViewerWidget(String name)
Create a new Widget
|
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() |
getAllEnabledFeatures, getAllFeatures, getCustomJavaScript, getFeatureProperty, getFeatureURLProperty, getName, isEnabledByDefault, setFeatureName, teardown
public ViewerWidget(String name)
public String toString()
toString
in class ViewerFeature
protected ActionListener createActionListener()
Quit.createActionListener()
protected ImageIcon getIcon(String path)
public void initialize(PDFViewer viewer)
ViewerFeature
initialize
in class ViewerFeature
public final PDFViewer getViewer()
protected final void setDocumentRequired(boolean required)
public boolean isDocumentRequired()
setDocumentRequired(boolean)
protected final void setComponent(String toolbar, JComponent component)
toolbar
- the name of the toolbar to put the component incomponent
- the componentpublic JComponent getComponent()
public boolean isButtonEnabledByDefault()
public boolean isMenuEnabledByDefault()
public void setButton(String toolbar, String icon, String tooltip)
toolbar
- the name of the toolbar to put the component inicon
- 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.public void setToolBarEnabled(boolean enabled)
public void setToolBarEnabledAlways(boolean always)
ToolbarDisabling
public void setToolBarFloatable(boolean floatable)
public void setToolBarFloating(boolean floating)
public void setMenu(String menu)
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.public void setMenu(String menu, char mnemonic)
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.public void action(ViewerEvent event)
ActionListener
returned by the default implementation of
createActionListener()
, and by default is a no-op.Copyright © 2001-2017 Big Faceless Organization