jsugar

/**

 * Window.java - Module to create a new window with JSugar.

 * Copyright © 2016 Maarten "Vngngdn" Vangeneugden

 * 

 * This program is free software: you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation, either version 3 of the License, or

 * (at your option) any later version.

 * 

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 * 

 * You should have received a copy of the GNU General Public License

 * along with this program.  If not, see <https://www.gnu.org/licenses/>.

 */

/*

 * TODO list:

 * - JSlider (It's the same as the JSpinner, only longer. So an extra.)

 * - JTable (And a JScrollBar to accompany it) (extra, because of JList)

 * - JFileChooser (?)

 * DONE list:

 * - JLabel

 * - JText

 * - JButton

 * - JDialogBoxes (you know, everything dialog related)

 * - JCheckbox

 * - JRadioButton (properly grouping them has been taken care of as well)

 * - JSpinner

 * - JComboBox

 * - JList

 */

import javax.swing.*; // FIXME: Maybe namespacing it to "javax.swing;" is a better idea.

import java.util.NoSuchElementException;

import java.lang.reflect.Method;

import java.io.File;

/**

 * Window class for the program.

 *

 * Window contains the necessary data and methods to present the user with what

 * he's familiar with as being a "window". To make it functional, the developer

 * can make use of a series of methods to add components to said window, remove

 * components, and so on.

 * Currently, Window also contains methods to show dialogs. This will be cleaned

 * in the near future.

 * @author Maarten Vangeneugden

 */

public class Window { // Must be public, in order to generate Javadoc.

	private JPanel panel; // The panel that contains all the components.

	private JFrame frame; // The "window" being presented to the user.

	/**

	 * Constructor of Window.

	 * By creating a new Window instance, this constructor will automatically

	 * start the initialization of the GUI. After doing so, the caller can

	 * start adding components to the window as pleased.

	 * @param title The title to be shown in the window's title bar.

	 */

	public Window(String title) {

		// Setting the UI style to the platform's UI style. Fuck Swing's,

		// really.

		try {

		UIManager.setLookAndFeel(

				UIManager.getSystemLookAndFeelClassName());

		} catch(Exception e) {

			e.printStackTrace();

		}

		if(title == null || title.equals("")) { // If the title was omitted:

			title = "JSugar";

		}

		this.panel = new JPanel();

		// TODO: The current title is "Hello world!" but that will become caller

		// defined soon.

		JFrame frame = new JFrame(title);

		// Makes it so that if the user clicks the X in the titlebar, the window

		// closes:

		frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);

		//frame.getContentPane().add(lblHelloWorld); // So you use a get() in order to set() data? #JavaWTF

		frame.setContentPane(this.panel); // Connecting the component panel to the window.

		// Makes the window fit to the necessary width and height, so it can show all "subcomponents".

		frame.pack(); 	

		frame.setVisible(true); // Makes the window visible to the user.

