Web Analytics Made Easy - Statcounter
Skip to content

User Settings API - Function Interface

UserSettings documentation

You have a couple of ways to access User Settings if your information is stored in JSON format. If you're using the INI format, then you must use the UserSettings object.

These are particularly useful directly in layouts, allowing you to you can easily set default values.

user_settings

Returns the current settings dictionary. If you've not setup the filename for the settings, a default one will be used and then read.

user_settings()

Parameter Descriptions

Name Type Default Description
RETURN (dict or str) The current settings dictionary as a dictionary or a nicely formatted string representing it

user_settings_delete_entry

Deletes an individual entry. If no filename has been specified up to this point, then a default filename will be used. After value has been deleted, the settings file is written to disk.

user_settings_delete_entry(
    key,
    silent_on_error = None
)

Parameter Descriptions

Name Type Default Description
key Any Setting to be saved. Can be any valid dictionary key type (hashable)
silent_on_error bool None Determines if an error popup should be shown if an error occurs. Overrides the silent onf effort setting from initialization

user_settings_delete_filename

Deltes the filename and path for your settings file. Either paramter can be optional. If you don't choose a path, one is provided for you that is OS specific Windows path default = users/name/AppData/Local/PySimpleGUI/settings. If you don't choose a filename, your application's filename + '.json' will be used Also sets your current dictionary to a blank one.

user_settings_delete_filename(
    filename = None,
    path = None,
    report_error = False
)

Parameter Descriptions

Name Type Default Description
filename str None The name of the file to use. Can be a full path and filename or just filename
path str None The folder that the settings file will be stored in. Do not include the filename.

user_settings_file_exists

Determines if a settings file exists. If so a boolean True is returned. If either a filename or a path is not included, then the appropriate default will be used.

user_settings_file_exists(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename str None Filename to check
path str None Path to the file. Defaults to a specific folder depending on the operating system
RETURN bool True if the file exists

user_settings_filename

Sets the filename and path for your settings file. Either paramter can be optional.

If you don't choose a path, one is provided for you that is OS specific Windows path default = users/name/AppData/Local/PySimpleGUI/settings.

If you don't choose a filename, your application's filename + '.json' will be used.

Normally the filename and path are split in the user_settings calls. However for this call they can be combined so that the filename contains both the path and filename.

user_settings_filename(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename str None The name of the file to use. Can be a full path and filename or just filename
path str None The folder that the settings file will be stored in. Do not include the filename.
RETURN str The full pathname of the settings file that has both the path and filename combined.

user_settings_get_entry

Returns the value of a specified setting. If the setting is not found in the settings dictionary, then the user specified default value will be returned. It no default is specified and nothing is found, then None is returned. If the key isn't in the dictionary, then it will be added and the settings file saved. If no filename has been specified up to this point, then a default filename will be assigned and used. The settings are SAVED prior to returning.

user_settings_get_entry(
    key,
    default = None
)

Parameter Descriptions

Name Type Default Description
default Any None Value to use should the key not be found in the dictionary
key Any Key used to lookup the setting in the settings dictionary
RETURN Any Value of specified settings

user_settings_load

Specifies the path and filename to use for the settings and reads the contents of the file. The filename can be a full filename including a path, or the path can be specified separately. If no filename is specified, then the caller's filename will be used with the extension ".json"

user_settings_load(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename str None Filename to load settings from (and save to in the future)
path str None Path to the file. Defaults to a specific folder depending on the operating system
RETURN dict The settings dictionary (i.e. all settings)

user_settings_save

Saves the current settings dictionary. If a filename or path is specified in the call, then it will override any previously specitfied filename to create a new settings file. The settings dictionary is then saved to the newly defined file.

user_settings_save(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename str None The fFilename to save to. Can specify a path or just the filename. If no filename specified, then the caller's filename will be used.
path str None The (optional) path to use to save the file.
RETURN str The full path and filename used to save the settings

user_settings_set_entry

Sets an individual setting to the specified value. If no filename has been specified up to this point, then a default filename will be used. After value has been modified, the settings file is written to disk.

user_settings_set_entry(
    key,
    value
)

Parameter Descriptions

Name Type Default Description
key Any Setting to be saved. Can be any valid dictionary key type
value Any Value to save as the setting's value. Can be anything

user_settings_silent_on_error

Used to control the display of error messages. By default, error messages are displayed to stdout.

user_settings_silent_on_error(
    silent_on_error = False
)

Parameter Descriptions

Name Type Default Description
silent_on_error bool False If True then all error messages are silenced (not displayed on the console)

user_settings_write_new_dictionary

Writes a specified dictionary to the currently defined settings filename.

user_settings_write_new_dictionary(
    settings_dict
)

Parameter Descriptions

Name Type Default Description
settings_dict dict The dictionary to be written to the currently defined settings file