Skip to content

levilamina::gui

Forms: the three screens sent to a player, whose callback arrives asynchronously.

The callback runs at most once and may never run

When the player answers, or closes the form, the callback runs once on the server thread. But if the mod is disabled before the player answers, the host mutes that callback and it never arrives. Therefore:

  • the callback is an FnOnce and is freed once it has run;
  • on the muted path the memory holding the closure is leaked on purpose. The code able to free it lives in a dynamic library that may already be unloaded, and freeing it is the real use-after-free.

It follows that cleanup that has to happen does not belong in a form callback: a player may never click.

CustomForm

Rust
1
2
3
pub struct CustomForm {
    // private fields
}

A custom form: input fields, toggles, dropdowns and sliders.

  • Implements: Debug, Clone, Default

CustomForm::new

Rust
1
pub fn new(title: impl Into<String>) -> CustomForm
  • Parameters:
    • title : impl Into<String>
  • Return type: CustomForm

CustomForm::submit

Rust
1
pub fn submit(mut self, text: impl Into<String>) -> CustomForm
  • Parameters:
    • text : impl Into<String>
  • Return type: CustomForm

CustomForm::header

Rust
1
pub fn header(mut self, text: &str) -> CustomForm
  • Parameters:
    • text : &str
  • Return type: CustomForm

CustomForm::label

Rust
1
pub fn label(mut self, text: &str) -> CustomForm
  • Parameters:
    • text : &str
  • Return type: CustomForm

CustomForm::divider

Rust
1
pub fn divider(mut self) -> CustomForm
  • Return type: CustomForm

CustomForm::input

Rust
1
pub fn input(mut self, name: &str, text: &str, placeholder: &str, default: &str) -> CustomForm
  • Parameters:
    • name : &str
    • text : &str
    • placeholder : &str
    • default : &str
  • Return type: CustomForm

CustomForm::toggle

Rust
1
pub fn toggle(mut self, name: &str, text: &str, default: bool) -> CustomForm
  • Parameters:
    • name : &str
    • text : &str
    • default : bool
  • Return type: CustomForm

CustomForm::dropdown

Rust
1
2
3
4
5
6
7
pub fn dropdown(
        mut self,
        name: &str,
        text: &str,
        options: &[&str],
        default: usize,
    ) -> CustomForm
  • Parameters:
    • name : &str
    • text : &str
    • options : &[&str]
    • default : usize
  • Return type: CustomForm

CustomForm::step_slider

Rust
1
2
3
4
5
6
7
pub fn step_slider(
        mut self,
        name: &str,
        text: &str,
        steps: &[&str],
        default: usize,
    ) -> CustomForm
  • Parameters:
    • name : &str
    • text : &str
    • steps : &[&str]
    • default : usize
  • Return type: CustomForm

CustomForm::slider

Rust
1
2
3
4
5
6
7
8
9
pub fn slider(
        mut self,
        name: &str,
        text: &str,
        min: f64,
        max: f64,
        step: f64,
        default: f64,
    ) -> CustomForm

A slider.

An out-of-range default, or a (max-min) that is not a whole multiple of step, makes the Bedrock client render nothing of the form at all, which the player sees as it opening and disappearing. The host clamps and warns, and getting it right before passing it in is better.

  • Parameters:
    • name : &str
    • text : &str
    • min : f64
    • max : f64
    • step : f64
    • default : f64
  • Return type: CustomForm

CustomForm::send

Rust
1
2
3
4
5
pub fn send(
        self,
        player: &Player,
        cb: impl FnOnce(FormResponse) + Send + 'static,
    ) -> Result<()>
  • Parameters:
    • player : &Player
    • cb : impl FnOnce(FormResponse) + Send + 'static
  • Return type: Result<()>
  • Slots: form_send

SimpleForm

Rust
1
2
3
pub struct SimpleForm {
    // private fields
}

A simple form: a column of buttons.

  • Implements: Debug, Clone, Default

SimpleForm::new

Rust
1
pub fn new(title: impl Into<String>) -> SimpleForm
  • Parameters:
    • title : impl Into<String>
  • Return type: SimpleForm

SimpleForm::content

Rust
1
pub fn content(mut self, content: impl Into<String>) -> SimpleForm
  • Parameters:
    • content : impl Into<String>
  • Return type: SimpleForm

SimpleForm::button

Rust
1
pub fn button(mut self, text: &str) -> SimpleForm
  • Parameters:
    • text : &str
  • Return type: SimpleForm

SimpleForm::button_with_image

Rust
1
pub fn button_with_image(mut self, text: &str, image: &str, image_type: &str) -> SimpleForm

