A DocumentListener egy megfigyelői interfész, amely lehetővé teszi, hogy a program értesítést kapjon egy szöveges dokumentum változásairól. A felület a java.util.EventListener interfészt terjeszti ki.
A DocumentListener olyan eseményeket figyel, amelyek egy szöveges dokumentum tartalmának beszúrásakor, törlésekor vagy attribútumainak módosításakor következnek be. A megfigyelőnek a dokumentum változásakor meghívott metódusokat kell megvalósítania.
A DocumentListener szerepe a Swingben
A Swing szöveges komponensei dokumentumokat használnak a megjelenített szöveg tárolására. A DocumentListener feladata, hogy megfigyelőként regisztrálva értesítést fogadjon a dokumentum módosításairól.
Az interfész absztrakt, ezért közvetlenül nem példányosítható. Egy olyan osztálynak kell megvalósítania, amely a dokumentum változásaira reagáló logikát tartalmazza.
A DocumentListener metódusai
| Metódus | Feladata |
|---|---|
| insertUpdate | Értesítést ad arról, hogy beszúrás történt a dokumentumba. |
| removeUpdate | Értesítést ad arról, hogy a dokumentum egy része törlődött. |
| changedUpdate | Értesítést ad arról, hogy egy attribútum vagy attribútumkészlet megváltozott. |
insertUpdate
Az insertUpdate metódus értesítést ad arról, hogy beszúrás történt a dokumentumba. A megadott tartomány az újonnan beszúrt terület határait jelöli.
A metódus paramétere a dokumentumeseményt tartalmazó DocumentEvent e objektum.
removeUpdate
A removeUpdate metódus értesítést ad arról, hogy a dokumentum egy része törlődött. A tartomány annak megfelelően van megadva, amit a nézet a frissítés előtt látott, vagyis a rögzített pozíciók frissítése előtt.
A metódus paramétere a dokumentumeseményt tartalmazó DocumentEvent e objektum.
changedUpdate
A changedUpdate metódus értesítést ad arról, hogy egy attribútum vagy attribútumkészlet megváltozott.
A metódus paramétere a dokumentumeseményt tartalmazó DocumentEvent e objektum.
A DocumentEvent paraméter
Mindhárom metódus egy DocumentEvent típusú eseményobjektumot kap paraméterként. Ez az objektum tartalmazza a dokumentumban bekövetkezett változáshoz kapcsolódó eseményt.
Az insertUpdate metódusban az esemény a frissen beszúrt régiót határolja. A removeUpdate metódusban a tartományt a nézet által a frissítés előtt látott állapot alapján adják meg.
A DocumentListener működésének eseménytípusai
Szöveg beszúrása
Amikor a dokumentumba új tartalom kerül, a DocumentListener az insertUpdate metóduson keresztül kap értesítést. A metódushoz tartozó esemény a frissen beszúrt régiót határolja.
Szöveg törlése
Amikor a dokumentum egy része törlődik, a DocumentListener a removeUpdate metóduson keresztül kap értesítést. A tartomány annak megfelelően van megadva, amit a nézet a frissítés előtt látott.
Attribútum módosítása
Amikor egy attribútum vagy attribútumkészlet változik, a DocumentListener a changedUpdate metóduson keresztül kap értesítést.
Az interfész felépítése
A DocumentListener a java.util.EventListener interfész kiterjesztése. A dokumentációban az interfész három eseménykezelő metódust tartalmaz: insertUpdate, removeUpdate és changedUpdate.
A dokumentált megvalósító osztályok között szerepel a JTextComponent.AccessibleJTextComponent.
A három metódus kapcsolata
A három metódus különböző dokumentumváltozásokhoz tartozik. A beszúrásokat az insertUpdate, a törléseket a removeUpdate, az attribútumok módosítását pedig a changedUpdate kezeli.
Mindegyik metódus ugyanilyen típusú eseményparamétert fogad, vagyis a DocumentEvent e objektumot. A különbség az esemény által jelzett dokumentumváltozás jellegében van.
Java Platform 1.1.7 dokumentációs környezet
A DocumentListener leírása a Java Platform 1.1.7 dokumentációjában szerepel. Az interfész dokumentációs szerkezete tartalmazza az áttekintést, a csomag- és osztályinformációkat, az öröklési fát, valamint a mezők, konstruktorok és metódusok összefoglalását és részletes leírását.
