class:: EZText
summary:: Wrapper class for a label, a text field and a value
categories:: GUI>EZ-GUI
related:: Classes/StaticText, Classes/TextField

description::
EZText is a wrapper class which creates an (optional) link::Classes/StaticText::, and a link::Classes/TextField::. The value is displayed as a compileString in the text field for editing.

subsection:: Some Important Issues Regarding EZText
If the parent is code::nil::, then EZText will create its own link::Classes/Window::. See link::Classes/EZGui:: for more options.

classmethods::

subsection:: Creation / Class Methods

method:: new

argument:: parent
The parent view or window. If the parent is nil, then EZText will create its own link::Classes/Window::, and place it conveniently on the screen if the bounds are a link::Classes/Point::. If the bounds are a link::Classes/Rect::, then the link::Classes/Rect:: determines the window bounds.

argument:: bounds
An instance of link::Classes/Rect:: or link::Classes/Point::. Default value is code::160@20::.

argument:: label
The label. Default value is code::nil::. If code::nil::, then no link::Classes/StaticText:: is created.

argument:: action
A link::Classes/Function:: called when the value changes. The function is passed the EZText instance as its argument.

argument:: initVal
The value to initialize the EZText with.

argument:: initAction
A link::Classes/Boolean:: indicating whether the action function should be called when setting the initial value. The default is false.

argument:: labelWidth
Number of pixels width for the label. The default is 60. In the code::\horz:: layout, if you specify the code::textWidth::, then the code::labelWidth:: is ignored and is set to the code::bounds.width - textWidth::.

argument:: textWidth
Number of pixels width for the number box. The default is 45. In code::\vert:: layout, code::textWidth:: defaults to the code::bounds.width::.

argument:: labelHeight
Default is 20.

argument:: layout
code::\vert::, or code::\horz::. The default is code::\horz::; code::\vert:: is a two line version.

argument:: gap
A link::Classes/Point::. By default, the view tries to get its parent's gap, otherwise it defaults to code::2@2::. Setting it overrides these.

argument:: margin
A link::Classes/Point::. This will inset the bounds occupied  by the subviews of view.

discussion::
Example:
code::
(
w = Window("EZText", Rect(300, 300, 260, 60)).front;
g = EZText( w,          // parent
            250@50,     // bounds
            "testing",  // label
            { |ez| (ez.value.asString ++" is the value of " ++ ez).postln }, // action
            [1, 2, 3],  // initValue
            true        // initAction
);
g.setColors(Color.grey,Color.white);
);

// Simplest version, no parent view, so a window is created
(
	g = EZText(label:" test ");
	g.action_({ |ez| (ez.value.asString ++" is the value of " ++ ez).postln });
);

(
	g = EZText(bounds: Rect( 100, 200, 150, 50), label:" test ", layout: \vert);
	g.action_({ |ez| (ez.value.asString ++" is the value of " ++ ez).postln });
);
::
The contained views can be accessed via the EZText instance variables: code::labelView::, code::textField::.

instancemethods::

method:: textField
Returns the textField.

method:: action
A link::Classes/Function:: to be evaluated when the value changes. Typical use is to type in a new value, and interpret it by hitting the evaluation shortcut. The first argument to the function will be the EZText.

method:: value
Gets/sets the value of the ezText. Does not perform the action.
argument:: inval
Any object.

method:: valueAction
Sets the value and performs the action.
argument:: val
Any object.

method:: doAction
Performs the action.

method:: enabled
Sets/gets whether the textfield is enabled.
argument:: bool
An instance of link::Classes/Boolean::. Default is code::true::.


subsection:: Changing Appearance

method:: setColors
argument:: stringBackground
An instance of link::Classes/Color::. The code::background:: of the label and unit views.
argument:: stringColor
An instance of link::Classes/Color::. The code::stringColor:: of the label and unit views.
argument:: textBackground
An instance of link::Classes/Color::. The code::background:: of the textField.
argument:: textStringColor
An instance of link::Classes/Color::. The code::stringColor:: of the textField.
argument:: textNormalColor
An instance of link::Classes/Color::. The code::normalColor:: of the textField.
argument:: textTypingColor
An instance of link::Classes/Color::. The code::typingColor:: of the textField.
argument:: background
An instance of link::Classes/Color::. The code::background:: of the enclosing view.

method:: font
Set the Font used by all the views.
argument:: font
An instance of link::Classes/Font::.

examples::
code::
// Simplest version
(		// basic use
		w=Window("ez", Rect(300, 300, 300, 50)).front;
		g=EZText(w, 290@40," test  ", textWidth: 220,layout:\horz);
		g.setColors(Color.grey,Color.white);
);


// lots of textFields on one window
(
w=Window.new.front;
w.view.decorator=FlowLayout(w.view.bounds);
w.view.decorator.gap=2@2;

40.do{
		g=EZText(w, 170@16," test  ", textWidth: 120,layout:\horz);
		g.setColors(Color.grey, Color.white, Color.grey(0.8));
};
);


// click these parentheses to see three variants
(

m=nil;
m=2@2;		//comment for no margin

/////////////////
/// Layout \horz

(		// with label
		g=EZText(nil, 170@20," freq  ", textWidth:120,layout:\horz,margin:m);
		g.setColors(Color.grey,Color.white,background: Color.grey(0.7));
		g.window.bounds = g.window.bounds.moveBy(-180,50);
);

(		// no label. use window name as label
		g=EZText(nil, 120@20, layout:\horz,margin:m);
		g.setColors(Color.grey,Color.white,background: Color.grey(0.7));
		g.window.bounds = g.window.bounds.moveBy(-180, -90);
		g.window.name="Freq";
);

/////////////////
/// Layout \vert

(		// all features
		g=EZText(nil, 120@60," freq  ", textWidth: 120,layout: \vert, margin:m);
		g.setColors(Color.grey,Color.white,background: Color.grey(0.7));
		g.window.bounds = g.window.bounds.moveBy(100,50);
);

)



// Simplest sound example
(
Tdef(\text).set(\note, [0, 2, 7], \dur, { [0.1, 0.2].choose });

w = Window("EZTexts", Rect(200, 400, 304, 120)).front;
w.addFlowLayout;

TdefGui(Tdef(\text), 0, w);
Tdef(\text).envir.keysValuesDo { |k, v|
	EZText(w, Rect(0,0,300,40), k, { |ez|
		Tdef(\text).envir.put(*[k, ez.value].postcs);
	}, v);
};

Tdef(\text, { |ev|
	var mydur;
	loop {
		mydur = ev.dur;
		(note: ev.note, dur: mydur).postln.play;
		mydur.wait;
	}
}).play;
)

// type these or similar functions into dur and note fields and evaluate:

{ [0.1, 0.2, 0.3].choose }
{ [ 0, 2, 7, 10 ].scramble.keep(rrand(0, 4)) }
::