Skip to content

Ghidra is a software reverse engineering (SRE) framework

9.3 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.widgets;

import java.awt.Component;
import java.util.ArrayList;
import java.util.List;

import javax.swing.Icon;

import ghidra.util.Swing;

/**
 * Class for creating OptionDialogs using the builder pattern.
 *
 * <P>At a minimum, an OptionDialog requires a title and a message.  They can be specified
 * in the constructor or set later.
 *
 * <P>You can also, specify the messageType or an icon.  The messageType is used to set the
 * icon to one of several predefined ones appropriate for the message(ERROR, WARNING, etc.)
 * You should not specify both, but if you do, the specified Icon will be used and the
 * MessageType will be ignored.
 *
 * <P>You can also add "options" which are custom buttons with the given text. Each option
 * button is mapped to a different integer dialog result.  The result values start at 1
 * for the first option and increment by 1 for each additional option.
 * For example, if you add options "yes" and "no" in that order, then pressing the "yes"
 * button will produce a dialog result of 1, and pressing the "no" button will produce a
 * dialog result of 2.  If no options are added, then an "OK" button will automatically be added.
 *
 * <P>You can also set the default button by calling {@link #setDefaultButton(String)} where the
 * string is the text of the button (the option) that you want to be the default .  For example, if you
 * have the options "yes" and "no", you can make the "no" button the default by specifying
 * "no" as the defaultOption.
 *
 * <P>You can also add a Cancel button, which will return a result of 0 if pressed. Note that this
 * is different than adding an option named "Cancel" which would return a result greater than
 * <code>0</code>, depending on where in the order it was added.
 *
 * <P><a id="RememberOption"></a>A "Remember Option" can be added to OptionDialog to
 * present the user with a choice for remembering a dialog result and automatically
 * returning that result instead of showing the dialog or similar dialogs in the future.
 * Note that for simple OK dialogs, there really isn't a meaningful result to remember, other
 * than a decision was made not to show the dialog again.
 *
 * <P>The "Remember Option" is represented as a checkBox at the bottom of an OptionDialog.
 * The checkBox text will be either "Apply to all", "Remember my decision",
 * or "Don't show again" depending on whether {@link #addApplyToAllOption()},
 * {@link #addDontShowAgainOption()}, or {@link #addRememberMyDecisionOption()} method is
 * called.  Each of these methods called will overwrite the previously called method.
 *
 * <P>If the user selects the checkBox, then the dialog result will be remembered.
 * In future calls to display that dialog , the dialog will first check if has a
 * {@link DialogRememberOption} object and that it has a remembered result, and if so, will just 
 * return the remembered result instead of showing the dialog.  The remember options will be used
 * as long as the dialog is being used by the client.  The client must hold onto the dialog so that
 * repeated calls will work as expected with the remember option chosen.   The client could instead
 * hold onto the builder and use the {@link #show()} method to get the same behavior.
 */
public class OptionDialogBuilder {
	private String title;
	private String message;
	private Icon icon;
	private int messageType;
	private boolean addCancelButton;
	private List<String> options;
	private String defaultOption;
	private DialogRememberOption rememberOption;

	/**
	 * Constructs an OptionDialogBuilder with not even the minimal information required. If
	 * this constructor is used, then both {@link #setTitle(String)} and the
	 * {@link #setMessage(String)} methods must be called
	 * or else the dialog will have no title or message.
	 */
	public OptionDialogBuilder() {
		this(null, null);
	}

	/**
	 * Constructs an OptionDialogBuilder with not even the minimal information required. If
	 * this constructor is used, then the {@link #setMessage(String)} method must be called
	 * or else the dialog will be blank.
	 *
	 * @param title the title of the dialog
	 */
	public OptionDialogBuilder(String title) {
		this(title, null);
	}

	/**
	 * Constructs an OptionDialogBuilder with the minimal information required. If no
	 * other information is set, the builder will create the simplest dialog that has
	 * a title, message and an "Ok" button.
	 *
	 * @param title the title of the dialog.
	 * @param message the main message to be displayed in the dialog.
	 */
	public OptionDialogBuilder(String title, String message) {
		this.title = title;
		this.message = message;
		this.options = new ArrayList<>();
		this.messageType = OptionDialog.PLAIN_MESSAGE;
	}

