def button(self, label, key=None):
"""Display a button widget.
Parameters
----------
label : str
A short label explaining to the user what this button is for.
key : str
An optional string to use as the unique key for the widget.
If this is omitted, a key will be generated for the widget
based on its content. Multiple widgets of the same type may
not share the same key.
Returns
-------
bool
If the button was clicked on the last run of the app.
Example
-------
>>> if st.button('Say hello'):
... st.write('Why hello there')
... else:
... st.write('Goodbye')
"""
button_proto = ButtonProto()
button_proto.label = label
button_proto.default = False
ui_value = register_widget("button", button_proto, user_key=key)
current_value = ui_value if ui_value is not None else False
return self.dg._enqueue("button", button_proto, current_value)
def test_get_widget_with_generated_key(self):
button_proto = ButtonProto()
button_proto.label = "the label"
self.assertTrue(
_get_widget_id(
"button",
button_proto).startswith(GENERATED_WIDGET_KEY_PREFIX))
def _button(
self,
label: str,
key: Optional[str],
help: Optional[str],
is_form_submitter: bool,
) -> bool:
button_proto = ButtonProto()
# It doesn't make sense to create a button inside a form (except
# for the "Form Submitter" button that's automatically created in
# every form). We throw an error to warn the user about this.
# We omit this check for scripts running outside streamlit, because
# they will have no report_ctx.
if streamlit._is_running_with_streamlit:
if is_in_form(self.dg) and not is_form_submitter:
raise StreamlitAPIException(
f"`st.button()` can't be used in an `st.form()`.{FORM_DOCS_INFO}"
)
elif not is_in_form(self.dg) and is_form_submitter:
raise StreamlitAPIException(
f"`st.form_submit_button()` must be used inside an `st.form()`.{FORM_DOCS_INFO}"
)
button_proto.label = label
button_proto.default = False
button_proto.is_form_submitter = is_form_submitter
button_proto.form_id = current_form_id(self.dg)
if help is not None:
button_proto.help = help
ui_value = register_widget("button", button_proto, user_key=key)
current_value = ui_value if ui_value is not None else False
return self.dg._enqueue("button", button_proto, current_value) # type: ignore
def _button(
self,
label: str,
key: Optional[str],
help: Optional[str],
is_form_submitter: bool,
on_click: Optional[WidgetCallback] = None,
args: Optional[WidgetArgs] = None,
kwargs: Optional[WidgetKwargs] = None,
*, # keyword-only arguments:
disabled: bool = False,
ctx: Optional[ScriptRunContext] = None,
) -> bool:
if not is_form_submitter:
check_callback_rules(self.dg, on_click)
check_session_state_rules(default_value=None,
key=key,
writes_allowed=False)
# It doesn't make sense to create a button inside a form (except
# for the "Form Submitter" button that's automatically created in
# every form). We throw an error to warn the user about this.
# We omit this check for scripts running outside streamlit, because
# they will have no script_run_ctx.
if streamlit._is_running_with_streamlit:
if is_in_form(self.dg) and not is_form_submitter:
raise StreamlitAPIException(
f"`st.button()` can't be used in an `st.form()`.{FORM_DOCS_INFO}"
)
elif not is_in_form(self.dg) and is_form_submitter:
raise StreamlitAPIException(
f"`st.form_submit_button()` must be used inside an `st.form()`.{FORM_DOCS_INFO}"
)
button_proto = ButtonProto()
button_proto.label = label
button_proto.default = False
button_proto.is_form_submitter = is_form_submitter
button_proto.form_id = current_form_id(self.dg)
button_proto.disabled = disabled
if help is not None:
button_proto.help = dedent(help)
def deserialize_button(ui_value: bool, widget_id: str = "") -> bool:
return ui_value or False
current_value, _ = register_widget(
"button",
button_proto,
user_key=key,
on_change_handler=on_click,
args=args,
kwargs=kwargs,
deserializer=deserialize_button,
serializer=bool,
ctx=ctx,
)
self.dg._enqueue("button", button_proto)
return cast(bool, current_value)
