NOTES.txt

1DESIGN PRINCIPLES
-----------------
* Accessibility. The library should be easy to set up and use. It should be easy and painless to quickly throw together a UI to control some parameters of a sketch. This is in spirit of the 'sketching metaphor' of processing.
* Minimalism. Graphic elements should be clean in design, easily readable and understandable. A basic but usable set of user interface elements should be provided.
* Extensibility. Allow for customizing the display of UI Elements and support creating completely new ones regardless of the type of data they represent.


IDEAS
-----
* Separate Event System Library (see ofxEvent)
* Basic Elements (Slider, Button, Toggle, Label, Divider)
* Sensible Defaults (Position, Size, Proportion)
* Grid Based Layout
* Graphical Layout Adjustment ("Edit Mode", Drag & Drop)
* Minimal Theme
* Auto connect to variables and functions (by name)
* Write your own elements (Functionality & Look)
* Accessible Documentation (see Interfascia)
* Documentation through examples
* GUI Overlay
* Save and load parameters
* Method Chaining (controlP5)
* Feedback when an Element auto-connects (console)
* Main GUI Object has a graphic representation (the overlay). When empty contains a notice that elements need to be added.
* Automatic Labels for elements
* Simplest way to create a GUI Element?
* Performance: Draw GUI in offscreen buffer. Only redraw when changed.
* Possible to avoid class syntax? (beginners!)
* When an element is created without any callbacks, print help text to the console.
* Container Widgets for grouping
* Save defaults in config file
* Extended PUI class with more features e.g. PUIAdvanced
* keyboard events for adding hotkeys (add focus property to widgets)
* PGraphics as render target -> (still need PApplet e.g. for events)
* put default settings in a config file
* use in real project. get first hand/practical feedback.


REFERENCES
----------
processing library basics https://github.com/processing/processing/wiki/Library-Basics
processing library guidelines https://github.com/processing/processing/wiki/Library-Guidelines
ofxUI https://github.com/rezaali/ofxUI
ofEvent http://www.openframeworks.cc/documentation/events/ofEvent.html
java reflection http://docs.oracle.com/javase/tutorial/reflect/
controlP5 http://code.google.com/p/controlp5/
GUIDO https://github.com/fjenett/Guido
tweaker http://bezier.de/processing/tweaker/
poco events: http://pocoproject.org/docs/package-Foundation.Events-index.html


EVENTS
------
Processing MouseEvent:
ENTER
EXIT
MOVE
PRESS - DRAG - RELEASE
PRESS - RELEASE - CLICK
WHEEL 
Parameters:
getX()
getY()
getButton() 
getCount()

Processing KeyEvent:
PRESS
RELEASE
TYPE
Parameters
getKey()
getKeyCode()

Processing Events without Arguments:
pre
draw
post
pause
resume
dispose

Element:
mouseEntered(x, y)
mouseMoved(x, y)
mouseExited(x, y)
mousePressed(x, y, button)
mouseReleased(x, y, button)
mouseClicked(x, y, button)
mouseDoubleClicked(x, y, button)
mouseDragged(x, y, button)
mouseScrolled(x, y, amount)

Element States:
active
hover
pressed
dragged


OpenFrameworks Events
---------------------
class ofEvent<ArgumentsType> : define an event (type)
ofAddListener(event, object, method) : register any method of any class to an event
ofRemoveListener(event, object, method)
ofNotifyEvent(event, arguments)

class ofEventArgs ()
class ofKeyEventArgs (type, key)
class ofMouseEventArgs (type, button, x, y)
class ofMessage (message)

class ofCoreEvents:
	ofEvent<ofEventArgs> setup, update, draw, exit
	ofEvent<ofKeyEventArgs> keyPressed, keyReleased
	ofEvent<ofMouseEventArgs> mouseMoved, mouseDragged, mousePressed, mouseReleased
	ofEvent<ofMessage> messageEvent
ofEvents() : returns a static instance of ofCoreEvents


ofxUI Classes & Events
----------------------
ofUICBGlue : connects to OF events

ofUIWidget : rendering, properties: name, kind, id, parent, visible, hit

ofUIEventArgs : holds a reference to a ofxUIWidget

ofUICanvas : extends ofUIWidget, ofUICBGlue. 
	ofEvent<ofxUIEventArgs> newGUIEvent : event registry

mechanism:
	gui = new ofxUICanvas()
	gui.addSlider("name")
	gui.addWidget(new ofUIWidget())
	ofAddListener(gui->newGUIEvent, this, guiEvent)
	central callback function: guiEvent(ofxUIEventArgs args)


