Skip to content

Ghidra is a software reverse engineering (SRE) framework

22.1 KB
Raw Blame
/* ###
 * IP: GHIDRA
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package docking.action;

import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.util.Objects;
import java.util.Set;
import java.util.function.Predicate;

import javax.swing.*;

import docking.*;
import docking.widgets.EmptyBorderButton;
import generic.theme.GIcon;
import ghidra.util.*;
import ghidra.util.datastruct.WeakDataStructureFactory;
import ghidra.util.datastruct.WeakSet;
import ghidra.util.exception.AssertException;
import gui.event.MouseBinding;
import resources.ResourceManager;
import utilities.util.reflection.ReflectionUtilities;

/**
 * <code>DockingAction</code> defines a user action associated with a toolbar icon and/or
 * menu item.  All actions must specify an action name which will be used to associate key bindings
 * and will be used as the popup menu item when needed.  This name should be unique across
 * the entire application.
 * <p>
 * DockingActions can be invoked from the global menu, a popup menu, a toolbar, and/or a keybinding,
 * depending on whether or not menuBarData, popupMenuData, toolBarData, and/or keyBindingData have
 * been set.
 * <p>
 * <b>
 * Implementors of this class should override {@link #actionPerformed(ActionContext)}.
 * </b>
 * <p>
 * Generally, implementors should also override {@link #isEnabledForContext(ActionContext)}.  This
 * method is used to determine if an action if applicable to the current context.   Overriding this
 * method allows actions to manage their own enablement.  Otherwise, the default behavior for this
 * method is to return the current enabled property of the action.  This allows for the possibility
 * for plugins to externally manage the enablement of its actions.
 * <P>
 * NOTE: If you wish to do your own external enablement management for an action (which is highly
 * discouraged), it is very important that you don't use any of the internal enablement mechanisms
 * by setting the predicates {@link #enabledWhen(Predicate)}, {@link #validContextWhen(Predicate)}
 * or overriding {@link #isValidContext(ActionContext)}. These predicates and methods trigger
 * internal enablement management which will interfere with you own calls to
 * {@link DockingAction#setEnabled(boolean)}.
 */
public abstract class DockingAction implements DockingActionIf {

	private WeakSet<PropertyChangeListener> propertyListeners =
		WeakDataStructureFactory.createCopyOnWriteWeakSet();

	private final String name;
	private final String owner;
	private String description = "";
	private String inceptionInformation;

	private boolean isEnabled = true;

	private KeyBindingType keyBindingType = KeyBindingType.INDIVIDUAL;
	private KeyBindingData defaultKeyBindingData;
	private KeyBindingData keyBindingData;
	private MenuBarData menuBarData;
	private PopupMenuData popupMenuData;
	private ToolBarData toolBarData;

	private Predicate<ActionContext> enabledPredicate;
	private Predicate<ActionContext> popupPredicate;
	private Predicate<ActionContext> validContextPredicate;
	private boolean shouldAddToAllWindows = false;
	private Class<? extends ActionContext> addToWindowWhenContextClass = null;
	private Class<? extends ActionContext> contextClass = ActionContext.class;

	// by default, actions only work on the active provider
	private boolean supportsDefaultContext = false;

	public DockingAction(String name, String owner) {
		this.name = name;
		this.owner = owner;

		recordInception();
		HelpLocation location = new HelpLocation(owner, name, inceptionInformation);
		setHelpLocation(location);
	}

	public DockingAction(String name, String owner, KeyBindingType kbType) {
		this(name, owner);
		this.keyBindingType = Objects.requireNonNull(kbType);
	}

	public DockingAction(String name, String owner, boolean supportsKeyBindings) {
		this(name, owner);
		this.keyBindingType =
			supportsKeyBindings ? KeyBindingType.INDIVIDUAL : KeyBindingType.UNSUPPORTED;
	}

	protected KeyBindingType getPreferredKeyBindingType() {
		return KeyBindingType.INDIVIDUAL;
	}

	@Override
	public abstract void actionPerformed(ActionContext context);

	@Override
	public void addPropertyChangeListener(PropertyChangeListener listener) {
		propertyListeners.add(listener);
	}

	@Override
	public void removePropertyChangeListener(PropertyChangeListener listener) {
		propertyListeners.remove(listener);
	}

	@Override
	public String getDescription() {
		return description;
	}

	@Override
	public String getFullName() {
		return getName() + " (" + getOwner() + ")";
	}

	@Override
	public MenuData getMenuBarData() {
		return menuBarData;
	}

	@Override
	public String getName() {
		return name;
	}

