treelist.h

Clase wxTreeListCtrl

Un control que combina las características de wxTreeCtrl y wxListCtrl.

Jerarquía:

Se trata de un control de árbol multicolumna que soporta opcionalmente imágenes y casillas de verificación para los elementos de la primera columna.

Actualmente se implementa utilizando wxDataViewCtrl internamente, pero proporciona una interfaz mucho más simple para el caso de uso común que aborda. Así, uno de los principios de diseño de este control es la simplicidad e intencionadamente no proporciona todas las características de wxDataViewCtrl. Lo más importante es que esta clase almacena todos sus datos internamente y no requiere que se defina un modelo personalizado para ello.

En su lugar, este control funciona como wxTreeCtrl o wxListCtrl no virtual y permite simplemente añadir elementos utilizando a href="#AppendItem">wxTreeListCtrl::AppendItem() y métodos relacionados. Normalmente, se empieza configurando las columnas (debe tener al menos una) llamando a wxTreeListCtrl::AppendColumn() y luego se añaden los elementos. Aunque sólo se puede especificar el texto de la primera columna al añadirlos, se puede utilizar wxTreeListCtrl::SetItemText() para establecer el texto de las otras columnas.

A diferencia de wxTreeCtrl o wxListCtrl este control puede ordenar sus elementos por si mismo. Para permitir al usuario ordenar el contenido del control pulsando sobre alguna columna, se debe utilizar el indicador wxCOL_SORTABLE cuando añada esa columna al control. Cuando una columna con esta bandera es pulsada, el control se ordena usando los valores de esta columna. Por defecto la ordenación se realiza utilizando la comparación por orden alfabético del texto de los ítems, lo cual no siempre es correcto (por ejemplo, esto no funciona para las columnas numéricas). Para cambiar esto puede utilizar el método SetItemComparator() para proporcionar un comparador personalizado, es decir, simplemente un objeto que implemente la comparación entre los dos elementos. El ejemplo de treelist muestra un ejemplo de cómo hacerlo. Y si se necesita ordenar el control mediante programación, se puede llamar al método SetSortColumn().

Estos son los estilos soportados por este control. Obsérvese que el uso de wxTL_USER_3STATE implica wxTL_3STATE y wxTL_3STATE a su vez implica wxTL_CHECKBOX.

Estilos

Esta clase admite los siguientes estilos:

wxTL_SINGLE: Selección única, este es el estilo por defecto.
wxTL_MULTIPLE: Permite selección múltiple, ver GetSelections().
wxTL_CHECKBOX: Muestra las casillas de verificación habituales, de 2 estados, para los elementos de la primera columna.
wxTL_3STATE: Muestra las casillas de verificación que pueden ser configuradas por el programa, pero no por el usuario, a un tercer estado indeterminado, para los elementos de la primera columna. Implica wxTL_CHECKBOX.
wxTL_USER_3STATE: Igual que wxTL_3STATE pero el usuario también puede poner las casillas de verificación en estado indeterminado. Implica wxTL_3STATE.
wxTL_NO_HEADER: No mostrar las cabeceras de las columnas, que se muestran por defecto. Hay que tener en cuenta que este estilo sólo está disponible desde wxWidgets 2.9.5.
wxTL_DEFAULT_STYLE: Estilo usado por el control por defecto, actualmente solo wxTL_SINGLE.

Eventos emitidos por esta clase

Las siguientes macros manejadoras de eventos redirigen los eventos a manejadores de funciones miembro 'func' con prototipos como:

void handlerFuncName(wxTreeListEvent& event)

Macros de evento:

