In this tutorial we will discuss the wxRuby GridSizer Layout Sizer.

The BoxSizer is one of the sizers in wxRuby designed to help with the layout management of widgets in the window. As the name suggests, it creates a grid of rows and columns in which widgets can be placed.

Below is the possible syntax and arguments for creating the GridSizer.

Wx::GridSizer.new(rows, cols, vgap, hgap)
Wx::GridSizer.new(cols, vgap, hgap)
Wx::GridSizer.new(rows, cols, gap)
Wx::GridSizer.new(cols, gap)

The rows and cols arguments are for the number of rows and columns, and the vgap and hgap arguments (or just gap) determine the vertical and horizontal (or both for gap, which can be both an array of two integers or a Wx::Size) distance (padding) between the rows and columns.

Note: When creating a GridSizer only the number of columns in the grid needs to be specified using the cols argument. The number of rows will be deduced automatically depending on the number of the elements added to the sizer. If a constructor form with a rows argument is used (and the value of the rows argument is not zero, meaning "unspecified") the sizer will check that no more than cols*rows elements are added to it, i.e. that no more than the given number of rows is used. Adding less than maximally allowed number of items is not an error however. Finally, it is also possible to specify the number of rows and use 0 for cols. In this case, the sizer will use the given fixed number of rows and as many columns as necessary.

Like any sizer, we can use the #add method to easily add new widgets into our GridSizer. The other two arguments are for proportion and flags (there are many overloaded versions of this method).

The below example creates four StaticText Widgets to place inside the Grid. We’ve used the Wx::ALIGN_CENTER flag so that they appear in the center of the cell they are placed in.

require 'wx'

class MyWindow < Wx::Frame
  def initialize(title)
    super(nil, title: title)
    @panel = Wx::Panel.new(self)

    grid = Wx::GridSizer.new(2, 2, 5, 5)

    grid.add(Wx::StaticText.new(@panel, label: 'Text'), 0, Wx::ALIGN_CENTER)
    grid.add(Wx::StaticText.new(@panel, label: 'Text'), 0, Wx::ALIGN_CENTER)
    grid.add(Wx::StaticText.new(@panel, label: 'Text'), 0, Wx::ALIGN_CENTER)
    grid.add(Wx::StaticText.new(@panel, label: 'Text'), 0, Wx::ALIGN_CENTER)
    
    @panel.set_sizer(grid)

    centre
  end
end

Wx::App.run do
  window = MyWindow.new("wxRuby GridSizer Guide")
  window.show
end

The output:

Remember, the order in which you add widgets to the GridSizer is important. The first widget added will appear in the (0, 0) slot, and then next will appear in the (0, 1) slot and so on.

Remember to use the #set_sizer method on the panel at the end, otherwise your widgets won’t display properly!

There are several other types of GridSizers that inherit some of it’s functionality while adding in some new feature of their own. There is FlexGridSizer, which can have rows and columns of different sizes. GridBagSizer which inherits from FlexGridSizer, is another GridSizer variant, adding in the ability to place widgets at specific locations in the grid.

Follow the links in the guide on layout managers in wxRuby to learn more about them, and how they can be better than GridSizer.