Packing Widgets(box and table widgets)

Box is a kind of containter widgets and there are two type box, horizontal box (HBox) and vertiacal box (VBox). Box is like a transparent frame to place widgets and its entity is invisible.

Let's take a look at the example to place button widgets into a box. This example inserts two buttons into a horizontal box.

Program box.rb:

require 'gtk'

window = Gtk::Window.new(Gtk::WINDOW_TOPLEVEL)
hbox = Gtk::HBox.new(false, 0)

button1 = Gtk::Button.new('Hello World')
button2 = Gtk::Button.new('button2')

hbox.pack_start button1, true, true, 0
hbox.pack_start button2, true, true, 0

window.add hbox
button1.show
button2.show
hbox.show
window.show
Gtk.main

Result of execution

Description of the example program

• hbox = Gtk::HBox.new(false, 0)
  Generates a horizontal box widget(Gtk::HBox). Arguments are described later on.
• button1 = Gtk::Button.new('Hello World')
  
• button2 = Gtk::Button.new('button2')
  Generate two buttons.
• hbox.pack_start button1, true, true, 0
  
• hbox.pack_start button2, true, true, 0
  Place button1 and button2 inside the horizontal box in order. See below for further details.
• window.add hbox
  Add the horizontal window to the toplevel window.
• button1.show
  
• button2.show
  
• hbox.show
  
• window.show
  Call show for each widget to show them.

Gtk::HBox.new(homogeneous, spacing)

Gtk::VBox.new(homogeneous, spacing)

They generate a box widget. homogeneous is flag of uniformness and specified with value true or false. If it is true, each widget placed inside the box is same size (same width in HBox / same height in VBox).
spacing is size (number of pixels) of gaps between placed widgets.

example
In the case Gtk::Hbox.new(false, 0)
In the case Gtk::Hbox.new(true, 0), the buttons are same width.
In the case Gtk::Hbox.new(true, 10), gap between the buttons is 10 pixels.

Horizontal/Vertical box have methods for packing, pack_start and pack_end.

box.pack_start child_widget, expand, fill, padding

Place child_widget inside box. In order of call, place from left to right in HBox, from top to bottom in VBox.

If expand is true, box stretches as wide as possible. If expand is false, box shrinks to fit to the inner widgets.
If fill is true and there are gaps around the inner widgets, the widgets fill gaps. If fill is false, the gaps remain. fill is effective only if expand is true.
padding specify the size (number of pixels) of space allocated around the each inner widget.

Example
In the above example, for there is only box inside the window, the window looks the same at started time irrespective of whether expand, fill are true or false. but the behavior is different when the window streached by function of a window manager. In the following images, the left one is a startup image, and the right is window-stretched one.

If expand is true, fill is true and padding is 0,
the HBox fills the window and the button widgets fills the HBox.

 => 

If expand is true, fill is false and padding is 0,
the box fills but the button widgets don't.

 => 

If expand is false, fill is false and padding is 0,
the box doesn't fill.

 => 

box.pack_end child_widget, expand, fill, padding

This is almost the same as pack_start, although it places widgets in reverse order to pack_start. pack_end places in called order, that is, HBox places from right to left, and VBox from bottom to top.

While box is used to place widgets in vertical/horizontal direction, table is used to align widgets with a grid.

Let's take a look at the example to place button widgets into a table.

Program table.rb:

require 'gtk'

window = Gtk::Window.new(Gtk::WINDOW_TOPLEVEL)

table = Gtk::Table.new(2, 2, false)

button1 = Gtk::Button.new('Hello World')
button2 = Gtk::Button.new('button2')
button3 = Gtk::Button.new('button3')

table.attach button1, 0, 1, 0, 1
table.attach button2, 1, 2, 0, 1
table.attach button3, 0, 2, 1, 2

window.add table
button1.show
button2.show
button3.show
table.show
window.show
Gtk.main

Result of execution

Description of the example program

• table = Gtk::Table.new(2, 2, false)
  It generates a 2x2 table widget. 3rd argument is flag of homogeneousness like a box.
• table.attach button1, 0, 1, 0, 1
  
• table.attach button2, 1, 2, 0, 1
  
• table.attach button3, 0, 2, 1, 2
  They place button widgets on the table widget. See below for further details.

Gtk::Table.new(rows, columns, homogeneous)

They generate a table widget. rows is specified with number of row, and columns with number of column. homogeneous is flag of uniformness and specified with value true or false. If it is true, each widget becomes same size as maximum in placed widgets size. If it is false, each widget becomes same width as maximum in placed widgets width and same height as maximum in placed widgets height.

For example, a table is laid out as the following figure for rows and columns are specified with 2.

 0          1          2
0+----------+----------+
 |          |          |
1+----------+----------+
 |          |          |
2+----------+----------+

Table has the method attach for placing widgets into a table.

table.attach child_widget,
             left_attach, right_attach, top_attach, bottom_attach,
             xoptions, yoptions, xpadding, ypadding

It places child_widget into the table.
left_attach, right_attach, top_attach, bottom_attach specify which side the widget is placed along. For instance, if you want to place a widget at the location of button2 in previous example, you can specify left_attach = 1, right_attach = 2, top_attach = 0, bottom_attach = 1. For the location of button3, you can specify left_attach = 0, right_attach = 2, top_attach = 1, bottom_attach = 2.

Arguments xoptions, yoptions, xpadding, ypadding are optional. xoptions, yoptions is option how to place a widget. You can give multiple options with bit-wise operator `or'(|). Available option values is defined under Gtk module as constants and shown in the following list.

• Gtk::FILL
  If this option is specified, the widget fills gap between the table grid and the widget.
• Gtk::SHRINK
  If this option is specified, the widget shrinks along the grid when the table grid is less than the widget(eg. window is resized).
• Gtk::EXPAND
  If this option is specified, the table expands as wide as possible.

If xoptions, yoptions is omitted or specified with nil, it is same as Gtk::FILL | Gtk::EXPAND

xpadding, ypadding specify how large space to make sure of the space arround the placed widget in number of pixels.

Exmaple
For xoptions and yoptions aren't specified in previous example, it is same as Gtk::FILL | Gtk::EXPAND is specified. button3 is placed over 2 blocks and the widget fills the blocks horizontally

If Gtk::FILL and Gtk::EXPAND aren't specified, for exmple, table.attach button3, 0, 2, 1, 2, 0, 0,
button3 widget doesn't expand.

If moreover the window is expanded by the WM function,
Gtk::FILL and Gtk::EXPAND are specified (implicitly) in the upper row, the block expands and the widget in the block also expands. The lower row doesn't expand.

There are the following methods to specify gaps between rows and between columns.

table.set_row_spacing row, spacing

This makes sure of gaps whose size is spacing below the row row.

table.set_column_spacing column, spacing

This makes sure of gaps whose size is spacing on the right of the column column.

table.set_row_spacings spacing

This makes sure of gaps whose size is spacing between all rows.

table.set_column_spacings spacing

This makes sure of gaps whose size is spacing between all columns.