	@Override
	public String getOwner() {
		return owner;
	}

	@Override
	public MenuData getPopupMenuData() {
		return popupMenuData;
	}

	@Override
	public ToolBarData getToolBarData() {
		return toolBarData;
	}

	@Override
	public String getInceptionInformation() {
		return inceptionInformation;
	}

	@Override
	public boolean isEnabled() {
		return isEnabled;
	}

	@Override
	public boolean isAddToPopup(ActionContext context) {
		if (popupPredicate != null) {
			return popupPredicate.test(context);
		}
		return isEnabledForContext(context);
	}

	@Override
	public boolean isEnabledForContext(ActionContext context) {
		if (enabledPredicate != null) {
			return enabledPredicate.test(context);
		}
		return isEnabled();
	}

	@Override
	public boolean isValidContext(ActionContext context) {
		if (validContextPredicate != null) {
			return validContextPredicate.test(context);
		}
		return true;
	}

	/**
	 * Determines if this action should be added to a window.
	 * <P>
	 * If the client wants the action on all windows, then they can call {@link #shouldAddToAllWindows}
	 * <P>
	 * If the client wants the action to be on a window only when the window can produce
	 * a certain context type, then the client should call
	 * {@link #addToWindowWhen(Class)}
	 * <P>
	 * Otherwise, by default, the action will only be on the main window.
	 *
	 */
	@Override
	public final boolean shouldAddToWindow(boolean isMainWindow, Set<Class<?>> contextTypes) {
		// this method only applies to actions with top level menus or tool bars.
		if (menuBarData == null && toolBarData == null) {
			return false;
		}

		// clients can specify that the action should be on all windows.
		if (shouldAddToAllWindows) {
			return true;
		}

		// clients can specify a context class that determines if an action should
		// be added to a window.
		if (addToWindowWhenContextClass != null) {
			for (Class<?> class1 : contextTypes) {
				if (addToWindowWhenContextClass.isAssignableFrom(class1)) {
					return true;
				}
			}
			return false;
		}

		// default to only appearing in main window
		return isMainWindow;
	}

	/**
	 * Set a specific Help location for this action.
	 * This will replace the default help location
	 * @param location the help location for the action.
	 */
	public void setHelpLocation(HelpLocation location) {
		DockingWindowManager.getHelpService().registerHelp(this, location);
	}

	/**
	 * Returns the help location for this action
	 * @return the help location for this action
	 */
	public HelpLocation getHelpLocation() {
		return DockingWindowManager.getHelpService().getHelpLocation(this);
	}

	/**
	 * Signals the help system that this action does not need a help entry.   Some actions
	 * are so obvious that they do not require help, such as an action that renames a file.
	 * <p>
	 * The method should be sparsely used, as most actions should provide help.
	 */
	public void markHelpUnnecessary() {
		DockingWindowManager.getHelpService().excludeFromHelp(this);
	}

	@Override
	public void setEnabled(boolean newValue) {
		if (isEnabled == newValue) {
			return;
		}
		isEnabled = newValue;
		firePropertyChanged(ENABLEMENT_PROPERTY, !isEnabled, isEnabled);
	}

	@Override
	public final JButton createButton() {
		JButton button = doCreateButton();
		button.setName(getName());
		button.setFocusable(false);
		Icon icon = toolBarData == null ? null : toolBarData.getIcon();
		if (icon == null) {
			icon = ResourceManager.getDefaultIcon();
		}

		button.setIcon(icon);
		String tt = getDescription();
		if (tt == null || tt.length() == 0) {
			tt = getName();
		}
		button.setToolTipText(tt);
		button.setEnabled(isEnabled());

		// Reverting GT-2452 because some buttons need to be able to respond to fast clicking.
		//button.setMultiClickThreshhold(500); // this prevents 2 callbacks from double-clicks

		return button;
	}

	@Override
	public JMenuItem createMenuItem(boolean isPopup) {
		JMenuItem menuItem = doCreateMenuItem();
		MenuData menuData = isPopup ? popupMenuData : menuBarData;
		if (menuData != null) {

			String text = menuData.getMenuItemName();
			String trimmed = StringUtilities.trimMiddle(text, 50);
			menuItem.setText(trimmed);
			Icon icon = menuData.getMenuIcon();
			menuItem.setIcon(icon);
			if (icon != null) {
				menuItem.setDisabledIcon(ResourceManager.getDisabledIcon(icon));
			}
			menuItem.setMnemonic(menuData.getMnemonic());
		}
		else {
			throw new AssertException(
				"No menu data for menu type: " + (isPopup ? "Popup" : "Menubar"));
		}
		KeyStroke ks = keyBindingData == null ? null : keyBindingData.getKeyBinding();
		if (ks != null) {
			menuItem.setAccelerator(ks);
		}
		menuItem.setEnabled(isEnabled);

		return menuItem;
	}

