1+ using System . Drawing ;
2+
13using LogExpert . Core . Config ;
24using LogExpert . Core . EventArguments ;
35
46namespace LogExpert . Core . Interface ;
57
6- //TODO: Add documentation
8+ /// <summary>
9+ /// Manages application configuration settings including loading, saving, importing, and exporting.
10+ /// Provides centralized access to application settings with automatic backup/recovery and validation.
11+ /// </summary>
12+ /// <remarks>
13+ /// This interface defines the contract for configuration management in LogExpert.
14+ /// Implementations use a singleton pattern and require explicit initialization via <see cref="Initialize"/>
15+ /// before accessing any settings. The manager handles JSON serialization, backup file creation,
16+ /// corruption recovery, and thread-safe operations.
17+ /// </remarks>
718public interface IConfigManager
819{
20+ /// <summary>
21+ /// Gets the current application settings.
22+ /// </summary>
23+ /// <remarks>
24+ /// Settings are lazy-loaded on first access. The manager must be initialized via
25+ /// <see cref="Initialize"/> before accessing this property.
26+ /// </remarks>
27+ /// <exception cref="InvalidOperationException">Thrown if accessed before initialization.</exception>
928 Settings Settings { get ; }
1029
30+ /// <summary>
31+ /// Gets the directory path for portable mode settings.
32+ /// </summary>
33+ /// <remarks>
34+ /// Returns the application startup path combined with "portable" subdirectory.
35+ /// When a portableMode.json file exists in this directory, the application runs in portable mode.
36+ /// </remarks>
1137 string PortableModeDir { get ; }
1238
39+ /// <summary>
40+ /// Gets the standard configuration directory path.
41+ /// </summary>
42+ /// <remarks>
43+ /// Returns the path to the AppData\Roaming\LogExpert directory where settings are stored
44+ /// when not running in portable mode.
45+ /// </remarks>
1346 string ConfigDir { get ; }
1447
15- IConfigManager Instance { get ; }
16-
48+ /// <summary>
49+ /// Gets the filename for the portable mode indicator file.
50+ /// </summary>
51+ /// <value>Returns "portableMode.json"</value>
1752 string PortableModeSettingsFileName { get ; }
1853
54+ /// <summary>
55+ /// Initializes the ConfigManager with application-specific paths and screen information.
56+ /// This method must be called once before accessing Settings or other configuration.
57+ /// </summary>
58+ /// <param name="applicationStartupPath">The application startup path (e.g., Application.StartupPath)</param>
59+ /// <param name="virtualScreenBounds">The virtual screen bounds (e.g., SystemInformation.VirtualScreen)</param>
60+ /// <remarks>
61+ /// This method should be called early in the application startup sequence, before any
62+ /// settings access. Subsequent calls are ignored with a warning logged.
63+ /// The virtual screen bounds are used to validate and correct window positions.
64+ /// </remarks>
65+ /// <exception cref="ArgumentException">Thrown if applicationStartupPath is null or whitespace.</exception>
66+ void Initialize ( string applicationStartupPath , Rectangle virtualScreenBounds ) ;
67+
68+ /// <summary>
69+ /// Exports specific settings to a file based on the provided flags.
70+ /// </summary>
71+ /// <param name="fileInfo">The file to export settings to. Will be created or overwritten.</param>
72+ /// <param name="highlightSettings">Flags indicating which settings to export (e.g., SettingsFlags.HighlightSettings)</param>
73+ /// <remarks>
74+ /// Currently only supports exporting highlight settings. Other flags may be ignored.
75+ /// The file is written in JSON format.
76+ /// </remarks>
77+ /// <exception cref="IOException">Thrown if the file cannot be written.</exception>
1978 void Export ( FileInfo fileInfo , SettingsFlags highlightSettings ) ;
2079
80+ /// <summary>
81+ /// Exports all current settings to a file.
82+ /// </summary>
83+ /// <param name="fileInfo">The file to export settings to. Will be created or overwritten.</param>
84+ /// <remarks>
85+ /// Exports the complete settings object including preferences, filters, history, and highlights.
86+ /// A backup (.bak) file is created if the target file already exists.
87+ /// </remarks>
88+ /// <exception cref="IOException">Thrown if the file cannot be written.</exception>
89+ /// <exception cref="InvalidOperationException">Thrown if settings validation fails.</exception>
2190 void Export ( FileInfo fileInfo ) ;
2291
92+ /// <summary>
93+ /// Imports settings from a file with validation and user confirmation support.
94+ /// </summary>
95+ /// <param name="fileInfo">The file to import settings from. Must exist.</param>
96+ /// <param name="importFlags">Flags controlling which parts of settings to import and how to merge them</param>
97+ /// <returns>
98+ /// An <see cref="ImportResult"/> indicating success, failure, or need for user confirmation.
99+ /// Check <see cref="ImportResult.Success"/> and <see cref="ImportResult.RequiresUserConfirmation"/> to determine the outcome.
100+ /// </returns>
101+ /// <remarks>
102+ /// This method validates the import file before applying changes. It detects corrupted files,
103+ /// empty/default settings, and handles backup recovery. If the import file appears empty,
104+ /// it returns a result requiring user confirmation to prevent accidental data loss.
105+ /// The current settings are only modified if the import is successful.
106+ /// </remarks>
23107 ImportResult Import ( FileInfo fileInfo , ExportImportFlags importFlags ) ;
24108
109+ /// <summary>
110+ /// Imports only highlight settings from a file.
111+ /// </summary>
112+ /// <param name="fileInfo">The file containing highlight settings to import. Must exist and contain valid highlight groups.</param>
113+ /// <param name="importFlags">Flags controlling whether to keep existing highlights or replace them</param>
114+ /// <remarks>
115+ /// This is a specialized import method for highlight configurations. If <see cref="ExportImportFlags.KeepExisting"/>
116+ /// is set, imported highlights are added to existing ones; otherwise, existing highlights are replaced.
117+ /// Changes are saved immediately after import.
118+ /// </remarks>
119+ /// <exception cref="ArgumentNullException">Thrown if fileInfo is null.</exception>
25120 void ImportHighlightSettings ( FileInfo fileInfo , ExportImportFlags importFlags ) ;
26121
122+ /// <summary>
123+ /// Occurs when configuration settings are changed and saved.
124+ /// </summary>
125+ /// <remarks>
126+ /// This event is raised after settings are successfully saved, allowing UI components and other
127+ /// parts of the application to respond to configuration changes. The event args include
128+ /// <see cref="SettingsFlags"/> indicating which settings were modified.
129+ /// </remarks>
27130 event EventHandler < ConfigChangedEventArgs > ConfigChanged ; //TODO: All handlers that are public shoulld be in Core
28131
132+ /// <summary>
133+ /// Saves the current settings with the specified flags.
134+ /// </summary>
135+ /// <param name="flags">Flags indicating which parts of settings have changed and should be saved</param>
136+ /// <remarks>
137+ /// This method saves settings to disk with automatic backup creation. A temporary file is used
138+ /// during the write operation to prevent corruption. The previous settings file is backed up
139+ /// as .bak before being replaced. After successful save, the <see cref="ConfigChanged"/> event is raised.
140+ /// Settings validation is performed before saving to prevent data loss.
141+ /// </remarks>
142+ /// <exception cref="InvalidOperationException">Thrown if settings validation fails.</exception>
143+ /// <exception cref="IOException">Thrown if the file cannot be written.</exception>
29144 void Save ( SettingsFlags flags ) ;
30145}
0 commit comments