Miscellaneous Widgets

Label
Labels are the main method of placing non-editable text in windows, for instance to place a title next to a Entry widget. You can specify the text in the constructor, or later with the set_text() or set_markup() methods.
The width of the label will be adjusted automatically. You can produce multi-line labels by putting line breaks ("\n") in the label string.
The label text can be justified using the set_justify() method. The widget is also capable of word-wrapping, which can be activated with set_line_wrap().
Gtk::Label support some simple formatting, for instance allowing you to make some text bold, colored, or larger. You can do this by providing a string to set_markup(), using the Pango Markup syntax. For instance, <b>bold text</b> and <s>strikethrough text</s> .
Reference

Example
Below is a short example to illustrate these functions. This example makes use of the Frame widget to better demonstrate the label styles. (The Frame widget is explained in the Frame section.) It is possible that the first character in m_Label_Normal is shown underlined only when you press the Alt key.

Label
Source Code

Entry

Simple Use
Entry widgets allow the user to enter text. You can change the contents with the set_text() method, and read the current contents with the get_text() method.
Occasionally you might want to make an Entry widget read-only. This can be done by passing false to the set_editable() method.
For the input of passwords, passphrases and other information you don't want echoed on the screen, calling set_visibility() with false will cause the text to be hidden.
You might want to be notified whenever the user types in a text entry widget. Gtk::Entry provides two signals, activate and changed, for this purpose. activate is emitted when the user presses the Enter key in a text-entry widget; changed is emitted when the text in the widget changes. You can use these, for instance, to validate or filter the text the user types. Moving the keyboard focus to another widget may also signal that the user has finished entering text. The focus_out_event signal that Gtk::Entry inherits from Gtk::Widget can notify you when that happens. The ComboBox with an Entry section contains example programs that use these signals.
If you pass true to the set_activates_default() method, pressing Enter in the Gtk::Entry will activate the default widget for the window containing the Gtk::Entry. This is especially useful in dialog boxes. The default widget is usually one of the dialog buttons, which e.g. will close the dialog box. To set a widget as the default widget, use Gtk::Widget::set_can_default() and Gtk::Widget::grab_default().
Reference

Simple Entry Example
This example uses Gtk::Entry. It also has two CheckButtons, with which you can toggle the editable and visible flags.

Entry
Source Code

Entry Completion
A Entry widget can offer a drop-down list of pre-existing choices based on the first few characters typed by the user. For instance, a search dialog could suggest text from previous searches.
To enable this functionality, you must create a EntryCompletion object, and provide it to the Entry widget via the set_completion() method.
The EntryCompletion may use a TreeModel containing possible entries, specified with set_model(). You should then call set_text_column() to specify which of your model columns should be used to match possible text entries.
Alternatively, if a complete list of possible entries would be too large or too inconvenient to generate, a callback slot may instead be specified with set_match_func(). This is also useful if you wish to match on a part of the string other than the start.
Reference

Entry Completion Example
This example creates a Gtk::EntryCompletion and associates it with a Gtk::Entry widget. The completion uses a Gtk::TreeModel of possible entries, and some additional actions.

Entry Completion
Source Code

Entry Icons
An Entry widget can show an icon at the start or end of the text area. The icon can be specifed by methods such as set_icon_from_pixbuf() or set_icon_from_icon_name(). An application can respond to the user pressing the icon by handling the signal_icon_press signal.

Entry Icon Example
This example shows a Gtk::Entry widget with a named search icon, and prints text to the terminal when the icon is pressed.

Entry with Icon
Source Code

Entry Progress
An Entry widget can show a progress bar inside the text area, under the entered text. The progress bar will be shown if the set_progress_fraction() or set_progress_pulse_step() methods are called.

Entry Progress Example
This example shows a Gtk::Entry widget with a progress bar.

Entry with Progress Bar
Source Code

SpinButton
A SpinButton allows the user to select a value from a range of numeric values. It has an Entry widget with increment and decrement buttons at the side. Clicking the buttons causes the value to 'spin' up and down across the range of possible values. The Entry widget may also be used to enter a value directly.
The value can have an adjustable number of decimal places, and the step size is configurable. SpinButtons have an 'auto-repeat' feature as well: holding down the increment or decrement button can optionally cause the value to change more quickly the longer the button is held down.
SpinButtons use an Adjustment object to hold information about the range of values. These Adjustment attributes are used by the Spin Button like so:
value: value for the Spin Button
lower: lower range value
upper: upper range value
step_increment: value to increment/decrement when pressing mouse button 1 on a button
page_increment: value to increment/decrement when pressing mouse button 2 on a button
page_size: unused
Additionally, mouse button 3 can be used to jump directly to the upper or lower values.
The SpinButton can create a default Adjustment, which you can access via the get_adjustment() method, or you can specify an existing Adjustment in the constructor.

Methods
The number of decimal places can be altered using the set_digits() method.
You can set the spinbutton's value using the set_value() method, and retrieve it with get_value().
The spin() method 'spins' the SpinButton, as if its increment or decrement button had been clicked. You need to specify a Gtk::SpinType to specify the direction or new position.
To prevent the user from typing non-numeric characters into the entry box, pass true to the set_numeric() method.
To make the SpinButton 'wrap' between its upper and lower bounds, use the set_wrap() method.
To force it to snap to the nearest step_increment, use set_snap_to_ticks().
Reference

Example
Here's an example of a SpinButton in action:

SpinButton
Source Code

ProgressBar
Progress bars are used to show the status of an ongoing operation. For instance, a ProgressBar can show how much of a task has been completed.
To change the value shown, use the set_fraction() method, passing a double between 0.0 and 1.0 to provide the new percentage.
A ProgressBar is horizontal and left-to-right by default, but you can change it to a vertical progress bar by using the set_orientation() method.
Reference

Activity Mode
Besides indicating the amount of progress that has occured, the progress bar can also be used to indicate that there is some activity; this is done by placing the progress bar in activity mode. In this mode, the progress bar displays a small rectangle which moves back and forth. Activity mode is useful in situations where the progress of an operation cannot be calculated as a value range (e.g., receiving a file of unknown length).
To do this, you need to call the pulse() method at regular intervals. You can also choose the step size, with the set_pulse_step() method.
The progress bar can also display a configurable text string within its trough, using the set_text() method.

Example

ProgressBar
Source Code

InfoBar
An InfoBar may show small items of information or ask brief questions. Unlike a Dialog, it appears at the top of the current window instead of opening a new window. Its API is very similar to the Gtk::Dialog API.
Reference

Example

InfoBar
Source Code

Tooltips
Tooltips are the little information windows that pop up when you leave your pointer over a widget for a few seconds. Use set_tooltip_text() to set a text string as a tooltip on any Widget. Gtk::ToolItems are not Widgets, but have the same method for convenience. Gtk::Tooltip is used for more advanced tooltip usage, such as showing an image as well as text.
Widget Reference
Tooltip Reference

Example

Tooltip
Source Code