35

VTreeWidget

Hereda de: Widget.

Esta clase representa el control Tree Widget. Con las funciones de esta clase tendremos acceso a la interfaz de un control de árbol basado en ítems, podremos crear vistas de datos jerarquizados. El control no tiene origen de datos por lo que podemos utilizarlo para visualizar datos tanto de tablas de origen Velneo como de cualquier origen de información.

Antes de añadir ítems al control se debe fijar el número de columnas. Esto permite que cada ítem pueda tener una o más etiquetas. El número de columnas en uso puede obtenerse con la propiedad columnCount.

El árbol puede tener una cabecera que contenga una sección por cada columna en el control. Esto facilita la configuración de las etiquetas de cada sección aplicando una lista de textos con la función setHeaderLabels().

Los ítems en el árbol pueden clasificarse por una columna en función de un orden predefinido. Si la ordenación está habilitada, el usuario podrá clasificar los ítems haciendo clic en la cabecera de columna. La ordenación puede activarse o desactivarse con la propiedad sortingEnabled. Con la propiedad sortingEnabled también podremos saber si la ordenación está o no habilitada.

Indice de propiedades

Boolean allColumnsShowFocus

Boolean alternatingRowColors

Boolean animated

Number autoScrollMargin

Number columnCount

Number editTriggers

Boolean expandsOnDoubleClick

Boolean headerHidden

Number horizontalScrollMode

Number indentation

Boolean itemsExpandable

Boolean rootIsDecorated

Number selectionBehavior

Number selectionMode

Boolean sortingEnabled

Boolean tabKeyNavigation

Number textElideMode

Number topLevelItemCount

Boolean uniformRowHeights

Number verticalScrollMode

Boolean wordWrap

Indice de funciones

Generales

void clear()

void collapseAll()

void expandAll()

void expandToDepth( Number depth )

void setIconSize( Number width, Number height )

Number sortColumn()

void sortItems( Number colum, Number order )

De cabecera / columna

Number columnWidth( Number column )

Number currentColumn()

void hideColumn( Number column )

void resizeColumnToContents( Number column )

void setColumnWidth( Number column, Number width )

void setHeaderLabel( Number column, String label )

void setHeaderLabel( String label )

void setHeaderLabels( StringArray labels)

void showColumn( Number column )

De ítems

VTreeItem addTopLevelItem()

VTreeItemRegister addTopLevelItemRegister( VRegister reg, VItemRegisterPatern patern )

Number addTopLevelItemRegisterList( VRegisterList regList, VItemRegisterPatern patern )

void collapseItemVTreeItem( item )

VTreeItem currentItem()

void deleteTopLevelItem( Number index )

void editItem( VTreeWidget item, Number columna=0 )

void expandItem( VTreeItem item )

VTreeItem insertTopLevelItem( Number index )

VTreeItem senderItem()

void scrollToItemVTreeItem( item, Number hint = VTreeWidget.EnsureVisible )

void setCurrentItem( VTreeWidget item, Number column )

VTreeItem topLevelItem( Number index )

De patrones

VItemRegisterPattern createItemRegPattern()

Señales

Item: activado

Item: cambio de seleccionado

Item: doble-click

Item: simple-click

Enumeraciones

EditTrigger

  • NoEditTriggers = 0x00

  • CurrentChanged = 0x01

  • DoubleClicked = 0x02

  • SelectedClicked = 0x04

  • EditKeyPressed = 0x08

  • AnyKeyPressed = 0x10

  • AllEditTriggers = 0x1F

ScrollHint

  • EnsureVisible = 0

  • PositionAtTop = 1

  • PositionAtBottom = 2

  • PositionAtCenter = 3

ScrollMode

  • ScrollPerItem = 0

  • ScrollPerPixel = 1

SelectionBehavior

  • SelectItems = 0

  • SelectRows = 1

  • SelectColumns = 2

SelectionMode

  • NoSelection = 0

  • SingleSelection = 1

  • MultiSelection = 2

  • ExtendedSelection = 3

  • ContiguousSelection = 4

