Asistence pole

Od uživatele se často očekává, že bude zadávat textové informace do jednoduchých polí, jako například do textového pole nebo pole se seznamem. Přestože je kód aplikace, který naplňuje tato pole obecně mnohem jednodušší než kód, který naplňuje komplexní prvky widget (jako například tabulku nebo strom), tato "jednoduchá" pole obvykle kladou větší nároky na uživatele. Uživatel musí určit, která pole vyžadují obsah, zda pole obsahují platný obsah a jaké volby jsou očekávány. Podpora asistence pole JFace poskytuje třídy, které napomáhají vést uživatele při úlohách zadávání vstupů.

Balíček org.eclipse.jface.fieldassist poskytuje asistenci dvěma způsoby. Podpora pro zdobená pole vám umožňuje zahrnout zdobení obrázků, která poskytují uživateli představu o stavu určitého pole. Podpora návrhu obsahu vám umožňuje poskytovat místní nabídky obsahové asistence, které uživateli předkládají možné varianty obsahu.

Zdobená pole

Zdobená pole vám umožňují umísťovat zdobení obrázků vedle polí definovaných v okně nebo v dialogovém okně. Zdobení lze umístit vedle jednoho ze čtyř rohů pole. Podobně jako prohlížeče mají zdobená pole přidávat funkčnost do řízení SWT při zachování přístupu k základnímu řízení. Rozhraní API pro DecoratedField vám umožňuje přidávat, skrývat a zobrazovat zdobení vedle polí. Přístup k základnímu řízení je poskytován, abyste mohli prostřednictvím stávajícího rozhraní API SWT ovlivňovat základní řízení, jako například nastavení obsahu, barvy nebo písma.

Vytváření zdobeného pole

Navenek se zdobené pole chová jako jednotlivý ovládací prvek. Uvnitř používají zdobená pole kompozitní řízení pro správu rozvržení pole a jeho zdobení. Ve většině případů by to nemělo klientským aplikacím vadit. Znamená to ovšem, že zdobené pole musí provést vlastní vytvoření ovládacího prvku. Vezměme si například tento úsek kódu, ve kterém aplikace vytváří textový ovládací prvek uvnitř jednoho ze svých dialogových oken:

...
// Vytvořit textové pole
Text text = new Text(parent, SWT.BORDER);
text.setText("nějaký text");
...

Chcete-li toto pole zdobit, vytvořilo by se následujícím způsobem:

...
// Vytvořit zdobené pole pro textový ovládací prvek
DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("nějaký text");
...

Stejné nadřízené a stylové bity, které se použijí pro vytvoření základního ovládacího prvku se rovněž použijí pro vytvoření zdobeného pole. Hlavním rozdílem v kódu je, že je poskytnuta instance IControlCreator, která vytváří specifický druh ovládacího prvku vyžadovaného v poli. Pro textová pole můžete použít třídu TextControlCreator k vytvoření ovládacího prvku. Máte rovněž naprostou volnost implementovat IControlCreator k vytvoření libovolného druhu ovládacího prvku uvnitř pole, jako např. pole se seznamem nebo prvku spinner.

Použití zdobení

Po vytvoření zdobeného pole je možné do něj přidat zdobení na jedno ze čtyř míst. Konstanty umístění SWT určují, kam je možné zdobení umístit. Chcete-li přidat zdobení, musíte určit FieldDecoration, které označuje obrázek pro zdobení a (volitelně) popisný text, který se zobrazí při najetí kurzorem myši na zdobení.

...
// Vytvořit zdobení pole a přidat je do pole
Image image = JFaceResources.getImage("myplugin.specialimage");
FieldDecoration mySpecialDecoration = new FieldDecoration(image, "This field is special");
field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false);
...

Pomocí logického parametru se určuje, zda má být zdobení zobrazeno neustále, nebo pouze při aplikaci ovládacího prvku. V tomto případě bude zdobení zobrazeno neustále. Mohou se ovšem vyskytnout situace, kdy by mělo být zdobení skryto nebo zobrazeno. Následující úsek kódu skryje již vytvořené zdobení.

...
// Objevilo se něco, kvůli čemu chci skrýt zdobení
field.hideDecoration(mySpecialDecoration);
...

Pokud dojde k aktualizaci obrázku nebo popisu, mělo by o tom být pole informováno, aby bylo možné zdobení překreslit.

...
// Něco činí toto pole zcela speciálním
mySpecialDecoration.setDescription("This field is extra-special");
field.updateDecoration(mySpecialDecoration);
...

Rozvržení zdobených a nezdobených polí

