Automatic generation produced by ISE Eiffel
note description: "[ Preferences. This class should be used for creating a preference system for an application. Briefly, preferences and their related attributes and values are stored at run-time in an appropriate PREFERENCE object. They must be created through the helper class PREFERENCE_MANAGER. In between sessions the preference will be saved in an underlying data store. To such data store implementation are provided by default, one for saving to the Windows Registry and one for saving to an XML file on disk. To use a different store, such as a database one must create a new class which implements the methods in PREFERENCES_STORAGE_I. Regardless of the underlying data store used the preferences are managed in the same way. There are 5 levels of control provided for such management: 1. Storage specified. Use `make_with_storage`. A storage for the underlying data store is provided. Values are retrieved from this storage between sessions. You can specify the location for this storage, when you create it. This storage's location must exist. 2. Storage and defaults specified. The same as in option 1, but a location of one or more default files is provided in addition to the data store location. Those files are XML files which contain the default values to use in a preference if it is not already defined in the data store. It is a convenient way to initialize your application with all the default values required "out of the box" for correct or preferred functioning. This file also contains additional attributes for preference configuration such a more detailed description of the preference, or whether it should be hidden by default. If two files list the same preference, the last one to mention it takes precedence. 3. Development use. Use `make` to create preferences. No underlying datastore location is provided. No default preference values are provided. A data store location is created automatically and modified preference values are tranparently retrieved between sessions. 4. Location specified. Use `make_with_location`. A location for the underlying data store is provided. Values are retrieved from this location between sessions. This location must exist. 5. Location and defaults specified. The same as in option 2, but using a storage with specified location. We recommend using 1. or 2. since 3,4,5 might become obsolete in the future. Once preferences they may be modified programmatically or through an user interface conforming to PREFERENCE_VIEW. A default interface is provided in PREFERENCES_WINDOW. You may implement your own style interface by implementing PREFERENCE_VIEW. You may also add your own application specific preferences by implementing PREFERENCE, and may provide a graphical widget to view or edit this preference by implementing PREFERENCE_WIDGET and then registering this widget to the PREFERENCES through the register_preference_widget procedure. ]" legal: "See notice at end of class." status: "See notice at end of class." date: "$Date: 2021-06-25 04:16:34 -0800 (Fri, 25 Jun 2021) $" revision: "$Revision: 105580 $" class interface PREFERENCES create make_with_storage (a_storage: PREFERENCES_STORAGE_I) -- Create preferences based on underlying storage engine a_storage. require a_storage_not_void: a_storage /= Void ensure has_session_values: session_values /= Void has_preferences_storage: preferences_storage /= Void managers_not_void: managers /= Void preferences_not_void: preferences /= Void default_values_not_void: default_values /= Void make_with_defaults_and_storage (a_defaults: ARRAY [READABLE_STRING_GENERAL]; a_storage: PREFERENCES_STORAGE_I) -- Create preferences and initialize values from those in a_defaults, -- using a_storage as preferences underlying storage engine. require default_not_void: a_defaults /= Void a_storage_not_void: a_storage /= Void ensure has_session_values: session_values /= Void has_preferences_storage: preferences_storage /= Void managers_not_void: managers /= Void preferences_not_void: preferences /= Void default_values_not_void: default_values /= Void make -- This creation routine creates a location to store and retrieve preferences -- between sessions. The location will be either a registry location of an XML file (depending -- on the implementation chosen) and will be named based upon the name of the application. -- You should use this to create preferences during the development phase, or when you do not -- care exactly where the preferences are stored and have no file containing default values for the -- application preferences. make_with_location (a_location: READABLE_STRING_32) -- Create preferences and store them in the location a_location between sessions. -- -- a_location is the path to either: -- * the root registry key where preferences will be stored, -- * or the file where preferences will be stored, -- depending on which implementation is chosen (registry or xml). require location_not_void: a_location /= Void location_not_empty: not a_location.is_empty make_with_location_and_version (a_location: READABLE_STRING_32; a_version: like version) -- Create preferences and store them in the location a_location between sessions. -- -- a_location is the path to either: -- * the root registry key where preferences will be stored, -- * or the file where preferences will be stored, -- depending on which implementation is chosen (registry or xml). require location_not_void: a_location /= Void location_not_empty: not a_location.is_empty a_version_not_void: a_version /= Void a_version_valid: valid_version (a_version) make_with_defaults_and_location (a_defaults: ARRAY [READABLE_STRING_GENERAL]; a_location: READABLE_STRING_32) -- Create preferences and initialize values from those in a_defaults, -- which is the path of one or more files that contain the default values. -- Preferences will be stored in a_location between sessions, which is the -- path to either: -- * the root registry key where preferences are stored, -- * or the file where preferences are stored, -- depending on which implementation is chosen (registry or xml). require default_not_void: a_defaults /= Void location_not_void: a_location /= Void location_not_empty: not a_location.is_empty make_with_defaults_and_location_and_version (a_defaults: ARRAY [READABLE_STRING_GENERAL]; a_location: READABLE_STRING_32; a_version: like version) -- Create preferences and initialize values from those in a_defaults, -- which is the path of one or more files that contain the default values. -- Preferences will be stored in a_location between sessions, which is the -- path to either: -- * the root registry key where preferences are stored, -- * or the file where preferences are stored, -- depending on which implementation is chosen (registry or xml). require default_not_void: a_defaults /= Void location_not_void: a_location /= Void location_not_empty: not a_location.is_empty a_version_not_void: a_version /= Void a_version_valid: valid_version (a_version) feature -- Access default_version: IMMUTABLE_STRING_32 -- Default version if none specified. -- (from PREFERENCES_VERSIONS) error_message_32: detachable STRING_32 -- Message explaining why Current could not be initialized. generating_type: TYPE [detachable PREFERENCES] -- Type of current object -- (type of which it is a direct instance) -- (from ANY) ensure -- from ANY generating_type_not_void: Result /= Void generator: STRING_8 -- Name of current object's generating class -- (base class of the type of which it is a direct instance) -- (from ANY) ensure -- from ANY generator_not_void: Result /= Void generator_not_empty: not Result.is_empty location: READABLE_STRING_GENERAL -- Storage's location save_defaults_to_store: BOOLEAN -- Should preferences with default values be saved to the underlying data store when saving? version: IMMUTABLE_STRING_32 -- Version format used by storage. Version_1_0: IMMUTABLE_STRING_32 -- (from PREFERENCES_VERSIONS) Version_2_0: IMMUTABLE_STRING_32 -- (from PREFERENCES_VERSIONS) feature -- Comparison frozen deep_equal (a: detachable ANY; b: like arg #1): BOOLEAN -- Are a and b either both void -- or attached to isomorphic object structures? -- (from ANY) ensure -- from ANY instance_free: class shallow_implies_deep: standard_equal (a, b) implies Result both_or_none_void: (a = Void) implies (Result = (b = Void)) same_type: (Result and (a /= Void)) implies (b /= Void and then a.same_type (b)) symmetric: Result implies deep_equal (b, a) frozen equal (a: detachable ANY; b: like arg #1): BOOLEAN -- Are a and b either both void or attached -- to objects considered equal? -- (from ANY) ensure -- from ANY instance_free: class definition: Result = (a = Void and b = Void) or else ((a /= Void and b /= Void) and then a.is_equal (b)) frozen is_deep_equal alias "≡≡≡" (other: PREFERENCES): BOOLEAN -- Are Current and other attached to isomorphic object structures? -- (from ANY) require -- from ANY other_not_void: other /= Void ensure -- from ANY shallow_implies_deep: standard_is_equal (other) implies Result same_type: Result implies same_type (other) symmetric: Result implies other.is_deep_equal (Current) is_equal (other: PREFERENCES): BOOLEAN -- Is other attached to an object considered -- equal to current object? -- (from ANY) require -- from ANY other_not_void: other /= Void ensure -- from ANY symmetric: Result implies other ~ Current consistent: standard_is_equal (other) implies Result frozen standard_equal (a: detachable ANY; b: like arg #1): BOOLEAN -- Are a and b either both void or attached to -- field-by-field identical objects of the same type? -- Always uses default object comparison criterion. -- (from ANY) ensure -- from ANY instance_free: class definition: Result = (a = Void and b = Void) or else ((a /= Void and b /= Void) and then a.standard_is_equal (b)) frozen standard_is_equal alias "≜" (other: PREFERENCES): BOOLEAN -- Is other attached to an object of the same type -- as current object, and field-by-field identical to it? -- (from ANY) require -- from ANY other_not_void: other /= Void ensure -- from ANY same_type: Result implies same_type (other) symmetric: Result implies other.standard_is_equal (Current) feature -- Status report conforms_to (other: ANY): BOOLEAN -- Does type of current object conform to type -- of other (as per Eiffel: The Language, chapter 13)? -- (from ANY) require -- from ANY other_not_void: other /= Void error_message_is_valid_as_string_8: BOOLEAN -- Is associated error message a valid string_8 value? same_type (other: ANY): BOOLEAN -- Is type of current object identical to type of other? -- (from ANY) require -- from ANY other_not_void: other /= Void ensure -- from ANY definition: Result = (conforms_to (other) and other.conforms_to (Current)) valid_version (a_version: detachable IMMUTABLE_STRING_32): BOOLEAN -- Is a_version a supported version? -- (from PREFERENCES_VERSIONS) feature -- Duplication copy (other: PREFERENCES) -- Update current object using fields of object attached -- to other, so as to yield equal objects. -- (from ANY) require -- from ANY other_not_void: other /= Void type_identity: same_type (other) ensure -- from ANY is_equal: Current ~ other frozen deep_copy (other: PREFERENCES) -- Effect equivalent to that of: -- `copy` (other . `deep_twin`) -- (from ANY) require -- from ANY other_not_void: other /= Void ensure -- from ANY deep_equal: deep_equal (Current, other) frozen deep_twin: PREFERENCES -- New object structure recursively duplicated from Current. -- (from ANY) ensure -- from ANY deep_twin_not_void: Result /= Void deep_equal: deep_equal (Current, Result) frozen standard_copy (other: PREFERENCES) -- Copy every field of other onto corresponding field -- of current object. -- (from ANY) require -- from ANY other_not_void: other /= Void type_identity: same_type (other) ensure -- from ANY is_standard_equal: standard_is_equal (other) frozen standard_twin: PREFERENCES -- New object field-by-field identical to other. -- Always uses default copying semantics. -- (from ANY) ensure -- from ANY standard_twin_not_void: Result /= Void equal: standard_equal (Result, Current) frozen twin: PREFERENCES -- New object equal to Current -- `twin` calls `copy`; to change copying/twinning semantics, redefine `copy`. -- (from ANY) ensure -- from ANY twin_not_void: Result /= Void is_equal: Result ~ Current feature -- Basic operations frozen default: detachable PREFERENCES -- Default value of object's type -- (from ANY) frozen default_pointer: POINTER -- Default value of type POINTER -- (Avoid the need to write p.`default` for -- some p of type POINTER.) -- (from ANY) ensure -- from ANY instance_free: class default_rescue -- Process exception for routines with no Rescue clause. -- (Default: do nothing.) -- (from ANY) frozen do_nothing -- Execute a null action. -- (from ANY) ensure -- from ANY instance_free: class feature -- Change report_error (m: READABLE_STRING_GENERAL) feature -- Filters new_document_builder: XML_CALLBACKS_DOCUMENT -- New tree construction filter -- Was declared in {XML_CALLBACKS_FILTER_FACTORY} as synonym of `new_tree_builder`. -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY tree_builder_not_void: Result /= Void new_namespace_resolver: XML_NAMESPACE_RESOLVER -- New namespace resolver -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY namespace_resolver_not_void: Result /= Void new_null: XML_CALLBACKS_NULL -- New null callback consumer -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY null_callback_not_void: Result /= Void new_tree_builder: XML_CALLBACKS_DOCUMENT -- New tree construction filter -- Was declared in {XML_CALLBACKS_FILTER_FACTORY} as synonym of `new_document_builder`. -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY tree_builder_not_void: Result /= Void feature -- Filters to implement new_content_concatenator: XML_CONTENT_CONCATENATOR -- New content concatenation filter. -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY content_concatenator_not_void: Result /= Void new_indent_pretty_print: XML_INDENT_PRETTY_PRINT_FILTER -- Indenting pretty print filter -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY indent_pretty_print_not_void: Result /= Void new_pretty_print: XML_PRETTY_PRINT_FILTER -- New pretty printer (to standard io) -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY pretty_print_not_void: Result /= Void new_xmlns_generator: XML_XMLNS_GENERATOR -- New xmlns: generator (opposite of namespace resolver) -- (from XML_CALLBACKS_FILTER_FACTORY) ensure -- from XML_CALLBACKS_FILTER_FACTORY xmlns_generator_not_void: Result /= Void feature -- Importation export_to_storage (a_storage: PREFERENCES_STORAGE_I; a_save_modified_values_only: BOOLEAN) -- Import preferences values from a_storage require a_storage_not_void: a_storage /= Void import_from_storage (a_storage: PREFERENCES_STORAGE_I) -- Import preferences values from a_storage require a_storage_not_void: a_storage /= Void import_from_storage_with_callback (a_storage: PREFERENCES_STORAGE_I; a_callback: detachable PROCEDURE [INTEGER_32, INTEGER_32, READABLE_STRING_GENERAL, READABLE_STRING_GENERAL]) -- Import preferences values from a_storage require a_storage_not_void: a_storage /= Void import_from_storage_with_callback_and_exclusion (a_storage: PREFERENCES_STORAGE_I; a_ignore_hidden_preference: BOOLEAN; a_callback: detachable PROCEDURE [INTEGER_32, INTEGER_32, READABLE_STRING_GENERAL, READABLE_STRING_GENERAL]; a_exclude_function: detachable FUNCTION [INTEGER_32, INTEGER_32, READABLE_STRING_GENERAL, READABLE_STRING_GENERAL, BOOLEAN]) -- Import preferences values from a_storage, on import call a_callback if any. -- If a_exclude_function is set, import related preference only if return is False. require a_storage_not_void: a_storage /= Void feature -- Manager has_manager (a_namespace: STRING_8): BOOLEAN -- Does Current contain manager with namespace a_namespace? require namespace_not_void: a_namespace /= Void namespace_not_empty: not a_namespace.is_empty manager (a_namespace: STRING_8): detachable PREFERENCE_MANAGER -- Associated manager to a_namespace. require namespace_not_void: a_namespace /= Void namespace_not_empty: not a_namespace.is_empty new_manager (a_namespace: STRING_8): PREFERENCE_MANAGER -- Create a new preference manager with namespace a_namespace. require namespace_not_void: a_namespace /= Void namespace_not_empty: not a_namespace.is_empty manager_unique: not has_manager (a_namespace) ensure result_not_void: Result /= Void manager_added: managers.has (a_namespace) feature -- Output Io: STD_FILES -- Handle to standard file setup -- (from ANY) ensure -- from ANY instance_free: class io_not_void: Result /= Void out: STRING_8 -- New string containing terse printable representation -- of current object -- (from ANY) ensure -- from ANY out_not_void: Result /= Void print (o: detachable ANY) -- Write terse external representation of o -- on standard output. -- (from ANY) ensure -- from ANY instance_free: class frozen tagged_out: STRING_8 -- New string containing terse printable representation -- of current object -- (from ANY) ensure -- from ANY tagged_out_not_void: Result /= Void feature -- Pipes callbacks_pipe (a: ARRAY [XML_CALLBACKS_FILTER]): XML_CALLBACKS -- Make a pipe, -- eg << new_tag_checker, new_pretty_print >> -- return first item of pipe. -- (from XML_CALLBACKS_FILTER_FACTORY) require -- from XML_CALLBACKS_FILTER_FACTORY a_not_void: a /= Void a_not_empty: a.count > 0 ensure -- from XML_CALLBACKS_FILTER_FACTORY pipe_not_void: Result /= Void standard_callbacks_pipe (a: ARRAY [XML_CALLBACKS_FILTER]): XML_CALLBACKS -- Add elements to standard validation pipe, which -- begins with: -- namespace resolver -> stop on error -- (from XML_CALLBACKS_FILTER_FACTORY) require -- from XML_CALLBACKS_FILTER_FACTORY a_not_void: a /= Void ensure -- from XML_CALLBACKS_FILTER_FACTORY pipe_not_void: Result /= Void feature -- Platform Operating_environment: OPERATING_ENVIRONMENT -- Objects available from the operating system -- (from ANY) ensure -- from ANY instance_free: class operating_environment_not_void: Result /= Void feature -- Preference get_preference (a_name: STRING_8): detachable PREFERENCE -- Fetch the preference with a_name. require name_not_void: a_name /= Void name_not_empty: not a_name.is_empty get_preference_value_direct (a_name: READABLE_STRING_GENERAL): detachable READABLE_STRING_32 -- Fetch the preference string value with a_name directly from the underlying datastore. -- Ignore values currently in `session_values` and `preferences`. Use this if the -- preference value has been changed externally and you need the updated value. -- If you are going to do this you must prepend the preference type name to the front of the preference -- since that is how it will have been saved. Return Void if no preference found. require name_not_void: a_name /= Void name_not_empty: not a_name.is_empty has_preference (a_name: STRING_8): BOOLEAN -- Does Current contain a preference with a_name? require name_not_void: a_name /= Void restore_defaults -- Restore all preferences which have associated default values to their default values. ensure all_preferences_default: True save_preference (a_preference: PREFERENCE) -- Save a_preference to underlying data store. require preference_not_void: a_preference /= Void save_preferences -- Commit all changes by saving the underlying data store. Only save preferences -- which are not using the default value. save_preferences_using_storage (a_storage: PREFERENCES_STORAGE_I; a_save_modified_values_only: BOOLEAN) -- Save all preferences value using a_storage. set_preference (a_name: STRING_8; a_preference: PREFERENCE) -- Override current value of preference with a_name in `preferences`? require name_not_void: a_name /= Void has_preference (a_name) feature -- Status Setting set_save_defaults (a_flag: BOOLEAN) -- Set `save_defaults_to_store` with a_flag. ensure value_set: save_defaults_to_store = a_flag feature -- Storage access preferences_storage_exists: BOOLEAN -- Does preferences storage exists ? invariant has_session_values: session_values /= Void has_preferences_storage: preferences_storage /= Void -- from ANY reflexive_equality: standard_is_equal (Current) reflexive_conformance: conforms_to (Current) note copyright: "Copyright (c) 1984-2021, Eiffel Software and others" license: "Eiffel Forum License v2 (see http://www.eiffel.com/licensing/forum.txt)" source: "[ Eiffel Software 5949 Hollister Ave., Goleta, CA 93117 USA Telephone 805-685-1006, Fax 805-685-6869 Website http://www.eiffel.com Customer support http://support.eiffel.com ]" end -- class PREFERENCES -- Generated by Eiffel Studio --
For more details: eiffel.org