README.md
1UtilsGrilla 0.8
2===============
3
4Librería con utilidades para el manejo y configuración de grillas de tipo TStringGrid
5
6Descripción
7===========
8
9La librería consiste en dos unidades y un Frame:
10
11* BasicGrilla.pas -> Rutinas básicas de manejo de la grilla.
12* UtilsGrilla.pas -> Definición del objeto TUtilGrilla.
13* FrameFiltCampo.pas -> Frame para filtrado de filas.
14
15No todas las unidades tienen que incluirse, Por lo general solo será necesario usar "UtilsGrilla".
16
17## TUtilGrilla ##
18
19La clase principal de la librería es TUtilGrilla. Este objeto es un envoltorio que permite administrar fácilmente una grilla de tipo TStringGrid.
20
21Las facilidades que ofrece TUtilGrilla son:
22
23- Mejora el desplazamiento de teclado, permitiendo usar <Ctrl>+teclas direccionales, para desplazarse hasta los extremos de la grilla.
24- Permite la creación sencilla de encabezados, Usando métodos como AgrEncabTxt() y AgrEncabNum().
25- Permite opciones de alineamiento, del texto dentro de la celda.
26- Permite ocultar fácilmente ciertas columnas.
27- Permite activar opciones comunes (como el dimensionado del ancho de las columnas), de forma sencilla, sin necesidad de usar conjuntos.
28- Permite crear estructuras de encabezados diversas para una misma grilla.
29- Permite asociar una columna de una grilla a un índice, para facilitar la carga de campos desde un archivo de texto o desde base de datos.
30- Brinda un soporte para posteriormente incluir, filtros por filas, en la grilla.
31- Incluye funciones de conversión de tipos, de modo que, por ejemplo, permiten leer o escribir valores de tipo "booleano", directamente desde o hacia la grilla.
32
33Para trabajar con una grilla se tiene dos formas:
34
351. Asociándola a una grilla desde el inicio:
36
37```
38 UtilGrilla := TUtilGrilla.Create(StringGrid1);
39 UtilGrilla.IniEncab;
40 UtilGrilla.AgrEncab('CAMPO1' , 40); //Con 40 pixeles de ancho
41 UtilGrilla.AgrEncab('CAMPO2' , 60); //Con 60 pixeles de ancho
42 UtilGrilla.AgrEncab('CAMPO3' , 35, -1).alineam := taRightJustify); //Justificado a la derecha
43 UtilGrilla.FinEncab;
44 ...
45```
46
472. Sin asociarla a una UtilGrilla:
48
49```
50 UtilGrilla := TUtilGrilla.Create;
51 UtilGrilla.IniEncab;
52 UtilGrilla.AgrEncab('CAMPO1' , 40); //Con 40 pixeles de ancho
53 UtilGrilla.AgrEncab('CAMPO2' , 60); //Con 60 pixeles de ancho
54 UtilGrilla.AgrEncab('CAMPO3' , 35, -1).alineam := taRightJustify; //Justificado a la derecha
55 UtilGrilla.FinEncab;
56 ...
57```
58
59En esta segunda forma, se debe asociar posteriormente a la UtilGrilla, usando el método:
60 UtilGrilla.AsignarGrilla(MiGrilla);
61
62, haciendo que la grilla tome los encabezados que se definieron en "UtilGrilla". De esta forma se pueden tener diversos objetos TUtilGrilla, para usarse en un solo objeto
63TStringGrid.
64
65Existen diversas opciones que se pueden cambiar directamente en TUtilGrilla, sin necesidad de configurar al TStringGrid, directamente.
66
67Algunas de estas opciones son:
68
69 MenuCampos: boolean //Activa o desactiva el menú contextual
70 OpDimensColumnas: boolean //activa el dimensionamiento de columnas
71 OpAutoNumeracion: boolean //activa el autodimensionado en la columna 0
72 OpResaltarEncabez: boolean //Resalta el encabezado, cuando se pasa el mouse
73 OpEncabezPulsable: boolean //Permite pulsar sobre los encabezados como botones
74 OpOrdenarConClick: boolean //Ordenación de filas pulsando en los encabezados
75 OpResaltFilaSelec: boolean //Resaltar fila seleccionada
76
77La propiedad MenuCampos, permite mostrar un menú PopUp, cuando se pulsa el botón derecho sobre la fila de los encabezados de la grilla. Dicho menú permite mostrar u ocultar las columnas de la grilla.
78
79Para el manejo de filtros, TUtilGrilla, incluye los siguientes métodos:
80
81 LimpiarFiltros; //Elimina todos los filtros internos
82 AgregarFiltro(); //Agrega un filtro a TUtilGrilla
83 Filtrar; //Filtra las filas, usando los filtros ingresados.
84
85Los filtros se ingresan como referencias a funciones que deben devolver TRUE, si la fila pasa el filtro y FALSE, en caso contrario.
86
87Todos los filtros agregados, se evalúan en cortocicuito, usando el operador AND.
88
89
90## TUtilGrillaFil ##
91
92
93
94Esta clase es similar a TUtilGrilla, pero se maneja a la grilla, por filas, permitiendo cambiar el color de fondo, del texto o los atributos de las filas, de forma independiente.
95
96Incluye las mismas facilidades de TUtilGrilla, pero adicionalmente:
97- Configura la selección por filas, aunque mantiene identificada a la celda seleccionada.
98- Permite cambiar atributos de las filas (color de fondo, color de texto y atributos de texto)
99- Permite activar y desactivar la selección múltiple de filas.
100- Permite crear columnas que muestren íconos en lugar de texto.
101
102Su uso es similar al de TUtilGrilla:
103
104```
105 UtilGrilla:= TUtilGrillaFil.Create(StringGrid1);
106 UtilGrilla.IniEncab;
107 UtilGrilla.AgrEncabTxt('CAMPO0', 40); //Con 40 pixeles de ancho
108 UtilGrilla.AgrEncabTxt('CAMPO1', 60); //Con 60 pixeles de ancho
109 UtilGrilla.AgrEncabNum('CAMPO2', 60); //Campo numérico, justificado a la derecha
110 UtilGrilla.AgrEncabIco('ÍCONO' , 60).alineam:=taCenter; //Ícono centrado
111 UtilGrilla.FinEncab;
112 UtilGrilla.ImageList := ImageList1; //Íconos a usar
113```
114
115 Para mayor información, se recomienda ver el proyecto ejemplo.
116
117
118## FrameFiltCampo ##
119
120
121
122Como un complemento para el manejo de grillas, se incluye el frame FrameFiltCampo.pas, que se comporta como un componente para realizar búsquedas filtrando las filas que no coincidan con el criterio de búsqueda. El algortimo de búsqueda está optimizado para manejar varios miles de filas sin retraso notorio.
123
124Para usar el frame, como cuadro de búsqueda, solo hay que colocarlo en el formulario, donde se encuentra la grilla, como se muestra en la figura. Al colocar el frame, se debe redimensionarlo pensando en que debe contener un cuadro de búsqueda y un combo para elegir el campo de búsqueda. Por defecto el frame viene con un tamaño muy superior al que suele usarse.
125
126### Configuración simple ###
127
128Para que un TfraFiltCampo, trabaje como filtro, se puede configurar de dos formas. La forma simple consiste en asociarla directamente a un objeto TUtilGrillaFil:
129
130```
131 fraFiltCampo1.Inic(UtilGrilla, 4); //asocia a un TUtilGrilla
132```
133
134Y no se necesita nada más. Esta definición asocia el frame a la grilla, configura todos los campos de la grilla, como parte del filtro, y elige el campo 4 (segundo parámetro), como campo por defecto para el filtro. Además configura el evento OnCambiaFiltro, para que se filtre la grilla en cada pulsación de tecla.
135
136Luego de esta configuración, solo bastaría con escribir sobre el editor del frame, para que automáticamente se empiecen a filtrar las filas en la grilla. El filtrado consiste en ocultar las filas que no cumplen con el criterio de búsqueda, se mantienen con un altura predefinida.
137
138### Configuración detallada ###
139
140La forma más detallada, la que permite más libertad, sería:
141
142```
143 fraFiltCampo1.Inic(StringGrid1); //asocia a grilla
144 fraFiltCampo1.LeerCamposDeGrilla(UtilGrilla.cols, 1); //configura menú de campos
145 UtilGrilla.AgregarFiltro(@fraFiltCampo1.Filtro); //agrega el filtro
146```
147
148Adicionalmente, para determinar cuando cambia el filtro (sea porque se ha modificado el texto de búsqueda o se cambia el campo de trabajo), se debe interceptar el método "OnCambiaFiltro".
149
150```
151 fraFiltCampo1.OnCambiaFiltro:=@fraFiltCampo_CambiaFiltro;
152```
153
154Luego, lo más común sería que este método, llame al método Filtrar() de UtilGrilla.
155
156Hay que notar que es posible agregar varios FrameFiltCampo, a un TUtilGrilla, y que funcionen a modo de filtro en cascada.
157
158### Tipos de búsqueda con TfraFiltCampo ###
159
160El tipo de búsueda por defecto, con TfraFiltCampo, consiste en que se buscarán en todas las filas, en el campo seleccionado, para ver si el contenido de texto mostrado (sea numérico, booleano, etc), incluye al texto escrito como palabra de búsqueda en el frame TfraFiltCampo (específicamente en el control TEdit, del frame).
161
162Es decir, que la búsqueda es equivalente al operador LIKE del lenguaje SQL, cuando trabaja con campos de texto.
163
164Sin embargo, cuando la búsqueda se hace en campos numéricos, es posible usar los operadores de comparación: =, <, >, <=, >= o <>.
165
166Así por ejemplo, si se escribe en el frame: ">5", se hará la comparación, en el campo indicado, comparando la cantidad a modo de número, mostrando las filas que etngan ese campo como un número mayor a 5.
167
168
169### TfraFiltCampo con StringGrid ###
170
171Si bien TfraFiltCampo, se ha creado para trabajar con un objeto TUtilGrilla, también es posible usarlo, con un TStringGrid común:
172
173```
174 fraFiltCampo1.Inic(StringGrid1);
175 fraFiltCampo1.AgregarColumnaFiltro('Por columna A', 1);
176 fraFiltCampo1.AgregarColumnaFiltro('Por columna B', 2);
177 fraFiltCampo1.OnCambiaFiltro:=@fraFiltCampo1CambiaFiltro;
178```
179
180En este caso habría que implementar en fraFiltCampo1CambiaFiltro(), el código que realice el filtrado sobre la grilla.
181
182### Objeto TListaCompletado ###
183
184Esta clase no tiene que ver con grillas, pero se incluye como una utilidad adicional.
185
186TListaCompletado permite implementar la funcionalidad de lista desplegable cuando se llena un control TEdit.
187
188En su forma de trabajo normal, se requiere de una grilla en donde deben estar los valores que se van a usar para llenar la lista de completado.
189
190Para usarlo se debe primero crear el objeto:
191
192```
193 completProv := TListaCompletado.Create;
194```
195
196Luego se debe asociarlo a un TEdit, indicando una grilla, y una columna, de donde se debe extraer los valores para la lista de completado del TEdit.
197
198```
199 completProv.Inic(txtEdit, grilla_datos, col_de_grilla_datos);
200```
201
202Opcionalmente se puede definir los eventos OnSelect y OnEditChange:
203
204```
205 completProv.OnSelect := @Proveed_Seleccionado;
206 completProv.OnEditChange := @Proveed_EditChange;
207```
208
209La utilidad principal del evento OnSelect, es fijar el enfoque al siguiente control después de haber seleccionado un valor para el TEEdit.
210
211Finalmente se debe destruir el objeto:
212
213```
214 completProv.Destroy;
215```
216
217Los valores a mostrar en la lista se obtienen usando la columna indciada de la grilla, y filtrando por el valor contenido en el TEdit.
218
219Si no se quiere usar una grilla como fuente de datos, se puede usar el evento OnLlenarLista, para implementar una rutina personalizada de llenado. Un ejemplo de rutina de llenado sería:
220
221```
222procedure TfrmIngTareo.Edit1_LlenarLista;
223var
224 lista: TListBox;
225begin
226 lista := completEdit1.listBox; //Accede a la lista de completado.
227 lista.Clear;
228
229 if CumpleFiltro('aaa' , Edit1.Text) then
230 lista.AddItem('aaa', nil);
231 if CumpleFiltro('bbb' , Edit1.Text) then
232 lista.AddItem('bbb', nil);
233
234 if lista.Count>0 then
235 lista.ItemIndex:=0; //selecciona el primer elemento
236end;
237```
238
239La función CumpleFiltro(), es una utilidad definida en BasicGrilla, que permite determinar si un texto cumple incluye otro texto.
240