Sample Elements
---------------
Button
	label
	state: down, up
	events: pressed, released, clicked(count)

Toggle
	label
	state: on, off
	events: toggled, toggledOn, toggledOff

Slider
	label
	min, max
	state: value
	events: slideStart, sliding(value), valueChanged(value)


Basic Element Requirements
--------------------------
1. Receive Events from PUI
2. Encapsulate State / Model
3. Encapsulate Rendering / View
4. Allow User Event Handling
5. Allow User Rendering

1. Receive Events from PUI
* Bundled Events (keyEvent, mouseEvent, drawEvent) or split up (mousePressed, mouseReleased, ...)
	* Bundled: less repeated code:  test for active / boundaries
* Test Responsibility (mouse position inside element), active, etc. In PUI or Widget?
* Do Keyboard Events make sense for elements? Need to combine with some kind of focus feature?
* Where are MouseButton Constants?
* Don't use UIEvents interface. this way the event methods can be protected and are only accessible in subclasses.
	Or use an package private abstract BaseWidget and extend it with empty implementations of handler methods

2. Encapsulate State / Model
Subclass Widget and add instance vars
* basic state (active, pressed, hover) with getters so vars can't be overridden in subclasses

3. Encapsulate Rendering / View
Subclass Widget and override draw().

4. Allow User Event Handling
Specify user events and provide callback registering via reflection.

5. Allow User Rendering
Specify a draw callback, where the complete element state is passed. or the element itself.


Feedback Florian 28.8.2013
--------------------------
* Widget Constructor: PUI as first Argument
* Generator Functions for Widgets in PUI. 
* Modular Generator function:  ui.new( "com.martinleopold.pui.widget.Bang", x, y, … );
* Widgets in own package: com.martinleopold.pui.widget
* The matrix might be changed when the draw callback comes