Při rozvržení zdobeného pole uvnitř okna nebo dialogového okna byste měli umístit ovládací prvek rozvržení pole, spíše než základního jednoduchého ovládacího prvku. Vezměte opět v úvahu kód pro vytvoření textového ovládacího prvku. Při rozvržení textového ovládacího prvku nastavuje aplikace data rozvržení na ovládací prvek.

...
// Vytvořit textové pole
Text text = new Text(parent, SWT.BORDER);
text.setText("nějaký text");
// Nastavit data rozvržení
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH, SWT.DEFAULT);
text.setLayoutData(data); 
...

Při rozvržení zdobeného pole by měla aplikace pustit data rozvržení na ovládací prvek rozvržení pole. V závislosti na požadovaném rozvržení může být nutné upravit velikost pole na velikost zdobení.

...
// Vytvořit zdobené pole pro textový ovládací prvek
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("nějaký text");
// Nastavit data rozvržení
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + 
   FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT);
field.getLayoutControl().setLayoutData(data); 
...

Podpora asistence pole nevyžaduje ani nepředpokládá, že v rámci určitého okna či dialogového okna používáte pouze zdobená pole. Rozvržení vašeho okna může být ovšem poněkud složitější, pokud používáte zdobená pole zároveň s jednoduchými ovládacími prvky. Pro uspořádání zdobených a nezdobených polí musíte vzít v úvahu odsazení vytvořené šířkou zdobení. Šířkou zdobení je jednoduše šířka jeho obrázku. Věci se ovšem mohou poněkud zkomplikovat, pokud používáte zdobení s různými šířkami. V takovém případě můžete věci zjednodušit registrováním všech zdobení v FieldDecorationRegistry.

Registr zdobení pole

Registr zdobení pole vám umožňuje registrovat a přistupovat ke zdobením polí pomocí ID řetězce. To usnadňuje odkazování na zdobení použitá v aplikaci. Chcete-li ID zdobení zpřístupnit ostatním modulům plug-in, můžete za tímto účelem definovat rozhraní API, které bude ID zdobení zobrazovat. Vezměte na vědomí, že registrování zdobení neovlivňuje životní cyklus obrázků uvnitř těchto zdobení. Vaše aplikace se může rozhodnout, jak budou tyto obrázky spravovány. Registr obrázků JFace lze například použít pro registraci a správu životního cyklu obrázku. Alternativně může vaše aplikace vytvářet obrázky na vyžádání a po ukončení používání je může odstranit. Dokumentace Javadoc pro metody registrace v FieldDecorationRegistry vysvětluje jednotlivé metody určování obrázků při registraci zdobení.

Registrace zdobení v registru zdobení pole může rovněž zjednodušit proces rozvržení při použití zdobených (a nezdobených) polí. Ve výchozím nastavení zjistí zdobené pole v registru zdobení pole maximální šířku zdobení a zajistí, aby všechna zdobení použila tuto šířku. To znamená, že všechna zdobená pole budou správně zarovnána bez ohledu na šířku kteréhokoli z nich. Chcete-li zarovnat nezdobená pole, můžete pomocí protokolu FieldDecorationRegistry získat šířku největšího zdobení a vytvořit potřebné odsazení.

...
// Vytvořit textové pole
Text text = new Text(parent, SWT.BORDER);
text.setText("nějaký text");
// Nastavit data rozvržení
GridData data = new GridData();
data.horizontalAlignment = SWT.FILL;
data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth();
text.setLayoutData(data); 
...

Přestože podpora asistence pole nestanovuje použití zdobení, registr rovněž definuje standardní zdobení, která lze použít v aplikacích pro zobrazení určitých stavů pole. Následující úsek kódu například používá standardní zdobení pro nezbytná pole:

...
// Vytvořit zdobené pole s požadovaným zdobením.
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
FieldDecoration requiredFieldIndicator = FieldDecorationRegistry.getDefault().
   getFieldDecoration(FieldDecorationRegistry.DEC_REQUIRED);
field.addDecoratedField(requiredFieldIndicator, SWT.BOTTOM | SWT.LEFT, false);
...

Návrhy obsahu

Kromě označení polí zdobením mohou aplikace poskytovat asistenci návrhů obsahu, která pro příslušné pole aktivuje rozevírací okno s návrhy. Tohoto chování dosáhnete nainstalováním ContentProposalAdapter na libovolný ovládací prvek. Následující úsek kódu nainstaluje adaptér návrhu obsahu na textový ovládací prvek. Vezměte na vědomí, že tento textový ovládací prvek může být prvkem vytvořeným přímo aplikací nebo může být získán ze zdobeného pole.

