Rex-EMoolator-docs/docs/en/reference/BUTTON.md

BUTTON

An interactive button with three visual states (normal, hovered, pressed) and separate graphics and sounds for each. A button can also be disabled — either completely (DISABLE) or while remaining visible (DISABLEBUTVISIBLE).

Internally the button is a small state machine. Every state transition automatically shows or hides the appropriate graphics, plays the linked sound, and may emit a signal.

Button states

State	Meaning
STANDARD	at rest — the GFXSTANDARD graphic is shown.
HOVERED	the cursor is over the button — the GFXONMOVE graphic is shown (or GFXSTANDARD if unset).
PRESSED	the button is being pressed — the GFXONCLICK graphic is shown (or GFXSTANDARD if unset).
DISABLED	the button is disabled and hidden.
DISABLED_BUT_VISIBLE	the button is disabled but the GFXSTANDARD graphic is shown.

Fields

DRAGGABLE

BOOL DRAGGABLE

Whether the button can be dragged.

ENABLE

BOOL ENABLE

Whether the button is enabled after initialisation. A value of FALSE puts the button into the DISABLED state.

GFXONCLICK

STRING GFXONCLICK

Name of the ANIMO or IMAGE variable shown in the PRESSED state. Optional — if unset, GFXSTANDARD keeps being shown while pressed.

GFXONMOVE

STRING GFXONMOVE

Name of the ANIMO or IMAGE variable shown in the HOVERED state. Optional.

GFXSTANDARD

STRING GFXSTANDARD

Name of the ANIMO or IMAGE variable shown at rest. If ENABLE is FALSE, the graphic is hidden after initialisation — with one exception: if the linked animation is already playing, it stays visible (example: the torch in 16BLAWA from Reksio i Skarb Piratów). In that case the linked graphic's TOCANVAS setting is ignored.

RECT

INTEGER, INTEGER, INTEGER, INTEGER RECT
STRING RECT

The cursor hit area. Two forms are accepted:

• Four integers xLeft,yBottom,xRight,yTop defining a rectangle on screen.
• The name of an ANIMO or IMAGE variable whose current graphic rectangle will be used.

If unset, the rectangle of the GFXSTANDARD variable is used.

SNDONCLICK

STRING SNDONCLICK

Name of the SOUND variable played on entering the PRESSED state.

SNDONMOVE

STRING SNDONMOVE

Name of the SOUND variable played on entering the HOVERED state.

SNDSTANDARD

STRING SNDSTANDARD

Name of the SOUND variable played on returning to the STANDARD state.

VISIBLE

BOOL VISIBLE

Persisted in script data but not observed by the engine — testing shows this field has no effect on button behaviour.

Methods

DISABLE

void DISABLE()

Disables the button and hides all linked graphics (GFXSTANDARD, GFXONMOVE, GFXONCLICK). Graphics linked via RECT are unaffected.

Examples

B_GLOBAL_PAUSE^DISABLE();

DISABLEBUTVISIBLE

void DISABLEBUTVISIBLE()

Disables the button but keeps the GFXSTANDARD graphic visible (like DISABLE, but the final state is DISABLED_BUT_VISIBLE).

Examples

BTNBONE^DISABLEBUTVISIBLE();
BTNFORGOT^DISABLEBUTVISIBLE();

ENABLE

void ENABLE()

Enables the button and restores visibility of the GFXSTANDARD graphic. Calling this on an already-enabled button has no effect.

Examples

B_GLOBAL_PAUSE^ENABLE();
BTNEXIT^ENABLE();

SETPRIORITY

void SETPRIORITY(INTEGER posZ)

Sets the rendering priority (Z position) of all three linked graphics (GFXSTANDARD, GFXONMOVE, GFXONCLICK). Higher values are drawn on top.

Parameters

• posZ — new priority value.

Examples

B_GLOBAL_PAUSE^SETPRIORITY(5001);
BTNNULLFADE^SETPRIORITY(40000);

SETRECT

void SETRECT(STRING varName)
void SETRECT(INTEGER xLeft, INTEGER yBottom, INTEGER xRight, INTEGER yTop)

Sets the cursor hit area. The first form copies the rectangle from a graphics variable; the second specifies it directly.

Parameters

• varName — name of the graphics variable (form 1).
• xLeft, yBottom, xRight, yTop — rectangle coordinates (form 2).

Examples

EXITPROGAM^SETRECT("ANNEXIT");
*STMP0^SETRECT([ITMPX+[ITMPDX*_I_]],[ITMPY+[ITMPDY*_I_]],[ITMPX+15+[ITMPDX*_I_]],[ITMPY+15+[ITMPDY*_I_]]);

SETSTD

void SETSTD(STRING varName)
void SETSTD(STRING varName, BOOL flag)

Sets the button's standard graphic (GFXSTANDARD) and zeroes its priority. Shipping scripts also use a two-argument form whose boolean flag is always FALSE; its meaning has not been established.

Parameters

• varName — name of the new standard graphic variable (an empty string "" clears the link).
• flag — configuration flag (form 2, meaning unknown).

Examples

BTNEXIT^SETSTD("ANNOBJECT2");
B_GLOBAL_PAUSE^SETSTD("",FALSE);
BTNBAD^SETSTD("ZLY",FALSE);

Signals

ONINIT

Fired when the object is initialised.

ONFOCUSON

Fired on the transition from STANDARD to HOVERED — i.e. when the cursor enters the button area.

ONFOCUSOFF

Fired on the transition from HOVERED to STANDARD — when the cursor leaves the button.

ONCLICKED

Fired on the transition into PRESSED (the mouse button has been pressed).

ONRELEASED

Fired on the transition from PRESSED to HOVERED — when the mouse button is released over the button area.

ONACTION

Fired together with ONRELEASED — confirms that a full click (press and release on the button area) has happened.

ONSTARTDRAGGING

Fired when dragging begins (only for buttons with DRAGGABLE set to TRUE).

ONENDDRAGGING

Fired when dragging ends.

ONSIGNAL

Fired when a signal arrives (see Events and signals).