Box¶

structure Box¶

Box objects are a type of WIDGET.

A Box is a rectangular widget that holds other widgets inside it.

A GUI window is a kind of Box, and is created from the GUI built-in function. You always need at least one Box created this way in order to have any GUI at all show up, and then you add the widgets you want to that Box.

Since a Box is a WIDGET, and a Box is a rectangle that contains widgets, that means you can also put a Box` inside of another ``Box. You do so by using the ADDHBOX or ADDVBOX suffixes of a box. Usually the reason to do this is to define exactly how you want a set of widgets laid out.

Suffix	Type	Description
Every suffix of `WIDGET`
`ADDLABEL(text)`	`Label`	Creates a label in the Box.
`ADDBUTTON(text)`	`Button`	Creates a clickable button in the Box.
`ADDCHECKBOX(text,on)`	`Button`	Creates a toggleable button in the Box.
`ADDRADIOBUTTON(text,on)`	`Button`	Creates an exclusive toggleable button in the Box.
`ADDTEXTFIELD(text)`	`TextField`	Creates an editable text field in the Box.
`ADDPOPUPMENU`	`PopupMenu`	Creates a popup menu.
`ADDHSLIDER(init,min,max)`	`Slider`	Creates a horizontal slider in the Box.
`ADDVSLIDER(init,min,max)`	`Slider`	Creates a vertical slider in the Box.
`ADDHLAYOUT`	`Box`	Creates an undecorated invisible Box in the Box, with horizontal flow.
`ADDVLAYOUT`	`Box`	Creates an undecorated invisible Box in the Box, with vertical flow.
`ADDHBOX`	`Box`	Creates a visible Box in the Box, with horizontal flow.
`ADDVBOX`	`Box`	Creates a visible Box in the Box, with vertical flow.
`ADDSTACK`	`Box`	Creates a nested stacked Box in the Box. Only one such box is shown at a time.
`ADDSCROLLBOX`	`ScrollBox`	Creates a nested scrollable Box of widgets.
`ADDSPACING(size)`	`Spacing`	Creates a blank space of the given size (flexible if -1).
`WIDGETS`	`List(Widget)`	Returns a LIST of the widgets that have been added to the Box.
`RADIOVALUE`	`String`	The string name of the currently selected radio button.
`ONRADIOCHANGE`	`KOSDelegate` (button)	A callback you want kOS to call whenever the radio button selection changes.
`SHOWONLY(widget)`		Hide all but the given widget.
`CLEAR`		Dispose all child widgets.

Box:ADDLABEL(text)¶

Parameters

text – String

Returns

Label

Creates a Label widget in this Box. The label will display the text message given in the parameter.

Box:ADDBUTTON(text)¶

Parameters

text – String

Returns

Button

Creates a clickable Button widget in this Box.

Box:ADDCHECKBOX(text, on)¶

Parameters

text – String text to display
on – Boolean state of the checkbox initially

Returns

Button

Creates a toggle-able Button widget in this Box. The Button will display the text message given in the parameter. The Button will initially start off turned on or turned off depending on the state of the on parameter.

Box:ADDRADIOBUTTON(text, on)¶

Parameters

text – String text to display
on – Boolean state of the checkbox initially

Returns

Button

Creates an exclusive toggle-able Button widget in this Box. The Button will display the text message given in the parameter. The Button will initially start off turned on or turned off depending on the state of the on parameter.

This button will be set to be exclusive, which means all other buttons in this Box which are also exclusive will be turned off when this button is turned on. All these “radio” buttons within this same box are considered to be in the same group for the sake of this check. In order to make two different radio button groups, you would need to create a box for each with BOX:ADDHBOX or BOX:ADDVBOX, and then add radio buttons to each of those boxes.

To read which radio button value is the one that is currently on, among the whole set of buttons, you can use BOX:RADIOVALUE.

Box:ADDTEXTFIELD(text)¶

Parameters

text – struct:String initial starting text in the field.

Returns

TextField

Creates a TextField widget in this Box. The textfield will allow the user to type a string into the field that you can read. The field will be a one-line string input.

Box:ADDPOPUPMENU()¶

Returns: PopupMenu

Creates a special kind of button known as a PopupMenu in the Box. This is a button that, when clicked, brings up a list of values to choose from. When the user picks a value, the popup list goes away and the button will be labeled with the selection from the list that was picked.

The list of values that will pop up are in the suffix PopupMenu:Options, which you must populate after having called ADDPOPUPMENU.

Example:

set mygui to GUI(100).
// Make a popup menu that lets you choose one of 4 color names:
set mypopup mygui:addpopupmenu().
set mypopup:options to LIST("red", "green", "yellow", "white").

mygui:show().
wait 15. // let you play with it for 15 seconds.
mygui:dispose(). // ditch the gui before leaving this example.

Box:ADDHSLIDER(init, min, max)¶

Parameters

init – Scalar starting value
min – Scalar left endpoint value
max – Scalar right endpoint value

Returns

Slider

Creates a horizontal Slider in the Box that adjusts a Scalar value. The value can take on any fractional amount between the minimum and maximum values given. Despite the names it is possible to make the min parameter larger than the max parameter, in which case the direction of the slider will be inverted, with the largest value at the left and the smallest at the right.

Box:ADDVSLIDER(init, min, max)¶

Parameters

init – Scalar starting value
min – Scalar top endpoint value
max – Scalar bottom endpoint value

Returns

Slider

Creates a vertical Slider in the Box that adjusts a Scalar value. The value can take on any fractional amount between the minimum and maximum values given. Despite the names it is possible to make the min parameter larger than the max parameter, in which case the direction of the slider will be inverted, with the largest value at the bottom and the smallest at the top.

Box:ADDHLAYOUT()¶

Returns: Box

Creates a nested transparent horizontally-arranged Box in this Box. You can’t see any visual evidence of this box other than how it forces the widgets inside it to get arranged. (The box has no borders showing, no background color, etc).

All the widgets added to such a box will arrange themselves horizontally (the more widgets you add, the wider the box gets).

There are three reasons you might want to nest one Box inside another Box:

You wish to isolate some radio buttons into their own Box so they form one radio button group.
You wish to force the GUI automatic layout system to place widgets in a particular arrangement by making it treat a group of widgets as a single rectangular chunk that gets arranged together as a unit.

Box:ADDVLAYOUT()¶

Returns: Box

Creates a nested transparent vertically-arranged Box in this Box. You can’t see any visual evidence of this box other than how it forces the widgets inside it to get arranged. (The box has no borders showing, no background color, etc).

All the widgets added to such a box will arrange themselves vertically (the more widgets you add, the taller the box gets).

(The Box returned by calling the built-in function Gui is a “VLayout” box which arranges things vertically like this.)

There are three reasons you might want to nest one Box inside another Box:

You wish to isolate some radio buttons into their own Box so they form one radio button group.
You wish to force the GUI automatic layout system to place widgets in a particular arrangement by making it treat a group of widgets as a single rectangular chunk that gets arranged together as a unit.

Box:ADDHBOX()¶

Returns: Box

This is identical to BOX:ADDHLAYOUT, other than the fact that it uses a different graphical style which lets you see the box.

Box:ADDVBOX()¶

Returns: Box

This is identical to BOX:ADDVLAYOUT, other than the fact that it uses a different graphical style which lets you see the box.

Box:ADDSTACK()¶

Returns: Box

Creates a nested stacked Box in this Box. (a Box which can be swapped for other similarly created boxes that occupy the same space on the screen.)

When you add several such boxes with multiple calls to BOX:ADDSTACK, then instead of these boxes being laid you horizontally or vertically next to each other as widgets would normally be, they all occupy the same space of the screen. However, only one such box in the set of stacked boxes will be visible at a time.

This is how you can implement a pane which has its contents replaced with several different variants depending on what variant you want to see at a time. (i.e. a window with an area who’s contents are toggled by hitting some “tab” buttons that change which version of the contents get shown.)

When several such boxes have been added, you can individually choose which one is shown, by which one is enabled. If two of them are enabled at the same time, then only the first enabled one it finds gets shown.

See SHOWONLY below for more information on how to manipulate these kinds of sub-boxes.

Box:ADDSCROLLBOX()¶

Returns: ScrollBox

Creates a nested scrollable box of widgets.

Using this kind of box, you can create an area of the Gui which holds contents bigger than it can show at once. It will add scrollbars to let you pan the view to see the rest of the content that is outside the visible box size.

To make this work, you will need to specify the size limits of the viewable area, otherwise the layout system will simply make the ScrollBox big enough to hold all the content, and thus it won’t need the scrollbars.

More details on how to do this can be found in the documentation for ScrollBox.

Box:ADDSPACING(size)¶

Parameters

size – Scalar the size of the area to take up with empty space.

Returns

Spacing

Creates blank space of the given size in pixels (flexible if -1).

This is used for cases where you’d like to force a widget to get indented, or pushed further down.

Whether this is horizontal or vertical space depends on whether it is inside a horizontal arrangement box or a vertical arrangement box. (myBox:ADDSPACING(20). is 20 pixels of width if myBox was a BOX:ADDHLAYOUT, but it’s 20 pixels of height if it was a BOX:ADDVLAYOUT.)

Example:

set mygui to GUI(400).
set mytitle to mygui:addlabel("This is my Panel").
set box1 to mygui:ADDHLAYOUT().
box1:addspacing(50). // 50 pixels indent inside horizontal box 1
set button1 to box1:addbutton("indented").
set box2 to mygui:ADDHLAYOUT().
box2:addspacing(100). // 100 pixels indent inside horizontal box 2
set button2 to box2:addbutton("indented more").
myGui:show().
print "Play with buttons for 15 seconds.".
wait 15.
myGui:dispose(). // get rid of the GUI before quitting the program.

Box:WIDGETS¶

Type: List(Widget)
Access: Get-only

Returns a LIST of the widgets that have been added to the Box, so that you may examine them. If you think of the GUI as a tree of widgets (which is what it is), then this is how you find the children of this box. It’s sort of the opposite of Widget:PARENT.

Note that adding or deleting from this list will not actually add or remove widgets from the box itself. (This list is an exported copy of the list of widgets, and not the actual list the box itself uses internally.)

Box:RADIOVALUE¶

Type: String
Access: Get-only

The text label of whichever radiobutton is turned on among all the radio buttons you’ve added with BOX:ADDRADIOBUTTON(text, on) to this box.

Because only one of the radio buttons within this box can be on at a time, this can be a faster way to see which has been selected than reading each button one a time to see which one is on.

If none of the buttons are turned on (for example, if the user hasn’t selected anything yet since the box was displayed), then this will return a value of "" (an empty string).

Box:ONRADIOCHANGE¶

Type: KOSDelegate
Access: Get/Set

The KOSDelegate accepts 1 parameter, a Button, and returns nothing.

A callback hook you want kOS to call whenever the radio button selection within this box changes.

Because a radio button set is defined at the level of a Box (see BOX:ADDRADIOBUTTON(text, on)), the callback hook you would like to be called whenever that radio button set changes which button is the selected one is also here on the Box widget.

The KOSDelegate must be a function (or anonymous function) that behaves as follows:

function myradiochangehook {
  parameter whichButton.

  // Do something here.  "whichButton" will be a variable set to
  // whichever radio button is the one that has just been switched
  // on.
}
set someBox:onradiochange to myradiochange@.

Example, using an anonymous function:

set someBox:onRadioChange to { parameter B.  print "You selected:  " + B:text. }.

Box:SHOWONLY(widget)¶

Parameters

widget –

Type widget

Widget

When multiple widgets have been placed inside this Box, this suffix is used to choose just one of them to be the one you want being shown at the moment. All other widgets within this box will be immediately hidden.

This is useful when you have several stacked boxes made with calls to BOX:ADDSTACK, and want to choose which one of them you are making visible at the moment.

Box:CLEAR()¶

Returns: none

Calling BOX:CLEAR() will get rid of all widgets you have added to this box by use of any of the above “ADD…..” suffixes. It will also call Widget:DISPOSE() on all of them.