listbox.h

Clase wxListBox

Un cuadro de lista se utiliza para seleccionar una o varias cadenas de una lista.

Jerarquía:

Las cadenas se muestran en un cuadro desplazable, con la cadena o cadenas seleccionadas marcadas en vídeo inverso. Un cuadro de lista puede ser de selección única (si se selecciona un elemento, se elimina la selección anterior) o de selección múltiple (al hacer clic en un elemento, éste se activa o desactiva independientemente de otras selecciones).

Los elementos de un cuadro de lista se numeran a partir de cero y, aunque el número máximo de elementos es ilimitado, normalmente es mejor utilizar un control virtual, que no requiera añadir todos los elementos a la vez, como wxDataViewCtrl o wxListCtrl con estilo wxLC_VIRTUAL, cuando se necesiten mostrar más de unos pocos cientos de elementos, ya que este control no está optimizado, ni desde el punto de vista del rendimiento ni desde el de la interfaz de usuario, para un gran número de elementos.

Observar que el cuadro de lista no admite caracteres de control distintos de TAB.

Estilos

Esta clase soporta los siguientes estilos:

wxLB_SINGLE: Lista de selección única.
wxLB_MULTIPLE: Lista de selección múltiple: el usuario puede activar y desactivar varios elementos. Es lo mismo que wxLB_EXTENDED en el soporte para wxGTK2.
wxLB_EXTENDED: Lista de selección extendida: el usuario puede extender la selección utilizando las teclas SHIFT o CTRL junto con las teclas de movimiento del cursor o el ratón.
wxLB_HSCROLL: Crea una barra de desplazamiento horizontal si el contenido es demasiado ancho (sólo Windows).
wxLB_ALWAYS_SB: Mostrar siempre una barra de desplazamiento vertical.
wxLB_NEEDED_SB: Sólo crea una barra de desplazamiento vertical si es necesario.
wxLB_NO_SB: No crear barra de desplazamiento vertical (sólo wxMSW y wxGTK).
wxLB_SORT: El contenido del listbox se ordena por orden alfabético.

Hay que tener en cuenta que los estilos wxLB_SINGLE, wxLB_MULTIPLE y wxLB_EXTENDED son mutuamente excluyentes y se puede especificar como máximo uno de ellos (la selección única es la predeterminada). Ver también los estilos de ventana.

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(wxCommandEvent& event)

Macros para eventos emitidos por esta clase:

EVT_LISTBOX(id, func): Procesa un evento wxEVT_LISTBOX, cuando se selecciona un elemento de la lista o cambia la selección.
EVT_LISTBOX_DCLICK(id, func): Procesa un evento wxEVT_LISTBOX_DCLICK, cuando se hace doble clic en el listbox. En algunas plataformas (especialmente wxGTK2) pulsar la tecla intro se maneja como un equivalente a un doble click.

Funciones miembro

wxListBox()

wxListBox::wxListBox()

Constructor por defecto.

wxListBox()

wxListBox::wxListBox( wxWindow * parent, wxWindowID id, const wxPoint & pos = wxDefaultPosition, const wxSize & size = wxDefaultSize, int n = 0, const wxString choices[] = NULL, long style = 0, const wxValidator & validator = wxDefaultValidator, const wxString & name = wxListBoxNameStr )

Constructor que crea y muestra un cuadro de lista.

Parámetros

parent: La ventana padre.
id: El ID de este control. Un valor de wxID_ANY indica un valor por defecto.
pos: La posición inicial. Si se especifica wxDefaultPosition se elige una posición por defecto.
size: Tamaño inicial. Si se especifica wxDefaultSize entonces la ventana se dimensiona adecuadamente.
n: Número de cadenas con las que se inicializa el control.
choices: Las cadenas a utilizar para inicializar el control.
style: Estilo de la ventana.
validator: El validador para este control.
name: El nombre de esta clase.

Nota: No soportado por wxPerl.

wxListBox()

wxListBox::wxListBox( wxWindow * parent, wxWindowID id, const wxPoint & pos = wxDefaultPosition, const wxSize & size = wxDefaultSize, const wxArrayString & choices, long style = 0, const wxValidator & validator = wxDefaultValidator, const wxString & name = wxListBoxNameStr )

