Box
On this page you find the documentation for the GUI Component Box.
This webpage only contains descriptions of the configuration methods that are specific to the Box component. The Box component also supports the configuration methods described on the page Component.
Introduction
The Box component is a layout that can have an optional child with a specific width and height specified by you. So if you ever want to give a GUI component a specific width and height, just use it as a child in a Box component.
The Box component will by default be sized per the GUI layout you use it in or cover the entire screen if it's the root GUI component. But its child component can be smaller than that.
Example showing what the Box component looks like when shown on the screen.
child() - Setting the child
Use the configuration method child() to tell the Box component which (optional) child it should have.
If the Box component has been given a size (for example by being the root layout, or by being used as a child in Rows or Columns and been given a grow(), etc.), then it's child will by default get the same size as the Box component itself (except its padding).
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(5).child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
)
}
}class StartPage extends Page{
createGui(){
return Rows.children(
Space.backgroundColor(`pink`),
Box.grow(1).padding(5).backgroundColor(`red`).child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
),
Space.backgroundColor(`gold`),
)
}
}If the Box component has not been given a size, then it will by default be big enough to contain it's child component.
class StartPage extends Page{
createGui(){
return Rows.children(
Space.backgroundColor(`pink`),
Box.padding(5).backgroundColor(`red`).child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
),
Space.backgroundColor(`gold`),
)
}
}width() - Setting the width
Use the configuration method width() to tell the Box component how wide its child should be. Pass it the width as a number. See also Units.
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).width(33.33).child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
)
}
}A better name on this method is probably childWidth(), since it sets the width of the child component, and not the width of the Box component, but to keep the code shorter, the name width() is used.
left() - Left aligning the box
If you use the configuration method width(), the child will by default be centered at the space given to it by its parent layout. Use the configuration method left() to tell the Box component that the child should be to the left instead.
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).width(33.33).left().child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
)
}
}right() - Right aligning the box
If you use the configuration method width(), the child will by default be centered at the space given to it by its parent layout. Use the configuration method right() to tell the Box component that the child should be to the right instead.
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).width(33.33).right().child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
)
}
}height() - Setting the height
Use the configuration method height() to tell the Box component how tall its child should be. Pass it the height as a number. See also Units.
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).height(50).child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
)
}
}A better name on this method is probably childHeight(), since it sets the height of the child component, and not the height of the Box component, but to keep the code shorter, the name height() is used.
top() - Top aligning the box
If you use the configuration method height(), the child will by default be centered at the space given to it by its parent layout. Use the configuration method top() to tell the Box component that the child should be to the top instead.
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).height(50).top().child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
)
}
}bottom() - Bottom aligning the box
If you use the configuration method height(), the child will by default be centered at the space given to it by its parent layout. Use the configuration method bottom() to tell the Box component that the child should be to the bottom instead.
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).height(50).bottom().child(
Text.backgroundColor(`lime`).text(`The child is lime!`)
)
}
}aspectRatio() - Setting the relation between width and height
Instead of giving the Box component an explicit width and height, you can use the width or height given to it by its parent layout or by calling the configuration methods width() or height() to automatically compute the other one based on the Box component's given aspect ratio, which is set with the configuration method aspectRatio(). Pass it the aspect ratio as two numbers:
- First the width
- Then the height
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).width(50).aspectRatio(1, 2).child(
Text.backgroundColor(`lime`).text(`Width is 50sw, the aspect ratio is 1:2 (i.e. the height should be twice as big as the width), so the height is computed as 100sw.`)
)
}
}If you use aspectRatio() without using width() and height(), then the Box component will get the biggest size possible to honor the given aspect ratio.
class StartPage extends Page{
createGui(){
return Box.backgroundColor(`red`).padding(1).aspectRatio(2, 1).child(
Text.backgroundColor(`lime`).text(`The width is always exactly 2 times bigger than the height, but never bigger than the screen!`)
)
}
}A better name on this method is probably childAspectRatio(), since it sets the aspect ratio of the child component, and not of the Box component, but to keep the code shorter, the name aspectRatio() is used.