Basic Dialogs

Choose Object Dialog

class CommonChooseObjectDialog(title_identifier, description_identifier, choices, title_tokens=(), description_tokens=(), per_page=25, mod_identity=None, required_tooltip=None, required_tooltip_tokens=())

Bases: sims4communitylib.dialogs.common_choose_dialog.CommonChooseDialog

Create a dialog that prompts the player to choose an object.

Note

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

def _common_testing_show_choose_object_dialog():

    def _on_chosen(choice: str, outcome: CommonChoiceOutcome):
        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),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    options = [
        ObjectPickerRow(
            option_id=1,
            name=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE),
            row_tooltip=None,
            icon=CommonIconUtils.load_checked_square_icon(),
            tag='Value 1'
        ),
        ObjectPickerRow(
            option_id=2,
            name=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 2'
        ),
        ObjectPickerRow(
            option_id=3,
            name=CommonLocalizationUtils.create_localized_string('Value 3'),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 3'
        )
    ]
    dialog = CommonChooseObjectDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        tuple(options),
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        per_page=2
    )
    dialog.show(on_chosen=_on_chosen)
Parameters:
  • title_identifier (Union[int, str, LocalizedString, CommonStringId]) – The title to display in the dialog.
  • description_identifier (Union[int, str, LocalizedString, CommonStringId]) – The description to display in the dialog.
  • choices (Iterator[ObjectPickerRow]) – The choices that can be chosen.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
  • per_page (int) – The number of rows to display per page. If the number of rows (including rows added after creation) exceeds this value, pagination will be added.
  • 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_row(row, *_, always_on_visible=False, **__)

Add a row to the dialog.

Parameters:
  • choice (ObjectPickerRow) – The row to add.
  • always_visible (bool, optional) – If set to True, the row will always appear in the dialog no matter which page. If False, the row will act as normal.
always_visible_rows

A collection of rows that will always appear in the dialog no matter which page.

Note

These rows are added to the dialog before the normal rows are added to the dialog.

Returns:A collection of rows added to the dialog that will always appear.
Return type:Tuple[ObjectPickerRow]
build_dialog(*_, **__)

Build the dialog.

Note

Override this method with any arguments you want to.

Returns:The built dialog or None if a problem occurs.
Return type:Union[UiDialogBase, None]
current_page

Retrieve the current page.

Returns:A number indicating the current page.
Return type:int
log_identifier

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

Note

This is the text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
rows

The rows to display in the dialog.

Returns:A collection of rows added to the dialog.
Return type:Tuple[BasePickerRow]
show(on_chosen=CommonFunctionUtils.noop, picker_type=UiObjectPicker.UiObjectPickerObjectPickerType.OBJECT, page=1, sim_info=None, categories=(), include_pagination=True)

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

Parameters:
  • on_chosen (Callable[[Any, CommonChoiceOutcome], optional) – A callback invoked upon the player choosing something from the list. Default is CommonFunctionUtils.noop.
  • picker_type (UiObjectPicker.UiObjectPickerObjectPickerType, optional) – The layout of the dialog. Default is UiObjectPicker.UiObjectPickerObjectPickerType.OBJECT.
  • page (int, optional) – The page to display. Ignored if there is only one page of choices. Default is 1.
  • sim_info (SimInfo, optional) – The Sim that will appear in the dialog image. The default Sim is the Active Sim. Default is None.
  • categories (Iterator[CommonDialogObjectOptionCategory], optional) – A collection of categories to display in the dialog. They will appear in a drop down above the rows. Default is an empty collection.
  • include_pagination (bool, optional) – If True, pagination will be applied. If False, no pagination will be applied. Default is True.

Choose Sim Dialog

class CommonChooseSimDialog(title_identifier, description_identifier, choices, title_tokens=(), description_tokens=(), mod_identity=None, required_tooltip=None, required_tooltip_tokens=())

Bases: sims4communitylib.dialogs.common_choose_dialog.CommonChooseDialog

Create a dialog to display a list of Sims to choose.

Note

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

def _common_testing_show_choose_sim_dialog():

    def _on_chosen(choice: Union[SimInfo, None], outcome: CommonChoiceOutcome):
        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),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    current_count = 0
    count = 25
    options = []
    for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
        if current_count >= count:
            break
        sim_id = CommonSimUtils.get_sim_id(sim_info)
        should_select = random.choice((True, False))
        is_enabled = random.choice((True, False))
        options.append(
            SimPickerRow(
                sim_id,
                select_default=should_select,
                tag=sim_info,
                is_enable=is_enabled
            )
        )
        current_count += 1

    dialog = CommonChooseSimDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        tuple(options),
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_chosen=_on_chosen, column_count=5)
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.
  • choices (Iterator[SimPickerRow]) – The choices to display in the dialog.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
  • 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_row(row, *_, **__)

