Objects¶

Choose Object Option Dialog¶

class CommonChooseObjectOptionDialog(title_identifier, description_identifier, title_tokens=(), description_tokens=(), on_close=CommonFunctionUtils.noop, mod_identity=None, per_page=25, required_tooltip=None, required_tooltip_tokens=())¶

Bases: sims4communitylib.dialogs.option_dialogs.common_choose_option_dialog.CommonChooseOptionDialog

A dialog that displays a list of options.

Note

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

Example usage:

def _on_option_chosen(option_identifier: DialogOptionIdentifierType, choice: DialogOptionValueType):
    pass

# LocalizedStrings within other LocalizedStrings
title_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_SOME_TEXT_FOR_TESTING,
        text_color=CommonLocalizedStringColor.GREEN
    ),
)
description_tokens = (
    CommonLocalizationUtils.create_localized_string(
        CommonStringId.TESTING_TEST_TEXT_WITH_SIM_FIRST_AND_LAST_NAME,
        tokens=(CommonSimUtils.get_active_sim_info(),),
        text_color=CommonLocalizedStringColor.BLUE
    ),
)

# Create the dialog and only showing 2 options per page.
option_dialog = 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
)

from sims4communitylib.utils.common_icon_utils import CommonIconUtils

# We add the options, in this case we have three options.
option_dialog.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
    )
)

option_dialog.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
    )
)

option_dialog.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
    )
)

option_dialog.show(
    sim_info=CommonSimUtils.get_active_sim_info()
)

Parameters:

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

add_option(option)¶

Add an option to the dialog.

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

build_dialog(picker_type=UiObjectPicker.UiObjectPickerObjectPickerType.OBJECT, page=1, sim_info=None, categories=(), sort_options=False)¶

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

Parameters:	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 SimInfo of 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 do display in the dialog. Default is an empty collection. sort_options (bool, optional) – If True, options will be sorted by display name, with the selected options on top. If False, options will not be sorted. Default is False.
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

show(picker_type=UiObjectPicker.UiObjectPickerObjectPickerType.OBJECT, page=1, sim_info=None, categories=())¶

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

Parameters:

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 SimInfo of 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 do display in the dialog. Default is an empty collection.
sort_options (bool, optional) – If True, options will be sorted by display name, with the selected options on top. If False, options will not be sorted. Default is False.

Object Option Category¶

class CommonDialogObjectOptionCategory(object_category, icon, category_name=None)¶

Bases: object

An option category.

Parameters:	object_category (str) – The category of the option. icon (int) – The decimal identifier of the icon for the category. category_name (LocalizedString) – The name of the category. Default is the object_category value.

Options¶

Action Option¶

class CommonDialogActionOption(context, on_chosen=CommonFunctionUtils.noop, always_visible=False)¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_select_option.CommonDialogSelectOption

An option that invokes a callback upon being chosen.

Parameters:	context (CommonDialogOptionContext) – A context to customize the dialog option. on_chosen (Callable[.., Any], optional) – A callback invoked when the dialog option is chosen. always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.

Open Dialog Option¶

class CommonDialogOpenDialogOption(create_dialog_callback, context, always_visible=False)¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_object_option.CommonDialogObjectOption

An option that branches into other options.

Parameters:

create_dialog_callback (Callable[.., CommonOptionDialog]) – A callback invoked when the dialog option is chosen. It should open a dialog.
context (CommonDialogOptionContext) – A context to customize the dialog option.
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.

icon¶

The icon of the option.

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

Input Float Option¶

class CommonDialogInputFloatOption(option_identifier, initial_value, context, min_value=0.0, max_value=2147483647.0, on_chosen=CommonFunctionUtils.noop, always_visible=False, dialog_description_identifier=None, dialog_description_tokens=())¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_object_option.CommonDialogObjectOption

An option to open a dialog to input a float value.

Parameters:

option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.
initial_value (float) – The value the option will have initially
context (CommonDialogOptionContext) – A context to customize the dialog option.
min_value (float, optional) – The minimum value allowed to be entered.
max_value (float, optional) – The maximum value allowed to be entered.
on_chosen (Callable[[DialogOptionIdentifierType, float, CommonChoiceOutcome], None], optional) – A callback invoked when the dialog option is chosen. args: (option_identifier, entered value, outcome)
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.
dialog_description_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – The description that will display in the input dialog separately from the option. If not provided the description from the provided context will be used instead.
dialog_description_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the dialog description.

icon¶

The icon of the option.

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

Input Integer Option¶

class CommonDialogInputIntegerOption(mod_identity, option_identifier, initial_value, context, min_value=0, max_value=2147483647, on_chosen=CommonFunctionUtils.noop, always_visible=False, dialog_description_identifier=None, dialog_description_tokens=())¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_object_option.CommonDialogObjectOption

An option to open a dialog to input an integer value.

Parameters:

