Finished automatically generated docs
Time to correct it by itself
This commit is contained in:
Patryk Gensch
249
docs/en/reference/BUTTON.md
Normal file
249
docs/en/reference/BUTTON.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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`](#button-states) state.
|
||||
|
||||
### GFXONCLICK
|
||||
|
||||
```
|
||||
STRING GFXONCLICK
|
||||
```
|
||||
|
||||
Name of the [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable shown in the [`PRESSED`](#button-states) state. Optional — if unset, `GFXSTANDARD` keeps being shown while pressed.
|
||||
|
||||
### GFXONMOVE
|
||||
|
||||
```
|
||||
STRING GFXONMOVE
|
||||
```
|
||||
|
||||
Name of the [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable shown in the [`HOVERED`](#button-states) state. Optional.
|
||||
|
||||
### GFXSTANDARD
|
||||
|
||||
```
|
||||
STRING GFXSTANDARD
|
||||
```
|
||||
|
||||
Name of the [`ANIMO`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable shown at rest. If [`ENABLE`](#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`](ANIMO.md#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`](ANIMO.md) or [`IMAGE`](IMAGE.md) variable whose current graphic rectangle will be used.
|
||||
|
||||
If unset, the rectangle of the [`GFXSTANDARD`](#gfxstandard) variable is used.
|
||||
|
||||
### SNDONCLICK
|
||||
|
||||
```
|
||||
STRING SNDONCLICK
|
||||
```
|
||||
|
||||
Name of the [`SOUND`](SOUND.md) variable played on entering the [`PRESSED`](#button-states) state.
|
||||
|
||||
### SNDONMOVE
|
||||
|
||||
```
|
||||
STRING SNDONMOVE
|
||||
```
|
||||
|
||||
Name of the [`SOUND`](SOUND.md) variable played on entering the [`HOVERED`](#button-states) state.
|
||||
|
||||
### SNDSTANDARD
|
||||
|
||||
```
|
||||
STRING SNDSTANDARD
|
||||
```
|
||||
|
||||
Name of the [`SOUND`](SOUND.md) variable played on returning to the [`STANDARD`](#button-states) 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`](#gfxstandard), [`GFXONMOVE`](#gfxonmove), [`GFXONCLICK`](#gfxonclick)). Graphics linked via [`RECT`](#rect) are unaffected.
|
||||
|
||||
**Examples**
|
||||
|
||||
```
|
||||
B_GLOBAL_PAUSE^DISABLE();
|
||||
```
|
||||
|
||||
### DISABLEBUTVISIBLE
|
||||
|
||||
```
|
||||
void DISABLEBUTVISIBLE()
|
||||
```
|
||||
|
||||
Disables the button but keeps the [`GFXSTANDARD`](#gfxstandard) graphic visible (like `DISABLE`, but the final state is [`DISABLED_BUT_VISIBLE`](#button-states)).
|
||||
|
||||
**Examples**
|
||||
|
||||
```
|
||||
BTNBONE^DISABLEBUTVISIBLE();
|
||||
BTNFORGOT^DISABLEBUTVISIBLE();
|
||||
```
|
||||
|
||||
### ENABLE
|
||||
|
||||
```
|
||||
void ENABLE()
|
||||
```
|
||||
|
||||
Enables the button and restores visibility of the [`GFXSTANDARD`](#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`](#gfxstandard), [`GFXONMOVE`](#gfxonmove), [`GFXONCLICK`](#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`](#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`](#button-states) to [`HOVERED`](#button-states) — i.e. when the cursor enters the button area.
|
||||
|
||||
### ONFOCUSOFF
|
||||
|
||||
Fired on the transition from [`HOVERED`](#button-states) to [`STANDARD`](#button-states) — when the cursor leaves the button.
|
||||
|
||||
### ONCLICKED
|
||||
|
||||
Fired on the transition into [`PRESSED`](#button-states) (the mouse button has been pressed).
|
||||
|
||||
### ONRELEASED
|
||||
|
||||
Fired on the transition from [`PRESSED`](#button-states) to [`HOVERED`](#button-states) — when the mouse button is released over the button area.
|
||||
|
||||
### ONACTION
|
||||
|
||||
Fired together with [`ONRELEASED`](#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`](#draggable) set to `TRUE`).
|
||||
|
||||
### ONENDDRAGGING
|
||||
|
||||
Fired when dragging ends.
|
||||
|
||||
### ONSIGNAL
|
||||
|
||||
Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
|
||||
Reference in New Issue
Block a user