1MiConfig 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 cfgFile.Asoc_Str('MyText', @MyText, Edit1, ''); 42 cfgFile.FileToProperties; 43end; 44 45procedure TConfig.FormShow(Sender: TObject); 46begin 47 cfgFile.PropertiesToWindow; 48end; 49 50procedure TConfig.BitAceptarClick(Sender: TObject); 51begin 52 cfgFile.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). 88 89También se puede usar el objeto "cfgFile" que se crea por defecto con la unidad, de modo que no es necesario crearlo. El objeto "cfgFile" define para el archivo de configuración, el nombre: <nombre del proyecto>.xml o <nombre del proyecto>.ini 90 91Luego 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: 92 93 Asoc_Int(); 94 Asoc_Dbl() 95 Asoc_Str() 96 Asoc_Bol() 97 Asoc_Enum() 98 99Estos 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. 100 101Después de crear las asociaciones, solo resta llamar a los métodos: 102 103* FileToProperties 104* PropertiesToWindow 105* PropertiesToFile 106* WindowToProperties 107 108Para 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). 109 110También es común que al terminar la aplicación se llame a PropertiesToFile() para mantener el valor de las variables asociadas. 111 112Todo 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(). 113 114Para ver el código de una implementación de este tipo, se recomienda leer los proyectos de ejemplo que vienen en la librería. 115 116### Asociando solamente propiedades a un archivo: 117 118Esta 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. 119 120``` 121 +-----------+ +-------------+ 122 | | FileToProperties | | 123 | | ---------------> | | 124 | Disco | | Variables | 125 | (File) | PropertiesToFile |(Properties) | 126 | | <--------------- | | 127 +-----------+ +-------------+ 128``` 129 130### Asociando solamente propiedades a controles: 131 132``` 133 +-------------+ +------------+ 134 | | PropertiesToWindow | | 135 | | -----------------> | | 136 | Variables | | Controles | 137 |(Properties) | WindowToProperties | (Window) | 138 | | <----------------- | | 139 +-------------+ +------------+ 140``` 141 142 143 144Para mayor información, revisar los códigos de ejemplo, de la página web. 145 146## Detectando errores 147 148Comunmente, 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: 149 150* FileToProperties 151* PropertiesToWindow 152* PropertiesToFile 153* WindowToProperties 154 155El objeto TMiConfigINI tiene un campo de cadena, llamado "MsjErr", cuyo objetivo es almacenar el error producido en la última operación. 156 157Así, es común usar el siguiente código en el evento OnClick, del botón ACEPTAR de las ventanas de configuración: 158 159``` 160procedure TConfig.BitAceptarClick(Sender: TObject); 161begin 162 cfgFile.WindowToProperties; 163 if cfgFile.MsjErr<>'' then begin 164 MsgErr(cfgFile.MsjErr); 165 exit; 166 end; 167 self.Close; 168end; 169``` 170## Dependencias 171 172Esta librería requiere de la librería MisUtils: https://github.com/t-edson/MisUtils 173 174