Share via

Informationen zu Listenfeldern

  • Artikel

Ein Listenfeldsteuerelement enthält eine einfache Liste, aus der der Benutzer in der Regel ein oder mehrere Elemente auswählen kann. Listenfelder bieten im Vergleich zu Listenansichtssteuerelementen eine begrenzte Flexibilität.

Listenfeldelemente können durch Textzeichenfolgen, Bitmaps oder beides dargestellt werden. Wenn das Listenfeld nicht groß genug ist, um alle Listenfeldelemente gleichzeitig anzuzeigen, stellt das Listenfeld eine Bildlaufleiste bereit. Der Benutzer scrollt durch die Listenfeldelemente und wendet die Auswahl status nach Bedarf an oder entfernt sie. Durch die Auswahl eines Listenfeldelements ändert sich das visuelle Erscheinungsbild, in der Regel durch Ändern der Text- und Hintergrundfarben in die in den relevanten Betriebssystemmetriken angegebenen Farben. Wenn der Benutzer ein Element auswählt oder deaktiviert, sendet das System eine Benachrichtigung an das übergeordnete Fenster des Listenfelds.

Bei einer ANSI-Anwendung konvertiert das System den Text in einem Listenfeld mithilfe der CP_ACP Codepage in Unicode. Dies kann zu Problemen führen. Beispielsweise werden römische Zeichen mit Akzenten in einem Nicht-Unicode-Listenfeld in Windows, japanische Version, verworren angezeigt. Um dies zu beheben, kompilieren Sie entweder die Anwendung als Unicode, oder verwenden Sie ein vom Besitzer gezeichnetes Listenfeld.

In diesem Abschnitt werden die folgenden Themen erläutert:

Erstellen eines Listenfelds

Die einfachste Möglichkeit zum Erstellen eines Listenfelds in einem Dialogfeld besteht darin, es aus der Toolbox in Microsoft Visual Studio auf Ihre Dialogressource zu ziehen. Um ein Listenfeld dynamisch zu erstellen oder ein Listenfeld in einem anderen Fenster als einem Dialogfeld zu erstellen, verwenden Sie die CreateWindowEx-Funktion , indem Sie die WC_LISTBOX Fensterklasse und die entsprechenden Listenfeldstile angeben.

Listenfeldtypen und -formatvorlagen

Es gibt zwei Arten von Listenfeldern: Einzelauswahl (Standard) und Mehrfachauswahl. In einem Listenfeld mit einzeler Auswahl kann der Benutzer jeweils nur ein Element auswählen. In einem Listenfeld mit mehrfacher Auswahl kann der Benutzer mehrere Elemente gleichzeitig auswählen. Um ein Listenfeld mit mehrfacher Auswahl zu erstellen, geben Sie die LBS_MULTIPLESEL - oder LBS_EXTENDEDSEL-Format an.

Die Darstellung und der Vorgang eines Listenfelds werden durch Listenfeldstile und Fensterstile gesteuert. Diese Formatvorlagen geben an, ob die Liste sortiert, in mehreren Spalten angeordnet, von der Anwendung gezeichnet ist usw. Die Dimensionen und Stile eines Listenfelds werden in der Regel in einer Dialogfeldvorlage definiert, die in den Ressourcen einer Anwendung enthalten ist.

Hinweis

Um visuelle Stile mit diesen Steuerelementen zu verwenden, muss eine Anwendung ein Manifest enthalten und Am Anfang des Programms InitCommonControls aufrufen. Informationen zu visuellen Formatvorlagen finden Sie unter Visuelle Stile. Informationen zu Manifesten finden Sie unter Aktivieren von visuellen Formatvorlagen.

Listenfeldfunktionen

Die DlgDirList-Funktion ersetzt den Inhalt eines Listenfelds durch die Namen von Laufwerken, Verzeichnissen und Dateien, die einem angegebenen Satz von Kriterien entsprechen. Die DlgDirSelectEx-Funktion ruft die aktuelle Auswahl in einem Listenfeld ab, das von DlgDirList initialisiert wird. Diese Funktionen ermöglichen es dem Benutzer, ein Laufwerk, ein Verzeichnis oder eine Datei aus einem Listenfeld auszuwählen, ohne den Speicherort und den Namen der Datei einzugeben.