EVT_TREELIST_SELECTION_CHANGED(id, func): Procesa el evento wxEVT_TREELIST_SELECTION_CHANGED y notifica el cambio de selección en el control. En el caso de selección única, el elemento indicado por el evento ha sido seleccionado y el elemento previamente seleccionado, si lo había, ha sido deseleccionado. En el caso de selección múltiple, la selección de este elemento acaba de cambiar (puede haber sido seleccionado o deseleccionado) pero hay que tener en cuenta que la selección de otros elementos podría haber cambiado también, utilizar wxTreeListCtrl::GetSelections() para recuperar la nueva selección si es necesario.
EVT_TREELIST_ITEM_EXPANDING(id, func): Procesa el evento wxEVT_TREELIST_ITEM_EXPANDING que notifica la expansión de la rama dada. Este evento se envía antes de que se produzca la expansión y puede ser vetado para evitar que ocurra.
EVT_TREELIST_ITEM_EXPANDED(id, func): Procesa el evento wxEVT_TREELIST_ITEM_EXPANDED notificando la expansión de la rama dada. Este evento se envía después de que se produzca la expansión y no puede ser vetado.
EVT_TREELIST_ITEM_CHECKED(id, func): Procesa el evento wxEVT_TREELIST_ITEM_CHECKED notificando sobre el usuario marcando o desmarcando el ítem. Se puede utilizar wxTreeListCtrl::GetCheckedState() para recuperar el nuevo estado del ítem y wxTreeListEvent::GetOldCheckedState() para obtener el anterior.
EVT_TREELIST_ITEM_ACTIVATED(id, func): Procesa el evento wxEVT_TREELIST_ITEM_ACTIVATED que notifica que el usuario ha hecho doble click sobre el ítem o lo ha activado desde el teclado.
EVT_TREELIST_ITEM_CONTEXT_MENU(id, func): Procesa el evento wxEVT_TREELIST_ITEM_CONTEXT_MENU que indica que se debe mostrar el menú emergente del ítem dado.
EVT_TREELIST_COLUMN_SORTED(id, func): Procesa el evento wxEVT_TREELIST_COLUMN_SORTED que indica que el contenido del control acaba de ser ordenado utilizando la columna especificada. El evento no contiene la dirección de ordenación, utilizar el método GetSortColumn() si se necesita conocerla.

Funciones miembro

wxTreeListCtrl()

wxTreeListCtrl::wxTreeListCtrl()

Constructor por defecto, llamar a Create() más tarde.

Este constructor se utiliza durante el proceso de construcción en dos partes cuando es imposible o indeseable crear la ventana al construir el objeto.

wxTreeListCtrl()

wxTreeListCtrl::wxTreeListCtrl( wxWindow * parent, wxWindowID id, const wxPoint & pos = wxDefaultPosition, const wxSize & size = wxDefaultSize, long style = wxTL_DEFAULT_STYLE, const wxString & name = wxTreeListCtrlNameStr )

Construcción completa, creando el objeto y su ventana.

Ver Create() para la descripción de los parámetros.

AppendColumn()

int wxTreeListCtrl::AppendColumn( const wxString & title, int width = wxCOL_WIDTH_AUTOSIZE, wxAlignment align = wxALIGN_LEFT, int flags = wxCOL_RESIZABLE )

Añade una columna con el título y los atributos dados.

Parámetros

title: La etiqueta de la columna.
width: El ancho de la columna en píxeles o el valor especial wxCOL_WIDTH_AUTOSIZE que indica que la columna debe ajustarse a su contenido. Hay que tener en cuenta que la última columna es especial y siempre se redimensionará para llenar todo el espacio no ocupado por las otras columnas, es decir, el ancho especificado aquí se ignora para ella.
align: Alineación tanto de la cabecera de la columna como de sus elementos.
flags: flags de columna, actualmente pueden incluir wxCOL_RESIZABLE para permitir al usuario redimensionar la columna y wxCOL_SORTABLE para permitir al usuario recurrir el contenido del control haciendo click en esta columna.

Valor de retorno

Índice de la nueva columna o -1 en caso de fallo.

AppendItem()

wxTreeListItem wxTreeListCtrl::AppendItem( wxTreeListItem parent, const wxString & text, int imageClosed = NO_IMAGE, int imageOpened = NO_IMAGE, wxClientData * data = nullptr )