SortOrder

  • AscendingOrder = 0

  • DescendingOrder = 1

TextElideMode

  • ElideLeft = 0

  • ElideRight = 1

  • ElideMiddle = 2

  • ElideNone = 3

Documentación de propiedades

allColumnsShowFocus

Esta propiedad fija si el foco estará en todas las columnas (true) o solo en una (false, valor por defecto).

alternatingRowColors

Esta propiedad fija si se usará un único color de fondo en todas las filas o ítems (valor false, por defecto) o se usarán colores alternativos diferentes para identificar mejor las filas pares e impares (valor true).

animated

Fija si las animaciones al expandir o contraer los ítems estarán activadas (true) o desactivadas (false, valor por defecto).

autoScrollMargin

Esta propiedad fija el área de autoScroll para que se dispare el posicionamiento del control para que el ítem en curso quede visible, el valor por defecto es 16 píxeles.

columnCount

Devuelve el nº de columnas en uso del control.

editTriggers

Esta propiedad permite configurar como se activará la edición de un ítem/columna del árbol. En el enum EditTrigger se pueden ver todos los valores que se pueden combinar para que la edición se active al hacer doble clic, seleccionar el contenido, al cambiar de celda, al presionar la tecla Intro, al presionar cualquier tecla, etc.

expandsOnDoubleClick

Esta propiedad permite fijar si los ítems del árbol se expanden al hacer sobre ellos doble clic. Por defecto su valor es true.

headerHidden

Esta propiedad permite fijar si la cabecera del control estará oculta. Por defecto su valor es false, es decir que la cabecera es visible.

horizontalScrollMode

Esta propiedad permite fijar si el scroll horizontal se realiza por ítem o por píxel en función de valor numérico asignado según el enum ScrollMode.

indentation

Esta propiedad permite fijar los píxeles de indentación que se usarán en la vista del árbol. El valor por defecto de esta propiedad es 20 píxeles.

itemsExpandable

Esta propiedad indica si los items son expandibles por el usuario. Su valor por defecto es true.

rootIsDecorated

Esta propiedad permite fijar si se visualizarán los controles para expandir o contraer los niveles superiores del árbol.

selectionBehavior

Esta propiedad fija como se comportará la selección del control, si será por ítem, por fila o por columna. Ver valores en el enum SelectionBehavior.

selectionMode

Esta propiedad permite fija el modo de selección del control, si se podrá seleccionar sólo una fila, sólo filas contiguas, selección extendida, multiselección, o no está permitida la selección. Ver los valores posible en el enum SelectionMode.

sortingEnabled

Esta propiedad permite fijar si la ordenación por columna está activada. El valor por defecto es false.

tabKeyNavigation

Esta propiedad permite fijar si está permitido el uso de la tecla de tabulación (Tab) para navegar adelante o hacia atrás entre las columnas de una fila.

textElideMode

Esta propiedad permite fijar como se comportará el control cuando los textos sean demasiado largos para ser visibles en una celda. Ver los valores posible de configuración en el enum TextElideMode. El valor por defecto es ElideRight (1).

topLevelItemCount

Devuelve el nº de ítems que existen en el nivel principal.

uniformRowHeights

Esta propiedad permite fijar que todos los ítems del árbol tengan el mismo alto. El valor por defecto es false.

verticalScrollMode

Esta propiedad permite fijar si el scroll vertical se realiza por ítems o por píxel en función de valor numérico asignado según el enum ScrollMode.

wordWrap

Esta propiedad permite fijar la política de ajuste de línea que se aplicará a los textos de los ítems. Si se fija a true el texto se cortará en una palabra para que se vean todas enteras, si es false no se cortará en ninguna palabra. El valor por defecto es false.

Documentación de funciones

Funciones generales

void clear()

Limpia todos los ítems del árbol.

void collapseAll()

Contrae todos los ítems del árbol dejando visible solo los ítem del nivel principal.

void expandAll()

Expande todo los ítems del árbol.

void expandToDepth( Number depth )

Expande todos los ítems del árbol hasta el nivel de profundidad especificado en el parámetro

