Wiki

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:

button1 = Button("Click me")

An alternative way is to use one of the stock actions (see  here for a complete list). For example:

button1 = Button(Stock.quit)

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

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:

# @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:

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

    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.
  2. 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.

    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

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

        _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:

        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:

        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

Attachments