GtkSpinButton Glade GTK C Program

How to use a GtkSpinButton in a GTK+ 3 application written in C using Glade user interface designer. This tutorial shows how to build a GTK+3 application that allows a user to enter a number in a GtkSpinButton widget. Clicking a button in the application reads the value from the spin button widget and writes it to a label.

The image below shows the GTK+3 C Glade application built in this tutorial. Glade is used to design the GUI user interface for the application.

GtkSpinButton Tutorial Application
GtkSpinButton Tutorial Application

In this tutorial, you will learn:

  • How to use a GtkSpinButton in Glade.
  • How to change a GtkSpinButton from its default disabled state in Glade.
  • How to read a number from a GtkSpinButton in a GTK+ 3 C program.

Getting a Number from a User in a GTK Application

Two options for getting a number as input from a user in a GTK GUI application are a text entry widget (GtkEntry) or a spin button (GtkSpinButton). The text entry widget requires some work to prevent a user from entering non-numerical characters. A spin button can be set to allow only numbers to be entered.

Gtk Text Entry and Spin Button
Gtk Text Entry and Spin Button

The image above shows the text entry widget (GtkEntry) at the top and the spin button (GtkSpinButton) at the bottom. The spin button has plus and minus buttons for incrementing and decrementing the number. The number can also be directly entered into the spin button widget by typing.

Because it is easier to set a spin button so that a user can enter only numbers and not alphabet characters, it was chosen for number entry in this tutorial.

GTK+ 3 GtkSpinButton Tutorial

Follow the tutorial steps below to build the GtkSpinButton application.

1. Create a New GTK Glade Project

Create a new GTK+ 3 application by using the GTK+ 3 Glade C programming template files. Using the template files, you will have a make file, a C source code directory and a glade file directory. Save the template files and sub-directories to a directory called spin_button.

Open the make file and change the name of the project to spin_button as follows.

The complete make file should look as follows

makefile:

If you are copying the above make file, remember to make sure that the indented lines are indented with tab characters, otherwise the make file will not work.

2. Build the User Interface in Glade

Glade is used to create a new window for this project. Overwrite or replace the window_main.glade file in the glade directory with the Glade file created in this part of the tutorial.

2.1 Create a New Glade Application Window

Open the Glade user interface designer application and place a new window by clicking Window under Toplevels in the left pane.

Create a New Glade Window
Create a New Glade Window

Save the new glade window as window_main.glade in the project’s glade directory by using File → Save from the top Glade menu.

Click the GtkWindow item in the top right Glade pane to select it. In the bottom right Glade pane, change the window ID to window_main and the Title to Spin Button.

Change the Window ID and Title
Change the Window ID and Title

Click the Signals tab in the lower right pane of Glade so that the handler for closing the window can be added. The on_window_main_destroy() function already exists in the C template code. It must be added next to destroy under GtkWidget in the lower right pane.

Add the Destroy Signal Handler
Add the Destroy Signal Handler

To add the destroy handler, click on the <Type here> text under Handler next to destroy as shown above. Start typing on and a suggested handler name will appear. Press the down arrow key and then hit Enter twice to select it. The suggested name should be on_window_main_destroy as seen in the above image.

Save the changes made to the main Glade application window.

2.2 Place Container Boxes in the Main Window

Instead of placing the widgets on a fixed grid, they are placed in boxes, a method known as “packing”. See the Glade Packing Tutorial for an explanation of Glade packing. A total of four boxes are placed for this application.

Click the Box widget under the Containers heading in the left Glade pane. Click on the main window to place the box. In the dialog box that pops up, change the Number of Items to 2 as shown below. Click the Create button.

Place a Box for Packing Widgets
Place a Box for Packing Widgets

Place a second box in the top half of the first box by using the Box widget button in the left Glade pane again. Change the number of items to 2. After placing the box, change the Orientation in the lower right Glade pane to Horizontal.

Place  a third box in the left half of the second box, with number of items set to 2. Leave the default vertical orientation.

Place a fourth box in the right half of the second box, with number of items set to 2. Leave the default vertical orientation.

Click on box2 in the top right Glade pane and check the Homogeneous checkbox in the bottom right Glade pane. Your window in Glade should now look as follows.

Glade Box Widgets in Main Window
Glade Box Widgets in Main Window

