jsugar

======

JSugar is a tiny, stupid framework, in an attempt to hide away the tons of

useless cruft that you get from working with Java's Swing.

Features

--------

Purely speaking, JSugar does not add anything new compared to when you're using

Swing. It does however, offer some considerable advantages over using Swing

directly:

* Easy creation of windows, that offer a series of convenient methods like

  createButton(), allowing for easy creation of small GUI programs.

* Built-in support for action triggering; Just say which method should be

  triggered where, and you're done.

* Easy learning curve, compared to manually handling Swing. Create a new Window,

  slap some components on it, add the methods it needs to call on trigger, and

  done.

* Relies mainly on primitive types, like integer arrays, and classes that are

  available in every recent OpenJDK version, like Strings.

* Completely [free software](https://www.gnu.org/philosophy/free-sw.html).

  to. Putting it in a seperate jar will cause more harm than good.

* Only RuntimeExceptions will be thrown, avoiding *exception infection* that

  you'll get from using self-defined exceptions in Java.

* Documentation available through JavaDoc. I do my very best to provide clear

  documentation, so you know how to use this without having to figure it out

  yourself.

* Components you add are returned to the caller, so if you do need some more

  advanced stuff, you can add it yourself.

Some other stuff that's inherint to Swing itself, might be fixed in a future

version, but some might not (Don't expect JSugar to become a thread-safe Swing

framework, Swing will stay Swing). I reserve the right to be lazy.

Limitations

-----------

The convenience causes some limitations, but they're fairly minor, and if you're

using JSugar, it's very unlikely you'd be bothered by them anyway, but here they

are:

* You can't add your own panels to the window, but you'll most likely just want

  to add some components to the window itself.

* The panels default to double buffering (which you should do anyway) and the

  flow layout.

* The window is automatically updated whenever a new component is added. When

  using Swing 'natively', you could postpone updating, but why did you add a

  component then in the first place?

* *Trigger methods* can only have 1 parameter, or none at all. That 1 parameter

  must be of type java.awt.event.ActionEvent. This should be enough for >80% of

  use cases, and if you really need more flexibility, you can add your own

  action handlers manually.

* Pressing the X in the title bar of the window closes it. >95% of use cases do

  this anyway.

* Some silly stuff like adding icons to buttons, checkboxes, ... is not

  possible. You'll have to do that yourself. Yet for most use cases,you might

  just do the sane thing and add text.

* Certain components don't offer the ability to attach a trigger action to them.

  We're talking about components like labels. But then again, these kind of

  components shouldn't get much triggers anyway.

* Some components have deliberately been left out, because they don't offer many

  information/interaction for the user. An example for this, is the

  JProgressBar. Although in some rare cases it's a very useful thing, but it's

  mainly eye candy, and you may just show the data in a JLabel anyway.

  However, if I feel like doing so, and the rest of the library is stable, I may

  add such components.

 * 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)

 * - JComboBox

 * - JFileChooser (?)

 * - JSpinner (Number scoller input widget)

 * - JLabel

 * - JText

 * - JButton

 * - JDialogBoxes (you know, everything dialog related)

 * - JCheckbox

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

 */

/**

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

	}

}