A button with an icon. image_type is "path" or "url".

  • Parameters:
    • text : &str
    • image : &str
    • image_type : &str
  • Return type: SimpleForm

SimpleForm::header

Rust
1
pub fn header(mut self, text: &str) -> SimpleForm
  • Parameters:
    • text : &str
  • Return type: SimpleForm

SimpleForm::label

Rust
1
pub fn label(mut self, text: &str) -> SimpleForm
  • Parameters:
    • text : &str
  • Return type: SimpleForm

SimpleForm::divider

Rust
1
pub fn divider(mut self) -> SimpleForm
  • Return type: SimpleForm

SimpleForm::send

Rust
1
2
3
4
5
pub fn send(
        self,
        player: &Player,
        cb: impl FnOnce(FormResponse) + Send + 'static,
    ) -> Result<()>

Sends it.

A form with no button at all cannot be pressed and can only be closed. It is stopped here in advance, because it is almost always a list that assembled empty rather than something intended.

  • Parameters:
    • player : &Player
    • cb : impl FnOnce(FormResponse) + Send + 'static
  • Return type: Result<()>
  • Slots: form_send

FormValue

Rust
1
2
3
4
5
6
7
pub enum FormValue {
        /// The selected index of a dropdown or a step slider.
        Index(usize),
        Number(f64),
        Text(String),
        Bool(bool),
}

The value one control of a custom form returns.

  • Implements: Debug, Clone, PartialEq

FormValue::as_index

Rust
1
pub fn as_index(&self) -> Option<usize>
  • Return type: Option<usize>

FormValue::as_f64

Rust
1
pub fn as_f64(&self) -> Option<f64>
  • Return type: Option<f64>

FormValue::as_i64

Rust
1
pub fn as_i64(&self) -> Option<i64>
  • Return type: Option<i64>

FormValue::as_bool

Rust
1
pub fn as_bool(&self) -> Option<bool>
  • Return type: Option<bool>

FormValue::as_str

Rust
1
pub fn as_str(&self) -> Option<&str>
  • Return type: Option<&str>

ModalForm

Rust
1
2
3
pub struct ModalForm {
    // private fields
}

A modal form: some text and two buttons.

  • Implements: Debug, Clone

ModalForm::new

Rust
1
pub fn new(title: impl Into<String>, content: impl Into<String>) -> ModalForm
  • Parameters:
    • title : impl Into<String>
    • content : impl Into<String>
  • Return type: ModalForm

ModalForm::upper

Rust
1
pub fn upper(mut self, text: impl Into<String>) -> ModalForm
  • Parameters:
    • text : impl Into<String>
  • Return type: ModalForm

ModalForm::lower

Rust
1
pub fn lower(mut self, text: impl Into<String>) -> ModalForm
  • Parameters:
    • text : impl Into<String>
  • Return type: ModalForm

ModalForm::send

Rust
1
2
3
4
5
pub fn send(
        self,
        player: &Player,
        cb: impl FnOnce(FormResponse) + Send + 'static,
    ) -> Result<()>
  • Parameters:
    • player : &Player
    • cb : impl FnOnce(FormResponse) + Send + 'static
  • Return type: Result<()>
  • Slots: form_send

FormResponse

Rust
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
pub enum FormResponse {
        /// The player closed the form. `reason` is the cancellation reason from the engine, or
        /// -1 when it cannot be read.
        Cancelled { reason: i32 },
        /// A simple form: which button was pressed.
        Button(usize),
        /// A modal form: `true` is the upper button.
        Modal { upper: bool },
        /// A custom form, indexed by control name.
        ///
        /// `values` holds the raw values and `texts` the text of the selected item of a dropdown
        /// or step slider. Both are given because the option list may have changed after the form
        /// was sent, and an index alone cannot be matched back.
        Custom {
            values: std::collections::BTreeMap<String, FormValue>,
            texts: std::collections::BTreeMap<String, String>,
        },
        /// The host answered with a shape this side cannot read. It is not swallowed: silently
        /// treating it as a cancellation would make the player pressing confirm and nothing
        /// happening an untraceable problem.
        Unknown { raw: String },
}

A player's answer to a form.

  • Implements: Debug, Clone, PartialEq

FormResponse::is_cancelled

Rust
1
pub fn is_cancelled(&self) -> bool
  • Return type: bool

FormResponse::value

Rust
1
pub fn value(&self, name: &str) -> Option<&FormValue>

Reads the value of one control of a custom form.

  • Parameters:
    • name : &str
  • Return type: Option<&FormValue>

FormResponse::text

Rust
1
pub fn text(&self, name: &str) -> Option<&str>

Reads the text of the selected item of one control of a custom form.

  • Parameters:
    • name : &str
  • Return type: Option<&str>