Außerdem gibt die GetListBoxInfo-Funktion die Anzahl der Elemente pro Spalte in einem angegebenen Listenfeld zurück.

Benachrichtigungsmeldungen aus Listenfeldern

Wenn ein Ereignis in einem Listenfeld auftritt, sendet das Listenfeld einen Benachrichtigungscode in Form einer WM_COMMAND Nachricht an die Dialogfeldprozedur des Besitzerfensters. Listenfeldbenachrichtigungscodes werden gesendet, wenn ein Benutzer ein Listenfeldelement auswählt, doppelt klickt oder abbricht. wenn das Listenfeld den Tastaturfokus empfängt oder verliert; und wenn das System nicht genügend Arbeitsspeicher für eine Listenfeldanforderung zuweisen kann. Eine WM_COMMAND Nachricht enthält den Listenfeldbezeichner im Wort mit niedriger Reihenfolge des wParam-Parameters und den Benachrichtigungscode im Wort mit hoher Reihenfolge. Der lParam-Parameter enthält das Steuerelementfensterhandle.

Eine Dialogfeldprozedur ist nicht erforderlich, um diese Nachrichten zu verarbeiten. die Standardfensterprozedur verarbeitet sie.

Eine Anwendung sollte die folgenden Listenfeldbenachrichtigungscodes überwachen und verarbeiten.

Benachrichtigungscode BESCHREIBUNG
LBN_DBLCLK Der Benutzer doppelklicken auf ein Element im Listenfeld.
LBN_ERRSPACE Das Listenfeld kann nicht genügend Arbeitsspeicher zuweisen, um eine Anforderung zu erfüllen.
LBN_KILLFOCUS Das Listenfeld verliert den Tastaturfokus.
LBN_SELCANCEL Der Benutzer bricht die Auswahl eines Elements im Listenfeld ab.
LBN_SELCHANGE Die Auswahl in einem Listenfeld wird sich gerade ändern.
LBN_SETFOCUS Das Listenfeld empfängt den Tastaturfokus.

Nachrichten an Listenfelder

Eine Dialogfeldprozedur kann Nachrichten an ein Listenfeld senden, um Listenfeldelemente hinzuzufügen, zu löschen, zu untersuchen und zu ändern. Beispielsweise könnte eine Dialogfeldprozedur eine LB_ADDSTRING Nachricht an ein Listenfeld senden, um ein Element hinzuzufügen, und eine LB_GETSEL Nachricht, um zu bestimmen, ob das Element ausgewählt ist. Andere Nachrichten legen Fest und rufen Informationen über die Größe, darstellung und das Verhalten des Listenfelds ab. Die LB_SETHORIZONTALEXTENT Nachricht legt beispielsweise die scrollbare Breite eines Listenfelds fest. Eine Dialogfeldprozedur kann jede Nachricht mithilfe der Funktion SendMessage oder SendDlgItemMessage an ein Listenfeld senden.

Auf ein Listenfeldelement wird häufig durch seinen Index verwiesen, eine ganze Zahl, die die Position des Elements im Listenfeld darstellt. Der Index des ersten Elements in einem Listenfeld ist 0, der Index des zweiten Elements ist 1 usw.

In der folgenden Tabelle wird beschrieben, wie die vordefinierte Listenfeldprozedur auf Listenfeldmeldungen reagiert.

