= Gtk Simple Widgets =

These are widgets that can be clicked or otherwise react to a user's request.  Gtk provides many different types of widgets, and only some are illustrated here.  Also, within each widget type, only a small amount of the supported behaviour is shown

== Buttons ==

A button displays some text and/or icon, and generates a 'clicked' signal when clicked by the user.
The simplest way to create a button is to pass it some text to use as the label:

{{{
#!cobra
button1 = Button("Click me")
}}}

An alternative way is to use one of the stock actions (see [http://developer.gnome.org/gtk/2.24/gtk-Stock-Items.html#GTK-STOCK-OK:CAPS here] for a complete list).  For example:

{{{
#!cobra
button1 = Button(Stock.quit)
}}}

To connect a method to a button, listen to the 'clicked' event.  For example:

{{{
#!cobra
listen button1.clicked, ref .buttonClicked
}}}

Below is a complete program to create and pack two buttons into a window.  When the top button is clicked, a message is printed on the terminal, and when the bottom button is clicked, the application quits.  The window should look something like:

[[Image(buttons.png)]]

{{{
#!cobra
# @args -pkg:gtk-sharp-2.0  # remove initial '#'

use Gtk

class ExampleWindow inherits Window
	cue init
		base.init("Buttons Example")
		.setDefaultSize(300,200)
		listen .deleteEvent, ref .quit
		.createWidgets

	def quit(obj, e)
		Application.quit

	def createWidgets
		# Create a button with given title text
		button1 = Button("Click me")
		# associate action when clicked
		listen button1.clicked, ref .buttonClicked

		# Create a button using stock 'quit' label and icon
		button2 = Button(Stock.quit)
		# associate action when clicked
		listen button2.clicked, ref .quit

		# Add the two buttons to the window within a box
		box = VBox(true, 0)
		box.packStart(button1, false, false, 20)
		box.packStart(button2, false, false, 20)

		.add(box)

	def buttonClicked(obj, e)
		print "Clicked button"

class MainProgram
	def main
		Application.init
		window = ExampleWindow()
		window.showAll
		Application.run
}}}

== Check Buttons ==

A check button has a label and a tick box; clicking on the button will tick or untick the box.  The checkbutton's state is stored in its attribute 'active'.  An example of a check button:

[[Image(checkbutton.png)]]

(To use this code, replace the 'createWidgets' method in the above example, and add the field definition.)

{{{
#!cobra
	var _checkbutton as CheckButton # store the check button as a field

	def createWidgets
		_checkbutton = CheckButton("select") # create the check button

		# Create a button to print out state of other widgets
		button = Button("Show State")
		# associate action when clicked
		listen button.clicked, ref .showState

		# Add the two buttons to the window within a box
		box = VBox(true, 0)
		box.packStart(_checkbutton, false, false, 20)
		box.packStart(button, false, false, 20)

		.add(box)

	def showState(obj, e)
		print "Check button state is", _checkbutton.active # report the check button's state
}}}


== Radio Buttons ==


== Combo Boxes ==


== Spin Buttons ==

A spin button is used to select a number from within a numeric range.  The user may click on the up/down arrows to the side of the field to change the value.

Using a spin button means first creating an instance of the 'Adjustment' class: this holds the min/max values for the range, as well as information on how large a jump the user can make.  The 'Adjustment' class takes 6 float parameters:

 * the initial value
 * the minimum value
 * the maximum value
 * the increment for a single step (e.g. one click on an arrow)
 * the increment for a page-up or page-down keypress
 * page size (but cobra tells me using any value other than 0 for this parameter is deprecated)

The spin button takes three parameters:

 * an instance of the 'Adjustment' class
 * the 'climb rate', which affects the acceleration when you hold a button down
 * the number of decimal places to show

The 'value' attribute of the spin button is used to retrieve the current value.

To create a spin box which covers the numbers 0 to 100, and produces integer values:

{{{
#!cobra
		model = Adjustment(50.0f, 0.0f, 100.0f, 1.0f, 10.0f, 0f)
		_spinbutton = SpinButton(model, 1.0f, 0)
}}}

To create a spin box which covers a floating point range -10.000 to 10.000, producing float values at intervals of 0.001:
{{{
#!cobra
		model = Adjustment(0.0f, -10.0f, 10.0f, 0.001f, 1.0f, 0f)
		_spinbutton = SpinButton(model, 1.0f, 3)
		_spinbutton.snapToTicks = true # used to round entries such as 1.2341 to 1.234
}}}


[[Image(spinbutton.png)]]