Chili:Tutorial

Wiki < Chili < Chili Tutorial

The Basics

In Chili, every element of the GUI has properties that control how it looks, and functions it can call when special events (such as a double click, or mouseover) affect it.

To use Chili inside a Lua widget, your widget:Initialize function should include the following code: <syntaxhighlight lang="lua">

 function widget:Initialize()
   Chili = WG.Chili
   Screen0 = Chili.Screen0
 end

</syntaxhighlight> Now, Chili is your route to creating new GUI elements, and Screen0 is the screen in which you add them.

Creating a Chili Component

To create a Chili component, you use its New function, for example: <syntaxhighlight lang="lua">

 Chili.Window:New{parent=Screen0, width='20%', height='20%'}

</syntaxhighlight> This creates a square window, taking up 1/5th of the screen. See the Hello World example for how to fit this code into a Chili widget.

If you forget to include parent=Screen0, your window will exist, but it won't be drawn anywhere. This is the instruction that tells Chili that you want your component to appear inside Screen0 - your screen.

If you look at the properties of a Window, you won't find any. But, Window inherits from Control - this means that a Window also has all the properties that a Control has. By looking at the properties of Control you can see that a Window actually has many options. Any properties that you don't specify are set to their default values.

The hierarchy of inheritance for all Chili objects can be found here.

Modifying components

Once a component exists you can modify its properties, whenever you like. When you do so, Chili will react and automatically change how the component is drawn. For example, <syntaxhighlight lang="lua">

 local myWindow = Chili.Window:New{parent=Screen0, width='20%', height='20%'}
 myWindow.x = 100
 myWindow.y = 100

</syntaxhighlight> results in the window above being placed on the screen at (100,100).

Many properties, such as x and y can be modified directly as though the component was a Lua table. Sometimes there are also functions to help you, for example in the properties of a CheckBox you can find a Toggle() function, which you would call as myCheckBox:Toggle()

Making a GUI from multiple components

Components can have children. Child components are placed inside of their parent components (and are drawn in front of it). The x-y coords, width, height, etc, of a component are relative to the area covered by its parent component.

For example: <syntaxhighlight lang="lua">

 window = Chili.Window:New{parent = Screen0,   x='25%', y='25%', width='50%', height='50%'}
 textBox = Chili.TextBox:New{parent = window,  x='10%', y='10%', width='80%', height='30%', text="Is the sky blue?"}
 yesButton = Chili.Button:New{parent = window, x='10%', y='60%', width='30%', height='30%', caption="Yes"}
 noButton = Chili.Button:New{parent = window,  x='60%', y='60%', width='30%', height='30%', caption="No"}

</syntaxhighlight> draws a Window in the center of the screen, containing a TextBox with the words "Is the sky blue?", and two clickable Buttons, for yes and no. It looks like

(TODO: picture).

See the example widgets page for how to make stuff happen when the buttons are clicked.

Children and Showing/Hiding

A component is drawn only when it is a child of another component that is drawn. Screen0 is a component of type Screen, and is always drawn, by default. A component that has no parent will never be drawn; it is said to be orphaned.

In a GUI, it's common to want components to sometimes be visible and sometimes be hidden. You can control this in two ways.

• Every component has Show() and Hide() functions, e.g. myWindow:Hide()
• Components can be orphaned/reattached to their parent.

Of course, Show() will only cause a component to be drawn if it is not orphaned.

There are many ways to specify (and change!) which components are children of which other components.

• To match the parent= used above, each component has a children={[1]=firstChild, [2]=secondChild, ...} table.
• There are the functions AddChild, RemoveChild, SetParent, ClearChildren and others.

A child component can have at most one parent, and a parent cannot have the same child more than once. However, a child can be removed from its original parent and then added to a new parent.