Igual que InsertItem() con wxTLI_LAST.

AreAllChildrenInState()

bool wxTreeListCtrl::AreAllChildrenInState( wxTreeListItem item, wxCheckBoxState state ) const

Devuelve true si todos los hijos del elemento dado están en el estado especificado.

Esto es especialmente útil para los controles con estilo wxTL_3STATE para permitir decidir si el estado efectivo padre debe ser el mismo estado, si todos sus hijos están en él, o wxCHK_UNDETERMINED.

AssignImageList()

void wxTreeListCtrl::AssignImageList(wxImageList * imageList)

Establece la lista de imágenes y da su propiedad al control.

La lista de imágenes asignada con este método será eliminada automáticamente por wxTreeListCtrl según corresponda (es decir, toma la propiedad de la lista).

CheckItem()

void wxTreeListCtrl::CheckItem( wxTreeListItem item, wxCheckBoxState state = wxCHK_CHECKED )

Cambia el estado de comprobación del elemento.

Parámetros

item: Elemento válido no raíz del árbol.
state: Uno de wxCHK_CHECKED, wxCHK_UNCHECKED o, para los controles con estilos wxTL_3STATE o wxTL_USER_3STATE, wxCHK_UNDETERMINED.

CheckItemRecursively()

void wxTreeListCtrl::CheckItemRecursively( wxTreeListItem item, wxCheckBoxState state = wxCHK_CHECKED )

Cambia el estado de comprobación del elemento dado y de todos sus hijos.

Es lo mismo que CheckItem(), pero comprueba o anula la comprobación no sólo del propio elemento, sino también de todos sus hijos de forma recursiva.

ClearColumns()

void wxTreeListCtrl::ClearColumns()

Elimina todas las columnas.

Collapse()

void wxTreeListCtrl::Collapse(wxTreeListItem ¡item)

Colapsa la rama del árbol dada.

Create()

bool wxTreeListCtrl::Create( wxWindow * parent, wxWindowID id, const wxPoint & pos = wxDefaultPosition, const wxSize & size = wxDefaultSize, long style = wxTL_DEFAULT_STYLE, const wxString & name = wxTreeListCtrlNameStr )

Crea la ventana de control.

Sólo puede ser llamado para los objetos creados usando el constructor por defecto y exactamente una vez.

Parámetros

parent: La ventana padre, debe ser no nula.
id: El identificador de la ventana, puede ser wxID_ANY.
pos: La posición inicial de la ventana, normalmente no se utiliza.
size: El tamaño inicial de la ventana, normalmente no se utiliza.
style: El estilo de la ventana, ver su descripción en la documentación de la clase.
name: El nombre de la ventana.

DeleteAllItems()

void wxTreeListCtrl::DeleteAllItems()

Borrar todos los elementos del árbol.

DeleteColumn()

bool wxTreeListCtrl::DeleteColumn(unsigned col)

Elimina la columna con el índice dado.

Parámetros

col: Índice de columna en un rango de 0 a GetColumnCount() (exclusivo).

Valor de retorno

True si la columna fue eliminada, false si el índice no es válido o la eliminación de la columna falló por alguna otra razón.

DeleteItem()

void wxTreeListCtrl::DeleteItem(wxTreeListItem item)

Elimina el elemento especificado.

EnsureVisible()

void wxTreeListCtrl::EnsureVisible(wxTreeListItem item)

Llamar a esto para asegurarse de que el elemento dado es visible.

Expand()

void wxTreeListCtrl::Expand(wxTreeListItem item)

Expande la rama del árbol dado.

GetCheckedState()

wxCheckBoxState wxTreeListCtrl::GetCheckedState(wxTreeListItem item) const

Devuelve el estado de la marca de chequeo del elemento.

El valor devuelto puede ser wxCHK_CHECKED, wxCHK_UNCHECKED o wxCHK_UNDETERMINED.

GetColumnCount()

unsigned wxTreeListCtrl::GetColumnCount() const

