Response

Choose Button Option Dialog

class CommonChooseButtonOptionDialog(mod_identity, title_identifier, description_identifier, title_tokens=(), description_tokens=(), include_previous_button=True, next_button_text=sims4communitylib.enums.strings_enum.CommonStringId.NEXT, previous_button_text=sims4communitylib.enums.strings_enum.CommonStringId.PREVIOUS, on_previous=<function CommonFunctionUtils.noop>, on_close=<function CommonFunctionUtils.noop>, per_page=10)

Bases: CommonChooseResponseOptionDialog

A dialog that displays a list of options.

Note

To see an example dialog, run the command s4clib_testing.show_choose_button_option_dialog in the in-game console.

Example usage:

def _on_option_chosen(option_identifier: DialogOptionIdentifierType, choice: DialogOptionValueType):
    pass

def _on_previous_chosen() -> None:
    pass

def _on_close() -> None:
    pass

# LocalizedStrings within other LocalizedStrings
title_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
        text_color=CommonLocalizedStringColor.GREEN
    ),
)
description_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME,
        tokens=(CommonSimUtils.get_active_sim_info(),),
        text_color=CommonLocalizedStringColor.BLUE
    ),
)
option_dialog = CommonChooseButtonOptionDialog(
    ModInfo.get_identity(),
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    on_previous=_on_previous_chosen,
    on_close=_on_close
)

