Option Dialogs

Choose Option Dialog

class CommonChooseOptionDialog(internal_dialog, on_close=CommonFunctionUtils.noop)

Bases: sims4communitylib.dialogs.option_dialogs.common_option_dialog.CommonOptionDialog

A dialog that displays a list of options.

Warning

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

Parameters:
  • internal_dialog (CommonChooseDialog) – The dialog this option dialog wraps.
  • on_close (Callable[[], None], optional) – A callback invoked upon the dialog closing.
add_option(option)

Add an option to the dialog.

Parameters:option (CommonDialogOption) – The option to add.
build_dialog(*_, **__)

Build the dialog.

Note

Override this function to provide your own arguments.

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

Determine if the dialog has selectable options.

Returns:True, if the dialog has any options in it. False, if not.
Return type:bool
option_count

The number of options within the dialog.

Returns:The number of options within the dialog.
Return type:int
show(*_, **__)

Show the dialog.

Note

Override this function to provide your own arguments.

Choose Options Dialog

class CommonChooseOptionsDialog(internal_dialog, on_close=CommonFunctionUtils.noop)

Bases: sims4communitylib.dialogs.option_dialogs.common_choose_option_dialog.CommonChooseOptionDialog

A dialog that displays a list of options and prompts to select multiple items.

Warning

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

Parameters:
  • internal_dialog (CommonChooseDialog) – The dialog this option dialog wraps.
  • on_close (Callable[[], None], optional) – A callback invoked upon the dialog closing.
build_dialog(*_, on_submit=CommonFunctionUtils.noop, min_selectable=1, max_selectable=1, allow_no_selection=False, **__)

Build the dialog.

Note

Override this function to provide your own arguments.

Parameters:
  • on_submit (Callable[[Tuple[DialogOptionValueType]], Any], optional) – When the dialog is submitted, this callback will be invoked with the chosen options.
  • min_selectable (int, optional) – The minimum number of options that can be chosen.
  • max_selectable (int, optional) – The maximum number of options that can be chosen.
  • allow_no_selection (bool, optional) – If True, the player may select no options. If False, the dialog will close with no options selected. Default is False.
Returns:

The built dialog or None if a problem occurs.

Return type:

Union[UiDialogBase, None]

show(*_, on_submit=CommonFunctionUtils.noop, min_selectable=1, max_selectable=1, allow_no_selection=False, **__)

Show the dialog.

Note

Override this function to provide your own arguments.

Parameters:
  • on_submit (Callable[[Tuple[DialogOptionValueType]], Any], optional) – When the dialog is submitted, this callback will be invoked with the chosen options.
  • min_selectable (int, optional) – The minimum number of options that can be chosen.
  • max_selectable (int, optional) – The maximum number of options that can be chosen.
  • allow_no_selection (bool, optional) – If True, the player may select no options. If False, the dialog will close with no options selected. Default is False.

Multi-pane Choose Options Dialog

class CommonMultiPaneChooseOptionDialog(mod_identity, title_identifier, description_identifier, title_tokens=(), description_tokens=(), on_close=CommonFunctionUtils.noop)

Bases: sims4communitylib.dialogs.option_dialogs.common_option_dialog.CommonOptionDialog

A container for multiple choose option dialogs.

Note

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

Warning

This dialog does not currently work with CommonChooseSimOptionDialog or CommonChooseSimsOptionDialog.

Example usage:
def _on_option_chosen_in_dialog_one(option_identifier: str, choice: str):
    pass

def _on_option_chosen_in_dialog_two(option_identifier: str, choice: str):
    pass

def _on_submit(chosen_options: Dict[int, Any]):
    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
    ),
)

sub_dialog_one = CommonChooseObjectOptionDialog(
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    per_page=2
)

sub_dialog_one.add_option(
    CommonDialogObjectOption(
        'Option 1',
        'Value 1',
        CommonDialogOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            CommonStringId.TESTING_TEST_BUTTON_ONE,
            icon=CommonIconUtils.load_checked_square_icon()
        ),
        on_chosen=_on_option_chosen_in_dialog_one
    )
)

