Skip to content

Ghidra is a software reverse engineering (SRE) framework

7.8 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.util.Objects;

import javax.swing.KeyStroke;

import docking.KeyBindingPrecedence;
import docking.actions.KeyBindingUtils;
import ghidra.framework.options.ActionTrigger;
import ghidra.util.Msg;
import gui.event.MouseBinding;
import utilities.util.reflection.ReflectionUtilities;

/**
 * A class for storing an action's key stroke, mouse binding or both.
 * <p>
 * Note: this class creates key strokes that work on key {@code pressed}.  This effectively
 * normalizes all client key bindings to work on the same type of key stroke (pressed, typed or
 * released).
 */
public class KeyBindingData {
	private KeyStroke keyStroke;
	private KeyBindingPrecedence keyBindingPrecedence = KeyBindingPrecedence.DefaultLevel;

	private MouseBinding mouseBinding;

	public KeyBindingData(KeyStroke keyStroke) {
		this(keyStroke, KeyBindingPrecedence.DefaultLevel);
	}

	public KeyBindingData(char c, int modifiers) {
		this((int) Character.toUpperCase(c), modifiers);
	}

	public KeyBindingData(int keyCode, int modifiers) {
		this(KeyStroke.getKeyStroke(keyCode, modifiers));
	}

	/**
	 * Constructs an instance of this class that uses a mouse binding instead of a key stroke.
	 * @param mouseBinding the mouse binding.
	 */
	public KeyBindingData(MouseBinding mouseBinding) {
		this.mouseBinding = Objects.requireNonNull(mouseBinding);
	}

	/**
	 * Creates a key stroke from the given text.  See
	 * {@link KeyBindingUtils#parseKeyStroke(KeyStroke)}.   The key stroke created for this class
	 * will always be a key {@code pressed} key stroke.
	 *
	 * @param keyStrokeString the key stroke string to parse
	 */
	public KeyBindingData(String keyStrokeString) {
		this(parseKeyStrokeString(keyStrokeString));
	}

	/**
	 * Creates a key binding data with the given action trigger.
	 * @param actionTrigger the trigger; may not be null
	 */
	public KeyBindingData(ActionTrigger actionTrigger) {
		Objects.requireNonNull(actionTrigger);
		this.keyStroke = actionTrigger.getKeyStroke();
		this.mouseBinding = actionTrigger.getMouseBinding();
	}

	public KeyBindingData(KeyStroke keyStroke, KeyBindingPrecedence precedence) {
		if (precedence == KeyBindingPrecedence.SystemActionsLevel) {
			throw new IllegalArgumentException(
				"Can't set precedence to System KeyBindingPrecedence");
		}
		this.keyStroke = Objects.requireNonNull(keyStroke);
		this.keyBindingPrecedence = Objects.requireNonNull(precedence);

		logKeyBindingWhitespaceWarning();
	}

	private void logKeyBindingWhitespaceWarning() {
        int keyCode = keyStroke.getKeyCode();
		if (keyCode != 0) {
			return; // key codes will get converted to text by KeyEvent
		}

		char keyChar = keyStroke.getKeyChar();
		if (!Character.isWhitespace(keyChar)) {
			return; // non-whitespace characters can be read
		}

		// Create a stack trace to take the developer to the place where the key stroke is created.
		// Update the trace so that the first item is that spot.  Remove excess Java elements.
		Throwable t =
			ReflectionUtilities.createThrowableWithStackOlderThan("KeyBindingData",
				"Builder");
		t = ReflectionUtilities.filterJavaThrowable(t);
		Msg.error(this, "Change key stroke to not use a whitespace character.  " +
			"(e.g., KeyBindingUtils.parseKeyStroke(\"space\"))", t);
	}

	private static KeyStroke parseKeyStrokeString(String keyStrokeString) {
		KeyStroke keyStroke = KeyBindingUtils.parseKeyStroke(keyStrokeString);
		if (keyStroke == null) {
			throw new IllegalArgumentException("Invalid keystroke string: " + keyStrokeString);
		}
		return keyStroke;
	}