# We add the options, in this case we have three options.
option_dialog.add_option(
    CommonDialogButtonOption(
        'Option 1',
        'Value 1',
        CommonDialogResponseOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            subtext_identifier=CommonStringId.TESTING_TEST_BUTTON_ONE
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.add_option(
    CommonDialogButtonOption(
        'Option 2',
        'Value 2',
        CommonDialogResponseOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            subtext_identifier=CommonStringId.TESTING_TEST_BUTTON_TWO,
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.add_option(
    CommonDialogButtonOption(
        'Option 3',
        'Value 3',
        CommonDialogResponseOptionContext(
            CommonLocalizationUtils.create_localized_string('Value 3'),
            subtext_identifier=CommonStringId.TESTING_TEST_BUTTON_TWO
        ),
        on_chosen=_on_option_chosen
    )
)

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info()
)

Parameters:

• mod_identity (CommonModIdentity) – The identity of the mod creating the dialog. See CommonModIdentity for more information.

• title_identifier (Union[int, str, LocalizedString, CommonStringId]) – A decimal identifier of the title text.

• description_identifier (Union[int, str, LocalizedString, CommonStringId]) – A decimal identifier of the description text.

• title_tokens (Iterator[Any], optional) – An iterator of Tokens to format into the title. Default is an empty collection.

• description_tokens (Iterator[Any], optional) – An iterator of Tokens to format into the description. Default is an empty collection.

• include_previous_button (bool, optional) – If True, the Previous button will be appended to the end of the dialog. Default is True.

• on_previous (Callable[[], None], optional) – A callback invoked upon the the Previous option being chosen. Default is CommonFunctionUtils.noop.

• on_close (Callable[[], None], optional) – A callback invoked upon the dialog closing. Default is CommonFunctionUtils.noop.

add_option(option)

Add an option to the dialog.

Parameters:

option (CommonDialogObjectOption) – The option to add.

build_dialog(dialog_options=0, sim_info=None, target_sim_info=None, page=1)

Build the dialog and invoke the callbacks upon the player making a choice.

Parameters:

• dialog_options (UiDialogOption, optional) – Options to apply to the dialog, such as removing the close button. Default is no options.

• sim_info (SimInfo, optional) – The SimInfo of the Sim that will appear in the dialog image. The default Sim is the active Sim. Default is None.

• target_sim_info (SimInfo, optional) – If provided, the dialog will appear as if it were a conversation instead of the normal view. Default is None.

• page (int, optional) – The page to build the dialog on. Default is the first page.

Returns:

The built dialog or None if a problem occurs.

Return type:

Union[UiDialogBase, None]

property log_identifier

A string identifier for the log used by instances of the class.

Note

This is the message identifier that will appear when logging messages.

Returns:

The identifier of the log

Return type:

str

show(dialog_options=0, sim_info=None, target_sim_info=None, page=1)

Show the dialog and invoke the callbacks upon the player making a choice.

Parameters:

• dialog_options (UiDialogOption, optional) – Options to apply to the dialog, such as removing the close button. Default is no options.

• sim_info (SimInfo, optional) – The SimInfo of the Sim that will appear in the dialog image. The default Sim is the active Sim. Default is None.

• target_sim_info (SimInfo, optional) – If provided, the dialog will appear as if it were a conversation instead of the normal view. Default is None.

• page (int, optional) – The page to show the dialog on. Default is the first page.

Choose Response Option Dialog

class CommonChooseResponseOptionDialog(internal_dialog, include_previous_button=True, on_previous=<function CommonFunctionUtils.noop>, on_close=<function CommonFunctionUtils.noop>)

Bases: CommonOptionDialog

A dialog that displays a list of options.

Warning

Unless you know what you are doing, do not create an instance of this class directly!

Parameters:

• internal_dialog (CommonChooseResponseDialog) – The dialog this option dialog wraps.

• include_previous_button (bool, optional) – If True, the Previous button will be appended to the end of the dialog. Default is True.

• on_previous (Callable[[], None], optional) – A callback invoked upon the Previous response being chosen. Default is no operation.

• on_close (Callable[[], None], optional) – A callback invoked upon the dialog closing.

add_option(option)

Add an option to the dialog.

Parameters:

option (CommonDialogResponseOption) – The option to add.

build_dialog(*_, **__)

Build the dialog.

Note

Override this function to provide your own arguments.

Returns:

The built dialog or None if a problem occurs.

Return type:

Union[CommonUiResponseDialog, None]

has_options()

Determine if the dialog has selectable options.

Returns:

True, if the dialog has any options in it. False, if not.

Return type:

bool

property option_count

The number of options within the dialog.

Returns:

The number of options within the dialog.

Return type:

int

show(*_, **__)

Show the dialog.

Note

Override this function to provide your own arguments.

Options

Button Option

class CommonDialogButtonOption(option_identifier, value, context, on_chosen=<function CommonFunctionUtils.noop>)

Bases: CommonDialogResponseOption

An option the player can choose within a dialog.

Parameters:

• option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.

• value (DialogResponseOptionValueType) – The value of the option.

• context (CommonDialogOptionContext) – A context to customize the dialog option.

• on_chosen (Callable[[DialogOptionIdentifierType, DialogResponseOptionValueType], None], optional) – A callback invoked when the dialog option is chosen. The values are as follows: (option_identifier, value)

as_response(option_id)

Convert the option into a response.

Parameters:

option_id (int) – The index of the option.

Returns:

The option as a Response

Return type:

CommonUiDialogResponse

property option_identifier

Used to identify the option.

property value

The value of the option.

Response Option

class CommonDialogResponseOption(value, context, on_chosen=<function CommonFunctionUtils.noop>)

Bases: object

An option the player can choose within a dialog.

Parameters:

• value (DialogOptionValueType) – The value of the option.

• context (CommonDialogResponseOptionContext) – A context to customize the dialog option.

• on_chosen (Callable[[DialogOptionValueType], Any], optional) – A callback invoked when the dialog option is chosen.

as_response(option_id)

Convert the option into a response.

Parameters:

option_id (int) – The index of the option.

Returns:

The option as a Response

Return type:

CommonUiDialogResponse

choose()

Choose the option.

Returns:

The result of choosing the option.

Return type:

Any

property context

The context of the option.

property disabled_text

The text that displays on the option as a tooltip. If provided, the option will also be disabled.

property on_chosen

The action to perform upon choosing this option.

property subtext

The subtext that displays under the option.

property text

The text of the dialog option.

property value

The value of the option.

Response Option

class CommonDialogResponseOptionContext(text_identifier, text_tokens=(), subtext_identifier=None, subtext_tokens=(), disabled_text_identifier=None, disabled_text_tokens=())

Bases: object

A context used by CommonDialogResponseOption that provides customization of options.

Parameters:

• text_identifier (Union[int, str, LocalizedString, CommonStringId]) – The text of the option.

• text_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the text.

• subtext_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – The subtext of the option. Default is None.

• subtext_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the description.

• disabled_text_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – The text that displays on the option as a tooltip. Setting this value will also disable the option. Default is None.

• disabled_text_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the description.

property disabled_text

The text that displays on the option as a tooltip. If provided, the option will also be disabled.

property subtext

The subtext that displays under the option.

property text

The text of the dialog option.