Constructor que crea y muestra un cuadro de lista.

Ver el otro constructor wxListBox(); la única diferencia es que esta sobrecarga toma un wxArrayString en lugar de un puntero a un array de wxString.

Nota: Utilizar una referencia a un array para el parámetro choices.

~wxListBox()

virtual wxListBox::~wxListBox()

Destructor, destruye el list box.

Create()

bool wxListBox::Create( wxWindow * parent, wxWindowID id, const wxPoint & pos = wxDefaultPosition, const wxSize & size = wxDefaultSize, const wxArrayString & choices, long style = 0, const wxValidator & validator = wxDefaultValidator, const wxString & name = wxListBoxNameStr )

Crea el listbox para la construcción en dos pasos.

Create()

bool wxListBox::Create( wxWindow * parent, wxWindowID id, const wxPoint & pos = wxDefaultPosition, const wxSize & size = wxDefaultSize, int n = 0, const wxString choices[] = NULL, long style = 0, const wxValidator & validator = wxDefaultValidator, const wxString & name = wxListBoxNameStr )

Crea el listbox para la construcción en dos pasos.

Deselect()

void wxListBox::Deselect(int n)

Deselecciona un elemento del cuadro de lista.

Parámetros

n: El elemento de base cero que se va a deseleccionar.

Observaciones

Sólo se aplica a los cuadros de lista de selección múltiple.

EnsureVisible()

virtual void wxListBox::EnsureVisible(int n)

Asegura que el elemento con el índice dado se muestra actualmente.

Este método desplaza el cuadro de lista sólo si es necesario y no hace nada si este elemento ya se muestra, a diferencia de SetFirstItem().

FindString()

virtual int wxListBox::FindString( const wxString & string, bool caseSensitive = false ) const

Busca un elemento cuya etiqueta coincida con la cadena dada.

Parámetros

string: Cadena a buscar.
caseSensitive: Si la búsqueda distingue entre mayúsculas y minúsculas (por defecto no).

Valor de retorno

La posición basada en cero del elemento, o wxNOT_FOUND si no se encontró la cadena.

Reimplementado de wxItemContainerImmutable.

GetCount()

virtual unsigned int wxListBox::GetCount() const

Devuelve el número de elementos del control.

Implementa wxItemContainerImmutable.

GetCountPerPage()

int wxListBox::GetCountPerPage() const

Devuelve el número de elementos que pueden caber verticalmente en el área visible del listbox.

Devuelve -1 si no se ha podido determinar el número de elementos por página. En wxGTK este método sólo puede determinar el número de elementos por página si hay al menos un elemento en el listbox.

GetSelection()

virtual int wxListBox::GetSelection() const

Devuelve el índice del elemento seleccionado o wxNOT_FOUND si no hay ningún elemento seleccionado.

Devuelve

La posición de la selección actual.

Observaciones

Este método sólo puede utilizarse con cuadros de lista de selección única, se debe utilizar wxListBox::GetSelections() para los cuadros de lista con estilo wxLB_MULTIPLE.

Implementa wxItemContainerImmutable.

GetSelections()

virtual int wxListBox::GetSelections(wxArrayInt & selections) const

Rellena un array de ints con las posiciones de los elementos actualmente seleccionados.

Parámetros

selections: Una referencia a una instancia de wxArrayInt que se utiliza para almacenar el resultado de la consulta.

GetString()

virtual wxString wxListBox::GetString(unsigned int n) const

Devuelve la etiqueta del elemento con el índice dado.

El índice debe ser válido, es decir, menor que el valor devuelto por GetCount(), de lo contrario se lanza un assert. Esta función no puede invocarse si el control está vacío.

Parámetros

n: El índice basado en cero.

Valor de retorno

La etiqueta del elemento.

Implementa wxItemContainerImmutable.

GetTopItem()

int wxListBox::GetTopItem() const

Devuelve el índice del elemento visible más alto.

Devuelve wxNOT_FOUND si el método no está implementado para la plataforma actual.

HitTest()

int wxListBox::HitTest(const wxPoint & point) const

Devuelve el elemento localizado en el punto, o wxNOT_FOUND si no hay ningún elemento localizado en el punto.

Actualmente está implementado para los entornos wxMSW, wxMac y wxGTK2.

