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