Nachricht Antwort
LB_ADDFILE Fügt eine Datei in ein Verzeichnislistenfeld ein, das von der DlgDirList-Funktion gefüllt wird, und ruft den Listenfeldindex des eingefügten Elements ab.
LB_ADDSTRING Fügt einem Listenfeld eine Zeichenfolge hinzu und gibt seinen Index zurück.
LB_DELETESTRING Entfernt eine Zeichenfolge aus einem Listenfeld und gibt die Anzahl der Zeichenfolgen zurück, die in der Liste verbleiben.
LB_DIR Fügt einem Listenfeld eine Liste mit Dateinamen hinzu und gibt den Index des zuletzt hinzugefügten Dateinamens zurück.
LB_FINDSTRING Gibt den Index der ersten Zeichenfolge im Listenfeld zurück, der mit einer angegebenen Zeichenfolge beginnt.
LB_FINDSTRINGEXACT Gibt den Index der Zeichenfolge im Listenfeld zurück, der einer angegebenen Zeichenfolge entspricht.
LB_GETANCHORINDEX Gibt den Index des Elements zurück, das die Maus zuletzt ausgewählt hat.
LB_GETCARETINDEX Gibt den Index des Elements zurück, das über das Fokusrechteck verfügt.
LB_GETCOUNT Gibt die Anzahl der Elemente im Listenfeld zurück.
LB_GETCURSEL Gibt den Index des aktuell ausgewählten Elements zurück.
LB_GETHORIZONTALEXTENT Gibt die scrollbare Breite eines Listenfelds in Pixel zurück.
LB_GETITEMDATA Gibt den Wert zurück, der dem angegebenen Element zugeordnet ist.
LB_GETITEMHEIGHT Gibt die Höhe eines Elements in einem Listenfeld in Pixel zurück.
LB_GETITEMRECT Ruft die Clientkoordinaten des angegebenen Listenfeldelements ab.
LB_GETLOCALE Ruft das Gebietsschema des Listenfelds ab. Das Wort mit hoher Ordnung enthält den Länder-/Regionscode, und das Wort mit niedriger Ordnung enthält den Sprachbezeichner.
LB_GETSEL Gibt den Auswahlstatus eines Listenfeldelements zurück.
LB_GETSELCOUNT Gibt die Anzahl der ausgewählten Elemente in einem Mehrfachauswahllistenfeld zurück.
LB_GETSELITEMS Erstellt ein Array der Indizes aller ausgewählten Elemente in einem Mehrfachauswahllistenfeld und gibt die Gesamtanzahl der ausgewählten Elemente zurück.
LB_GETTEXT Ruft die einem angegebenen Element zugeordnete Zeichenfolge und die Länge der Zeichenfolge ab.
LB_GETTEXTLEN Gibt die Länge der einem angegebenen Element zugeordneten Zeichenfolge in Zeichen zurück.
LB_GETTOPINDEX Gibt den Index des ersten sichtbaren Elements in einem Listenfeld zurück.
LB_INITSTORAGE Ordnet Arbeitsspeicher für die angegebene Anzahl von Elementen und die zugehörigen Zeichenfolgen zu.
LB_INSERTSTRING Fügt eine Zeichenfolge an einem angegebenen Index in ein Listenfeld ein.
LB_ITEMFROMPOINT Ruft den nullbasierten Index des Elements ab, das dem angegebenen Punkt in einem Listenfeld am nächsten liegt.
LB_RESETCONTENT Entfernt alle Elemente aus einem Listenfeld.
LB_SELECTSTRING Wählt die erste gefundene Zeichenfolge aus, die mit einem angegebenen Präfix übereinstimmt.
LB_SELITEMRANGE Wählt einen angegebenen Bereich von Elementen in einem Listenfeld aus.
LB_SELITEMRANGEEX Wählt einen angegebenen Elementbereich aus, wenn der Index des ersten Elements im Bereich kleiner als der Index des letzten Elements im Bereich ist. Bricht die Auswahl im Bereich ab, wenn der Index des ersten Elements größer als das letzte ist.
LB_SETANCHORINDEX Legt das Element, das die Maus zuletzt ausgewählt hat, auf ein angegebenes Element fest.
LB_SETCARETINDEX Legt das Fokusrechteck auf ein angegebenes Listenfeldelement fest.
LB_SETCOLUMNWIDTH Legt die Breite aller Spalten in einem Listenfeld in Pixel fest.
LB_SETCOUNT Legt die Anzahl der Elemente in einem Listenfeld fest.
LB_SETCURSEL Wählt ein angegebenes Listenfeldelement aus.
LB_SETHORIZONTALEXTENT Legt die scrollbare Breite eines Listenfelds in Pixel fest.
LB_SETITEMDATA Ordnet einem Listenfeldelement einen Wert zu.
LB_SETITEMHEIGHT Legt die Höhe eines Elements oder elementes in einem Listenfeld in Pixel fest.
LB_SETLOCALE Legt das Gebietsschema eines Listenfelds fest und gibt den vorherigen Gebietsschemabezeichner zurück.
LB_SETSEL Wählt ein Element in einem Mehrfachauswahllistenfeld aus.
LB_SETTABSTOPS Legt die Tabstopps auf die in einem angegebenen Array angegebenen fest.
LB_SETTOPINDEX Führt einen Bildlauf im Listenfeld durch, sodass sich das angegebene Element am oberen Rand des sichtbaren Bereichs befindet.