	private MouseBinding getMouseBinding() {
		return keyBindingData == null ? null : keyBindingData.getMouseBinding();
	}

	@Override
	public KeyBindingType getKeyBindingType() {
		return keyBindingType;
	}

	@Override
	public KeyStroke getKeyBinding() {
		return keyBindingData == null ? null : keyBindingData.getKeyBinding();
	}

	@Override
	public KeyBindingData getKeyBindingData() {
		return keyBindingData;
	}

	@Override
	public KeyBindingData getDefaultKeyBindingData() {
		return defaultKeyBindingData;
	}

	@Override
	public void setKeyBindingData(KeyBindingData newKeyBindingData) {
		if (!supportsKeyBinding(newKeyBindingData)) {
			return;
		}

		KeyBindingData oldData = keyBindingData;
		keyBindingData = KeyBindingData.validateKeyBindingData(newKeyBindingData);

		if (defaultKeyBindingData == null) {
			defaultKeyBindingData = keyBindingData;
		}

		firePropertyChanged(KEYBINDING_DATA_PROPERTY, oldData, keyBindingData);
	}

	// this allows framework classes to directly set the default value
	protected void setDefaultKeyBindingData(KeyBindingData kbd) {
		defaultKeyBindingData = kbd;
	}

	private boolean supportsKeyBinding(KeyBindingData kbData) {

		KeyBindingType type = getKeyBindingType();
		if (type.supportsKeyBindings()) {
			return true;
		}

		KeyBindingPrecedence precedence = null;
		if (kbData != null) {
			precedence = kbData.getKeyBindingPrecedence();
		}

		if (precedence == KeyBindingPrecedence.SystemActionsLevel) {
			return true; // system actions are special
		}

		// log a trace message instead of throwing an exception, as to not break any legacy code
		Msg.error(this, "Action does not support key bindings: " + getFullName(), new Throwable());
		return false;
	}

	@Override
	public void setUnvalidatedKeyBindingData(KeyBindingData newKeyBindingData) {
		if (Objects.equals(keyBindingData, newKeyBindingData)) {
			return;
		}

		KeyBindingData oldData = keyBindingData;
		keyBindingData = newKeyBindingData;
		firePropertyChanged(KEYBINDING_DATA_PROPERTY, oldData, keyBindingData);
	}

	@Override
	public Class<? extends ActionContext> getContextClass() {
		return contextClass;
	}

	@Override
	public boolean supportsDefaultContext() {
		return supportsDefaultContext;
	}

	@Override
	public void setContextClass(Class<? extends ActionContext> type,
			boolean supportsDefaultContext) {
		this.contextClass = type;
		this.supportsDefaultContext = supportsDefaultContext;
		validContextPredicate = ac -> contextClass.isInstance(ac);
	}
//==================================================================================================
// Non interface methods
//==================================================================================================

	/**
	 * Sets the {@link MenuData} to be used to put this action on the tool's menu bar
	 * @param newMenuData the MenuData to be used to put this action on the tool's menu bar
	 */
	public void setMenuBarData(MenuData newMenuData) {
		MenuBarData oldData = menuBarData;
		MenuBarData newDataCopy = newMenuData == null ? null : new MenuBarData(this, newMenuData);

		menuBarData = newDataCopy;
		firePropertyChanged(MENUBAR_DATA_PROPERTY, oldData, newDataCopy);
	}

	/**
	 * Sets the {@link MenuData} to be used to put this action in the tool's popup menu
	 * @param newMenuData the MenuData to be used to put this action on the tool's popup menu
	 */
	public void setPopupMenuData(MenuData newMenuData) {
		PopupMenuData oldData = popupMenuData;
		PopupMenuData newDataCopy =
			newMenuData == null ? null : new PopupMenuData(this, newMenuData);
		popupMenuData = newDataCopy;
		firePropertyChanged(POPUP_MENU_DATA_PROPERTY, oldData, newDataCopy);
	}

	/**
	 * Sets the {@link ToolBarData} to be used to put this action on the tool's toolbar
	 * @param newToolBarData the ToolBarData to be used to put this action on the tool's toolbar
	 */
	public void setToolBarData(ToolBarData newToolBarData) {

		ToolBarData oldData = toolBarData;
		ToolBarData newToolBarDataCopy = newToolBarData == null ? null
				: new ToolBarData(this, newToolBarData.getIcon(), newToolBarData.getToolBarGroup(),
					newToolBarData.getToolBarSubGroup());
		toolBarData = newToolBarDataCopy;
		firePropertyChanged(TOOLBAR_DATA_PROPERTY, oldData, newToolBarDataCopy);
	}