Parámetros

point: Punto del ítem (en coordenadas cliente) a obtener.

Valor de retorno

Elemento localizado en el punto, o wxNOT_FOUND si no está implementado o el elemento no existe.

HitTest()

int wxListBox::HitTest( int x, int y ) const

Esta es una función miembro sobrecargada, proporcionada por conveniencia. Sólo difiere de la función anterior en los argumentos que acepta.

InsertItems()

void wxListBox::InsertItems( const wxArrayString & items, unsigned int pos )

Inserta el número dado de cadenas antes de la posición especificada.

Parámetros

items: Etiquetas de los elementos a insertar.
pos: Posición antes de la cual insertar los ítems: si pos es 0 los ítems se insertarán al principio del listbox.

Nota: Utilizar una referencia a un array para el parámetro items.

InsertItems()

void wxListBox::InsertItems( unsigned int nItems, const wxString * items, unsigned int pos )

Inserta el número dado de cadenas antes de la posición especificada.

Parámetros

nItems: Número de elementos de la matriz items.
items: Etiquetas de los elementos a insertar.
pos: Posición antes de la cual insertar los ítems: si pos es 0 los ítems se insertarán al principio del listbox.

Nota: No soportado por wxPerl.

IsSelected()

virtual bool wxListBox::IsSelected(int n) const

Determina si un elemento está seleccionado.

Parámetros

n: El índice del elemento basado en cero.

Valor de retorno

true si el ítem dado está seleccionado, false en caso contrario.

IsSorted()

virtual bool wxListBox::IsSorted() const

Devuelve true si el listbox tiene el estilo wxLB_SORT.

Este método está pensado principalmente para uso interno.

MSWSetTabStops()

virtual bool wxListBox::MSWSetTabStops(const wxVector< int > & tabStops)

Función específica de MSW para establecer distancias de tabulación personalizadas.

Los tabuladores se expresan en anchuras de unidad de diálogo, es decir, «cuartos de la anchura media de los caracteres de la fuente seleccionada en el cuadro de lista».

Parámetros

tabStops: Si este argumento está vacío, los tabuladores vuelven a su valor por defecto (cada 32 unidades de diálogo). Si contiene un único elemento, los tabuladores se fijan en cada múltiplo del valor dado. En caso contrario, los tabuladores se fijan en cada elemento de la matriz, que debe estar en orden ascendente.

Valor de retorno

true si se establecen todos los tabuladores especificados, false en caso contrario

Disponibilidad: sólo disponible para la versión wxMSW.

SetFirstItem()

void wxListBox::SetFirstItem(const wxString & string)

Establece el elemento especificado como primer elemento visible.

Parámetros

string: La cadena que debe ser visible.

SetFirstItem()

void wxListBox::SetFirstItem(int n)

Establece el elemento especificado como primer elemento visible.

Parámetros

n: El índice de elemento basado en cero que debe ser visible.

SetSelection()

virtual void wxListBox::SetSelection(int n)

Establece la selección en el elemento n dado o elimina la selección por completo si n == wxNOT_FOUND.

Hay que tener en cuenta que esto no provoca la emisión de ningún evento de comando ni deselecciona ningún otro elemento de los controles que admiten selecciones múltiples.

Parámetros

n: La posición de la cadena a seleccionar, empezando por cero.

Implementa wxItemContainerImmutable.

SetString()

virtual void wxListBox::SetString( unsigned int n, const wxString & string )

Establece la etiqueta para el elemento dado.

Parámetros

n: El índice del elemento en base cero.
string: La etiqueta a establecer.

Implementa wxItemContainerImmutable.

SetStringSelection()

virtual bool wxListBox::SetStringSelection(const wxString & s)

Selecciona el ítem cuya etiqueta coincide con la cadena s.

SetStringSelection()

virtual bool wxListBox::SetStringSelection( const wxString & s, bool select )

Selecciona o deselecciona el ítem cuya etiqueta coincide con la cadena s. Si select es true selecciona el ítem, si es false lo deselecciona.

Métodos y datos heredados

Esta clase hereda los métodos y datos miembro públicos y protegidos de wxControl, wxWindow, wxEvtHandler, wxObject, wxItemContainer y wxItemContainerImmutable.