Setting and Retrieving the State of GUI Components

Creating and placing GUI components is only the first step -- without interaction or dynamic behavior, they don't do much.

In this section, you'll learn how to set and retrieve the state of GUI components after placing them, such as reading text from a field or updating colors or graphics.

- Table of Contents -

Changing and Retrieving Colors
Changing and Retrieving Position
Changing and Retrieving Size
Modifying and Retrieving Text
Modifying and Retrieving Graphics Resources
Modifying and Retrieving Boolean and Other Values

Changing and Retrieving Colors

Changing Colors

To change the color of a GUI component, use the setComponentColor function. Its format is as follows:

- Function Format -

void setComponentColor (
  int id,
  int fgRed, int fgGreen, int fgBlue, int fgAlpha,
  int bgRed, int bgGreen, init bgBlue, int bgAlpha
)

Arguments:

id: ID of the GUI component to change the color of
fgRed, fgGreen, fgBlue, fgAlpa: RGBA values for the foreground color (0-255 each)
bgRed, bgGreen, bgBlue, bgAlpa: RGBA values for the background color (0-255 each)

The color values follow the RGBA color model, which adds an alpha (transparency) component to the usual RGB (Red, Green, Blue). These values follow the properties below:

Value range for each component: 0 (none) to 255 (full)
For alpha: 0 is fully transparent, 255 is fully opaque

Note: Color blending is done using additive color mixing -- like how light works -- not subtractive mixing like paint. The result may differ significantly from what you might expect from pigment blending.

How Color Components Are Combined

Colors are mixed using additive color mixing, similar to how light works -- not subtractive mixing like paint.

Retrieving Colors

To get the current color settings of a GUI component, use the getComponentColor function:

- Function Format -

int[ ][ ] getComponentColor ( int id )

Arguments:

id: ID of the component whose color you want to retrieve

Return value:
A 2x4 int array containing the RGBA values:

result[0][0] - [0][3]: Foreground color (R, G, B, A)
result[1][0] - [1][3]: Background color (R, G, B, A)

Supported Components

The "setComponentColor" and "getComponentColor" functions can be used with the following GUI components:

Window / Button / Text Field / Text Area / Check Box / Select Field / Text Label / Image Label

Changing and Retrieving Position

Changing Position

To change the position of a GUI component, use the "setComponentLocation" function:

- Function Format -

void setComponentLocation ( int id, int x, int y )

Arguments:

id: ID of the component to move
x, y: New coordinates for the top-left corner

Retrieving Position

To get the current position of a GUI component, use the "getComponentLocation" function:

- Function Format -

int[ ] getComponentLocation ( int id )

Arguments:

id: ID of the component whose position you want to retrieve

Return value:
An int array of size 2:

result[0]: x-coordinate
result[1]: y-coordinate

Supported Components

These position functions can be used with the following GUI components:

Window / Button / Text Field / Text Area / Check Box / Select Field / Text Label / Image Label

Changing and Retrieving Size

Changing Size

To change the size of a GUI component, use the "setComponentSize" function:

- Function Format -

void setComponentSize ( int id, int width, int height )

Arguments:

id: ID of the component to resize
width, height: New width and height values

Retrieving Size

To get the current size of a GUI component, use the getComponentSize function:

- Function Format -

int[ ] getComponentSize ( int id )

Arguments:

id: ID of the component whose size you want to retrieve

Return value:
An int array of size 2:

result[0]: Width
result[1]: Height

Supported Components

setComponentSizeおよびgetComponentSize関数は、以下のGUIコンポーネントなどに対して使用できます。

Window / Button / Text Field / Text Area / Check Box / Select Field / Text Label / Image Label

Modifying and Retrieving Text

Modifying Text

To change the text of a GUI component, use the setComponentText function:

- Function Format -

void setComponentText( int id, string text )

Arguments:

id: The ID of the component whose text you want to change
text: The new text to display

Retrieving Text

To retrieve the text from a GUI component, use the "getComponentText" function:

- Function Format -

string getComponentText( int id )

Arguments:

id: The ID of the component from which to retrieve the text

Return value:
Returns the current text as a string.

Supported Components

The "setComponentText" and "getComponentText" functions can be used with the following GUI components:

Button / Text Field / Text Area / Check Box / Select Field / Text Label

Modifying and Retrieving Graphics Resources

Modifying Graphics

For components that display graphics -- such as image labels -- you can change the displayed graphics resource by using the setComponentGraphics function:

- Function Format -

void setComponentGraphics( int componentID, int graphicsID )

Arguments:

componentID: The ID of the GUI component to modify
grapnicsID: The ID of the graphics resource to display

Retrieving Graphics

To retrieve the ID of the graphics resource currently being displayed by a component, use the "getComponentGraphics" function:

- Function Format -

int getComponentGraphics( int componentID )

Arguments:

componentID: The ID of the component to retrieve the resource ID from

Return value:
Returns the ID of the graphics resource currently displayed.

Supported Components

The "setComponentGraphics" and "getComponentGraphics" functions can be used with the following GUI components:

Image Label

Modifying and Retrieving Boolean and Other Values

Modifying Boolean Values

For components that have binary ON/OFF states -- such as check boxes -- use the setComponentBool function to set the value:

- Function Format -

void setComponentBool ( int id, bool state )

Arguments:

id: The ID of the component to modify
state: The boolean value to set (true or false)

Retrieving Boolean Values

To retrieve a boolean value from a component, use the "getComponentBool" function:

- Function Format -

bool getComponentBool ( int id )

Arguments:

id: The ID of the component from which to retrieve the value

Return value:
Returns the boolean state as a bool. For example, with a check box, it returns true if checked, and false otherwise.

Supported Components

The "setComponentBool" and "getComponentBool" functions can be used with the following GUI components:

Check Box

Other Types of Values

Although not covered in this guide, some GUI components -- such as sliders -- allow control over other types of values such as "int" or "float".

These components can be handled using the same pattern, with functions like:

setComponentInt / getComponentInt
setComponentFloat / getComponentFloat

For details on these components and functions, please refer to the GUI Library Specification.