Standardfenster-Nachrichtenverarbeitung

Die Fensterprozedur für die vordefinierte Listenfeldfensterklasse führt die Standardverarbeitung für alle Nachrichten durch, die das Listenfeld nicht verarbeitet. Wenn die Listenfeldprozedur false für eine Nachricht zurückgibt, überprüft die vordefinierte Fensterprozedur die Nachricht und führt Standardaktionen aus, wie in der folgenden Tabelle gezeigt.

Nachricht Standardaktion
WM_CHAR Verschiebt die Auswahl auf das erste Element, das mit dem zeichen beginnt, das der Benutzer eingegeben hat. Wenn das Listenfeld das Format LBS_OWNERDRAW aufweist, wird keine Aktion ausgeführt. Mehrere Zeichen, die innerhalb eines kurzen Intervalls eingegeben werden, werden als Gruppe behandelt, und das erste Element, das mit dieser Zeichenreihe beginnt, wird ausgewählt.
WM_CREATE Erstellt ein leeres Listenfeld.
WM_DESTROY Zerstört das Listenfeld und gibt alle ressourcen frei, die es verwendet.
Übergibt die Nachricht an die Dialogfeldprozedur oder den Prozess des übergeordneten Fensters.
WM_ENABLE Wenn das Steuerelement sichtbar ist, wird das Rechteck ungültig, damit die Zeichenfolgen grau gezeichnet werden können.
WM_ERASEBKGND Löscht den Hintergrund eines Listenfelds. Wenn das Listenfeld das Format LBS_OWNERDRAW aufweist, wird der Hintergrund nicht gelöscht.
WM_GETDLGCODE Gibt DLGC_WANTARROWS | DLGC_WANTCHARS, die angibt, dass die Standardmäßige Listenfeldprozedur die Pfeiltasten und WM_CHAR Nachrichten verarbeitet.
WM_GETFONT Gibt ein Handle an die aktuelle Schriftart für das Listenfeld zurück.
WM_HSCROLL Führt einen horizontalen Bildlauf im Listenfeld durch.
WM_KEYDOWN Verarbeitet virtuelle Schlüssel zum Scrollen. Der virtuelle Schlüssel ist der Index des Elements, in das das Caretzeichen verschoben werden soll. Die Auswahl wird nicht geändert.
WM_KILLFOCUS Schaltet das Caret aus und zerstört es. Sendet einen LBN_KILLFOCUS Benachrichtigungscode an den Besitzer des Listenfelds.
WM_LBUTTONDBLCLK Verfolgt die Maus im Clientbereich des Listenfelds nach. Dadurch kann der Benutzer eine Auswahl abbrechen, wenn die Maustaste außerhalb des Clientbereichs des Listenfelds losgelassen wird.
WM_LBUTTONDOWN Verfolgt die Maus im Clientbereich des Listenfelds nach. Dadurch kann der Benutzer eine Auswahl abbrechen, wenn die Maustaste außerhalb des Clientbereichs des Listenfelds losgelassen wird.
WM_LBUTTONUP Verfolgt die Maus im Clientbereich des Listenfelds nach. Dadurch kann der Benutzer eine Auswahl abbrechen, wenn die Maustaste außerhalb des Clientbereichs des Listenfelds freigegeben wird.
WM_MOUSEMOVE Verfolgt die Maus im Clientbereich des Listenfelds nach. Dadurch kann der Benutzer eine Auswahl abbrechen, wenn die Maustaste außerhalb des Clientbereichs des Listenfelds freigegeben wird.
WM_PAINT Führt einen unterklassierten Malvorgang mithilfe des Listenfeldhandles für den Gerätekontext (Device Context, DC) aus.
WM_SETFOCUS Aktiviert das Caret und sendet einen LBN_SETFOCUS Benachrichtigungscode an den Besitzer des Listenfelds.
WM_SETFONT Legt eine neue Schriftart für das Listenfeld fest.
WM_SETREDRAW Legt das Redrawflag basierend auf dem Wert von wParam fest oder löscht es.
WM_SIZE Ändert die Größe des Listenfelds in eine integrale Anzahl von Elementen.
WM_VSCROLL Scrollt das Listenfeld vertikal.

