Basic Dialogs

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]

Choose Object

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. Default is False.
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 message identifier 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, sort_rows=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.
  • sort_rows (bool, optional) – If True, rows will be sorted by display name, with the selected rows on top. If False, rows will not be sorted. Default is False.

Choose Outfit

Choose Response

class CommonChooseResponseDialog(mod_identity, title_identifier, description_identifier, responses, title_tokens=(), description_tokens=(), next_button_text=CommonStringId.NEXT, previous_button_text=CommonStringId.PREVIOUS)

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

Create a dialog that prompts the player to choose a response.

Note

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

def _common_testing_show_choose_response_dialog():

    def _on_chosen(choice: str, outcome: CommonChoiceOutcome):
        pass

    responses: Tuple[CommonUiDialogResponse] = (
        CommonUiDialogResponse(
            1,
            'Value 1',
            text=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_ONE)
        ),
        CommonUiDialogResponse(
            2,
            'Value 2',
            text=CommonLocalizationUtils.create_localized_string(CommonStringId.TESTING_TEST_BUTTON_TWO)
        ),
        CommonUiDialogResponse(
            3,
            'Value 3',
            text=CommonLocalizationUtils.create_localized_string('Test Button 3')
        )
    )
    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),)

    active_sim_info = CommonSimUtils.get_active_sim_info()
    dialog = CommonChooseResponseDialog(
        ModInfo.get_identity(),
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        responses,
        title_tokens=title_tokens,
        description_tokens=description_tokens,
        per_page=2
    )
    dialog.show(
        on_chosen=_on_chosen,
        sim_info=active_sim_info,
        include_previous_button=False
    )
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.
  • responses (Iterator[CommonUiDialogResponse]) – The choices that can be chosen.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title. Default is no tokens.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description. Default is no tokens.
  • next_button_text (Union[int, str, LocalizedString, CommonStringId], optional) – The text the Next button will display, if the Next button is added. Default is Next.
  • previous_button_text (Union[int, str, LocalizedString, CommonStringId], optional) – The text the Previous button will display, if the Previous button is added. Default is Previous.
  • per_page (int, optional) – The number of responses to display per page of the dialog. Default is 10.
  • mod_identity (CommonModIdentity, optional) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
add_response(response, *_, always_visible=False, **__)

Add a response to the dialog.

Parameters:
  • response (CommonUiDialogResponse) – The response to add.
  • always_visible (bool, optional) – If set to True, the response will always appear in the dialog no matter which page. If False, the response will act as normal. Default is False.
always_visible_responses

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

Note

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

Returns:A collection of responses added to the dialog that will always appear.
Return type:Tuple[CommonUiDialogResponse]
build_dialog(sim_info=None, target_sim_info=None, on_chosen=CommonFunctionUtils.noop, on_previous=CommonFunctionUtils.noop, dialog_options=0, include_previous_button=True, include_pagination=True, page=1)

Build the dialog.

Parameters:
  • sim_info (SimInfo, optional) – A Sim that will appear in the top left image when the dialog is shown. If set to None, the active Sim will be used. 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.
  • on_chosen (Callable[[Any, CommonChoiceOutcome], None], optional) – A callback performed when a choice is made. Default is no operation.
  • on_previous (Callable[[], None], optional) – A callback performed when the Previous response is chosen. Default is no operation.
  • dialog_options (UiDialogOption, optional) – Display options for the dialog, such as hiding the close button. Default is no display options.
  • include_previous_button (bool, optional) – If True, the Previous button will be appended to the end of the dialog. Default is True.
  • include_pagination (bool, optional) – If True, pagination will be applied. If False, no pagination will be applied. Default is True. The include_previous_button argument will override this setting!
  • 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[CommonUiResponseDialog, None]

current_page

The current page shown of the dialog.

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
responses

The responses to display in the dialog.

show(sim_info=None, target_sim_info=None, on_chosen=CommonFunctionUtils.noop, on_previous=CommonFunctionUtils.noop, dialog_options=0, include_previous_button=True, include_pagination=True, page=1)

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