2.3 Place Widgets in the Boxes

Using the left Glade pane, place the following widgets in the boxes on the main window. These widgets are found under Control and Display in the left Glade pane. Hover the mouse cursor over the icons in the left pane to see the name of each widget in the pop up tool tip.

  • Place a Button in the very bottom box of the window – the big area at the bottom of the window as can be seen in the above image. Click the Button icon in the left pane and then click on the window. Use this method to place the other widgets described next.
  • Place a Spin Button (GtkSpinButton) in the top right rectangle.
  • Place Label widgets in the remaining 3 rectangles.

Your window should now look as follows.

Glade Window with Widgets Placed
Glade Window with Widgets Placed

2.4 Edit Widget Attributes

Click the top left label to select it. In the lower half of the right Glade pane, change the label text to Enter Quantity: in the Label field under Appearance. Scroll down the bottom half of the right Glade pane and change the horizontal alignment to 0.0 in the Horizontal box under the Alignment and Padding heading. This left aligns the label text.

Do the same as above for the label below, but change its text to Quantity Entered:. Do the same for the last label which is positioned below the spin button, but change its text to and its ID to lbl_quantity.

Click the spin button at the top right of the window to select it. Change the ID of the spin button to sbtn_quantity.

At this stage the window looks as follows.

Edited Glade Window
Edited Glade Window

Click the button widget at the bottom of the window to select it. Change the button text to Update (under Label with optional image) and the button ID to btn_update.

2.5 Space the Widgets

Click the button at the right of the top Glade toolbar (Preview snapshot) to see what the window looks like when used in an application. If the preview snapshot button is missing from the toolbar, click the main window in the top right Glade pane and it should appear.

Notice that the widgets are too close together giving the window a cramped appearance. This can be changed by changing padding and margin attributes of the widgets.

Glade Preview Snapshot
Glade Preview Snapshot
Window Border Margins

A margin of 8 pixels around the main window gives a better appearance because the widgets do not push right up to the edge of the window. The margin is added by changing the Margins values of box1, the main box that holds all other widgets.

Select the box1 in the Glade editor at the top of the right pane. Click the Common tab in the lower half of the right pane. Scroll down to find Margins under Widget Spacing. Change the Top, Bottom, Left and Right margin spacing to 8. Use the Preview snapshot button to view the changes.

Spacing Between Widgets

Select box3 using the top right Glade pane. This box holds the two top left label widgets. Under the Common tab in the lower right Glade pane, change the right margin to 10. Under the General tab, click Homogeneous.

Click box4 to select it. This box holds the spin button and the third label. Under the General tab in the lower right pane of Glade, click Homogeneous.

Select the button at the bottom of the window. Under the Common tab, change the top margin to 20 to add some space above the button.

Change the top margin of both the Quantity Entered: text and the label (lbl_quantity) to 14. This adds space between these two labels and the widgets above them.

The edited window in Glade and the preview snapshot should now look as follows.

Glade Edited Window and Preview Window
Glade Edited Window and Preview Window

2.6 Edit the GtkSpinButton to Enable It

Notice that the GtkSpinButton widget in the preview window is disabled. Clicking the plus or minus button has no effect in the preview snapshot. To enable the spin button, an adjustment object, of type GtkAdjustment must be added to the project. This object must then be linked to the spin button. All of this is done in the Glade editor.

In the left Glade pane under Miscellaneous, click the Adjustment button as shown below.

Place a GtkAdjustment Using Adjustment in Glade
Place a GtkAdjustment Using Adjustment in Glade

An Adjustment will be added to the project when the Adjustment button is clicked. With the Adjustment selected, change its values under the General tab at the bottom right of Glade as follows.

  • Value: 1 – sets the initial value in the widget
  • Minimum Value: 1 – can’t decrement below this value
  • Maximum Value: 99999 – can’t increment above this value

Leave the other items at their default values as shown below.

Glade Adjustment Settings
Glade Adjustment Settings

The GtkAdjustment must now be linked to the spin button. Click the spin button in the top right Glade pane. Make sure that the General tab is selected in the lower half of the right Glade pane. Click the pencil icon at the right of the Adjustment box under Spin Button Attributes. In the dialog box that pops up, click the radio button to the left of adjustment1 and then click the OK button.