Theme System
------------
* A Collection of Colors (RGBA)
* Defined as an interface (background, outline, outline_highlight, fill, fill_highlight, padded, padded_outline
* A font. 3 sizes

ofxUI Theme
-----------
event handlers -> state -> drawing flags -> drawing stages
colors: background, outline,  outline highlight, fill, fill highlight, padded, padded outline

widget:
string name
int kind
bool visible
int ID
bool hit
int state (normal, over, down, sustained)

draw steps:
padded
padded outline
background
outline
outlinehighlight
fill
fillhighlight


Grid System / Layout
--------------------

ofxUI Layout
------------
widget positions (relative to last widget): down, up, left, right
widget alignments (alignment relative to canvas): left, right, top, bottom, center, free
keep track of last added widget



Processing drawing / outline / fill
-----------------------------------
fill produces the given dimensions (width and height)
stroke is overlayed starting at the top left corner but is 1px wider and higher



Auto Connection System
----------------------


Sketch Reflection
-----------------
Sketch is a public class
Default Package
extends processing.core.PApplet
default access methods are made public
default access fields remain default.

getDeclaredFields(), getDeclaredMethods() -> also lists non-public members
getFields(), getMethods() -> only public members, but also inherited

without setAccessible(): can set only public fields, call default (=implicit public) and public methods
with setAccessible(): can set all fields, call all methods

can access inherited members

System.getSecurityManager():
222 Mac Java 1.7: null
2.0.3 Mac Java 1.7: null
2.0.3 Win XP: null
2.0.2 Win 7 64bit: null
2.0.2 Ubuntu: null


Access Modifiers
----------------
private: own class
default (package private): own package (second most restricitve)
protected: own package and subclasses in different packages
public: everyone

top level classes can have: public, default
members can have: public, protected, default, private


Access
------
library stuff can use private and default access (package private)
user stuff is public
widget is designed to be extended. can use protected


Widgets with Labels
-------------------
* Label as member
* Widget decides where to place the label
* Needs a label, that can adjust to its contents
* How should a label react to setting its contents? (cut it's contents? adjust size to contents?)
* How to adjust its size? Label can be placed next to the widget in either direction.
* Widgets better have Rect as a member not as a superclass? 
* have two components (widget and label) and a joint rect
* Label default behavior: autowidth or fixed width?


ofxUIWidgetWithLabel
--------------------
extends ofxUIWidget
label as member
hasLabel method for widgets and widgetwithlabels
label rectparent to rect of widget
label set embedded
padding rect is expanded to include the label rect



PUI - Public API
----------------
* init
	new PUI(PApplet)
	PUI PUI.init(PApplet) --> better name for beginners
	PUI PUI.new(PApplet) --> consistent with new syntax. more "advanced"
* create (and add) widgets
	Button addButton(), Toggle addToggle(), Slider addSlider(), ...
* retrieve widgets
	by name? Widget getWidget(name), Widget retrieve(name)
* theme
	PUI setTheme(Theme)
	? setTheme(enum)
	* colors 
		PUI setBackground, setOutline, setOutlineHighlight, setFill, setFillHighlight
		(int color), (r, g, b), (r, g, b, a), (g), (g, a)
	* padding
		PUI setPadding(float gridUnits)
	* font
		PUI setFont(PFont);
		PUI setFont(name);
* grid
	* size
		PUI setGrid(float widthPx, float heightPx)
		(can be stored as float, multiples even out)

* add (externally created) widgets
	add(Widget)

? naming: background() gets, background(c) sets
* check p5 naming for getters / setters
* p5 exposes fields: frameCount, width, displayWidth, focused, frameRate --> these vars will be updated each frame



Widget - Public API
-------------------
* name: used for auto connect, retrieval, auto label
	? should they be unique
* id (int)
	? do i need to use this if i have unique names
* visible (is drawn)
* active (receive events)
	? split active and visible
		doesn't make sense to be invisble but receive events?
* state: normal, over, down, sustained / hover, pressed, dragged
	internally, work with mutually exclusive state enum (NORMAL, HOVERED, PRESSED, DRAGGED)
	provide public methods hovered(), pressed(), dragged()
* label
	Widget setLabel(text)
* register event handlers
	Widget onEvent(String method/field)
* access state
	? getters/setters vs. vars
	? separate object to encapsulate state
		methods on same object simpler

* size (in grid units)
	Widget setSize(gUs, gUs), setWidth(gUs), setheight(gUs)
	? get size
* position (in grid units or pixels)
	Widget setPosition(guX, guY)
	? get position
* construct with new
	new Button(name), new Button(name, x, y, w, h)
	? pui in constructor (auto add) or not
	? name in constuctor
* individual theme
	cascading theme structure, where a child can override its parents properties
* override drawing
	Widget onDraw(String method)

* don't use UIEvents interface -> these methods should be package private / protected


Accessors
---------
in private, fields can be used
for public interfaces, use accessors


Guidelines
----------
* minimal
* accessible
* extensible
* when in doubt: keep it simple i.e. leave it out (for now)


Sample Program
--------------
* Widgets
* Themes
* Grid
* custom drawing
* widget events


Review 
------
* custom widget size
	-> just set and relayout
* custom widget position
	-> add ability to pin objects in layout
* loop through onDraw, onMouse (from Widget), label, noLabel (from WidgetWithLabel) with return type of respective class
	-> Generics: ugly, lots of compiler warnings
	-> override all these methods in subclasses to return the respective types
	?
* state as methods instead of public fields?
	-> base state maybe not, for extended state it's maybe ok because setting the state should be possible
	-> but: does't fire callbacks when setting the state this way
	?
* name (default label, auto connect, retrieval)
	-> makes code a good deal shorter
		ui.addButton().label("b1").onClick("buttonClick") vs. ui.addButton("b1");
	-> not so obvious what happens
* widgets without PUI?
	-> pui needed for draw, callbacks, relayout (i.e. setting size)
	-> why have a widget without PUI? add a widget to multiple PUIs?


Ways to use
-----------
* Use PUI Object
* Extending Widget yourself and adding it to PUI
? Multiple PUIs


Examples
--------
* Simple GUI (some elements with callback, simple use case)
* create elements
* connect elements (callback options)
* general element options (position, size, label)
* specific element options (label, slider, button, ..)

Auto Connect
------------
* connect to method with specific args
* if not found connect to method with widget as arg
* if not found connect to methos without arg
* if not found connect to field with type

Connection Options
------------------
* onEvent() -> specific events with callback methods
	* can have multiple parameter options
* connect(), attach() -> auto connect to methods, fields

Release Procedure
-----------------
* update examples
* update resources/build.properties (library.prettyVersion)
* update README.md
* clean and build
* commit
* create tag
* push upstream
* create release on github


How to calculate columns
------------------------
* column width 12
* column gap 1


Parameterless Callbacks
-----------------------
* create void event: Event<Void> onClickVoid = new Event<Void>();
* fire it using null argument: onClickVoid.fire(null);


Decisions
---------
x newRow(), newColumn() also on Widgets, for convenience?
	not right now / doesn't add functionality / keep it minimal
x layout manager vs. exact placement? layout not default.
	exact placement is possible. having an automatic layout by default facilitates quick guis
x snap to grid better than relational paddings?
	stick to relational for now. find reasons why snap to grid might be better.
	better for interactive / drag & drop placement of widgets
x bundle a selection of fonts with the lib?
	a good default font, maybe provide 2 alternatives?
x remove "add" prefix from widget generators?
	good to identify and group all generators
	can't really compare to p5 rect(), ellipse(), ...
x with smaller pui size: widget can draw outsize of pui. should this be ok?
	then, size is only for the background
	-> draw into PGraphics, but it's not a priority
x draw into a PGraphics? (make it settable). the PGraphics is drawn onto the canvas when not custom set.
	adds flexibility. PGraphics can be set, in which case the rendering of the PGraphics into the canvas is disable
x where to have theme constants? (or how else to set theme) * Theme constants in PUI object?
	setTheme(int), setTheme(String) or: theme(int), theme(String), theme() -> get the theme
x should setting grid, font, padding have an effect on widgets created before?
	-> no. can stay the way it is. if you want to change all, do it first.
x custom padding per widget?
	-> yes, for the sake of customizability. but not now.
x Slider: show value in UI?
	-> yes, as an extension. for now a label can be hooked up to the slider
x how to control an int, with a slider?
	just truncate the slider output to int. if the slider is long enough, you will get all ints in the range
	x should a slider be able to connect to an int? (automatically truncating its value)

x how to best encapsulate base widget state (active, hover, pressed, focus, ...). who needs to see it?
	* maybe visible should be a method, so WidgetWithLabel can override to also hide label
	* widget state as method or field?
	-> needs to be publicly available (for callbacks)
	-> generally not writable, except active, visible
	use: isHovered(), isPressed(), isDragged(), isActive(), isVisible()
	activate(), deactivate(), show(), hide()
	hovered, pressed, dragged are generalizations. dragged includes pressed includes hovered -> enum could be used
	expose metrics: positionX(), positionY(), width(), height()
	expose last mouse position: mouseX(), mouseY() (relative to widget)
	can't do it consistently as fields: x, y, width, height -> don't represent layout rect
	
~ how to encapsulate special element state (slider value, ...)
	possible to use fields.
	if view is always updated from the field, the field can be used to set the value.
	buffering: needs a check for changed values, instead of dirty flags. at the end of draw the drawn value is saved
	Slider: value, Button: pressed, Toggle: on, RangeSlider: float[2] range, Label: text

	pro: easier?
		 processing uses fields to get values
		 easier to translate to js
	con: can't do it consistently with base state (x, y, width, height need to be different for Widget with label)
		 -> could have extra fields which represent the public value, and update them accordingly
		 hard to trigger callbacks when value is set from the ouside (need to double all values and compare them)
	
	beides implementieren: man kann die felder einfach offen lassen. aber macht es komplizierter. 

	I have: 
	widget metrics:
	positionX
	positionY
	width
	height

	mouse state:
	isHovered / mouse over widget
	isPressed / mouse pressed over widget
	isDragged / dragging widget
	(mouseX, mouseY)  / last mouse position relative to widget

	general state:
	isActive / receives and handles mouse events
	isVisible / is displayed

	special state:
	e.g. Slider: value
	e.g. Button: pressed
	e.g. Label: text

x decide on callback possibilities (onEvent, connect, attach, ...)
	specific events: onEvent(method)
	connect to field : connectToField(fieldName), sets(), updates()
		connects to the field, if it's available with the correct type. may have a fallback type
	connect to method: connectToMethod(methodName), calls()
	auto connect: connect(name) -> does it connect to both, or with priorities? naming alternative: attach()
	* its easier to remember/handle: connection options connect to *all* functions/vars of the given name
	* -> so scrap priorities. connect to all.
	* -> if you don't want a connection, change the name in your program!

~ name constructor
	keep empty constructor?

x subclassing Widget:
	-> "must implement the inherited abstract method Widget.getThis()"
	-> needs default constructor (), or a defined explicit constructor (PUI) ...
	-> Widget needs to be public, its constructors protected
	-> draw(), mousePressed() etc. need to be protected
	-> no need to use type argument when instantiating
	   should produce:  warning: [rawtypes] found raw type: Widget,  but processing doesn't show that warning
	   missing type arguments for generic class Widget<T> where T is a type-variable: T extends Widget<T> declared in class Widget
	-> should processing somtime decide to show warnings, we will get them

x Widgets: use generics for chainability or manual overrides to return the correct widget type?
	-> need to override: onDraw(), onMouse(), position(), size(), label(), noLabel()
	-> a user made subclass also needs to override those methods
	-> no need to override: isActive(), isVisible(). (they return a value, not the Widget)
	-> use generics for now. 
	   it works, and subclasses don't have to implement all base functions for chainability.
	   subclasses need to be defined as MyWidget extends Widget<MyWidget> for chainability to work.
	   should be easier than implementing 6 functions, and subclassing is advanced anyway

x which constructors to have for widgets?
	-> remove constructors only used with 0,0 size that use auto layout anyway
	? what about the doLayout constructor
	? a constructor that doesn't use the layout module?
	  -> needed for labels contained in widgetswithlabels
	  every widget is added to the layout by default
	  what about *not* adding it to the layout by default? 
	  -> when it's created with new, it's not in the layout
		 widgets created with new can't be added. need a public addToLayout method in PUI
		 subclasses need to add it, which they can't. need to add a protected addToLayout method to Widget


Theme Review
------------
* Setting: PUI.setTheme(), Widget.setTheme()
* Options:
	preset Theme objects: setTheme(Theme.THEME_NAME)
	enum: enum ThemePreset {DEFAULT, THEME_NAME1, THEME_NAME2 }
	int, string: no need for prefixes
* Setting individual colors ?
* Overriding individual colors ?


Features Review
---------------
PUI
* init. new PUI() / PUI.init()
* create (and add) widgets. addButton(), addToggle(), ...
* theme
	* colors
	* color presets
	* font
* layout
	* grid
	* padding
* size
* position
* toggle

* create widgets with name. -> default label, connect, retrieve
? retrieve widgets. find(name)
? add (externally created) widgets
* more layout modes and direction



Widget
* base state. hovered, pressed, dragged
* base settings. active, visible.
* label
* register event handlers. onEvent()
* connect
	* to method
	* to variable
	* auto.
* special state. Slider value, etc.
* size (in grid units)
* position (in grid units or pixels)

* override drawing
* construct with new
* individual theme. colors, font, padding
* label position
* callbacks on specific objects


Guidelines
----------
Stick with features I already have and try them out in real projects and get user feedback.
Then decide on changes.
Get a good, usable core set of features out and put them to the test.


Main Goals
----------
* accessibility: easily create widgets and connect them to the sketch
  -> auto layout, auto connect, special widget state
* customize: change looks and behavior
  -> color presets, individual overrides, base widget state
* extend: create own widgets


Processing Getters/Setters
--------------------------
displayHeight, displayWidth, focused, frameCount, frameRate, height, width
size(), frameRate()
mouseButton, mousePressed, mouseX, mouseY, pmouseX, pmouseY
key, keyCode, keyPressed
day(), hour(), millis(), minute(), month(), second(), year()s
-> setters are all methods
-> some getters are methods
-> fields are (probably) all reset every frame, so overwriting doesn't matter


Documentation
-------------
docco. not really usable with java (out of the box). atlassian-docco (for java) has loads of dependencies
processing docs. web/index.html -> just write it in html. use prettyfy.js or highlight.js for code


First use in real Project
-------------------------
* Worked quite well, overall!
* use label for displaying a var. 
	* easily putting ints and stuff in. 
	* relayout problem?
* simple hotkeys for buttons.
* need multitoggle
	* switching modes in a project
* color picker (hsb, rgb)
* widget initial values
	* sync, when a var is connected to a widget?
* setting the size of pui (how many cols)
* easier setting themes
* themes need to be legible. (std theme is not!)
* which std. font?
	* NewMedia fett is not readable that well anymore.


Writing a Widget
----------------
* Extend Widget or WidgetWithLabel
* implement constructor (pui, width, height)
* override getThis()
* add data and public accessors
* override draw(PApplet) using
* add events
* create add method in PUI


NOTES
-----
* maybe use "get" prefix for widget data getters, to indicate return of a value, and break of chaining.
* color picker pushes CPU usage to 100%
x color picker events, accessor names
x color picker lock to one slider
x color picker drag outside of bounds
* name change pUI -> PUI 
* performance: drawing operations (pushs/pops)
* P3D rects render differently (1px right/down)
* naming conventions? getters begin with "get" or "is", to indicate a break of chaining.
* empty constructor for label
* VSlider callback only works with Slider argument
* rework theme legibility (again)
x add key binding support to button and toggle
* remove ui/elements ? 
* multiple UIs, switch UIs (does show/hide deactivate events??);