Skip to content

Ghidra is a software reverse engineering (SRE) framework

11.7 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.menu;

import java.util.ArrayList;
import java.util.List;

import javax.swing.Icon;
import javax.swing.JButton;

import docking.ActionContext;
import docking.action.*;
import docking.widgets.EventTrigger;
import ghidra.util.HelpLocation;
import ghidra.util.Swing;
import ghidra.util.exception.AssertException;
import help.Help;
import resources.icons.EmptyIcon;

/**
 * An action that can be in one of multiple states.
 * 
 * <p>
 * The button of this action has a drop-down icon that allows users to change the state of the
 * button. As the user changes the state of this action,
 * {@link #actionStateChanged(ActionState, EventTrigger)} will be called. Clients may also use the
 * button of this action to respond to button presses by overriding
 * {@link #actionPerformed(ActionContext)}.
 *
 * <p>
 * This action is intended primarily for use as toolbar actions. Alternatively, some clients use
 * this action to add a button to custom widgets. In the custom use case, clients should use
 * {@link NonToolbarMultiStateAction}.
 * 
 * @param <T> the type of the user data
 * @see MultiActionDockingAction
 */
public abstract class MultiStateDockingAction<T> extends DockingAction {

	private static Icon EMPTY_ICON = new EmptyIcon(16, 16);

	private List<ActionState<T>> actionStates = new ArrayList<>();
	private ActionState<T> currentState = null;
	private MultiActionDockingActionIf multiActionGenerator;
	private MultipleActionDockingToolbarButton multipleButton;

	private Icon defaultIcon;
	private boolean useCheckboxForIcons;

	/**
	 * Constructor
	 *
	 * @param name the action name
	 * @param owner the owner
	 */
	public MultiStateDockingAction(String name, String owner) {
		this(name, owner, KeyBindingType.INDIVIDUAL);
	}

	/**
	 * Constructor
	 *
	 * @param name the action name
	 * @param owner the owner
	 * @param type the key binding type
	 */
	public MultiStateDockingAction(String name, String owner, KeyBindingType type) {
		super(name, owner, type);
		multiActionGenerator = context -> getStateActions();

		// set this here so we don't have to check for null elsewhere
		super.setToolBarData(new ToolBarData(null));
	}

	/**
	 * This method will be called as the user changes the selected button state
	 * 
	 * @param newActionState the newly selected state
	 * @param trigger the source of the event
	 */
	public abstract void actionStateChanged(ActionState<T> newActionState, EventTrigger trigger);

	/**
	 * This method is called when the user clicks the button <B>when this action is used as part of
	 * the default {@link DockingAction} framework.</B>
	 * 
	 * <p>
	 * This is the callback to be overridden when the child wishes to respond to user button presses
	 * that are on the button and not the drop-down. The default behavior is to show the popup menu
	 * when the button is clicked.
	 */
	@Override
	public void actionPerformed(ActionContext context) {
		Swing.runLater(() -> multipleButton.showPopup());
	}

	/**
	 * Overrides the default icons for actions shown in popup menu of the multi-state action.
	 * 
	 * <p>
	 * By default, the popup menu items will use the icons as provided by the {@link ActionState}.
	 * By passing true to this method, icons will not be used in the popup menu. Instead, a checkbox
	 * icon will be used to show the active action state.
	 *
	 * @param useCheckboxForIcons true to use a checkbox
	 */
	public void setUseCheckboxForIcons(boolean useCheckboxForIcons) {
		this.useCheckboxForIcons = useCheckboxForIcons;
	}

	/**
	 * Sets the icon to use if the active action state does not supply an icon.
	 * 
	 * <p>
	 * This is useful if you wish for your action states to not use icon, but desire the action
	 * itself to have an icon.
	 *
	 * @param icon the icon
	 */
	public void setDefaultIcon(Icon icon) {
		this.defaultIcon = icon;
	}

	/**
	 * Extension point: Get the states to display when the button is clicked
	 * 
	 * <p>
	 * This is called when the button is clicked, immediately before the menu is displayed. It is
	 * generally recommended to ensure the current state is included in this list. The states will
	 * be displayed in the order of the returned list.
	 * 
	 * @return the list of possible states
	 */
	protected List<ActionState<T>> getStates() {
		return actionStates;
	}

	private void updateStates() {
		List<ActionState<T>> newStates = getStates();
		if (newStates.equals(actionStates)) {
			return;
		}
		actionStates.clear();
		actionStates.addAll(newStates);
	}

	/**
	 * Check if the given state can be selected
	 * 
	 * @param state the state to check
	 * @return true (the default) if selectable, false to disable
	 */
	protected boolean isStateEnabled(ActionState<T> state) {
		return true;
	}

	protected List<DockingActionIf> getStateActions() {
		updateStates();
		List<DockingActionIf> actions = new ArrayList<>(actionStates.size());
		for (ActionState<T> actionState : actionStates) {
			boolean isSelected = actionState.equals(currentState);
			DockingActionIf a = useCheckboxForIcons
					? new ActionStateToggleAction(actionState, isSelected)
					: new ActionStateAction(actionState, isSelected);
			boolean isEnabled = isStateEnabled(actionState);
			a.setEnabled(isEnabled);
			actions.add(a);
		}
		return actions;
	}

	public void setGroup(String group) {
		ToolBarData tbd = getToolBarData();
		tbd.setToolBarGroup(group);
	}

	public void setSubGroup(String subGroup) {
		ToolBarData tbd = getToolBarData();
		tbd.setToolBarSubGroup(subGroup);
	}

	/**
	 * Add the supplied {@code ActionState}.
	 * 
	 * @param actionState the {@code ActionState} to add
	 */
	public void addActionState(ActionState<T> actionState) {
		actionStates.add(actionState);
		if (actionStates.size() == 1) {
			setCurrentActionState(actionState);
		}
	}