In the preview snapshot, the value in the spin button can now be changed using the plus and minus buttons.

2.7 Final Widget Layout Touches

The following changes in Glade improve the appearance and functionality of the application.

Set the Spin Button Width

Select the spin button by clicking it. In the lower right Glade pane, make sure that the General tab is selected. Make the following changes under the General tab.

  • Maximum width in characters: 10 – at top of pane, under ID – sets the maximum width of the spin button in characters.
  • Value: 1 – under Spin Button Attributes heading – the initial value in the spin button.
  • Numeric – check this box so that only numbers can be typed in the spin button widget box.
  • Maximum length: 5 – found under Entry – maximum number of digits that can be entered in the spin button. This corresponds to the maximum value set in adjustment, 99999, which consists of 5 digits. A user can now not type a value higher than 99999.
  • Width in chars: 10 – adds some space to the right of the number entered in the spin button for better appearance.
Disable Sizing of the Main Window

Click the main window in the top right Glade pane to select it. Make sure that the General tab is selected in the lower half of the right Glade pane. Scroll down the lower half of the right pane to find the Window Flags section. Uncheck the Resizable checkbox.

This change prevents the application window from being resized which is unnecessary for this simple application – i.e. there is no need to resize the application window, so this functionality is disabled.

Check the Modal box under Windows Flags. This change removes the maximize box from the top right of the application window. There is no need to maximize the application window.

Save the changes made to the Glade file. The main application code can now be written.

3. Write the C Code for the Program

Open main.c found in the src directory of the project for editing. Below is the full listing of the main.c file. The steps that follow show what changes to make to the main.c template file to implement the spin button application.

main.c:

3.1 Get Pointers to Widgets

When the Update button is clicked, the application must read the value in the spin button and write it to the lbl_quantity label. We therefore need to pass pointers to these two widgets to the button clicked handler. Pointers to widgets are passed using a structure as explained in the tutorial on how to get pointer to widgets in a GTK+ 3 Glade application.

The following steps show how to add the widgets structure to the C code.

Widget Structure Definition

Add the code near the top of main.c that defines the widget structure as follows.

Instantiate the Widget Structure in Memory

Assign memory for the widget structure using g_slice_new() at the top of main() below the other variable declarations as shown below.

Load the Widget Pointers into the Structure

Pointers to the desired widgets are placed into the newly created structure.

Connect Signals

Use gtk_builder_connect_signals() to connect handler functions from the Glade file to signals in the application. Pass the widget structure as the second parameter to this function as shown below.

Free the Widget Memory

Free the memory assigned to the widget structure at the bottom of main(), just before returning.

3.2 Add the Button Clicked Event Handler

Open the project’s Glade file again for editing. The handler for the button clicked signal must be added. In Glade, click the Update button to select it.

In the lower right Glade pane, select the Signals tab. Under the GtkButton item, click the <type here> text under the Handler column next to clicked. Click the <type here> text again to start editing it. Type on and then press the down arrow key to select the suggested handler name. Hit Enter twice on the keyboard to select the handler name which should be on_btn_update_clicked.

Now add this handler function to the code in main.c as follows.

How do we know what parameters can be passed to the above GtkButton clicked handler? Go to the GTK+3 GtkButton reference, scroll down to find the Signals heading. Click the clicked item under the Signals heading. The reference shows that the first parameter passed to the function is a pointer to a GtkButton and the second parameter is a pointer to user data, which is our widget structure.

In the above handler function gtk_spin_button_get_value_as_int() is used to read the value from the GtkSpinButton and store it in the quantity variable. This integer value is then converted to a string and written to the lbl_quantity label widget.

4. Build and Run the Application

Open a command line terminal and change to the project’s directory. This is easily done in one step in Linux Mint by right clicking in the spin_button directory in the File Browser application and selecting Open in Terminal from the menu that pops up.

Type make to build the project. Type ./spin_button to run the application from the command line.

Development Tools Details

This tutorial was developed on a Linux Mint 18.1 64-bit Mate computer using:

  • Glade version 3.18.3
  • GTK+3 version 3.18.9
  • GCC version 5.4.0

One thought on “GtkSpinButton Glade GTK C Program”

Leave a Reply

Your email address will not be published. Required fields are marked *