Parámetros:

  • depth: número que identifica el nivel máximo de profundidad de ítems que se expandirán.

void setIconSize( Number width, Number height )

Fija el tamaño de los iconos a mostrar en el árbol.

Parámetros:

  • width: ancho en píxeles del icono.

  • height: alto en píxeles del icono.

Number sortColumn()

Devuelve el nº de la columna utilizada para ordenar el control.

void sortItems( Number colum, Number order )

Ordena el control por la columna especificada en el primer parámetro con el criterio establecido en el segundo parámetro.

Parámetros:

  • column: número de columna por la que se ordena.

  • order: criterio de clasificación, ver enum SortOrder.

Funciones de cabecera / columna

Number columnWidth( Number column )

Devuelve el ancho en píxeles de la columna especificada en el parámetro.

Parámetros:

  • column: número que representa la posición de un columna en el árbol.

Number currentColumn()

Devuelve el nº de la columna en curso (activa) del árbol.

void hideColumn( Number column )

Oculta la columna especificada en el parámetro.

Parámetros:

  • column: número de columna que se ocultará.

void resizeColumnToContents( Number column )

Ajusta el ancho de la columna especifica en el parámetro al contenido de la misma.

Parámetros:

  • column: número de columna a ajustar el ancho.

void setColumnWidth( Number column, Number width )

Fija el ancho de la columna especifica en el primer parámetro con el ancho en píxeles especificado en el segundo parámetro.

Parámetros:

  • column: número de columna a fijar el ancho.

  • width: número de píxeles de ancho.

void setHeaderLabel( Number column, String label )

Fija la etiqueta de la cabecera de una columna.

Parámetros:

  • column: número de columna.

  • label: etiqueta a mostrar en la cabecera.

void setHeaderLabel( String label )

Fija la etiqueta de cabecera del árbol.

void setHeaderLabels( StringArray labels)

Añade una columna en la cabecera de cada ítem y fija la etiqueta de cada columna.

Parámetros:

  • labels: array de cadenas con los textos de las cabeceras.

void showColumn( Number column )

Hace visible la columna especificada en el parámetro.

Parámetros:

  • column: número de columna a hacer visible.

Funciones de ítems

VTreeItem addTopLevelItem()

Añade un ítem de nivel principal al árbol, a continuación del último ítem de nivel principal que exista en el árbol y devuelve un objeto de la clase VTreeItem sobre el que se puede aplicar propiedades, añadir columnas, etc.

VTreeItemRegister addTopLevelItemRegister( VRegister reg, VItemRegisterPatern patern )

Añade al control un ítem de nivel superior con el registro y patrón especificados en los parámetros y devuelve un objeto de la clase VTreeItemRegister con el ítem creado.

Parámetros:

Number addTopLevelItemRegisterList( VRegisterList regList, VItemRegisterPatern patern )

Añade al control un grupo de ítems de nivel superior con la lista de registros y patrón especificados en los parámetros y devuelve el número de ítems creados.

Parámetros:

  • regList: registro, objeto de la clase VRegisterList.

  • patern: patrón, objeto de la clase VItemRegisterPatern.

void collapseItem( VTreeItem item )

Contrae el ítem indicado en el parámetro, dejando ocultos todos sus ítem hijos.

Parámetros:

  • item: objeto de la clase VTreeItem que representa al ítem que queremos contraer.

VTreeItem currentItem()

Devuelve un objeto de la clase VTreeItem que representa al ítem activo o en curso.

void deleteTopLevelItem( Number index )

Eliminar el ítem de nivel principal especificado en el parámetro. Se elimina del árbol tanto ese ítem como todos sus hijos.

Parámetros:

  • index: número que identificado el ítem de nivel principal que queremos eliminar.

void editItem( VTreeWidget item, Number columna=0 )

Activa la edición del dato correspondiente al ítem y columna especificados en los parámetros.

Parámetros:

  • ítem: número que identifica a la fila o ítem a editar.

  • columna: número que identifica a la fila o ítem a editar, por defecto asume la 0 que es la primera.