Devuelve el número total de columnas.

GetColumnWidth()

int wxTreeListCtrl::GetColumnWidth(unsigned col) const

Obtiene la anchura actual de la columna dada en píxeles.

GetDataView()

wxDataViewCtrl* wxTreeListCtrl::GetDataView() const

Devuelve la parte de la vista de este control como wxDataViewCtrl.

Este método puede devolver nullptr en el futuro, para versiones de esta clase no basadas en wxDataViewCtrl, utilizar GetView() a menos que realmente se necesite utilizar métodos wxDataViewCtrl en el objeto devuelto.

GetFirstChild()

wxTreeListItem wxTreeListCtrl::GetFirstChild(wxTreeListItem item) const

Devuelve el primer hijo del elemento dado.

El elemento puede ser el elemento raíz.

El valor devuelto puede no ser válido si el elemento no tiene ningún hijo.

GetFirstItem()

wxTreeListItem wxTreeListCtrl::GetFirstItem() const

Devuelve el primer elemento del árbol.

Es el primer hijo del elemento raíz.

GetItemData()

wxClientData* wxTreeListCtrl::GetItemData(wxTreeListItem item) const

Obtiene los datos asociados al elemento dado.

El puntero devuelto puede ser nullptr.

No debe ser borrado por el llamante ya que esto lo hará el propio control.

GetItemParent()

wxTreeListItem wxTreeListCtrl::GetItemParent(wxTreeListItem item) const

Devuelve el elemento padre del elemento dado.

Todos los elementos visibles en el árbol tienen elementos padre válidos, sólo el elemento raíz nunca mostrado carece de padre.

GetItemText()

const wxString& wxTreeListCtrl::GetItemText( wxTreeListItem item, unsigned col = 0 ) const

Devuelve el texto del elemento dado.

Por defecto, devuelve el texto de la primera columna, pero se puede especificar cualquier otra mediante el argumento col.

GetNextItem()

wxTreeListItem wxTreeListCtrl::GetNextItem(wxTreeListItem item) const

Obtiene el elemento siguiente al dado en el orden de recorrido del árbol en profundidad.

La llamada a esta función a partir del resultado de GetFirstItem() permite iterar sobre todos los elementos del árbol.

La iteración se detiene cuando esta función devuelve un elemento no válido, es decir

for ( wxTreeListItem item = tree->GetFirstItem();
      item.IsOk();
      item = tree->GetNextItem(item) )
{
    ... Hacer algo con cada elemento del árbol ...
}

GetNextSibling()

wxTreeListItem wxTreeListCtrl::GetNextSibling(wxTreeListItem item) const

Devuelve el siguiente hermano del elemento dado.

El valor devuelto puede no ser válido si no hay más hermanos.

GetRootItem()

wxTreeListItem wxTreeListCtrl::GetRootItem() const

Devuelve el elemento raíz (nunca mostrado).

GetSelection()

wxTreeListItem wxTreeListCtrl::GetSelection() const

Devuelve el elemento seleccionado actualmente.

Este método no puede utilizarse con controles multiselección, utilizar GetSelections() en su lugar.

El valor devuelto puede no ser válido si aún no se ha seleccionado ningún elemento. Una vez seleccionado un elemento en un control de selección única, mantendrá una selección válida.

GetSelections()

unsigned wxTreeListCtrl::GetSelections(wxTreeListItems & selections) const

Rellena el array proporcionado con todos los elementos seleccionados.

Este método puede utilizarse tanto en el caso de selección única como en el de selección múltiple.

Se destruye el contenido del array anterior.

Devuelve el número de elementos seleccionados.

GetSortColumn()

bool wxTreeListCtrl::GetSortColumn( unsigned * col, bool * ascendingOrder = nullptr )

Devuelve la columna utilizada actualmente para la ordenación, si existe.

Si el control no está ordenado, la función simplemente devuelve false y no modifica ninguno de sus parámetros de salida.

Parámetros