Add a row to the dialog.

Parameters:row (BasePickerRow) – The row to add.
build_dialog(*_, **__)

Build the dialog.

Note

Override this method with any arguments you want to.

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 text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
rows

The rows to display in the dialog.

Returns:A collection of rows added to the dialog.
Return type:Tuple[BasePickerRow]
show(on_chosen=CommonFunctionUtils.noop, sim_info=None, should_show_names=True, hide_row_descriptions=False, column_count=3)

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

Parameters:
  • on_chosen (Callable[[Any, CommonChoiceOutcome], Any], optional) – A callback invoked upon the player choosing a Sim from the list. Cannot be None.
  • 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. Minimum: 3, Maximum: 8
Raises:

AssertionError – when something is wrong with the arguments or no rows were added to the dialog.

Choose Sims Dialog

class CommonChooseSimsDialog(title_identifier, description_identifier, choices, title_tokens=(), description_tokens=(), mod_identity=None, required_tooltip=None, required_tooltip_tokens=())

Bases: sims4communitylib.dialogs.common_choose_sim_dialog.CommonChooseSimDialog

Create a dialog that prompts the player to choose a number of Sims.

Note

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

def _common_testing_show_choose_sims_dialog():

     def _on_chosen(choice: Union[Tuple[SimInfo], None], outcome: CommonChoiceOutcome):
         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),)
     from sims4communitylib.utils.common_icon_utils import CommonIconUtils
     current_count = 0
     count = 25
     options = []
     for sim_info in CommonSimUtils.get_sim_info_for_all_sims_generator():
         if current_count >= count:
             break
         sim_id = CommonSimUtils.get_sim_id(sim_info)
         is_enabled = random.choice((True, False))
         options.append(
             SimPickerRow(
                 sim_id,
                 select_default=False,
                 tag=sim_info,
                 is_enable=is_enabled
             )
         )
         current_count += 1

     dialog = CommonChooseSimsDialog(
         CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
         CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
         tuple(options),
         title_tokens=title_tokens,
         description_tokens=description_tokens
     )
     dialog.show(
         on_chosen=_on_chosen,
         column_count=5,
         min_selectable=2,
         max_selectable=6
     )
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.
  • choices (Iterator[SimPickerRow]) – The choices to display in the dialog.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
  • 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.
build_dialog(*_, **__)

Build the dialog.

Note

