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(), además una cabecera personalizada puede configurarse con la función setHeaderItem() de la clase VTreeWidgetItem.

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.

Esta clase se ha incorporado al API en la versión 7.16.

Propiedades

Tipo	Propiedad
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

Funciones

Generales

Retorno	Función
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

Retorno	Función
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

Retorno	Función
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 )
void	scrollToItemVTreeItem( item, Number hint = VTreeWidget.EnsureVisible )
void	setCurrentItem( VTreeWidget item, Number column )
VTreeItem	topLevelItem( Number index )

De patrones

Retorno	Función
VItemRegisterPattern	createItemRegPattern()

Señales

Señal

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º 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º 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º 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º 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º 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º de columna a fijar el ancho.

• width: Nº de píxeles de ancho.

void setHeaderLabel( Number column, String label )

Fija la etiqueta de la cabecera de una columna.

Parámetros:

• column: Nº 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º 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 VTreeWidgetItem 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 VTreeWidgetItemRegister con el ítem creado.

Parámetros:

• reg: Registro, objeto de la clase VRegister.

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

Esta clase se ha incorporado al API en la versión 7.17.

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.

Esta clase se ha incorporado al API en la versión 7.17.

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º 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º que identifica a la fila o ítem a editar.

• columna: Nº 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º 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 VTreeWidgetItem que representa la fila que se utilizará como posición para la inserción del nuevo ítem de nivel principal.

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º 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º de item a activar.

• column: Nº 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º 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.

Ejemplo

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();
};