Die vordefinierte Listenfeldprozedur übergibt alle anderen Nachrichten zur Standardverarbeitung an DefWindowProc .

listenfelder Owner-Drawn

Eine Anwendung kann ein vom Besitzer gezeichnetes Listenfeld erstellen, um die Verantwortung für das Malen von Listenelementen zu übernehmen. Das übergeordnete Fenster oder Dialogfeld eines vom Besitzer gezeichneten Listenfelds (dessen Besitzer) empfängt WM_DRAWITEM Nachrichten, wenn ein Teil des Listenfelds gezeichnet werden muss. Ein vom Besitzer gezeichnetes Listenfeld kann andere Informationen als oder zusätzlich zu Textzeichenfolgen auflisten.

Der Besitzer eines vom Besitzer gezeichneten Listenfelds muss die WM_DRAWITEM Nachricht verarbeiten. Diese Nachricht wird immer dann gesendet, wenn ein Teil des Listenfelds neu gezeichnet werden muss. Der Besitzer muss möglicherweise andere Nachrichten verarbeiten, abhängig von den Formaten, die für das Listenfeld angegeben sind.

Eine Anwendung kann ein vom Besitzer gezeichnetes Listenfeld erstellen, indem sie das LBS_OWNERDRAWFIXED - oder LBS_OWNERDRAWVARIABLE-Format angibt. Wenn alle Listenelemente im Listenfeld die gleiche Höhe aufweisen, z. B. Zeichenfolgen oder Symbole, kann eine Anwendung das format LBS_OWNERDRAWFIXED verwenden. Wenn Listenelemente eine unterschiedliche Höhe aufweisen (z. B. Bitmaps unterschiedlicher Größe), kann eine Anwendung den LBS_OWNERDRAWVARIABLE Stil verwenden.

Der Besitzer eines vom Besitzer gezeichneten Listenfelds kann eine WM_MEASUREITEM Nachricht verarbeiten, um die Dimensionen von Listenelementen anzugeben. Wenn die Anwendung das Listenfeld im LBS_OWNERDRAWFIXED-Format erstellt, sendet das System die WM_MEASUREITEM Nachricht nur einmal. Die vom Besitzer angegebenen Dimensionen werden für alle Listenelemente verwendet. Wenn die LBS_OWNERDRAWVARIABLE-Format verwendet wird, sendet das System eine WM_MEASUREITEM Nachricht für jedes Listenelement, das dem Listenfeld hinzugefügt wird. Der Besitzer kann die Höhe eines Listenelements jederzeit mithilfe der LB_GETITEMHEIGHT bzw. LB_SETITEMHEIGHT Nachrichten bestimmen oder festlegen.

Wenn die in einem vom Besitzer gezeichneten Listenfeld angezeigten Informationen Text enthalten, kann eine Anwendung den Text für jedes Listenelement nachverfolgen, indem sie die LBS_HASSTRINGS Formatvorlage angibt. Listenfelder mit dem LBS_SORT Format werden basierend auf diesem Text sortiert. Wenn ein Listenfeld sortiert, aber nicht vom LBS_HASSTRINGS Stil ist, muss der Besitzer die WM_COMPAREITEM Nachricht verarbeiten.

In einem vom Besitzer gezeichneten Listenfeld muss der Besitzer Listenelemente nachverfolgen, die andere Informationen als oder zusätzlich zu Text enthalten. Eine praktische Möglichkeit hierfür ist das Speichern des Handle in den Informationen als Elementdaten mithilfe der LB_SETITEMDATA Nachricht. Um Datenobjekte freizugeben, die Elementen in einem Listenfeld zugeordnet sind, kann der Besitzer die WM_DELETEITEM Nachricht verarbeiten.

Ein Beispiel für ein vom Besitzer gezeichnetes Listenfeld finden Sie unter Erstellen eines Owner-Drawn Listenfelds.

Listenfelder ziehen

