jsugar | Gitar

Added the begin of the JavaDoc for the JList creator method.

Author: Vngngdn
Date: Aug. 10, 2016, 6:36 p.m.
Hash: fc46395293130814d070142e129f82b8939d32f2
Parent: 7539cb4c37ba221b16cc1a5963ef58a3c6349e9b
Modified file: Window.java
Window.java ¶

5 additions and 1 deletion.
View changes Hide changes
 * 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:
 * - JList
 * - JSlider
 * - JTable (And a JScrollBar to accompany it)
 * - JTable (And a JScrollBar to accompany it)
 * - 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
 */

/**
 * 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
 */
import javax.swing.*; // FIXME: Maybe namespacing it to "javax.swing;" is a better idea.
import java.util.NoSuchElementException;
import java.lang.reflect.Method;

class Window {
	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() {
		this.panel = new JPanel();
		// TODO: The current title is "Hello world!" but that will become caller
		// defined soon.
		JFrame frame = new JFrame("Hello world!");
		// 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 objectInstance 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. 
	 */
	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: {@see 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. 

	/**
	 * 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();
	}
}
