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.
- mod_identity (CommonModIdentity) – The identity of the mod creating the dialog. See
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]