col: Recibe el índice de la columna utilizada para ordenar si no es nula.
ascendingOrder: Recibe true o false dependiendo de si los elementos están ordenados en orden ascendente o descendente.

Valor de retorno

true si el control está ordenado o false si no lo está.

GetView()

wxWindow* wxTreeListCtrl::GetView() const

Devuelve la parte de la vista de este control como una wxWindow.

Este método siempre devuelve un puntero no nulo una vez creada la ventana.

InsertItem()

wxTreeListItem wxTreeListCtrl::InsertItem( wxTreeListItem parent, wxTreeListItem previous, const wxString & text, int imageClosed = NO_IMAGE, int imageOpened = NO_IMAGE, wxClientData * data = nullptr )

Inserta un nuevo elemento en el árbol.

Parámetros

parent: El elemento padre. Debe ser válido, puede ser GetRootItem().; El ítem anterior al que éste debe insertarse inmediatamente después. Debe ser válido pero puede ser uno de los valores especiales wxTLI_FIRST o wxTLI_LAST indicando que el elemento debe insertarse antes del primer hijo de su padre (si lo hay) o después del último.
text: Texto del elemento.
imageClosed: La imagen normal del elemento, puede ser NO_IMAGE para no mostrar ninguna imagen.
imageOpened: La imagen del ítem mostrada cuando está en estado expandido.
data: Puntero opcional a los datos del cliente que puede ser recuperado posteriormente usando GetItemData() y que será borrado por el árbol cuando el propio ítem sea borrado.

IsExpanded()

bool wxTreeListCtrl::IsExpanded(wxTreeListItem item) const

Devuelve si el elemento dado está expandido.

IsSelected()

bool wxTreeListCtrl::IsSelected(wxTreeListItem item) const

Devuelve true si el elemento está seleccionado.

Este método puede utilizarse tanto en el modo de selección única como en el de selección múltiple.

PrependItem()

wxTreeListItem wxTreeListCtrl::PrependItem( wxTreeListItem parent, const wxString & text, int imageClosed = NO_IMAGE, int imageOpened = NO_IMAGE, wxClientData * data = nullptr )

Igual que InsertItem() con wxTLI_FIRST.

Select()

void wxTreeListCtrl::Select(wxTreeListItem item)

Selecciona el elemento dado.

En el modo de selección simple, anula la selección de cualquier otro elemento seleccionado; en el caso de selección múltiple, se añade a la selección.

SelectAll()

void wxTreeListCtrl::SelectAll()

Selecciona todos los elementos de control.

Sólo se puede utilizar en el modo de selección múltiple.

SetColumnWidth()

void wxTreeListCtrl::SetColumnWidth( unsigned col, int width )

Cambia el ancho de la columna dada.

Establece la anchura de la columna al valor dado en píxeles o al valor suficientemente grande para que quepan todos los elementos si width es wxCOL_WIDTH_AUTOSIZE.

Hay que tener en cuenta que el ajuste de la anchura de la última columna se ignora ya que esta columna siempre se redimensiona para llenar el espacio dejado por las otras columnas.

SetImageList()

void wxTreeListCtrl::SetImageList(wxImageList * imageList)

Establece la lista de imágenes.

La lista de imágenes asignada con este método no será borrada por el propio control y tendrá que ser borrarla explícitamente, utilizar AssignImageList() para dar la propiedad de la lista de imágenes al control.

Parámetros

imageList: Lista de imágenes a utilizar, puede ser nullptr para no mostrar más imágenes.

SetItemComparator()

void wxTreeListCtrl::SetItemComparator(wxTreeListItemComparator * comparator)

Establece el objeto a utilizar para comparar los elementos.

Este objeto se utilizará cuando el control se ordene porque el usuario haya pulsado sobre una columna ordenable o se haya llamado a SetSortColumn().

El puntero proporcionado es almacenado por el control por lo que el objeto al que apunta debe tener un tiempo de vida igual o superior al del propio control. Además, el puntero puede ser nullptr para dejar de utilizar el comparador personalizado y volver a la comparación alfabética por defecto.

