Adding a new option to the EPANET GUI may seem simple, but there are several considerations to take into account. I will use this pull request to outline the steps for adding a new option to the EPANET GUI for any future additions.
You should check these notes for each file against the changes in the PR.
consts.txt
Add a new record to theHydraulicProps array; this is the order it is seen in the GUI from Data > Options > Hydraulic.
Increase the size of the HydraulicProps array
The order is not the same as the array used by DefOptions and TOptions (Network.Options.Data). In other files, we need magic numbers or complex logic to connect the HydraulicProps array to the Network.Options.Data and DefOptions array.
Add a new record to the end of DefOptions that matches the internal array used by TOptions. It is necessary to add it to the end for backward compatibility (more on this later).
DefOptions is the global default values for the options.
Uglobals.pas
Increase the MAXOPTIONS size, which is used by both TOptions and DefOptions.
Add a new analysis option index, which is used to find the correct place of the option in the internal memory.
Bump the version number to determine if the .net file is compatible with the current version of EPANET (more on this later).
Uinput.pas
Update the function EditOptions to align the PropList with HydraulicProps and Network.Options.Data.
Update the function ValidOption that takes the index of the PropList, which matches HydraulicProps, and align it with Network.Options.Data.
Uexport.pas
Update the function ExportDataBase to save the new option to the .inp file.
Uimport.pas
Update the function ReadOptionData to read the new option from the .inp file.
You may need to update the OptionWords array to identify the new option in the .inp file.
Ufileio.pas
This file is used to read and write .net files; it saves a binary version of the internal Network structure. Because we are adding a new option, it won't be compatible with older versions of EPANET.
It uses an internal ReadArray/WriteArray that saves the length of arrays and also checks it against the internal array length. However, this will cause a problem with older versions because it won't read all the strings in the binary file.
For this reason, we need to bump the version number and add support to read old versions of .net files by assigning default values to the new options.
We also need to consider how we handle compatibility between development versions. I'm tempted to not accept .net files from development versions to make things simpler.
We could simplify things by aligning all three arrays (HydraulicProps, DefOptions, TOptions), but this would cause backward compatibility issues when reading .net files. However, this could be managed in Ufileio.pas.
Uinifile.pas
Used to save the default values of the options to the .ini file.
You need to update ReadDefaults and SaveDefaults to align the different arrays (HydraulicProps, TOptions).
Ddefault.pas
You need to update SetDefaults and GetDefaults to align the different arrays (HydraulicProps, TOptions).
This view changes the current network analysis options, and if you select "Save as defaults for all new projects," it will save the new option to the .ini file.
Adding a new option to the EPANET GUI may seem simple, but there are several considerations to take into account. I will use this pull request to outline the steps for adding a new option to the EPANET GUI for any future additions.
You should check these notes for each file against the changes in the PR.
consts.txt
HydraulicPropsarray; this is the order it is seen in the GUI from Data > Options > Hydraulic.HydraulicPropsarrayDefOptionsandTOptions(Network.Options.Data). In other files, we need magic numbers or complex logic to connect theHydraulicPropsarray to theNetwork.Options.DataandDefOptions array.DefOptionsthat matches the internal array used byTOptions. It is necessary to add it to the end for backward compatibility (more on this later).DefOptionsis the global default values for the options.Uglobals.pas
MAXOPTIONSsize, which is used by bothTOptionsandDefOptions.Uinput.pas
EditOptionsto align thePropListwithHydraulicPropsandNetwork.Options.Data.ValidOptionthat takes the index of thePropList, which matchesHydraulicProps, and align it with Network.Options.Data.Uexport.pas
ExportDataBaseto save the new option to the .inp file.Uimport.pas
ReadOptionDatato read the new option from the .inp file.OptionWordsarray to identify the new option in the .inp file.Ufileio.pas
ReadArray/WriteArraythat saves the length of arrays and also checks it against the internal array length. However, this will cause a problem with older versions because it won't read all the strings in the binary file.HydraulicProps,DefOptions,TOptions), but this would cause backward compatibility issues when reading .net files. However, this could be managed in Ufileio.pas.Uinifile.pas
ReadDefaultsandSaveDefaultsto align the different arrays (HydraulicProps,TOptions).Ddefault.pas
SetDefaultsandGetDefaultsto align the different arrays (HydraulicProps,TOptions).Closes #5 Closes #14 Closes #15