...
autoActivationCharacters = new char[] { '#', '(' };
keyStroke = KeyStroke.getInstance("Ctrl+Space");
// předpokládejme, že nějakým způsobem již došlo k vytvoření myTextControl
ContentProposalAdapter adapter = new ContentProposalAdapter(
	myTextControl, new TextContentAdapter(), 
	new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}),
	keyStroke, autoActivationCharacters);

Aby bylo možné získat a nastavit obsah ovládacího prvku, jakmile uživatel vybere návrh v rozevíracím okně, musí adaptér obsahovat instanci IControlContentAdapter, která může získat a nastavit obsah určitého druhu ovládacího prvku. Pro textová pole můžete použít třídu TextContentAdapter. Máte ovšem naprostou volnost implementovat IControlContentAdapter pro použití adaptéru návrhu obsahu s jakýmkoli jiným druhem ovládacího prvku.

Při vytváření adaptéru návrhu obsahu musíte rovněž určit instanci IContentProposalProvider, ze které budou získávány samotné návrhy. Tento poskytovatel zodpovídá za navracení škály návrhů obsahu. Samotné návrhy jsou specifikovány jako instance IContentProposal, ze kterých lze získat štítek a obsah návrhu a rovněž další informace, jako například podrobný popis návrhu.

Ve výše uvedeném příkladu je použit SimpleContentProposalProvider. Tento poskytovatel je definován zadáním jednoduché škály řetězců jako návrhů obsahu. Jednoduchý poskytovatel implementuje nezbytný protokol pro mapování každého řetězce na očekávaný IContentProposal. Flexibilita IContentProposalProvider vám umožňuje implementovat poskytovatele návrhů s rozšířenými vlastnostmi, jako například filtrování návrhů na základě obsahu ovládacího prvku, poskytnutí vysvětlujících štítků v rozevíracím okně namísto vkládaného aktuálního obsahu a zadání očekávané pozice kurzoru po vložení návrhu. Pro informace o pokročilém použití konzultujte Příklad asistence pole a vyhledejte implementátory IContentProposalProvider.

Konfigurace adaptéru návrhu obsahu

Ukázali jsme si, že základní definice adaptéru návrhu obsahu zahrnuje ovládací prvek, pro který jsou poskytnuty návrhy, adaptér obsahu používaný pro změnu obsahu ovládacího prvku a poskytovatele návrhu, který definuje seznam návrhů v rozevíracím okně. Kromě těchto základů existuje řada dalších možností konfigurace adaptéru návrhu obsahu:

Příklad asistence obsahu vám umožňuje konfigurovat tyto různé volby v předvolbách příkladu a vyzkoušet jejich různé kombinace. Adaptér lze například nakonfigurovat tak, aby byl vyvolán explicitně pomocí stisku klávesy a vložil obsah návrhu do ovládacího prvku, čímž se do značné míry chová jako obsahová asistence textového editoru. Případně může být nakonfigurován bez explicitního stisku klávesy, znaků automatické aktivace a nahrazení obsahu, čímž se chová spíše jako styl dokončení s použitím paměti stisknutých kláves používaný v adresách URL webových prohlížečů nebo ve vyhledávacích polích. Podrobnosti o těchto metodách a jejich vzájemné interakci viz dokumentace Javadoc.

Asistence pole pracovní plochy

Podpora asistence pole na úrovni JFace poskytuje vaší aplikaci značnou flexibilitu při stanovování zdobení polí a zobrazování návrhů pro jejich obsah. To je žádoucí u samostatných aplikací JFace nebo u samostatných aplikací klienta rich. Pokud se má ovšem vaše aplikace integrovat do ostatních modulů plug-in, jako například do Eclipse SDK nebo modulů třetích stran, budete pravděpodobně chtít použít podporu asistence obsahu způsobem, který je konzistentní s ostatními moduly plug-in. Pracovní plocha definuje obslužné třídy, které používají asistenci pole pro specifické druhy interakcí.

Například třída ContentAssistField vytváří pole obsahující symbol žárovky, který oznamuje uživateli dostupnost obsahové asistence. Zároveň konfiguruje adaptér návrhu obsahu pro vložení stylu obsahové asistence. Poskytuje také popisovač pro příkaz obsahové asistence na úrovni pracovní plochy, aby došlo k otevření rozevíracího okna návrhů obsahu, jakmile uživatel stiskne klávesu nebo spustí sekvenci zadanou ve vazbách kláves pracovní plochy. Další podrobnosti o těchto obslužných třídách viz balíček org.eclipse.ui.fieldassist.

U tohoto balíčku se předpokládá, že se bude vyvíjet tak, jak bude pracovní plocha rozšiřovat použití asistence pole a standardizovat použití zdobení pro určité stavy polí.