Ein Ziehlistenfeld ist ein spezieller Listenfeldtyp, der es dem Benutzer ermöglicht, Elemente von einer Position an eine andere zu ziehen. Eine Anwendung kann ein Ziehlistenfeld verwenden, um Zeichenfolgen in einer bestimmten Sequenz anzuzeigen und es dem Benutzer zu ermöglichen, die Sequenz zu ändern, indem die Elemente in die Position gezogen werden.

Erstellen von Ziehlistenfeldern

Ziehlistenfelder weisen die gleichen Fensterstile auf und verarbeiten dieselben Nachrichten wie Standardlistenfelder. Um ein Ziehlistenfeld zu erstellen, erstellen Sie zuerst ein Standardlistenfeld, und rufen Sie dann die MakeDragList-Funktion auf. Um ein Listenfeld in einem Dialogfeld in ein Ziehlistenfeld zu konvertieren, können Sie MakeDragList aufrufen, wenn die WM_INITDIALOG Nachricht verarbeitet wird.

Ziehen von Listenfeldnachrichten

Ein Ziehlistenfeld benachrichtigt das übergeordnete Fenster von Ziehereignissen, indem es eine Ziehlistennachricht sendet. Das übergeordnete Fenster muss die Ziehlistennachricht verarbeiten.

Das Listenfeld zum Ziehen registriert diese Nachricht, wenn die MakeDragList-Funktion aufgerufen wird. Um den Nachrichtenbezeichner (numerischer Wert) der Ziehlistennachricht abzurufen, rufen Sie die Funktion RegisterWindowMessage auf, und geben Sie den Wert DRAGLISTMSGSTRING an.

Der wParam-Parameter der Ziehlistenmeldung ist der Steuerelementbezeichner für das Ziehlistenfeld. Der lParam-Parameter ist die Adresse einer DRAGLISTINFO-Struktur , die den Benachrichtigungscode für das Drag-Ereignis und andere Informationen enthält. Der Rückgabewert der Nachricht hängt von der Benachrichtigung ab.

Benachrichtigungscodes für Listenfeld ziehen

Der Benachrichtigungscode für die Ziehliste, der durch das Element "uNotification " der DRAGLISTINFO-Struktur identifiziert wird, die in der Ziehlistennachricht enthalten ist, kann DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAG oder DL_DROPPED sein.

Der DL_BEGINDRAG Benachrichtigungscode wird gesendet, wenn sich der Cursor auf einem Listenelement befindet und der Benutzer auf die linke Maustaste klickt. Das übergeordnete Fenster kann TRUE zurückgeben, um den Ziehvorgang zu starten, oder FALSE , um das Ziehen nicht zuzulassen. Auf diese Weise kann das übergeordnete Fenster das Ziehen für einige Listenelemente aktivieren und für andere deaktivieren. Sie können bestimmen, welches Listenelement sich an der angegebenen Position befindet, indem Sie die LBItemFromPt-Funktion verwenden.

Wenn das Ziehen aktiv ist, wird der DL_DRAGGING Benachrichtigungscode gesendet, wenn die Maus bewegt wird, oder in regelmäßigen Abständen, wenn die Maus nicht bewegt wird. Das übergeordnete Fenster sollte zuerst das Listenelement unter dem Cursor mithilfe von LBItemFromPt bestimmen und dann das Einfügesymbol mithilfe der DrawInsert-Funktion zeichnen. Wenn Sie true für den bAutoScroll-Parameter von LBItemFromPt angeben, können Sie bewirken, dass das Listenfeld um eine Zeile scrollt, wenn sich der Cursor oberhalb oder unterhalb des Clientbereichs befindet. Der Wert, den Sie für diese Benachrichtigung zurückgeben, gibt den Typ des Mauscursors an, den das Ziehlistenfeld festlegen soll.

Der DL_CANCELDRAG Benachrichtigungscode wird gesendet, wenn der Benutzer einen Ziehvorgang durch Klicken mit der rechten Maustaste oder Drücken der ESC-Taste abbricht. Der DL_DROPPED Benachrichtigungscode wird gesendet, wenn der Benutzer einen Ziehvorgang durch Loslassen der linken Maustaste abschließt, auch wenn sich der Cursor nicht über einem Listenelement befindet. Das Ziehlistenfeld gibt die Mausaufnahme vor dem Senden einer Benachrichtigung frei. Der Rückgabewert dieser beiden Benachrichtigungen wird ignoriert. Liste ziehen