Override this method with any arguments you want to.

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 text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
show(on_chosen=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_chosen (Callable[[Union[Tuple[Any], None], CommonChoiceOutcome], Any], optional) – A callback invoked upon the player submitting their chosen Sims from the list. Default is CommonFunctionUtils.noop.
  • 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.
  • 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.
Raises:
  • AssertionError – When something is wrong with the arguments or no rows were added to the dialog.
  • AttributeError – When Min or Max Selectable are invalid.

Multi-pane Choose Dialog

class CommonMultiPaneChooseDialog(mod_identity, title_identifier, description_identifier, title_tokens=(), description_tokens=())

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

Create a multi-pane dialog that prompts the player to choose from multiple dialogs and submit their choices.

Note

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

Warning

This dialog does not currently work with CommonChooseSimDialog or CommonChooseSimsDialog.

def _common_testing_show_multi_pane_choose_dialog():

    def _on_submit(choices_made: Tuple[Any], outcome: CommonChoiceOutcome) -> None:
        pass

    def _on_sub_dialog_one_chosen(choice: Any, outcome: CommonChoiceOutcome) -> None:
        pass

    def _on_sub_dialog_two_chosen(choice: Any, outcome: CommonChoiceOutcome) -> 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),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    # Create the dialog.
    dialog = CommonMultiPaneChooseDialog(
        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
    )

    sub_dialog_one_options = [
        ObjectPickerRow(
            option_id=1,
            name=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE),
            row_tooltip=None,
            icon=CommonIconUtils.load_checked_square_icon(),
            tag='Value 1'
        ),
        ObjectPickerRow(
            option_id=2,
            name=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_SOME_TEXT_FOR_TESTING),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 2'
        ),
        ObjectPickerRow(
            option_id=3,
            name=CommonLocalizationUtils.create_localized_string('Value 3'),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 3'
        )
    ]

    # Add sub dialog one.
    sub_dialog_one = CommonChooseObjectDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        tuple(sub_dialog_one_options),
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.add_sub_dialog(sub_dialog_one, on_chosen=_on_sub_dialog_one_chosen)

    # Add sub dialog two.
    sub_dialog_two_options = [
        ObjectPickerRow(
            option_id=4,
            name=CommonLocalizationUtils.create_localized_string('Value 4'),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE),
            row_tooltip=None,
            icon=CommonIconUtils.load_checked_square_icon(),
            tag='Value 4'
        ),
        ObjectPickerRow(
            option_id=5,
            name=CommonLocalizationUtils.create_localized_string('Value 5'),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 5'
        ),
        ObjectPickerRow(
            option_id=6,
            name=CommonLocalizationUtils.create_localized_string('Value 6'),
            row_description=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO),
            row_tooltip=None,
            icon=CommonIconUtils.load_arrow_navigate_into_icon(),
            tag='Value 6'
        )
    ]

    sub_dialog_two = CommonChooseObjectDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        tuple(sub_dialog_two_options),
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )

    dialog.add_sub_dialog(sub_dialog_two, on_chosen=_on_sub_dialog_two_chosen)

    # Show the dialog.
    dialog.show(on_submit=_on_submit)
Parameters:
  • title_identifier (Union[int, str, LocalizedString, CommonStringId]) – The title to display in the dialog.
  • description_identifier (Union[int, str, LocalizedString, CommonStringId]) – The description to display in the dialog.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
add_sub_dialog(sub_dialog, *dialog_arguments, **dialog_keyword_arguments)

Add a sub dialog to the dialog.

Parameters:
  • sub_dialog (CommonChooseDialog) – An instance of a choose dialog.
  • dialog_arguments (Any) – Arguments to pass to the sub dialog when building it.
  • dialog_keyword_arguments (Any) – Keyword arguments to pass to the sub dialog when building it.
build_dialog(*_, **__)

Build the dialog.

Note

Override this method with any arguments you want to.

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 text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
show(on_submit=CommonFunctionUtils.noop, sim_info=None)

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

Parameters:
  • on_submit (Callable[[Dict[int, Tuple[Any]], CommonChoiceOutcome], Any], optional) – A callback invoked upon the player submitting the dialog and the choices within it. Default is CommonFunctionUtils.noop. Each choice is mapped as follows The key is the dialog index starting at 0. The value is the choice made within that sub dialog.
  • sim_info (SimInfo, optional) – The Sim that will appear in the dialog image. The default Sim is the Active Sim. Default is None.

Input Float Dialog

class CommonInputFloatDialog(title_identifier, description_identifier, initial_value, min_value=0.0, max_value=2147483647.0, title_tokens=(), description_tokens=(), mod_identity=None)

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

Create a dialog that prompts the player to enter a float value.

Note

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

def _common_testing_show_input_float_dialog():

    def _on_chosen(choice: float, outcome: CommonChoiceOutcome):
        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),)
    from sims4communitylib.utils.common_icon_utils import CommonIconUtils
    dialog = CommonInputFloatDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        2.0,
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_submit=_on_chosen)
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.
  • initial_value (float) – The initial value that will appear in the input box.
  • min_value (float, optional) – The minimum value allowed to be entered by the player. Default is 0.0
  • max_value (float, optional) – The maximum value allowed to be entered by the player. Default is Max Int.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
log_identifier

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

Note

This is the text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
show(on_submit=CommonFunctionUtils.noop)

Show the dialog and invoke the callbacks upon the player submitting a value.