Parameters:
  • sim_info (SimInfo, optional) – 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.
  • on_chosen (Callable[[Any, CommonChoiceOutcome], optional) – A callback invoked upon the player choosing something from the list. Default is CommonFunctionUtils.noop.
  • on_previous (Callable[[], None], optional) – A callback performed when the previous response is chosen. Default is no operation.
  • dialog_options (UiDialogOption, optional) – Options to apply to the dialog, such as removing the close button. Default is no options.
  • include_previous_button (bool, optional) – If True, the Previous button will be appended to the end of the dialog, if False, the Previous button will not be shown unless the current page is greater than 1. Default is True.
  • include_pagination (bool, optional) – If True, pagination will be applied. If False, no pagination will be applied. Default is True. The include_previous_button argument will override this setting!
  • page (int, optional) – The page to show the dialog on. Default is the first page.

Choose Sim

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 message identifier 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

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 message identifier 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.

Input Float

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_submit(input_value: 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_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.
  • 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 message identifier that will appear when logging messages.

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

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

Parameters:
  • sim_info (SimInfo, optional) – The Sim that owns the dialog. Set to None to use the Active Sim. Default is None.
  • on_submit (Callable[[Union[float, None], CommonChoiceOutcome], Any], optional) – A callback invoked upon the player submitting a value. Default is CommonFunctionUtils.noop.

Input Text

class CommonInputTextDialog(mod_identity, title_identifier, description_identifier, initial_value, title_tokens=(), description_tokens=())

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

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

Note

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

def _common_testing_show_input_text_dialog():

    def _on_submit(input_value: 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
    dialog = CommonInputTextDialog(
        ModInfo.get_identity(),
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        'default_text',
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_submit=_on_submit)
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.
  • initial_value (str) – The initial value that will appear in the input box.
  • title_tokens (Iterator[Any], optional) – Tokens to format into the title.
  • description_tokens (Iterator[Any], optional) – Tokens to format into the description.
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, on_submit=CommonFunctionUtils.noop)

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

Parameters:
  • sim_info (SimInfo, optional) – The Sim that owns the dialog. Set to None to use the Active Sim. Default is None.
  • on_submit (Callable[[Union[str, None], CommonChoiceOutcome], Any], optional) – A callback invoked upon the player submitting a value. Default is CommonFunctionUtils.noop.

Input Multi Text

class CommonInputMultiTextDialog(mod_identity, title_identifier, description_identifier, input_fields, title_tokens=(), description_tokens=())

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

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

Note

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

def _common_testing_show_input_text_dialog():

    def _on_submit(input_value: 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
    dialog = CommonInputMultiTextDialog(
        ModInfo.get_identity(),
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
        (
          CommonInputTextField('first_input_field', 'initial_text', title='First Input', default_text='default text stuff'),
          CommonInputTextField('input_box_two', 'initial_text_two', default_text=CommonStringId.TESTING_TEST_TEXT_NO_TOKENS),
          CommonInputTextField('input_box_three', 'initial_text_three', title='Numbers Only', character_restriction=CommonCharacterRestriction.NUMBERS_ONLY)
        ),
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(on_submit=_on_submit)
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.
  • input_fields (Iterator[CommonInputTextField]) – An iterator of input fields 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.
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, on_submit=CommonFunctionUtils.noop)

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

Parameters:
  • sim_info (SimInfo, optional) – The Sim that owns the dialog. Set to None to use the Active Sim. Default is None.
  • on_submit (Callable[[Union[str, None], CommonChoiceOutcome], Any], optional) – A callback invoked upon the player submitting a value. Default is CommonFunctionUtils.noop.

Input Text Field

class CommonInputTextField(identifier, initial_value, title=None, character_restriction=CommonCharacterRestriction.NONE, default_text=None)

Bases: object

A field intended for use with an input text dialog. It allows entering of text.

Parameters:
  • identifier (str) – The identifier of the input.
  • initial_value (str) – The initial value of the text input.
  • title (Union[int, str, LocalizedString, CommonStringId, CommonLocalizedStringSeparator], optional) – A title to display above the input. Default is None.
  • character_restriction (CommonCharacterRestriction, optional) – A character restriction to enforce what can be entered or not. Default is NONE.
  • default_text (Union[int, str, LocalizedString, CommonStringId, CommonLocalizedStringSeparator], optional) – The default text shown when nothing is entered into the field. Default is None.
character_restriction

A character restriction to enforce what can be entered or not.

default_text

The default text that will show in the field when nothing is entered.

identifier

The identifier of the input.

initial_value

The initial value the field will have entered.

log_identifier
title

The title to display above the text field.

Input Integer

class CommonInputIntegerDialog(title_identifier, description_identifier, initial_value, min_value=0, max_value=2147483647, title_tokens=(), description_tokens=(), mod_identity=None)

Bases: sims4communitylib.dialogs.common_dialog.CommonDialog

Create a dialog that prompts the player to enter an integer value.

Note

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

def _common_testing_show_input_integer_dialog():

    def _on_submit(input_value: integer, 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,
        title_tokens=title_tokens,
        description_tokens=description_tokens
    )
    dialog.show(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.
  • initial_value (int) – The initial value that will appear in the input box.
  • min_value (int, optional) – The minimum value allowed to be entered by the player. Default is 0.0
  • max_value (int, 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 message identifier that will appear when logging messages.

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

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

Parameters:
  • sim_info (SimInfo, optional) – The Sim that owns the dialog. Set to None to use the Active Sim. Default is None.
  • on_submit (Callable[[Union[int, None], CommonChoiceOutcome], Any], optional) – A callback invoked upon the player submitting a value. Default is CommonFunctionUtils.noop.

Multi-pane Choose

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 message identifier 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.

Ok Dialog

class CommonOkDialog(title_identifier: Union[int, str, <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd286ccb90>, sims4communitylib.enums.strings_enum.CommonStringId], description_identifier: Union[int, str, <sphinx.ext.autodoc.importer._MockObject object at 0x7fcd286ccb90>, 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 0x7fcd286ccb90>, 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 message identifier 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.

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 message identifier 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.

Purchase Objects

class CommonPurchaseObjectsDialog(mod_identity, title_identifier, description_identifier, purchasable_object_rows, title_tokens=(), description_tokens=(), required_tooltip=None, required_tooltip_tokens=())

Bases: sims4communitylib.dialogs.common_choose_dialog.CommonChooseDialog

Create a dialog that allows the player to purchase some objects.

Note

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

def _common_testing_show_purchase_objects_dialog():
    def _on_chosen(choices: Any, outcome: CommonChoiceOutcome):
        output('Chose {} with result: {}.'.format(pformat(choices), pformat(outcome)))

# 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),)
show_discount = True
from sims4communitylib.utils.common_icon_utils import CommonIconUtils
active_sim_info = CommonSimUtils.get_active_sim_info()
obj_id = 20359
obj_definition = CommonObjectUtils.get_object_definition(obj_id)
tags = obj_definition.build_buy_tags
options = [
    PurchasePickerRow(
        def_id=obj_definition.id,
        num_owned=CommonSimInventoryUtils.get_count_of_object_in_inventory(active_sim_info, obj_id),
        tags=obj_definition.build_buy_tags,
        num_available=2000,
        custom_price=50,
        objects=tuple(),
        show_discount=show_discount,
        icon_info_data_override=None,  # Should be an instance of IconInfoData
        is_enable=True,
        row_tooltip=None,
        row_description=None
    ),
]
categories = list()
for tag in tags:
    tag_name = CommonGameTag.value_to_name.get(tag, None)
    if tag_name is None:
        continue
    categories.append(CommonDialogObjectOptionCategory(tag, obj_definition.icon, category_name=tag_name))
dialog = CommonPurchaseObjectsDialog(
    ModInfo.get_identity(),
    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, categories=categories)
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.
  • purchasable_objects (Iterator[PurchasePickerRow]) – The objects that may be purchased
  • 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:choice (PurchasePickerRow) – 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]
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, target_sim_info_to_receive_objects=None, categories=(), object_delivery_method=CommonObjectDeliveryMethod.INVENTORY)

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.
  • target_sim_info_to_receive_objects (SimInfo, optional) – The Sim that will appear in the dialog image. They will also be the receiver of purchased objects if object_delivery_method is set to INVENTORY. 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.
  • object_delivery_method (CommonObjectDeliveryMethod, optional) – The method of delivery for purchased objects. If set to INVENTORY, objects that are purchased will be immediately available within the inventory of the specified Sim or the Active Sim if no Sim is specified. If set to MAIL, objects that are purchased will be delivered via the Mail Man. They may also appear within the Household Inventory upon the mail being delivered. Default is INVENTORY.

Targeted Question

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 message identifier 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.