sub_dialog_one.add_option(
    CommonDialogObjectOption(
        'Option 2',
        'Value 2',
        CommonDialogOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            CommonStringId.TESTING_TEST_BUTTON_TWO,
            icon=CommonIconUtils.load_arrow_navigate_into_icon()
        ),
        on_chosen=_on_option_chosen_in_dialog_one
    )
)

sub_dialog_one.add_option(
    CommonDialogObjectOption(
        'Option 3',
        'Value 3',
        CommonDialogOptionContext(
            CommonLocalizationUtils.create_localized_string('Value 3'),
            CommonStringId.TESTING_TEST_BUTTON_TWO,
            icon=CommonIconUtils.load_arrow_navigate_into_icon()
        ),
        on_chosen=_on_option_chosen_in_dialog_one
    )
)

sub_dialog_two = CommonChooseObjectOptionDialog(
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    CommonStringId.TESTING_TEST_TEXT_WITH_STRING_TOKEN,
    title_tokens=title_tokens,
    description_tokens=description_tokens,
    per_page=2
)

sub_dialog_two.add_option(
    CommonDialogObjectOption(
        'Option 4',
        'Value 4',
        CommonDialogOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            CommonStringId.TESTING_TEST_BUTTON_ONE,
            icon=CommonIconUtils.load_checked_square_icon()
        ),
        on_chosen=_on_option_chosen_in_dialog_two
    )
)

sub_dialog_two.add_option(
    CommonDialogObjectOption(
        'Option 5',
        'Value 5',
        CommonDialogOptionContext(
            CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
            CommonStringId.TESTING_TEST_BUTTON_TWO,
            icon=CommonIconUtils.load_arrow_navigate_into_icon()
        ),
        on_chosen=_on_option_chosen_in_dialog_two
    )
)

sub_dialog_two.add_option(
    CommonDialogObjectOption(
        'Option 6',
        'Value 6',
        CommonDialogOptionContext(
            CommonLocalizationUtils.create_localized_string('Value 3'),
            CommonStringId.TESTING_TEST_BUTTON_TWO,
            icon=CommonIconUtils.load_arrow_navigate_into_icon()
        ),
        on_chosen=_on_option_chosen_in_dialog_two
    )
)

option_dialog = CommonMultiPaneChooseOptionDialog(
    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
)

option_dialog.add_sub_dialog(sub_dialog_one)
option_dialog.add_sub_dialog(sub_dialog_two)

option_dialog.show(
    on_submit=_on_submit,
    sim_info=CommonSimUtils.get_active_sim_info()
)
Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
  • title_identifier (Union[int, str, LocalizedString, CommonStringId]) – A decimal identifier of the title text.
  • description_identifier (Union[int, str, LocalizedString, CommonStringId]) – A decimal identifier of the description text.
  • title_tokens (Iterator[Any], optional) – An iterator of Tokens to format into the title. Default is an empty collection.
  • description_tokens (Iterator[Any], optional) – An iterator of Tokens to format into the description. Default is an empty collection.
  • on_close (Callable[[], None], optional) – A callback invoked upon the dialog closing. Default is CommonFunctionUtils.noop.
add_sub_dialog(sub_dialog, *dialog_arguments, **dialog_keyword_arguments)

Add a sub dialog.

Parameters:
  • sub_dialog (CommonChooseOptionDialog) – An instance of a choose option dialog.
  • dialog_arguments (Any, optional) – Arguments to pass to the sub dialog when building it.
  • dialog_keyword_arguments (Any, optional) – Keyword arguments to pass to the sub dialog when building it.
build_dialog(on_submit=CommonFunctionUtils.noop, sim_info=None)

Build the dialog and invoke the callbacks upon the player submitting their selections.