	/**
	 * Sets the title for the OptionDialog.
	 *
	 * @param title the title for the dialog.
	 * @return this builder object.
	 */
	public OptionDialogBuilder setTitle(String title) {
		this.title = title;
		return this;
	}

	/**
	 * Sets the main message for the OptionDialog.
	 *
	 * @param message the main message for the dialog.
	 * @return this builder object.
	 */
	public OptionDialogBuilder setMessage(String message) {
		this.message = message;
		return this;
	}

	/**
	 * Sets the Icon for the OptionDialog.
	 * <P>
	 * If both an Icon and a message type are specified,
	 * the icon will take precedence.
	 *
	 * @param icon the icon to display in the dialog.
	 * @return this builder object.
	 */
	public OptionDialogBuilder setIcon(Icon icon) {
		this.icon = icon;
		return this;
	}

	/**
	 * Sets the message type for the OptionDialog which will determine the icon that
	 * is in the dialog.
	 *
	 * @param messageType used to specify that this dialog is one of the set types.  See
	 * {@link OptionDialog} for the list of defined messageTypes.
	 * @return this builder object.
	 */
	public OptionDialogBuilder setMessageType(int messageType) {
		this.messageType = messageType;
		return this;
	}

	/**
	 * Adds a cancel button to the OptionDialog.
	 *
	 * @return this builder object.
	 */
	public OptionDialogBuilder addCancel() {
		addCancelButton = true;
		return this;
	}

	/**
	 * Adds a button option to the dialog.
	 *
	 * @param optionName the name of the button to be added to the dialog
	 * @return this builder object.
	 */
	public OptionDialogBuilder addOption(String optionName) {
		options.add(optionName);
		return this;
	}

	/**
	 * Sets the name of the button to be used as the default button.
	 *
	 * @param optionName the name of the option to be the default.
	 * @return this builder object.
	 */
	public OptionDialogBuilder setDefaultButton(String optionName) {
		defaultOption = optionName;
		return this;
	}

	/**
	 * Adds an "Apply to all" option to the dialog. See <a href="#RememberOption">
	 * header documentation</a> for details.
	 * <P>
	 * This will replace any previously added "checkBox" options.
	 *
	 * @return this builder object.
	 */
	public OptionDialogBuilder addApplyToAllOption() {
		this.rememberOption = new DialogRememberOption("Apply to all");
		return this;
	}

	/**
	 * Adds a "Don't show again" option to the dialog. See <a href="#RememberOption">
	 * header documentation</a> for details.
	 * <P>
	 * This will replace any previously added "checkBox" options.
	 *
	 * @return this builder object.
	 */
	public OptionDialogBuilder addDontShowAgainOption() {
		this.rememberOption = new DialogRememberOption("Don't show again");
		return this;
	}

	/**
	 * Adds a "Remember my decision" option to the dialog. See <a href="#RememberOption">
	 * header documentation</a> for details.
	 * <P>
	 * This will replace any previously added "checkBox" options.
	 *
	 * @return this builder object.
	 */
	public OptionDialogBuilder addRememberMyDecisionOption() {
		this.rememberOption = new DialogRememberOption("Remember my decision");
		return this;
	}

	/**
	 * Builds an OptionDialog based on the values set in this builder.
	 *
	 * @return an OptionDialog built based on the values set in this builder.
	 */
	public OptionDialog build() {
		return Swing.runNow(() -> {
			return new OptionDialog(title, message, messageType, icon, addCancelButton,
				rememberOption, options, defaultOption);
		});
	}

	/**
	 * Builds and shows an OptionDialog based on the values set in this builder.
	 *
	 * @return the result returned from the OptionDialog after the user selected an option.
	 */
	public int show() {
		return show(null);
	}

	/**
	 * Builds and shows an OptionDialog based on the values set in this builder.
	 *
	 * @param parent the component to use as the OptionDialog's parent when displaying it.
	 * @return the result returned from the OptionDialog after the user selected an option.
	 */
	public int show(Component parent) {
		if (rememberOption != null && rememberOption.hasRememberedResult()) {
			return rememberOption.getRememberedResult();
		}

		OptionDialog dialog = build();
		dialog.show(parent);
		return dialog.getResult();
	}
}