void expandItem( VTreeItem item )

Expande los ítems hijos del ítem especificado en el parámetro.

Parámetros:

  • ítem: número que identifica a la fila o ítem a expandir.

VTreeItem insertTopLevelItem( Number index )

Inserta un ítem de nivel principal al árbol antes del ítem especificado en el parámetro y devuelve un objeto de la clase VTreeItem sobre el que se puede aplicar propiedades, añadir columnas, etc.

Parámetro:

  • item: objeto de la clase VTreeItem que representa la fila que se utilizará como posición para la inserción del nuevo ítem de nivel principal.

VTreeItem senderItem()

Permite establecer el ítem del treewidget que genera cualquier señal de tipo ítem.

void scrollToItem( VTreeItem item, Number hint = VTreeWidget.EnsureVisible )

Se posiciona el árbol de forma que garantiza que el ítem especificado sea visible en el control. El tipo de scroll a realizar se puede configurar en el segundo parámetro, por defecto asume el valor asegurar visibilidad, pero se puede configurar para que el ítem se posicione al principio, al final o en el centro del control siempre que sea posible por su posición y el nº de ítems existentes en el árbol.

Parámetro:

  • item: número de fila o ítem a visualizar.

  • hint: ver enum ScrollHint

void setCurrentItem( VTreeWidget item, Number column )

Activa el ítem y columna especificados convirtiéndolos en la celda activa.

Parámetros:

  • item: número de item a activar.

  • column: número de la columna a activar.

VTreeItem topLevelItem( Number index )

Devuelve un objeto de la clase VTreeItem que representa al ítem de nivel superior especificado en el parámetro.

Parámetro:

  • index: número del ítem de nivel superior.

Funciones de patrones

VItemRegisterPattern createItemRegPattern()

Crea un nuevo objeto de la clase VItemRegisterPattern con el que podemos configurar a nivel de patrón las columnas, formularios de alta, baja y modificación, los colores, fuentes y alineaciones a aplicar a los nodos del árbol añadidos a través del patrón.

Ejemplos

1. Procesar un fichero xml con formato xbel 1.0 y mostrar el resultado un control del tipo treeWidget.

importClass("VXmlReader");
importClass("VFile");

// -------------------------------------------------------
// Parseador de ficheros XML en formato xbel 1.0
// -------------------------------------------------------

// Preparamos el control treewidget
var treeWidget = theRoot.dataView().control("TREE_WIDGET");
treeWidget.clear();

// Leemos el fichero desde la senda del control
var fileEdit = theRoot.dataView().control("FILE");
var inFile = new VFile( fileEdit.text );
inFile.open(VFile.OpenModeReadOnly);

// Preparamos el objeto para parsear el XML
var xml = new VXmlReader();
xml.setFile(inFile);

// Leemos el primer elemento del fichero para comprobar que es de tipo xbel versión 1.0
if (xml.readNextStartElement()) 
{
    if (xml.name() == "xbel" && xml.attributeValue("version") == "1.0")
    {
        // XBEL read
        while (xml.readNextStartElement()) 
        {
            if (xml.name() == "folder")
                readFolder(treeWidget, 0, xml);
            else if (xml.name() == "bookmark")
                readBookmark(treeWidget, 0, xml);
            else if (xml.name() == "separator")
                readSeparator(treeWidget, 0, xml);
            else
                xml.skipCurrentElement();
        };
    }
    else
        xml.raiseError("Este fichero no es un XBEL 1.0");
};

// Ajusta las columnas al contenido
treeWidget.resizeColumnToContents(0);
treeWidget.setFocus();

// --------------------------
// Lectura de la carpeta
// --------------------------
function readFolder(tree, item, xml)
{
    var itemFolder;
    if (item)
        itemFolder = item.addChild();
    else
        itemFolder = tree.addTopLevelItem();
    var folded = (xml.attributeValue("folded") != "no");
    itemFolder.setExpanded(!folded);

    while (xml.readNextStartElement()) 
    {
        if (xml.name() == "title")
            readTitle(itemFolder, xml);
        else if (xml.name() == "folder")
            readFolder(tree, itemFolder, xml);
        else if (xml.name() == "bookmark")
            readBookmark(tree, itemFolder, xml);
        else if (xml.name() == "separator")
            readSeparator(tree, itemFolder, xml);
        else
            xml.skipCurrentElement();
    };
};