Parameters:on_submit (Callable[[Union[float, None], CommonChoiceOutcome], Any], optional) – A callback invoked upon the player submitting a value. Default is CommonFunctionUtils.noop.

Ok Dialog

class CommonOkDialog(title_identifier: Union[int, str, <sphinx.ext.autodoc.importer._MockObject object at 0x7fd9eef7d898>, sims4communitylib.enums.strings_enum.CommonStringId], description_identifier: Union[int, str, <sphinx.ext.autodoc.importer._MockObject object at 0x7fd9eef7d898>, sims4communitylib.enums.strings_enum.CommonStringId], title_tokens: Iterator[Any] = (), description_tokens: Iterator[Any] = (), ok_text_identifier: Union[int, str, <sphinx.ext.autodoc.importer._MockObject object at 0x7fd9eef7d898>, sims4communitylib.enums.strings_enum.CommonStringId] = 3648501874, ok_text_tokens: Iterator[Any] = (), mod_identity: sims4communitylib.mod_support.mod_identity.CommonModIdentity = None)

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

CommonOkDialog( title_identifier, description_identifier, title_tokens=(), description_tokens=(), ok_text_identifier=CommonStringId.OK, ok_text_tokens=(),
mod_identity=None )

Use to create an acknowledgement dialog.

Note

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

def _common_testing_show_ok_dialog():

    def _on_acknowledged(_dialog: UiDialogOk):
        if _dialog.accepted:
            pass
        else:
            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),)
    dialog = CommonOkDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        ok_text_identifier=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE, text_color=CommonLocalizedStringColor.RED)
    )
    dialog.show(on_acknowledged=_on_acknowledged)
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) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
  • ok_text_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – A decimal identifier for the Ok button text.
  • ok_text_tokens (Iterator[Any], optional) – Tokens to format into the Ok button text.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
log_identifier

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

Note

This is the text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
show(on_acknowledged=CommonFunctionUtils.noop)

Show the dialog and invoke the callback upon the player acknowledging the dialog.

Parameters:on_acknowledged (Callable[[UiDialogOk], Any], optional) – Invoked upon the player acknowledging (Hitting Ok) or closing the dialog.

Targeted Question Dialog

class CommonTargetedQuestionDialog(question_text, question_tokens=(), ok_text_identifier=CommonStringId.OK, ok_text_tokens=(), cancel_text_identifier=CommonStringId.CANCEL, cancel_text_tokens=(), mod_identity=None)

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

A Sim to Sim question dialog.

Note

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

def _common_testing_show_targeted_question_dialog():

    def _ok_chosen(_: UiDialogOkCancel):
        pass

    def _cancel_chosen(_: UiDialogOkCancel):
        pass

    # LocalizedStrings within other LocalizedStrings
    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),)
    dialog = CommonTargetedQuestionDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        question_tokens=description_tokens,
        ok_text_identifier=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE, text_color=CommonLocalizedStringColor.RED),
        cancel_text_identifier=CommonStringId.TESTING_TEST_BUTTON_TWO
    )
    dialog.show(
        CommonSimUtils.get_active_sim_info(),
        tuple(CommonSimUtils.get_sim_info_for_all_sims_generator())[0],
        on_ok_selected=_ok_chosen,
        on_cancel_selected=_cancel_chosen
    )
Parameters:
  • question_text (Union[int, str, LocalizedString, CommonStringId]) – A decimal identifier of the question text.
  • question_tokens (Iterator[Any], optional) – Tokens to format into the question text.
  • ok_text_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – A decimal identifier for the Ok text.
  • ok_text_tokens (Iterator[Any], optional) – Tokens to format into the Ok text.
  • cancel_text_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – A decimal identifier for the Cancel text.
  • cancel_text_tokens (Iterator[Any], optional) – Tokens to format into the Cancel text.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
log_identifier

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

Note

This is the text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
show(sim_info, target_sim_info, on_ok_selected=CommonFunctionUtils.noop, on_cancel_selected=CommonFunctionUtils.noop)

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

