= 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 ==

Radio buttons present a set of choices to the user; only one choice can be selected at any time.  

There are two things to think about when using radio buttons:

 1. putting the radio buttons into a group, so as one is selected the others become unselected.
 1. retrieving the selected value.

A straightforward way to retrieve the selected value is to listen for the 'toggle' events on each radio button.  When a radio button is toggled, it is selected, and a method can be called to store the relevant value.  Placing radio buttons into the same group is done by passing the first radio button as an argument to the constructor for the second and subsequent radio buttons.

{{{
#!cobra
	var _state as String # stores the current selected item in the list of radio buttons 

	def selected1(obj, e) # update state as first radio button has been selected
		_state = "Cobra"

	def createWidgets
		# ... create first radio button
		radio1 = RadioButton("Cobra")
		listen radio1.toggled, ref .selected1
		# the second radio button uses the first, to put them in the same group
		radio2 = RadioButton(radio1, "Java")
		listen radio2.toggled, ref .selected2

}}}

[[Image(radiobuttons.png)]]


== Combo Boxes ==

The combo box allows the user to select from a predefined list of items.  The current selection is always shown to the user.  Different variations of the combo box exist, such as allowing the user to enter some text to make a selection.  Combo boxes can display different kinds of information. Before display, a 'cell renderer' must be created to control how the items in the list are displayed.  And the list of items must be added to a suitable data store.

The example here simply displays a list of strings. The renderer is an instance of '!CellRendererText', and the store is a simple '!ListStore'.  The currently selected item ''index'' can be found as {{{_combobox.active}}} 

[[Image(combobox.png)]]

{{{
#!cobra

		_combobox = ComboBox()
		_combobox.clear
		# create and add the text renderer to the combox box
		cell = CellRendererText()
		_combobox.packStart(cell, false)
		_combobox.addAttribute(cell, "text", 0)
		# create and set the backing store of items to display
		store = ListStore(String)
		_combobox.model = store
		# add string values to list store
		for planet in ["Mercury", "Venus", "Earth", "Mars",      _
			       "Jupiter", "Saturn", "Uranus", "Neptune"]
			store.appendValues(planet)
		# set the index of the item to display
		_combobox.active = 5 
}}}

== 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)]]