// ----------------------
// Lectura del  título
// ----------------------
function readTitle( item, xml )
{
    var title = xml.readElementText();
    item.setText(0, title);
};

// ---------------------------
// Lectura del  bookmark
// ---------------------------
function readBookmark(tree, item, xml)
{
    var itemBookmark;
    if (item)
        itemBookmark = item.addChild();
    else
        itemBookmark = tree.addTopLevelItem();

    itemBookmark.setFlags(0 | itemBookmark.flags() | VTreeItem.ItemIsEditable);
    itemBookmark.setText(0, "Título desconocido");
    itemBookmark.setText(1, xml.attributeValue("href"));

    while (xml.readNextStartElement()) 
    {
        if (xml.name() == "title")
            readTitle(itemBookmark, xml);
        else
            xml.skipCurrentElement();
    };
};

// --------------------------
// Lectura del separador
// --------------------------
function readSeparator(tree, item, xml)
{
    var itemSeparator;
    if (item)
        itemSeparator = item.addChild();
    else
        itemSeparator = tree.addTopLevelItem();

    itemSeparator.setText(0, "...............................................................................");
    xml.skipCurrentElement();
};

2. Ejemplo de uso de las señales ítem: expandido e ítem: contraído para optimizar su carga

En este caso cargaremos inicialmente los ítems de primer nivel (clientes) y cargaremos y destruiremos los de segundo nivel (facturas) con las señales ítem: expandido e ítem: cotraído, respectivamente, cuando despleguemos o contraigamos ramas.

2.1. Carga de los ítems de primer nivel

Se crearán desde un manejador de evento disparado con la señal post inicializado del formulario.

importClass("VQuery");

var tree = theRoot.dataView().control("TRE");
var bus = new VQuery(theRoot);	
bus.setQuery( "migestion_app/CLIENTES" );
if (bus.exec())
{
	var registerListOut = bus.result();
	var itemExpanded = 0;
	for (var i = 0 ; i < registerListOut.size() ; i++)
	{
		var register = registerListOut.readAt(i);
		var item = tree.addTopLevelItem();
		item.setText( 0, register.fieldToString("ID") + ". " + register.fieldToString("NAME") );
		item.setText( 1, register.fieldToString("ID") );
		item.setExpandable( true );
	}
}

2.2. Cargar los ítems hijos de una rama al desplegarla

Se hará desde un manejador de evento disparado con la señal ítem: expandido del formulario.

importClass("VQuery");

var senderItem = theSender.senderItem();
if (senderItem)
{
	var bExpandable = false;
	var bus = new VQuery(theRoot);
	bus.setQuery( "migestion/FACTURAS_CLT" );
	bus.setVar( "ENT", senderItem.text(1)+"0");
	
	if (bus.exec())
	{
		var registerList = bus.result();
		for (var i = 0 ; i < registerList.size() ; i++)
		{
			bExpandable = true;
			var register = registerList.readAt(i);
			var id = register.fieldToInt("ID");
			var codigo = parseInt(senderItem.text(1));
		
			var item = senderItem.addChild();
			item.setText( 0, register.fieldToString("ID") + ". " + register.fieldToDate("FECHA") );
			item.setText( 1, register.fieldToString("ID") );
			item.setExpandable( false);
		}
	}
	senderItem.setExpandable( bExpandable );
}

2.3. Quitar los ítems hijos de una rama al contraerla

Se hará desde un manejador de evento disparado con la señal ítem: cotraído del formulario.

var senderItem = theSender.senderItem();
if (senderItem)
{
	for (var i = senderItem.childCount() ; i > 0; i--)
	{
		senderItem.deleteChild(i-1);
	}
}