What's a Stack? What's a Flow? --The Shoes Layout Manager

To effectively use any GUI toolkit, you have to understand its layout manager (or geometry manager). In Qt, you have HBoxes and VBoxes, in Tk you have the Packer and in Shoes you have stacks and flows. It sounds cryptic but read on--it's very simple.

A stack does just as the name implies. They stack things vertically. If you put three buttons in a stack, they'll be stacked vertically, one on top of each other. If you run out of room in the window, a scrollbar will appear on the right side of the window to allow you to view all of the elements in the window.

Note that when it's said that the buttons are "inside" of the stack, it just means they were created inside of the block passed to the stack method. In this case, the three buttons are created while inside of the block passed to the stack method, so they're "inside" of the stack.

Shoes.app :width => 200, :height => 140 do
  stack do
    button "Button 1"
    button "Button 2"
    button "Button 3"
  end
end

A flow packs things horizontally. If three buttons are created inside of a flow, they'll appear next to each other.

Shoes.app :width => 400, :height => 140 do
  flow do
    button "Button 1"
    button "Button 2"
    button "Button 3"
  end
end

The main window is itself a flow. The previous example could have been written without the flow block and the same thing would have happened: the three buttons would have been created side by side.

Shoes.app :width => 400, :height => 140 do
  button "Button 1"
  button "Button 2"
  button "Button 3"
end

There's one more important thing to understand about flows. If you run out of space horizontally, Shoes will never create a horizontal scroll bar. Instead, Shoes will create the elements lower down on the "next line" of the application. It's like when you reach the end of a line in a word processor. The word processor doesn't create a scrollbar and let you keep typing off the page, instead it places the words on the next line.

Shoes.app :width => 400, :height => 140 do
  button "Button 1"
  button "Button 2"
  button "Button 3"
  button "Button 4"
  button "Button 5"
  button "Button 6"
end

Until now, we haven't given any dimensions when creating stacks and flow; they've simply taken as much space as they needed. However, dimensions can be given in the same way dimensions are given to the Shoes.app method call. This example creates a flow that's not as wide as the window and adds buttons to it. A border style is also given to it to visually identify where the flow is.

Shoes.app :width => 400, :height => 140 do
  flow :width => 250 do
    border red

    button "Button 1"
    button "Button 2"
    button "Button 3"
    button "Button 4"
    button "Button 5"
    button "Button 6"
  end
end

You can see by the red border that the flow doesn't extend all the way to the edge of the window. When the third button is going to be created, there's not enough room for it so Shoes moves down to the next line.

Flows and stacks don't just contain the visual elements of an application, they can also contain other flows and stacks. By combining flows and stacks, you can create complex layouts of visual elements with relative ease.

If you're a Web developer, you may note this is very similar to the CSS layout engine. This is intentional. Shoes is heavily influenced by the Web. In fact, one of the basic visual elements in Shoes is the "Link" and you can even arrange Shoes applications into "pages."

In this example, a flow containing 3 stacks is created. This will create a 3 column layout, with the elements in each column being displayed vertically (because each column is a stack). The width of the stacks is not a pixel width as in previous examples, but rather 33%. This means each column will take 33% of the available horizontal space in the application.

Shoes.app :width => 400, :height => 140 do
  flow do

    stack :width => '33%' do
      button "Button 1"
      button "Button 2"
      button "Button 3"
      button "Button 4"
    end

    stack :width => '33%' do
      para "This is the paragraph " +
        "text, it will wrap around " +[b r] "and fill the column."
    end

    stack :width => '33%' do
      button "Button 1"
      button "Button 2"
      button "Button 3"
      button "Button 4"
    end

  end
end