	/**
	 * Returns a key binding data object that matches the given trigger.  If the existing key 
	 * binding object already matches the new trigger, then the existing key binding data is 
	 * returned.  If the new trigger is null, the null will be returned.
	 * 
	 * @param kbData the existing key binding data; my be null
	 * @param newTrigger the new action trigger; may be null
	 * @return a key binding data based on the new action trigger; may be null
	 */
	public static KeyBindingData update(KeyBindingData kbData, ActionTrigger newTrigger) {
		if (kbData == null) {
			if (newTrigger == null) {
				return null; // no change
			}
			return new KeyBindingData(newTrigger); // trigger added
		}

		if (newTrigger == null) {
			return null; // trigger has been cleared
		}

		ActionTrigger existingTrigger = kbData.getActionTrigger();
		if (existingTrigger.equals(newTrigger)) {
			return kbData;
		}

		return new KeyBindingData(newTrigger);
	}

	/**
	 * Returns an accelerator keystroke to be associated with this action.
	 * @return the binding
	 */
	public KeyStroke getKeyBinding() {
		return keyStroke;
	}

	/**
	 * Returns the keyBindingPrecedence for this action
	 * @return the precedence
	 */
	public KeyBindingPrecedence getKeyBindingPrecedence() {
		return keyBindingPrecedence;
	}

	/**
	 * Returns the mouse binding assigned to this key binding data.
	 * @return the mouse binding; may be null
	 */
	public MouseBinding getMouseBinding() {
		return mouseBinding;
	}

	/**
	 * Creates a new action trigger with the values of this class
	 * @return the action trigger
	 */
	public ActionTrigger getActionTrigger() {
		return new ActionTrigger(keyStroke, mouseBinding);
	}

	@Override
	public String toString() {
		return getClass().getSimpleName() + "[KeyStroke=" + keyStroke + ", precedence=" +
			keyBindingPrecedence + ", MouseBinding=" + mouseBinding + "]";
	}

	@Override
	public int hashCode() {
		return Objects.hash(keyBindingPrecedence, keyStroke, mouseBinding);
	}

	@Override
	public boolean equals(Object obj) {
		if (this == obj) {
			return true;
		}
		if (obj == null) {
			return false;
		}
		if (getClass() != obj.getClass()) {
			return false;
		}

		KeyBindingData other = (KeyBindingData) obj;
		if (keyBindingPrecedence != other.keyBindingPrecedence) {
			return false;
		}
		if (!Objects.equals(keyStroke, other.keyStroke)) {
			return false;
		}
		if (!Objects.equals(mouseBinding, other.mouseBinding)) {
			return false;
		}
		return true;
	}

	static KeyBindingData createSystemKeyBindingData(KeyStroke keyStroke) {
		KeyBindingData keyBindingData = new KeyBindingData(keyStroke);
		keyBindingData.keyBindingPrecedence = KeyBindingPrecedence.SystemActionsLevel;
		return keyBindingData;
	}

	/**
	 * Updates the given data with system-independent versions of key modifiers.  For example,
	 * the <code>control</code> key will be converted to the <code>command</code> key on the Mac.
	 * @param newKeyBindingData the data to validate
	 * @return the potentially changed data
	 */
	static KeyBindingData validateKeyBindingData(KeyBindingData newKeyBindingData) {
		if (newKeyBindingData == null) {
			return null;
		}

		KeyStroke keyBinding = newKeyBindingData.getKeyBinding();
		if (keyBinding == null) {
			// not sure when this can happen
			return newKeyBindingData;
		}

		KeyBindingPrecedence precedence = newKeyBindingData.getKeyBindingPrecedence();
		if (precedence == KeyBindingPrecedence.SystemActionsLevel) {
			KeyBindingData kbd =
				createSystemKeyBindingData(KeyBindingUtils.validateKeyStroke(keyBinding));
			kbd.mouseBinding = newKeyBindingData.mouseBinding;
			return kbd;
		}

		KeyBindingData kbd =
			new KeyBindingData(KeyBindingUtils.validateKeyStroke(keyBinding), precedence);
		kbd.mouseBinding = newKeyBindingData.mouseBinding;
		return kbd;
	}
}