README.md

1
JSugar
2
======
3
4
JSugar is a tiny, stupid framework, in an attempt to hide away the tons of
5
useless cruft that you get from working with Java's Swing.
6
7
Features
8
--------
9
10
Purely speaking, JSugar does not add anything new compared to when you're using
11
Swing. It does however, offer some considerable advantages over using Swing
12
directly:
13
14
* Easy creation of windows, that offer a series of convenient methods like
15
  createButton(), allowing for easy creation of small GUI programs.
16
* Built-in support for action triggering; Just say which method should be
17
  triggered where, and you're done.
18
* Easy learning curve, compared to manually handling Swing. Create a new Window,
19
  slap some components on it, add the methods it needs to call on trigger, and
20
  done.
21
* Relies mainly on primitive types, like integer arrays, and classes that are
22
  available in every recent OpenJDK version, like Strings.
23
* Completely [free/libre software](https://www.gnu.org/philosophy/free-sw.html).
24
* Very lightweight. It's just a bunch of source files that you can directly link
25
  to. Putting it in a seperate jar will cause more harm than good.
26
* Only RuntimeExceptions will be thrown, avoiding *exception infection* that
27
  you'll get from using self-defined exceptions in Java.
28
* Documentation available through JavaDoc. I do my very best to provide clear
29
  documentation, so you know how to use this without having to figure it out
30
  yourself.
31
* Components you add are returned to the caller, so if you do need some more
32
  advanced stuff, you can add it yourself.
33
34
Some other stuff that's inherint to Swing itself, might be fixed in a future
35
version, but some might not (Don't expect JSugar to become a thread-safe Swing
36
framework, Swing will stay Swing). I reserve the right to be lazy.
37
38
Limitations
39
-----------
40
41
The convenience causes some limitations, but they're fairly minor, and if you're
42
using JSugar, it's very unlikely you'd be bothered by them anyway, but here they
43
are:
44
45
* You can't add your own panels to the window, but you'll most likely just want
46
  to add some components to the window itself.
47
* The panels default to double buffering (which you should do anyway) and the
48
  flow layout.
49
* The window is automatically updated whenever a new component is added. When
50
  using Swing 'natively', you could postpone updating, but why did you add a
51
  component then in the first place?
52
* *Trigger methods* can only have 1 parameter, or none at all. That 1 parameter
53
  must be of type java.awt.event.ActionEvent. This should be enough for >80% of
54
  use cases, and if you really need more flexibility, you can add your own
55
  action handlers manually.
56
* Pressing the X in the title bar of the window closes it. >95% of use cases do
57
  this anyway.
58
* Some silly stuff like adding icons to buttons, checkboxes, ... is not
59
  possible. You'll have to do that yourself. Yet for most use cases,you might
60
  just do the sane thing and add text.
61
* Certain components don't offer the ability to attach a trigger action to them.
62
  We're talking about components like labels. But then again, these kind of
63
  components shouldn't get much triggers anyway.
64
* Some components have deliberately been left out, because they don't offer many
65
  information/interaction for the user. An example for this, is the
66
  JProgressBar. Although in some rare cases it's a very useful thing, but it's
67
  mainly eye candy, and you may just show the data in a JLabel anyway.
68
  However, if I feel like doing so, and the rest of the library is stable, I may
69
  add such components.
70