mod_identity (CommonModIdentity) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.
initial_value (int) – The value the option will have initially
context (CommonDialogOptionContext) – A context to customize the dialog option.
min_value (int, optional) – The minimum value allowed to be entered.
max_value (int, optional) – The maximum value allowed to be entered.
on_chosen (Callable[[DialogOptionIdentifierType, int, CommonChoiceOutcome], None], optional) – A callback invoked when the dialog option is chosen. args: (option_identifier, entered value, outcome)
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.
dialog_description_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – The description that will display in the input dialog separately from the option. If not provided the description from the provided context will be used instead.
dialog_description_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the dialog description.

icon¶

The icon of the option.

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

Input Text Option¶

class CommonDialogInputTextOption(mod_identity, option_identifier, initial_value, context, on_chosen=CommonFunctionUtils.noop, always_visible=False, dialog_description_identifier=None, dialog_description_tokens=())¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_object_option.CommonDialogObjectOption

An option to open a dialog to input a text value.

Parameters:

mod_identity (CommonModIdentity) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.
initial_value (str) – The value the option will have initially
context (CommonDialogOptionContext) – A context to customize the dialog option.
on_chosen (Callable[[DialogOptionIdentifierType, int, CommonChoiceOutcome], None], optional) – A callback invoked when the dialog option is chosen. args: (option_identifier, entered value, outcome)
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.
dialog_description_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – The description that will display in the input dialog separately from the option. If not provided the description from the provided context will be used instead.
dialog_description_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the dialog description.

icon¶

The icon of the option.

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

Input Multi Text Option¶

class CommonDialogInputMultiTextOption(mod_identity, option_identifier, input_fields, context, on_chosen=CommonFunctionUtils.noop, always_visible=False, dialog_description_identifier=None, dialog_description_tokens=())¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_object_option.CommonDialogObjectOption

An option to open a dialog to input a text value.

Parameters:

mod_identity (CommonModIdentity) – The identity of the mod creating the dialog. See CommonModIdentity for more information.
option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.
input_fields (Iterator[CommonInputTextField]) – An iterator of input fields to display in the dialog when the option is chosen.
context (CommonDialogOptionContext) – A context to customize the dialog option.
on_chosen (Callable[[DialogOptionIdentifierType, int, CommonChoiceOutcome], None], optional) – A callback invoked when the dialog option is chosen. args: (option_identifier, entered value, outcome)
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.
dialog_description_identifier (Union[int, str, LocalizedString, CommonStringId], optional) – The description that will display in the input dialog separately from the option. If not provided the description from the provided context will be used instead.
dialog_description_tokens (Iterator[Any], optional) – An iterator of Tokens that will be formatted into the dialog description.

icon¶

The icon of the option.

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

Object Option¶

class CommonDialogObjectOption(option_identifier, value, context, on_chosen=CommonFunctionUtils.noop)¶

Bases: sims4communitylib.dialogs.option_dialogs.options.common_dialog_option.CommonDialogOption

An option the player can choose within a dialog.

Parameters:

option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.
value (DialogOptionValueType) – The value of the option.
context (CommonDialogOptionContext) – A context to customize the dialog option.
on_chosen (Callable[[DialogOptionIdentifierType, DialogOptionValueType], None], optional) – A callback invoked when the dialog option is chosen. The values are as follows: (option_identifier, value)
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.

always_visible¶

Determine if the option will always be visible.

Returns:	If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal.
Return type:	bool

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:	ObjectPickerRow

option_identifier¶

Used to identify the option.

Returns:	The identity of the option.
Return type:	str

value¶

The value of the option.

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

Select Option¶

class CommonDialogSelectOption(option_identifier, value, context, on_chosen=CommonFunctionUtils.noop, always_visible=False)¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_object_option.CommonDialogObjectOption

An option that invokes a callback, passing in its value.

Parameters:

option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.
value (DialogOptionValueType) – The value of the option.
context (CommonDialogOptionContext) – A context to customize the dialog option.
on_chosen (Callable[[DialogOptionIdentifierType, DialogOptionValueType], None], optional) – A callback invoked when the dialog option is chosen.
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.

icon¶

The icon of the option.

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

Toggle Option¶

class CommonDialogToggleOption(option_identifier, value, context, on_chosen=CommonFunctionUtils.noop, always_visible=False)¶

Bases: sims4communitylib.dialogs.option_dialogs.options.objects.common_dialog_object_option.CommonDialogObjectOption

An option with two states, on or off.

Parameters:

option_identifier (DialogOptionIdentifierType) – A string that identifies the option from other options.
value (bool) – The value of the option.
context (CommonDialogOptionContext) – A context to customize the dialog option.
on_chosen (Callable[[DialogOptionIdentifierType, bool], None], optional) – A callback invoked when the dialog option is chosen. The values are as follows: (option_identifier, not value)
always_visible (bool, optional) – If set to True, the option will always appear in the dialog no matter which page. If False, the option will act as normal. Default is False.

choose()¶

Choose the option.

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

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[[bool], Any]

value¶

The value of the option.

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