Sims

Choose Sim Option Dialog

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

Bases: sims4communitylib.dialogs.option_dialogs.common_choose_option_dialog.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]
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=CommonFunctionUtils.noop, mod_identity=None, required_tooltip=None, required_tooltip_tokens=())

Bases: sims4communitylib.dialogs.option_dialogs.common_choose_options_dialog.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=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=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=CommonFunctionUtils.noop)

Bases: sims4communitylib.dialogs.option_dialogs.options.common_dialog_option.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
sim_id

The id of the Sim in this option.

Returns:The id of the Sim within the option.
Return type:int
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: sims4communitylib.dialogs.option_dialogs.options.common_dialog_option_context.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.