	/**
	 * Creates a reserved keybinding for this action. Reserved keybindings cannot be changed by
	 * the user and have a special high precedence for being process before other actions. Also,
	 * other actions are prevented from using the same KeyStroke as a reserved keybinding.
	 * @param keyStroke the keystroke to be used for the keybinding
	 */
	void createSystemKeyBinding(KeyStroke keyStroke) {
		KeyBindingData data = KeyBindingData.createSystemKeyBindingData(keyStroke);
		setKeyBindingData(data);
	}

	/**
	 * Sets the description to be used in the tooltip.
	 * @param newDescription the description to be set.
	 */
	public void setDescription(String newDescription) {
		if (SystemUtilities.isEqual(newDescription, description)) {
			return;
		}
		String oldDescription = description;
		description = newDescription;
		firePropertyChanged(DESCRIPTION_PROPERTY, oldDescription, newDescription);
	}

	/**
	 * Cleans up any resources used by the action.
	 */
	@Override
	public void dispose() {
		propertyListeners.clear();
	}

	@Override
	public String toString() {
		return getName() + "  (" + getOwner() + ")";
	}

	@Override
	public String getHelpInfo() {
		StringBuilder buffer = new StringBuilder();
		buffer.append("   ACTION:    ").append(getOwner()).append(" - ").append(getName());
		buffer.append('\n');

		// menu path
		if (menuBarData != null) {
			buffer.append("        MENU PATH:           ")
					.append(menuBarData.getMenuPathAsString());
			buffer.append('\n');
			buffer.append("        MENU GROUP:        ").append(menuBarData.getMenuGroup());
			buffer.append('\n');

			String menuSubGroup = menuBarData.getMenuSubGroup();
			if (menuSubGroup != null) {
				buffer.append("        MENU SUB-GROUP:        ").append(menuSubGroup);
				buffer.append('\n');
			}

			String parentGroup = menuBarData.getParentMenuGroup();
			if (parentGroup != null) {
				buffer.append("        PARENT GROUP:         ").append(parentGroup);
				buffer.append('\n');
			}

			String iconName = getIconName(menuBarData.getMenuIcon());
			if (iconName != null) {
				buffer.append("        MENU ICON:     ").append(iconName);
				buffer.append('\n');
			}

			String iconId = getIconId(menuBarData.getMenuIcon());
			if (iconId != null) {
				buffer.append("        MENU ICON ID:     ").append(iconId);
				buffer.append('\n');
			}
		}

		// popup menu path
		if (popupMenuData != null) {
			buffer.append("        POPUP PATH:         ")
					.append(popupMenuData.getMenuPathAsString());
			buffer.append('\n');
			buffer.append("        POPUP GROUP:      ").append(popupMenuData.getMenuGroup());
			buffer.append('\n');

			String parentGroup = popupMenuData.getParentMenuGroup();
			if (parentGroup != null) {
				buffer.append("        PARENT GROUP:         ").append(parentGroup);
				buffer.append('\n');
			}

			String menuSubGroup = popupMenuData.getMenuSubGroup();
			if (menuSubGroup != MenuData.NO_SUBGROUP) {
				buffer.append("        POPUP SUB-GROUP:         ").append(menuSubGroup);
				buffer.append('\n');
			}

			String iconName = getIconName(popupMenuData.getMenuIcon());
			if (iconName != null) {
				buffer.append("        POPUP ICON:     ").append(iconName);
				buffer.append('\n');
			}

			String iconId = getIconId(popupMenuData.getMenuIcon());
			if (iconId != null) {
				buffer.append("        POPUP ICON ID:     ").append(iconId);
				buffer.append('\n');
			}
		}

		if (toolBarData != null) {
			buffer.append("        TOOLBAR GROUP:  ").append(toolBarData.getToolBarGroup());
			buffer.append('\n');

			String iconName = getIconName(toolBarData.getIcon());
			if (iconName != null) {
				buffer.append("        TOOLBAR ICON:     ").append(iconName);
				buffer.append('\n');
			}

			String iconId = getIconId(toolBarData.getIcon());
			if (iconId != null) {
				buffer.append("        TOOLBAR ICON ID:     ").append(iconId);
				buffer.append('\n');
			}
		}

		KeyStroke keyStroke = getKeyBinding();
		if (keyStroke != null) {
			buffer.append("        KEYBINDING:          ").append(keyStroke);
			buffer.append('\n');
		}

		MouseBinding mouseBinding = getMouseBinding();
		if (mouseBinding != null) {
			buffer.append("        MOUSE BINDING:       ").append(mouseBinding);
		}

		String inception = getInceptionInformation();
		if (inception != null) {
			buffer.append("\n    \n");
			buffer.append("   CREATED AT: ").append(inception);
			buffer.append("\n    ");
		}
		else {
			Msg.debug(this, "No inception info");
		}

		return buffer.toString();
	}