	public void setActionStates(List<ActionState<T>> newStates) {
		if (newStates.isEmpty()) {
			throw new IllegalArgumentException("You must provide at least one ActionState");
		}
		actionStates = new ArrayList<>(newStates);
		setCurrentActionState(actionStates.get(0));
	}

	public T getCurrentUserData() {
		return currentState == null ? null : currentState.getUserData();
	}

	public ActionState<T> getCurrentState() {
		return currentState;
	}

	public List<ActionState<T>> getAllActionStates() {
		return new ArrayList<>(actionStates);
	}

	public void setCurrentActionStateByUserData(T t) {
		updateStates();
		for (ActionState<T> actionState : actionStates) {

			// Note: most clients will pass a T that is already in our list.  However, to be more
			//       flexible, such as for clients with a T class of String, we should have no
			//       problem using equals() here.
			// if (actionState.getUserData() == t) {
			if (actionState.getUserData().equals(t)) {
				doSetCurrentActionState(actionState, EventTrigger.API_CALL);
				return;
			}
		}

		throw new AssertException(
			"Attempted to set an action state by a user type not contained herein: " + t);
	}

	public void setCurrentActionState(ActionState<T> actionState) {
		setCurrentActionStateWithTrigger(actionState, EventTrigger.API_CALL);
	}

	public void setCurrentActionStateWithTrigger(ActionState<T> actionState, EventTrigger trigger) {
		updateStates();
		doSetCurrentActionState(actionState, trigger);
	}

	protected void doSetCurrentActionState(ActionState<T> actionState, EventTrigger trigger) {
		if (!actionStates.contains(actionState)) {
			throw new IllegalArgumentException(
				"Attempted to set actionState to unknown ActionState.");
		}
		currentState = actionState;
		setButtonState(actionState);

		ToolBarData tbd = getToolBarData();
		tbd.setIcon(getIcon(actionState));

		setDescription(getToolTipText());
		actionStateChanged(actionState, trigger);
	}

	private Icon getIcon(ActionState<T> actionState) {
		Icon icon = actionState.getIcon();
		if (icon != null) {
			return icon;
		}

		if (defaultIcon != null) {
			return defaultIcon;
		}

		return EMPTY_ICON;
	}

	@Override
	public JButton doCreateButton() {
		multipleButton = new MultipleActionDockingToolbarButton(multiActionGenerator);
		if (currentState != null) {
			setButtonState(currentState);
		}

		return multipleButton;
	}

	private void setButtonState(ActionState<T> actionState) {

		if (multipleButton == null) {
			return;
		}

		if (actionState == null) {
			multipleButton.setIcon(null);
			multipleButton.setToolTipText(null);
			return;
		}

		Icon icon = getIcon(actionState);
		multipleButton.setIcon(icon);
		multipleButton.setToolTipText(actionState.getName());
	}

	@Override
	public void setMenuBarData(MenuData newMenuData) {
		throw new UnsupportedOperationException();
	}

	protected void superSetMenuBarData(MenuData newMenuData) {
		super.setMenuBarData(newMenuData);
	}

	@Override
	public void setPopupMenuData(MenuData newMenuData) {
		throw new UnsupportedOperationException();
	}

	public String getToolTipText() {
		if (actionStates.isEmpty()) {
			return getName() + ": <no action states installed>";
		}
		return getName() + ": " + getCurrentState().getName();
	}

	protected void showPopup() {
		multipleButton.showPopup();
	}

//==================================================================================================
// Inner Classes
//==================================================================================================

	private class ActionStateToggleAction extends ToggleDockingAction {

		private final ActionState<T> actionState;

		private ActionStateToggleAction(ActionState<T> actionState, boolean isSelected) {
			super(actionState.getName(), "MultiStateAction");

			this.actionState = actionState;

			setSelected(isSelected);

			setMenuBarData(new MenuData(new String[] { actionState.getName() }));
			HelpLocation helpLocation = actionState.getHelpLocation();
			if (helpLocation != null) {
				setHelpLocation(helpLocation);
			}
			else {
				HelpLocation parentHelp =
					Help.getHelpService().getHelpLocation(MultiStateDockingAction.this);
				setHelpLocation(parentHelp);
			}
		}

		@Override
		public String getInceptionInformation() {
			// we want the debug info for these internal actions to be that of the outer class
			return MultiStateDockingAction.this.getInceptionInformation();
		}

		@Override
		public void actionPerformed(ActionContext context) {
			setCurrentActionStateWithTrigger(actionState, EventTrigger.GUI_ACTION);
		}

	}

	private class ActionStateAction extends DockingAction {

		private final ActionState<T> actionState;

		private ActionStateAction(ActionState<T> actionState, boolean isSelected) {
			super(actionState.getName(), "MultiStateAction");
			this.actionState = actionState;

			setMenuBarData(
				new MenuData(new String[] { actionState.getName() }, actionState.getIcon()));
			HelpLocation helpLocation = actionState.getHelpLocation();
			if (helpLocation != null) {
				setHelpLocation(helpLocation);
			}
			else {
				HelpLocation parentHelp =
					Help.getHelpService().getHelpLocation(MultiStateDockingAction.this);
				setHelpLocation(parentHelp);
			}
		}

		@Override
		public String getInceptionInformation() {
			// we want the debug info for these internal actions to be that of the outer class
			return MultiStateDockingAction.this.getInceptionInformation();
		}

		@Override
		public void actionPerformed(ActionContext context) {
			setCurrentActionStateWithTrigger(actionState, EventTrigger.GUI_ACTION);
		}

	}

}