1MiConfig 0.4 2============ 3 4## Descripción 5 6MiConfig es una librería de Lazarus, que puede ser usada para crear fácilmente formularios de configuración. 7 8Con esta librería se simplifica considerablemente, la creación de ventanas de configuración, porque la librería incluye métodos predefinidos que facilitan la manipulación de variables (propiedades) de la aplicación, de modo que editarlos en un diálogo y guardar los cambios a disco, se hacen de forma casi transparente. 9 10Se pueden usar archivos INI o XML. 11 12Con la librería "MiConfig", se pueden crear formularios de configuración sencillos como este: 13 14``` 15unit FormConfig; 16{$mode objfpc}{$H+} 17interface 18uses ..., MiConfigINI; 19 20type 21 TConfig = class(TForm) 22 BitCancel: TBitBtn; 23 BitAceptar: TBitBtn; 24 Edit1: TEdit; 25 procedure BitAceptarClick(Sender: TObject); 26 procedure FormShow(Sender: TObject); 27 public 28 //vars to manage 29 MyText : string; 30 procedure Initiate; 31 end; 32 33var 34 Config: TConfig; 35 36implementation 37{$R *.lfm} 38procedure TConfig.Initiate; 39begin 40 //asociate vars to controls 41 iniFile.Asoc_Str('MyText', @MyText, Edit1, ''); 42 iniFile.FileToProperties; 43end; 44 45procedure TConfig.FormShow(Sender: TObject); 46begin 47 iniFile.PropertiesToWindow; 48end; 49 50procedure TConfig.BitAceptarClick(Sender: TObject); 51begin 52 iniFile.WindowToProperties; 53 self.Close; 54end; 55 56end. 57``` 58 59Con este código se podrá editar el valor de la variable "texto" con el control "Edit1", y guardar los cambios a disco o leerlos desde allí. 60 61## Modo de uso 62 63La librería puede trabajar en 3 formas: 64 651. Asociando propiedades a controles y a un archivo: 662. Asociando solamente propiedades a un archivo: 673. Asociando solamente propiedades a controles: 68 69### Asociando propiedades a controles y a un archivo: 70 71Esta es la forma más común, cuando se trabaja con formularios o diálogos de configuración, ya que es deseable poder modificar ciertas propiedades de la aplicación y mantener estos cambios en disco. 72 73El siguiente diagrama muestra el flujo de información, y los métodos que permiten realizar ese flujo: 74 75``` 76 +-----------+ +-------------+ +------------+ 77 | | FileToProperties | | PropertiesToWindow | | 78 | | ---------------> | | -----------------> | | 79 | Disco | | Variables | | Controles | 80 | (File) | PropertiesToFile |(Properties) | WindowToProperties | (Window) | 81 | | <--------------- | | <----------------- | | 82 +-----------+ +-------------+ +------------+ 83``` 84 85De acuerdo al formato de archivo a manejar, se deberá usar la unidad TMiConfigINI o TMiConfigXML. 86 87Para empezar a trabajar, se debe crear una instancia del objeto TMiConfigINI (o TMiConfigXML, si se quiere trabajar con XML). También se puede usar el objeto "cfgFile" que se crea por defecto con la unidad. 88 89Luego se deben crear asociaciones de las variables a guardar, y los controles que permitirán modificar estas variables. Para ello, existen un conjunto de métodos que permiten realizar estas asociaciones: 90 91 Asoc_Int(); 92 Asoc_Dbl() 93 Asoc_Str() 94 Asoc_Bol() 95 Asoc_Enum() 96 97Estos métodos están sobrecargados, para permitir la asociación con diversos controles. Así por ejemplo, es posible asociar un entero a un control TEdit, pero también se puede asociar a un TSpinEdit. 98 99Después de crear las asociaciones, solo resta llamar a los métodos: 100 101* FileToProperties 102* PropertiesToWindow 103* PropertiesToFile 104* WindowToProperties 105 106Para realizar el movimiento de datos. Así por ejemplo, lo normal es leer todas las propiedades al iniciar la aplicación, entonces se debe llamar a FileToProperties() en el evento OnCreate o en el evento OnShow (recomendado). 107 108También es común que al terminar la aplicación se llame a PropertiesToFile() para mantener el valor de las variables asociadas. 109 110Todo este manejo de las propiedades, se puede hacer en el formulario principal, pero lo recomendable es crear un formulario especial o diálogo, de configuración, de modo que incluya los botones ACPETAR y CANCELAR. En este caso, solo cuando se acepten los cambios se debe llamar a WindowToProperties(). 111 112Para ver el código de una implementación de este tipo, se recomienda leer los proyectos de ejemplo que vienen en la librería. 113 114### Asociando solamente propiedades a un archivo: 115 116Esta forma de trabajo, se puede usar cuando no es necesario editar las propiedades en controles, porque usualmente tienen otros medio para modificarse, como podría ser el ancho o el alto de la ventana principal. 117 118``` 119 +-----------+ +-------------+ 120 | | FileToProperties | | 121 | | ---------------> | | 122 | Disco | | Variables | 123 | (File) | PropertiesToFile |(Properties) | 124 | | <--------------- | | 125 +-----------+ +-------------+ 126``` 127 128### Asociando solamente propiedades a controles: 129 130``` 131 +-------------+ +------------+ 132 | | PropertiesToWindow | | 133 | | -----------------> | | 134 | Variables | | Controles | 135 |(Properties) | WindowToProperties | (Window) | 136 | | <----------------- | | 137 +-------------+ +------------+ 138``` 139 140 141 142Para mayor información, revisar los códigos de ejemplo, de la página web. 143 144## Detectando errores 145 146Comunmente, los errores pueden producirse cuando se colocan valores erróneos en los controles asociados a variables, o cuando se accede a disco. Esto es, cuando se ejecuta alguno de estos métodos: 147 148* FileToProperties 149* PropertiesToWindow 150* PropertiesToFile 151* WindowToProperties 152 153El objeto TMiConfigINI tiene un campo de cadena, llamado "MsjErr", cuyo objetivo es almacenar el error producido en la última operación. 154 155Así, es común usar el siguiente código en el evento OnClick, del botón ACEPTAR de las ventanas de configuración: 156 157``` 158procedure TConfig.BitAceptarClick(Sender: TObject); 159begin 160 iniFile.WindowToProperties; 161 if iniFile.MsjErr<>'' then begin 162 MsgErr(iniFile.MsjErr); 163 exit; 164 end; 165 self.Close; 166end; 167``` 168## Dependencias 169 170Esta librería requiere de la librería MisUtils: https://github.com/t-edson/MisUtils 171 172