	private String getIconId(Icon icon) {
		if (icon instanceof GIcon gIcon) {
			return gIcon.getId();
		}
		return null;
	}

	private String getIconName(Icon icon) {
		if (icon == null) {
			return null;
		}

		String iconName = ResourceManager.getIconName(icon);
		if (iconName == null) {
			return null;
		}

		int index = iconName.lastIndexOf('/');
		if (index != -1) {
			return iconName.substring(index + 1);
		}
		return iconName;
	}

	public void firePropertyChanged(String propertyName, Object oldValue, Object newValue) {
		if (Objects.equals(oldValue, newValue)) {
			return;
		}
		PropertyChangeEvent event = new PropertyChangeEvent(this, propertyName, oldValue, newValue);
		for (PropertyChangeListener listener : propertyListeners) {
			listener.propertyChange(event);
		}
	}

	@Override
	public Object getHelpObject() {
		return this;
	}

	/**
	 * Sets a predicate for dynamically determining the action's enabled state.  If this
	 * predicate is not set, the action's enable state must be controlled directly using the
	 * {@link DockingAction#setEnabled(boolean)} method. See
	 * {@link DockingActionIf#isEnabledForContext(ActionContext)}
	 *
	 * @param predicate the predicate that will be used to dynamically determine an action's
	 * enabled state.
	 */
	public void enabledWhen(Predicate<ActionContext> predicate) {
		enabledPredicate = predicate;
	}

	/**
	 * Sets a predicate for dynamically determining if this action should be included in
	 * an impending pop-up menu.  If this predicate is not set, the action's will be included
	 * in an impending pop-up, if it is enabled. See
	 * {@link DockingActionIf#isAddToPopup(ActionContext)}
	 *
	 * @param predicate the predicate that will be used to dynamically determine an action's
	 * enabled state.
	 */
	public void popupWhen(Predicate<ActionContext> predicate) {
		popupPredicate = predicate;
	}

	/**
	 * Sets a predicate for dynamically determining if this action is valid for the current
	 * {@link ActionContext}.  See {@link DockingActionIf#isValidContext(ActionContext)}
	 *
	 * @param predicate the predicate that will be used to dynamically determine an action's
	 * validity for a given {@link ActionContext}
	 */
	public void validContextWhen(Predicate<ActionContext> predicate) {
		validContextPredicate = predicate;
	}

	/**
	 * Sets the ActionContext class for when this action should be added to a window
	 * <P>
	 * If this is set, then the action will only be added to windows that have providers
	 * that can produce an ActionContext that is appropriate for this action.
	 * 
	 * @param addToWindowContextClass the ActionContext class required to be producible by a
	 * provider that is hosted in that window before this action is added to that
	 * window.
	 *
	 */
	public void addToWindowWhen(Class<? extends ActionContext> addToWindowContextClass) {
		addToWindowWhenContextClass = addToWindowContextClass;
	}

	/**
	 * Tells this action to add itself to all windows
	 * 
	 * @param b to add to all windows or not
	 */
	public void setAddToAllWindows(boolean b) {
		shouldAddToAllWindows = b;
	}

//==================================================================================================
// Non-public methods
//==================================================================================================

	protected JButton doCreateButton() {
		return new EmptyBorderButton();
	}

	protected JMenuItem doCreateMenuItem() {
		return new DockingMenuItem();
	}

	private void recordInception() {
		if (!SystemUtilities.isInDevelopmentMode()) {
			inceptionInformation = "";
			return;
		}
		inceptionInformation = getInceptionFromTheFirstClassThatIsNotUsOrABuilder();
	}

	protected String getInceptionFromTheFirstClassThatIsNotUsOrABuilder() {
		Throwable t = ReflectionUtilities.createThrowableWithStackOlderThan(getClass());
		StackTraceElement[] trace =
			ReflectionUtilities.filterStackTrace(t.getStackTrace(), "ActionBuilder");
		String classInfo = trace[0].toString();
		return classInfo;
	}

}