Sims¶

Choose Sim Option Dialog¶

class CommonChooseSimOptionDialog(title_identifier, description_identifier, title_tokens=(), description_tokens=(), on_close=<function CommonFunctionUtils.noop>, mod_identity=None, required_tooltip=None, required_tooltip_tokens=())¶

Bases: CommonChooseOptionDialog

A dialog that displays a list of Sims for selection.

Note

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

Example usage:

def _on_chosen(_sim_info: SimInfo):
    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
    ),
)

# Create the dialog and show a number of Sims in 4 columns.
option_dialog = CommonChooseSimOptionDialog(
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    mod_identity=ModInfo.get_identity()
)

current_count = 0
count = 25

for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
    if current_count >= count:
        break
    should_select = random.choice((True, False))
    is_enabled = random.choice((True, False))
    option_dialog.add_option(
        CommonDialogSimOption(
            sim_info,
            CommonDialogSimOptionContext(
                is_enabled=is_enabled,
                is_selected=should_select
            ),
            on_chosen=_on_chosen
        )
    )

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info(),
    column_count=4
)

Parameters:

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.
description_tokens (Iterator[Any], optional) – An iterator of Tokens to format into the description.
on_close (Callable[[], None], optional) – A callback invoked upon the dialog closing.
mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
required_tooltip (Union[int, str, LocalizedString, CommonStringId], optional) – If provided, this text will display when the dialog requires at least one choice and a choice has not been made. Default is None.
required_tooltip_tokens (Iterator[Any], optional) – Tokens to format into the required tooltip. Default is an empty collection.

add_option(option)¶

Add an option to the dialog.

Parameters:: option (CommonDialogSimOption) – The option to add.

build_dialog(sim_info=None, should_show_names=True, hide_row_descriptions=False, column_count=3)¶

Build the dialog.

Parameters:

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.
should_show_names (bool, optional) – If True, then the names of the Sims will display in the dialog. Default is True.
hide_row_descriptions (bool, optional) – A flag to hide the row descriptions. Default is False.
column_count (int, optional) – The number of columns to display Sims in. Default is 3.

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(sim_info=None, should_show_names=True, hide_row_descriptions=False, column_count=3)¶

Show the dialog.

Parameters:

sim_info (SimInfo, optional) – The SimInfo of the Sim that will appear in the dialog image. The default Sim is the active Sim.
should_show_names (bool, optional) – If True, then the names of the Sims will display in the dialog.
hide_row_descriptions (bool, optional) – A flag to hide the row descriptions.
column_count (int, optional) – The number of columns to display Sims in.

Choose Sims Option Dialog¶

class CommonChooseSimsOptionDialog(title_identifier, description_identifier, title_tokens=(), description_tokens=(), on_close=<function CommonFunctionUtils.noop>, mod_identity=None, required_tooltip=None, required_tooltip_tokens=())¶

Bases: CommonChooseOptionsDialog

A dialog that displays a list of Sims for selection and prompts to select multiple Sims.

Note

This dialog allows selection of multiple Sims.

Note

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

Example usage:

def _on_submit(sim_info_list: Tuple[SimInfo]):
    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
    ),
)

# Create the dialog and show a number of Sims in 4 columns and being able to select up to 5 Sims.
option_dialog = CommonChooseSimsOptionDialog(
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    mod_identity=ModInfo.get_identity()
)

current_count = 0
count = 25

for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
    if current_count >= count:
        break
    should_select = random.choice((True, False))
    is_enabled = random.choice((True, False))
    option_dialog.add_option(
        CommonDialogSimOption(
            sim_info,
            CommonDialogSimOptionContext(
                is_enabled=is_enabled,
                is_selected=should_select
            )
        )
    )

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info(),
    column_count=4,
    max_selectable=5,
    on_submit=_on_submit
)