Parameters:
  • sim_info (SimInfo) – The Sim that is the source of the question.
  • target_sim_info (SimInfo) – The Sim that is the target of the question.
  • on_ok_selected (Callable[[UiDialogOkCancel], Any], optional) – Invoked upon the player clicking the Ok button in the dialog.
  • on_cancel_selected (Callable[[UiDialogOkCancel], Any], optional) – Invoked upon the player clicking the Cancel button in the dialog.

Ok/Cancel Dialog

class CommonOkCancelDialog(title_identifier, description_identifier, title_tokens=(), description_tokens=(), ok_text_identifier=CommonStringId.OK, ok_text_tokens=(), cancel_text_identifier=CommonStringId.CANCEL, cancel_text_tokens=(), mod_identity=None)

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

Use to create a prompt dialog.

Note

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

def _common_testing_show_ok_cancel_dialog():

    def _ok_chosen(_: UiDialogOkCancel):
        pass

    def _cancel_chosen(_: UiDialogOkCancel):
        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),)
    dialog = CommonOkCancelDialog(
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        ok_text_identifier=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE, text_color=CommonLocalizedStringColor.RED),
        cancel_text_identifier=CommonStringId.TESTING_TEST_BUTTON_TWO
    )
    dialog.show(on_ok_selected=_ok_chosen, on_cancel_selected=_cancel_chosen)
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) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
  • ok_text_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – A decimal identifier for the Ok text.
  • ok_text_tokens (Iterator[Any], optional) – Tokens to format into the Ok text.
  • cancel_text_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – A decimal identifier for the Cancel text.
  • cancel_text_tokens (Iterator[Any], optional) – Tokens to format into the Cancel text.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
log_identifier

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

Note

This is the text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
show(on_ok_selected=CommonFunctionUtils.noop, on_cancel_selected=CommonFunctionUtils.noop)

Show the dialog and invoke the callbacks upon the player selecting an option.

Parameters:
  • on_ok_selected (Callable[[UiDialogOkCancel], Any], optional) – Invoked upon the player selecting Ok in the dialog.
  • on_cancel_selected (Callable[[UiDialogOkCancel], Any], optional) – Invoked upon the player selecting Cancel in the dialog.

Dialog

class CommonDialog(title_identifier, description_identifier, title_tokens=(), description_tokens=(), mod_identity=None)

Bases: sims4communitylib.logging.has_log.HasLog

An inheritable class for creating a dialog.

Note

It is recommended to utilize one of the ready made dialogs, instead of creating a custom CommonDialog

Parameters:
  • title_identifier (Union[int, str, LocalizedString, CommonStringId]) – The title to display in the dialog.
  • description_identifier (Union[int, str, LocalizedString, CommonStringId]) – The description to display in the dialog.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title. Default is an empty collection.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description. Default is an empty collection.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information. Default is None.
build_dialog(*_, **__)

Build the dialog.

Note

Override this method with any arguments you want to.

Returns:The built dialog or None if a problem occurs.
Return type:Union[UiDialogBase, None]
mod_identity

The identity of the mod that owns this property

Warning

Override this property with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:An instance of CommonModIdentity
Return type:CommonModIdentity
Raises:NotImplementedError – Thrown when the property is not implemented.
show(*_, **__)

Display the dialog to the player.

Note

Override this method with any arguments you want to.

Choose Dialog

class CommonChooseDialog(title_identifier, description_identifier, rows, title_tokens=(), description_tokens=(), mod_identity=None, required_tooltip=None, required_tooltip_tokens=())

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog, abc.ABC

A dialog that prompts the player to choose something.

Parameters:
  • title_identifier (Union[int, str, LocalizedString, CommonStringId]) – The title to display in the dialog.
  • description_identifier (Union[int, str, LocalizedString, CommonStringId]) – The description to display in the dialog.
  • rows (Iterator[BasePickerRow]) – The rows to display in the dialog.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title. Default is an empty collection.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description. Default is an empty collection.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information. Default is None.
  • 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_row(row, *_, **__)

Add a row to the dialog.

Parameters:row (BasePickerRow) – The row to add.
required_tooltip

A tooltip that will display when the dialog requires at least one choice and a choice has not been made.

Returns:A localized string or None if no value provided.
Return type:Union[LocalizedString, None]
rows

The rows to display in the dialog.

Returns:A collection of rows added to the dialog.
Return type:Tuple[BasePickerRow]