Parameters:
  • on_submit (Callable[[Dict[int, Tuple[Any]]], 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. 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.
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 submitting their selections.

Parameters:
  • on_submit (Callable[[Dict[int, Tuple[Any]]], Any], optional) – A callback invoked upon the player submitting the dialog and the choices within it. Each choice is mapped as follows: The key is the index of the dialog a value belongs to, starting at 0. The value is the choice made within that dialog. 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.

Options

Dialog Option

class CommonDialogOption(value, context, on_chosen=CommonFunctionUtils.noop)

Bases: object

An option the player can choose within a dialog.

Parameters:
  • value (DialogOptionValueType) – The value of the option.
  • context (CommonDialogOptionContext) – A context to customize the dialog option.
  • on_chosen (Callable[[DialogOptionValueType], Any], optional) – A callback invoked when the dialog option is chosen.
as_row(option_id)

Convert the option into a picker row.

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

Choose the option.

Returns:The result of choosing the option.
Return type:Any
context

The context of the option.

Returns:The context of the option.
Return type:CommonDialogOptionContext
description

The description of the option.

Returns:The description of the option.
Return type:LocalizedString
hashed_tag_list

Same as tag_list, but the values are hashed.

Returns:Same as tag_list, but the values are hashed.
Return type:Tuple[str]
icon

The icon of the option.

Returns:The icon of the option.
Return type:Any
on_chosen

The action to perform upon choosing this option.

Returns:The action to perform upon choosing this option.
Return type:Callable[[DialogOptionValueType], Any]
tag_list

A collection of tags used to filter the option.

Returns:A collection of tags used to filter the option.
Return type:Tuple[str]
title

The title of the option.

Returns:The title of the option.
Return type:LocalizedString
tooltip

The tooltip displayed to the player on hover.

Returns:The tooltip displayed when hovering the option or None if no tooltip specified.
Return type:Union[CommonLocalizationUtils.LocalizedTooltip, None]
value

The value of the option.

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

Dialog Option Context

class CommonDialogOptionContext(title_identifier, description_identifier, description_tokens=(), tooltip_text_identifier=None, tooltip_tokens=(), icon=None, is_enabled=True, is_selected=False, tag_list=())

Bases: object

A context used by CommonDialogOption that provides customization of options.

Parameters:
  • title_identifier (Union[int, str, LocalizedString, CommonStringId]) – The title of the option.
  • description_identifier (Union[int, str, LocalizedString, CommonStringId]) – The description of the option.
  • title_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the title.
  • description_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the description.
  • tooltip_text_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – Text that will be displayed upon hovering the option.
  • tooltip_tokens (Tuple[Any], optional) – An iterator of Tokens that will be formatted into the tooltip text.
  • icon (Any, optional) – The icon to display for the option.
  • is_enabled (bool, optional) – If True, the dialog option will be selectable in the dialog. If False, the dialog option will be disabled in the dialog.
  • is_selected (bool, optional) – If True, the dialog option will already be selected in the dialog. If False, the dialog option will not be selected in the dialog.
description

A description of what the dialog option does.

Returns:A description of what the dialog option does.
Return type:LocalizedString
hashed_tag_list

Same as tag_list, but the values are hashed.

Returns:Same as tag_list, but the values are hashed.
Return type:Tuple[str]
icon

The icon displayed for this dialog option.

Returns:The icon displayed for this dialog option.
Return type:Any
is_enabled

Determine if the dialog option is enabled.

Returns:True, if the dialog option is enabled. False, if not.
Return type:bool
is_selected

Determine if the dialog option is selected.

Returns:True, if the dialog option is selected. False, if not.
Return type:bool
tag_list

A collection of tags used to filter the option.

Returns:A collection of tags used to filter the option.
Return type:Tuple[str]
title

The title of the dialog option.

Returns:The title of the dialog option.
Return type:LocalizedString
tooltip

The tooltip displayed to the player on hover.

Returns:The tooltip displayed to the player on hover or None if no tooltip was specified.
Return type:Union[CommonLocalizationUtils.LocalizedTooltip, None]