SetItemData()

void wxTreeListCtrl::SetItemData( wxTreeListItem item, wxClientData * data )

Establece los datos asociados con el elemento dado.

Los datos anteriores del cliente, si los hubiera, se eliminan cuando se llama a esta función, por lo que puede utilizarse para eliminar el objeto de datos del elemento actual y restablecerlo pasando nullptr como argumento de datos.

SetItemImage()

void wxTreeListCtrl::SetItemImage( wxTreeListItem item, int closed, int opened = NO_IMAGE )

Establece las imágenes para el elemento dado.

Ver InsertItem() para las descripciones de los parámetros de las imágenes.

SetItemText()

void wxTreeListCtrl::SetItemText( wxTreeListItem item, const wxString & text )

Establece el texto de la primera columna del elemento dado.

SetItemText()

void wxTreeListCtrl::SetItemText( wxTreeListItem item, unsigned col, const wxString & text )

Establece el texto de la columna especificada del elemento dado.

SetSortColumn()

void wxTreeListCtrl::SetSortColumn( unsigned col, bool ascendingOrder = true )

Establece la columna que se utilizará para ordenar y el orden en que se ordenará.

Al llamar a este método se reordena el contenido del control utilizando los valores de los elementos de la columna especificada. La ordenación utiliza el comparador personalizado establecido con SetItemComparator() o la comparación alfabética de los textos de los elementos si no se ha especificado ninguno.

Hay que tener en cuenta que actualmente no hay forma de restablecer el orden de clasificación.

Parámetros

col: Un índice de columna válido.
ascendingOrder: Indica si los elementos deben ordenarse en orden ascendente (de la A a la Z) o descendente (de la Z a la A).

UncheckItem()

void wxTreeListCtrl::UncheckItem(wxTreeListItem item)

Desmarca el elemento dado.

Es sinónimo de CheckItem(wxCHK_UNCHECKED).

Unselect()

void wxTreeListCtrl::Unselect(wxTreeListItem item)

Deselecciona el elemento dado.

Este método sólo se puede utilizar en el modo de selección múltiple.

UnselectAll()

void wxTreeListCtrl::UnselectAll()

Deselecciona todos los elementos de control.

Sólo se puede utilizar en el modo de selección múltiple.

UpdateItemParentStateRecursively()

void wxTreeListCtrl::UpdateItemParentStateRecursively(wxTreeListItem item)

Actualiza el estado del elemento padre para reflejar el estado comprobado de sus hijos.

Este método actualiza el elemento padre de forma recursiva: si este elemento y todos sus hermanos están marcados, el elemento padre también lo estará. Si este elemento y todos sus hermanos están desmarcados, el padre también lo estará. Y si los hermanos de este elemento no están todos en el mismo estado, el padre pasará a estado indeterminado. Y entonces la misma lógica se aplicará al padre padre y así recursivamente.

Esta función se llama normalmente cuando el estado del elemento dado ha cambiado desde el manejador EVT_TREELIST_ITEM_CHECKED() en los controles que tienen la bandera wxTL_3STATE. Hay que tener en cuenta que sin esta bandera esta función no puede trabajar, ya que sería incapaz de establecer el estado de un padre con ambos elementos comprobados y no comprobados por lo que sólo se le permite llamar cuando esta bandera está activada.

WidthFor()

int wxTreeListCtrl::WidthFor(const wxString & text) const

Obtiene el ancho apropiado para mostrar el texto dado.

Se suele utilizar como segundo argumento para AppendColumn() o con SetColumnWidth().

Datos miembro

NO_IMAGE

const int wxTreeListCtrl::NO_IMAGE = -1

Constante que indica que no se debe utilizar ninguna imagen para un elemento.

Métodos y datos heredados

Esta clase hereda los métodos y datos miembro públicos y protegidos de wxObject, wxWindow y wxEvtHandle.