Parameters:

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.
description_tokens (Iterator[Any], optional) – An iterator of Tokens to format into the description.
on_close (Callable[[], None], optional) – A callback invoked upon the dialog closing.
mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
required_tooltip (Union[int, str, LocalizedString, CommonStringId], optional) – If provided, this text will display when the dialog requires at least one choice and a choice has not been made. Default is None.
required_tooltip_tokens (Iterator[Any], optional) – Tokens to format into the required tooltip. Default is an empty collection.

add_option(option)¶

Add an option to the dialog.

Parameters:: option (CommonDialogOption) – The option to add.

build_dialog(on_submit=<function CommonFunctionUtils.noop>, sim_info=None, should_show_names=True, hide_row_descriptions=False, column_count=3, min_selectable=1, max_selectable=1)¶

Show the dialog and invoke the callbacks upon the player submitting their selection.

Parameters:

on_submit (Callable[[Tuple[SimInfo]], Any], optional) – A callback invoked upon the player choosing Sims. Default is CommonFunctionUtils.noop.
sim_info (SimInfo, optional) – The SimInfo of the Sim that will appear in the dialog image. If None, it will be the active Sim. Default is None.
should_show_names (bool, optional) – If True, then the names of the Sims will display in the dialog. Default is True.
hide_row_descriptions (bool, optional) – A flag to hide the row descriptions. Default is False.
column_count (int, optional) – The number of columns to display Sims in. Default is 3.
min_selectable (int, optional) – The minimum number of Sims that must be chosen. Default is 1.
max_selectable (int, optional) – The maximum number of Sims that can be chosen. Default is 1.

Returns:

The built dialog or None if a problem occurs.

Return type:

Union[UiDialogBase, None]

show(on_submit=<function CommonFunctionUtils.noop>, sim_info=None, should_show_names=True, hide_row_descriptions=False, column_count=3, min_selectable=1, max_selectable=1)¶

Show the dialog and invoke the callbacks upon the player submitting their selection.

Parameters:

on_submit (Callable[[Tuple[SimInfo]], Any], optional) – A callback invoked upon the player choosing Sims. Default is CommonFunctionUtils.noop.
sim_info (SimInfo, optional) – The SimInfo of the Sim that will appear in the dialog image. If None, it will be the active Sim. Default is None.
should_show_names (bool, optional) – If True, then the names of the Sims will display in the dialog. Default is True.
hide_row_descriptions (bool, optional) – A flag to hide the row descriptions. Default is False.
column_count (int, optional) – The number of columns to display Sims in. Default is 3.
min_selectable (int, optional) – The minimum number of Sims that must be chosen. Default is 1.
max_selectable (int, optional) – The maximum number of Sims that can be chosen. Default is 1.

Options¶

Sim Option¶

class CommonDialogSimOption(sim_info, context, on_chosen=<function CommonFunctionUtils.noop>)¶

Bases: CommonDialogOption

An option the player can choose within a dialog.

Parameters:

sim_info (SimInfo) – The Sim that will be chosen when the option is chosen.
context (CommonDialogOptionContext) – A context to customize the dialog option.
on_chosen (Callable[[SimInfo], Any], optional) – A callback invoked when the dialog option is chosen. args: (sim_info)

as_row(option_id)¶

Convert the option into a picker row.

Parameters:: option_id (int) – The index of the option.
Returns:: The option as a Picker Row
Return type:: SimPickerRow

property sim_id¶

The id of the Sim in this option.

Returns:: The id of the Sim within the option.
Return type:: int

property value¶

The value of the option.

Returns:: The value of the option.
Return type:: DialogOptionValueType

Sim Option Context¶

class CommonDialogSimOptionContext(is_enabled=True, is_selected=False)¶

Bases: CommonDialogOptionContext

A context used by CommonDialogSimOption that contains customization of the option.

Parameters:

is_enabled (bool, optional) – If True, the Sim will be selectable in the dialog. If False, the Sim will be disabled in the dialog.
is_selected (bool, optional) – If True, the Sim will already be selected in the dialog. If False, the Sim will not be selected in the dialog.