		this.frame = frame;

	}

	/**

	 * Resizes the window to fit all components.

	 * By calling this method, the window will evaluate the currently visible

	 * components, and resize itself so that all components become properly

	 * visible.

	 */

	private void updateWindow() {

		this.frame.pack();

	}

	/**

	 * A series of tests for method and class handling.

	 * When a caller presents certain methods with data concerning reflection,

	 * the Java classes you need to use for that are quite opaque, and don't

	 * offer much safety in any way.

	 * The solution therefore, is run some validation checks, but these take up

	 * a decent amount of space in terms of LoC.

	 * This method takes care of all that. Call this function whenever data

	 * needs to be validated.

	 * @param methodName The name of the method, as it is declared in object.

	 * @param object The class instance in where this method will be called.

	 * @return The method that could be derived from the supplied data, or null

	 * if that wasn't possible.

	 * @throws NullPointerException if either methodName or object are null

	 * pointers.

	 * @throws IllegalArgumentException if methodName is empty, or the method

	 * does not appear to be declared in the given object, or object is not a

	 * class.

	 */

	// All unchecked typecasts are safe, and the use of raw types is taken care

	// of.

	@SuppressWarnings({"unchecked","rawtypes"})

	private Method handleReflectionData(String methodName, Object object) {

		// Null pointer checking:

		if (methodName == null || object == null) {

			throw new NullPointerException("One or more of the given parameters are null pointers.");

		}

		// XXX: Some might say the next line should be in an else{} block. But

		// Scoping rules require that I'd then have to wrap the rest of the

		// method in the same else to use it.

		Class methodClass = object.getClass(); 

		if (methodName.equals("")) {

			throw new IllegalArgumentException("The given methodName was empty.");

		}

		Method method;

		try { // First: Look if there's a method without parameters.

			method = methodClass.getMethod(methodName, null);

		}

		catch (NoSuchMethodException exception) {

			try {

				// It's possible that the method requires an event parameter, so

				// check for that as well:

				Class<?>[] parameters = {java.awt.event.ActionEvent.class};

				method = methodClass.getMethod(methodName, parameters);

			}

			catch (NoSuchMethodException e) {

				throw new IllegalArgumentException("The given method does not appear in the given class. Be aware that the given method mustn't have any parameters, or only 1 parameter, which has to be of type java.awt.event.ActionEvent.");

			}

		}

		// At this stage, the given data has been validated, and we've been able

		// to retrieve the method itself.

		return method;

	}

	/**

	 * Creates a button in the GUI for interaction.

	 * This function offers a convenient way to create a button, that can be

	 * directly interacted with by the user. After creation, the button itself

	 * is returned to the caller, if he wishes to do something else with it.

	 * @param text The text that will be displayed in the button.

	 * @param action The action that will be returned to the action listener.

	 * @param methodName The name of the method that will be called when an

	 * action is triggered.

	 * @param triggerObject The object instance that contains the given method.

	 * This may only be a null pointer if triggerMethod is not an instance

	 * method.

	 * performed. This method may accept an ActionEvent parameter as its only

	 * parameter, or no parameters at all.

	 * @throws NullPointerException if triggerMethod is a null pointer, or

	 * the empty String was given.

	 * @throws IllegalArgumentException if triggerMethod has more than 1

	 * parameter, or the 1 required parameter is not of type ActionEvent.

	 * @return The button that was created.

	 * @see java.awt.event.ActionEvent

	 * @see java.lang.reflect.Method#invoke

	 */

	public JButton createButton(String text, String action, String methodName, Object triggerObject) {

		Method triggerMethod = this.handleReflectionData(methodName, triggerObject);

		// For starters, we first assert that the given parameters are valid:

		if (text == null) {

			text = "";

		}

		if (action == null) {

			action = "";

		}

		// When the method gets here, everything's been validated correctly.

		JButton button = new JButton(text);

		button.setActionCommand(action);

		button.addActionListener(

				new java.awt.event.ActionListener() {

					public void actionPerformed(java.awt.event.ActionEvent event) {

						try {

							triggerMethod.setAccessible(true);

							if (triggerMethod.getParameterTypes().length == 0) {

								// FIXME: Next line throws a warning?

								triggerMethod.invoke(triggerObject, null);

							}

							else {

								triggerMethod.invoke(triggerObject, new Object[]{event});

							}

						}

						catch (Exception useless) {

							/*

							 * XXX: Some info on why I don't just throw said

							 * Exception to the caller:

							 * Java has this awful language constraint, which

							 * forces every damn exception that isn't a subclass

							 * of RuntimeException, to be declared in the method

							 * declaration. This tends to infect all underlying

							 * methods as well, and all that for reasons I can't

							 * comprehend. In order to keep JSugar a simple and

							 * clean library, I'll rather just handle it here,

							 * and throw a RuntimeException with appropriate

							 * details.

							 */

							throw new IllegalArgumentException("triggerMethod is not accessible from this context.");

						}

					}

				});

		this.addComponent(button);

		return button;

	}

	/**

	 * Ask the user for input through a dialog box.

	 * This method presents the user with an input field, that can accept

	 * textual input. The method will return the given input after the user's

	 * clicked a button to send.

	 * @param text The text/question to be asked to the user.

	 * @return A String, equal to what the user entered.

	 * @throws NullPointerException if text is a null pointer.

	 */

	public String inputDialog(String text) {

		if (text == null) {

			throw new NullPointerException("The given text/question was a null pointer.");

		}

		return JOptionPane.showInputDialog(text);

	}

	/**

	 * Give the user a dialog box.

	 * This method can be used to provide a simple dialog to the user.

	 * This will show the user the given question, after which a boolean value

	 * is returned, holding the choice.

	 * @param text The text/question to be asked to the user.

	 * @return True if the user confirms, False if he denies.

	 * @throws NullPointerException if text is a null pointer.

	 */

	public boolean confirmDialog(String text) {

		if (text == null) {

			throw new NullPointerException("The given text/question was a null pointer.");

		}

		final int ACCEPTED = 0;

		//final int DENIED = 1; // Not used in the current context.

		int result = this.choiceDialog(text, new String[]{"Confirm", "Deny"});

		if (result == ACCEPTED) {

			return true;

		}

		else {

			return false;

		}

	}

	/**

	 * Give the user a choice dialog box.

	 * This method gives the user a simple dialog with predefined choices.

	 * These choices are to be provided by the caller in a simple array.

	 *

	 * Tip: This method works extremely well with arbitrary created choices.

	 * That is: if the outcome of the dialog is trivial (e.g. Only 1 choice),

	 * then that value is immediately returned.

	 * @param text The text/question to be asked to the user.

	 * @param choices An array of Strings, containing the choices the user can

	 * pick.

	 * @return The index value of the picked choice, or -1 if no choices were

	 * given.

	 * @throws NullPointerException if text is a null pointer.

	 */

	public int choiceDialog(String text, String[] choices) {

		if (text == null) {

			throw new NullPointerException("The given text/question was a null pointer.");

		}

		// First: handling the trivial cases:

		if (choices.length == 0) {

			return -1;

		}

		else if (choices.length == 1) {

			return 0;

		}

		int answer = JOptionPane.CLOSED_OPTION;

		// The dialog needs to be shown again until the user has made a possible

		// choice, i.e. Chickening out using the close button is not possible

		// (Because that returns CLOSED_OPTION).

		while (answer == JOptionPane.CLOSED_OPTION) {

				JOptionPane.showOptionDialog(

					null, // The parent component. May become the panel?

					text, // The text/question to describe the goal

					"Dialog", // The text in the title bar

					JOptionPane.DEFAULT_OPTION, // The kind of available options

					JOptionPane.QUESTION_MESSAGE, // The type of message

					null, // The icon to show

					choices, // The possible choices

					choices[0] // The standard choice

					);

		}

		return answer;

	}

	/**

	 * Creates a label in the GUI for interaction.

	 * This function offers a convenient way to create a label, that can be

	 * directly interacted with by the user. After creation, the label itself

	 * is returned to the caller, if he wishes to do something else with it.

	 * @param text The text that will be displayed in the label.

	 * @return The label that was created.

	 */

	public JLabel createLabel(String text) {

		JLabel label = new JLabel(text);

		this.addComponent(label);

		return label;

	}

	/**

	 * Adds a checkbox to the window.

	 * By providing a String, you can use this method to easily

	 * create a checkbox, and add it to the window. 

	 * @param text The text to put next to the checkbox.

	 * @return The checkbox that was created and added to the GUI.

	 */

	public JCheckBox createCheckbox(String text) {

		JCheckBox checkbox = new JCheckBox(text);

		this.addComponent(checkbox);

		return checkbox;

	}

	/**

	 * Adds radio buttons to the window.

	 * Given a list of Strings, this method will create the same amount of radio

	 * buttons.

	 *

	 * The radio buttons will silently be grouped in a ButtonGroup object,

	 * making them automatically disable each other, so only 1 radio button can

	 * be enabled. This ButtonGroup is immutable.

	 *

	 * If you need a mutable ButtonGroup, create your own, and use the 

	 * {@link #addComponent} method to add the radio buttons manually.

	 * @param text An array of Strings. The length of the array will determine

	 * the amount of radio buttons that will be created.

	 * @return An array of radio buttons, in the same order as text.

	 */

	public JRadioButton[] createRadioButtons(String text[]) {

		JRadioButton[] radioButtons = new JRadioButton[text.length];

		ButtonGroup buttonGroup = new ButtonGroup();

		for (int i=0; i<radioButtons.length; i++) {

			radioButtons[i].setText(text[i]);

			buttonGroup.add(radioButtons[i]);

			this.addComponent(radioButtons[i]);

		}

		assert radioButtons.length == buttonGroup.getButtonCount() : "The amount of radio buttons ("+ radioButtons.length +") differs from the amount of buttons in buttonGroup ("+ buttonGroup.getButtonCount() +").";

		return radioButtons;

	}

	/**

	 * Adds a number spinner component to the GUI.

	 * This method allows the caller to create a so-called "spinner component"

	 * to the window. This spinner is an input box, in which only integers can

	 * be put.

	 *

	 * The caller can set a range, a start value, and a step size.

	 *

	 * The spinner created with this method may modify itself based on the

	 * parameters.

	 * For example: If the minimum and maximum value are equal, the spinner will

	 * be disabled.

	 *

	 * @param minimum The minimum value that can be selected.

	 * @param maximum The maximum value that can be selected.

	 * @param start The value that will initially be shown in the component.

	 * @param stepSize The step size when the user increases/decreases the

	 * value.

	 * @throws IllegalArgumentException if minimum is larger than maximum, 

	 * start is not in the range of the selectable values, or stepsize is not a

	 * natural number.

	 * @return The JSpinner that was added to the window.

	 */

	public JSpinner createSpinner(int minimum, int maximum, int start, int stepSize) {

		// As usual, we begin with checking the contract:

		if(minimum > maximum) {

			throw new IllegalArgumentException("The minimum value ("+ minimum +") was larger than the maximum value ("+ maximum +")");

		}

		// The "start ∉ [minimum, maximum]" is done by the SpinnerNumberModel

		// constructor, which will be constructed later.

		if(stepSize <= 0) { // stepSize ∉ ℕ¹ (In Belgium: ℕ₀)

			throw new IllegalArgumentException("The stepSize ("+ stepSize +") is not a natural number (excluding 0).");

		}

		// If the contract is valid, we can begin:

		/*

		 * I'd like to interject here, because this is a nice example of why

		 * JSugar was a good idea:

		 * If you want a spinner, you'll typically want an integer spinner. But

		 * in Swing, when you create a JSpinner, it creates a JSpinner, with a

		 * predefined 'SpinnerNumberModel' attached to it.

		 * It's this model you then have to extract from the created spinner, on

		 * which you need to apply the configuration.

		 * What you actually have to do, is create a SpinnerNumberModel

		 * yourself, put your settings on that, and then, create a JSpinner to

		 * which you give that SpinnerNumberModel.

		 * In essence: The entire Java framework is shit.

		 */

		SpinnerNumberModel spinnerSettings = new SpinnerNumberModel(

				start,

				minimum,

				maximum,

				stepSize

				);

		JSpinner spinner = new JSpinner(spinnerSettings);

		if(minimum == maximum) { // Trivial value is set already, --> disable.

			spinner.setEnabled(false);

		}

		this.addComponent(spinner);

		return spinner;

	}

	/**

	 * Adds a number spinner component to the GUI.

	 * This method allows the caller to create a so-called "spinner component"

	 * to the window. This spinner is an input box, in which only integers can

	 * be put.

	 * 

	 * Tip: This method is a convenience method, and works extremely well with

	 * arbitrary data.

	 * For example: The start value is automatically set to the minimal possible

	 * value, and the step size defaults to 1.

	 * If the minimum and maximum are equal, the component will be disabled, and

	 * thus, be locked on the only (trivially) possible value.

	 * If minimum is larger than maximum, the method will notify you of this,

	 * but also swap the values. So you can rest assured that the spinner will

	 * handle errors, but also, inform you about it.

	 * @param minimum The minimum value that can be selected.

	 * @param maximum The maximum value that can be selected.

	 * @return The JSpinner component that was added to the window.

	 */

	public JSpinner createSpinner(int minimum, int maximum) {

		// The disabling of equal values is done in the full createSpinner(), so

		// this is merely switching values if they need to be swapped.

		if(minimum > maximum) {

			System.err.println("minimum ("+ minimum +") was larger than maximum ("+ maximum +").");

			// FIXME: Consider whether it's appropriate to print a stacktrace

			// here, which may be convenient for debugging.

			// XXX: I know you don't need the help variable when swapping

			// integers, because you can also do basic arithmetics. Change it if

			// it causes too much eye burn for you.

			int swapValue = minimum;

			minimum = maximum;

			maximum = swapValue;

		}

		// Yeah, these 2 variables make you cringe huh, performance addicts?

		// Drown me in the tears of your useless performance-related opinions.

		int startValue = minimum;

		int stepSize = 1;

		return this.createSpinner(minimum, maximum, startValue, stepSize);

	}

	/**

	 * Adds a combobox to the GUI.

	 * Allows the caller to create a combobox by providing the values that

	 * should be put in it.

	 *

	 * This method can only be used for String values. If that is not what you

	 * need, consider creating your own combobox and adding it manually. Or, if

	 * you need a combobox for integers, consider {@link #createSpinner}.

	 *

	 * WARNING: {@link JComboBox#getSelectedItem} returns an object, not a

	 * String. You need to manually typecast this. This is a constraint of the

	 * Swing framework.

	 * @param items An array of Strings that will be put in the combobox.

	 * @throws NullPointerException if one of the values in items is a null

	 * pointer.

	 * @throws IllegalArgumentException if items is empty.

	 * @return The JCombobox that was added to the window.

	 */

	public JComboBox<String> addComboBox(String[] items) {

		// Contract validation:

		if(items.length == 0) {

			throw new IllegalArgumentException("The given array of items was empty.");

		}

		for(String item : items) {

			if(item == null) {

				throw new NullPointerException("One of the given Strings is a null pointer.");

			}

		}

		// Contract validated, create the component:

		JComboBox<String> comboBox = new JComboBox<String>(items);

		comboBox.setSelectedIndex(0);

		if(comboBox.getItemCount() == 1) { // Trivial selection

			comboBox.setEnabled(false);

		}

		this.addComponent(comboBox);

		return comboBox;

	}

	/**

	 * Creates a list of the given data, and adds it to the GUI.

	 * This will create a JList component, containing the given data. 

	 * To jar up your memory: A list in this context, is a component in which

	 * data of the same type is printed out. The user of said list, can then

	 * select a subset of these items.

	 *

	 * @see JList for a collection of possible operations.

	 * @param items The String items that will be put in the list.

	 * @throws NullPointerException if one of the values in items is a null

	 * pointer.

	 * @throws IllegalArgumentException if items is empty.

	 * @return A JList component, that was a added to the GUI.

	 */

	public JList createList(String[] items) {

		// Contract validation:

		if(items.length == 0) {

			throw new IllegalArgumentException("The given array of items was empty.");

		}

		for(String item : items) {

			if(item == null) {

				throw new NullPointerException("One of the given Strings is a null pointer.");

			}

		}

		// Contract validated, create the component:

		JList list = new JList(items);

		this.addComponent(list);

		return list;

	}

	/**

	 * Creates a table of the given data, and adds it to the GUI.

	 * This method allows you to create a table with sorting functionality in

	 * the GUI.

	 * This method relies on implications, deducted from the given data. That

	 * is, the length of the rows and columns is calculated by the longest

	 * length it can find in the nested array.

	 * To change the data, take a look at the JTable documentation.

	 *

	 * @see JTable for a collection of possible operations.

	 * @param items The String items that will be put in the list.

	 * @throws NullPointerException if one of the values in items is a null

	 * pointer.

	 * @throws IllegalArgumentException if items is empty, or the amount of

	 * column names does not correspond with the given amount of items.

	 * @return A JTable component, that was a added to the GUI.

	 */

	public JTable createTable(String[] columns, String[][] items) {

		// Contract validation:

		if(items.length == 0) {

			throw new IllegalArgumentException("The given array of items was empty.");

		}

		if(columns.length != items[0].length) {

			throw new IllegalArgumentException("The amount of columns does not correspond to the given amount of items.");

		}

		for(int i=0; i<items.length; i++) {

			if(items[i] == null) {

				throw new NullPointerException("One of the given Strings is a null pointer.");

			}

		}

		// Contract validated, create the component:

		// Deducting max length:

		int columnCount = columns.length;

		int rowCount = items.length;

		JTable table = new JTable(items, columns);

		this.addComponent(table);

		return table;

	}

	/**

	 * Adds the given component to the GUI.

	 * This method allows its caller to give a pre-made component, so that it

	 * can be added to the GUI. Even though its main use is for the Window class

	 * itself, the user of JSugar can also use it to create components himself,

	 * and then add them. As such, this method doesn't provide parameters for

	 * reflection/action triggering purposes.

	 * @param component The component to be added to the window.

	 * @throws NullPointerException if the given component is a null pointer.

	 */

	public void addComponent(JComponent component) {

		int originalSize = this.panel.getComponentCount();

		this.panel.add(component); // Throws the exception if null.

		this.updateWindow();

		assert originalSize == this.panel.getComponentCount()-1 : "A component was supposed to be added to the window, but the total amount of components was unchanged after the addition.";

	}

	/**

	 * Removes the given component from the GUI.

	 * This method allows its caller to remove a component from the GUI.

	 * @param component The component to be removed.

	 * @throws NoSuchElementException if the given component does not exist in

	 * the GUI.

	 * @throws NullPointerException if the given component is a null pointer.

	 */

	public void removeComponent(JComponent component) {

		int originalSize = this.panel.getComponentCount();

		this.panel.remove(component);

		int newSize = this.panel.getComponentCount();

		if (originalSize != newSize+1) {

			throw new NoSuchElementException("The given component does not exist in the GUI.");

		}

		this.updateWindow();

	}

	/**

	 * Prompts the user with a file chooser dialog.

	 * By calling this method, the user will be presented with a file chooser

	 * dialog, out of which a single file can be selected. If the selected file

	 * exists, a File object is returned, a null pointer if the user cancelled.

	 * @return A File object representing the file the user selected, or null

	 * otherwise.

	 */

	public File openFileChooserDialog() {

		JFileChooser fileDialog = new JFileChooser();

		fileDialog.setFileSelectionMode(JFileChooser.FILES_ONLY);

		int userResponse = fileDialog.showOpenDialog(this.panel);

		if(userResponse == JFileChooser.APPROVE_OPTION) {

			return fileDialog.getSelectedFile();

		}

		else {

			return null;

		}

	}

}