4. GUI Layouts #

This tutorial will teach you how to create more fancy GUIs by using multiple GUI components in your pages' GUIs.

The root component #

As you know, you should in the Page method createGui() use GUI components from Bagatell to create and send back the page's GUI. This method, as all methods, can only send back one value, and in this case that value should be a GUI component. That GUI component is know as the page's root component, and it will cover the entire screen. That it indeed does cover the entire screen is easy to verify by giving the component a background color.

class StartPage extends Page{
	createGui(){
		return Text(`This Text component doesn't have a background color, so who knows what space it occupies?`)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

class StartPage extends Page{
	createGui(){
		return Text.background(`orange`)(`This Text component has an orange background, so it's easy too see what space it occupies.`)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

Using multiple GUI components #

But if createGui() can send back only one GUI component, how can I use multiple GUI components? There exists some GUI components whose sole purpose it to contain and position other GUI components on the screen. These GUI components are called Layouts, and the GUI components they contain are called Children. By using a layout, createGui() can send back only one GUI component (the layout), but that GUI component can in turn contain other GUI components. And when the layout is shown on the screen, it will position and show the GUI components it contains (its children) on the screen too. This way we can build a GUI consisting of multiple GUI components!

Let's go through some of the layouts we can use.

The Rows component #

The GUI component called Rows is a layout that position its children as rows (the first child at the top, the second child below that one, and so on). All children are as wide as the Rows component, and their height is by default just big enough to surround their content. The Rows component's main content should be the children it should contain (pass them as individual arguments to Rows() (arguments must be separated by ,)).

class StartPage extends Page{
	createGui(){
		return Rows.background(`yellow`)(
			Text.background(`lime`)(`First text.`), // First child.
			Text.background(`aqua`)(`Second text, and this text is quite long, spanning multiple lines.`), // Second child
			Text.background(`gold`).left()(`Third text, left aligned.`), // Third child (the comma here is not needed, but it's OK to have it).
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

Resizing children #

By default, the children will just be tall enough to surround their content. By using the configuration method size() on a child, you can pass it a number indicating how many shares of the remaining available space in the Rows component the child should occupy.

class StartPage extends Page{
	createGui(){
		return Rows.background(`yellow`)(
			Text.size(1).background(`lime`)(`First text.`), // Since this is the only child with a size, it will occupy all remaining space (no matter which number you pass it).
			Text.background(`aqua`)(`Second text, and this text is quite long, spanning multiple lines.`),
			Text.background(`gold`).left()(`Third text, left aligned.`), // This comma is not needed, but it's OK to have it.
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

class StartPage extends Page{
	createGui(){
		// There are 3 thirds (1+2) in total in this example.
		return Rows.background(`yellow`)(
			Text.size(1).background(`lime`)(`First text.`), // 1 third of the remaining space.
			Text.background(`aqua`)(`Second text, and this text is quite long, spanning multiple lines.`),
			Text.size(2).background(`gold`).left()(`Third text, left aligned.`), // 2 thirds of the remaining space.
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

The Space component #

Often when you use a Layout, you want some children to just occupy some space to move the other children to the place you want them to be at. For example, instead of only using a Text component that covers the entire screen, you might want it to be as small as possible at the bottom of the screen. To achieve that, you can use the Rows component, and let its first child occupy all remaining space, and the second child (the Text component) to be as small as possible. Since the purpose of the first child is to just occupy some space, the Space component is the best choice to use for this.

Children in the Rows component are always just tall enough to surround their content, except if they have their size set to a number. The only exception to this is the Space component, who by default has its size set to 1. That is, the two code pieces below are identical.

Space

Space.size(1)

The reason Space has its size set to 1 by default is because that's often how you want to use it, but if you want it to have another number, just pass it to size() as usual.

class StartPage extends Page{
	createGui(){
		return Rows.background(`yellow`)(
			Space,
			Text.background(`lime`)(`I'm just as tall as the text, and I'm at the bottom!`),
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

If you want to center the Text component vertically instead, simply add another Space component below it.

class StartPage extends Page{
	createGui(){
		return Rows.background(`yellow`)(
			Space, // Will occupy 1 share of the remaining space.
			Text.background(`lime`)(`I'm just as tall as the text, and I'm vertically centered!`),
			Space, // Will occupy 1 share of the remaining space.
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

The Cols component #

The GUI Component Cols (short for Columns) works kind of the same way as the Rows component, but it positions its children as columns instead of rows. The children will always be as tall as the Cols component, and their width will by default be just wide enough to surround the content in the child. The configuration method size() can be used on the children to tell them how many shares of the remaining horizontal space they should occupy. And, just as for the Rows component, the Space component has a default size of 1.

class StartPage extends Page{
	createGui(){
		return Cols.background(`yellow`)(
			Text.background(`lime`)(`#1`),
			Text.background(`aqua`)(`Number 2`),
			Text.background(`gold`).bottom()(`Third`),
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

class StartPage extends Page{
	createGui(){
		return Cols.background(`yellow`)(
			Text.size(2).background(`lime`)(`#1`),
			Text.background(`aqua`)(`Number 2`),
			Text.size(1).background(`gold`).bottom()(`Third`),
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

class StartPage extends Page{
	createGui(){
		return Cols.background(`yellow`)(
			Text.background(`lime`)(`Left!`),
			Space,
			Text.background(`gold`)(`Right!`),
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

Combining Layouts #

A page containing just rows or just columns is usually not that fun. By combining the Rows component and the Cols component (use one as a child to the other), you can create many different usable layouts.

class StartPage extends Page{
	createGui(){
		return Rows(
			Text.size(1).background(`white`)(`Main content`),
			Cols.background(`lime`)(
				Space,
				Button(`Option 1`),
				Space,
				Button(`Option 2`),
				Space,
				Button(`Option 3`),
				Space,
			),
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

class StartPage extends Page{
	createGui(){
		return Rows.padding(5)(
			Space,
			Text(`Login`),
			Space,
			Cols(
				Text(`Username:`).size(1),
				EnterText.size(1),
			),
			Space.size(0.1),
			Cols(
				Text(`Password:`).size(1),
				EnterText.size(1),
			),
			Space,
			Cols(
				Space,
				Button(`Login`),
				Space,
			),
			Space.size(5),
		)
	}
}

class MyApp extends App{
	createStartPage(){
		return new StartPage()
	}
}

That's it! #

Good work, now you have learned the basics about using layouts and building more fancy GUIs! 🥳 It takes some practice before you're good at seeing GUIs as rows and columns, but you actually don't need more than this to create a wide variety of layouts. Just look at your web browser; all GUI components in it are arranged as rows and columns!

To be continued! 😅 Hang in there!