Třída: cUniEval

Třída cUniEval implementuje univerzální rozhraní pro validaci formulářů, editačních tabulek, zpracování uživatelských povelů od menu a desktop commanderu. Freelance používá jednoduchý a robustní princip validace: každý formulář anebo tabulkový editor může mít vlastní validátor. Aplikace jako taková pak má aplikační validátor. Validátor je objekt následníka třídy cUniEval; v rámci konstrukce formuláře či tabulky se zadává jeho jméno. Při otevření formuláře Freelance automaticky vytvoří objekt validátoru a zaregistruje jeho validační rozhraní.
Validace vždy začíná tak, že Freelance volá metody validátoru při určitých akcích nad formulářem či tabulkou, tedy nikdy explicitně. Validací se obecně rozumí provedení kódu, které tyto metody implementují. Některé metody (onCreate, onLoad, … ) se mohou objevit, přesněji být volány jak v kontextu validace formuláře, tak i tabulky a v případě aplikačního validátoru i v kontextu aplikace.
Rozlišení kontextu a původce volání je nejdůležitější u sdílených validátorů, což jsou validátory formulářů obsahujících jednu či více tabulek, a to proto, že stejnou metodu (např. onLoad() může volat více než jeden objekt).
Zde je tedy nanejvýš důležité

· Zjistit, zda kontextem je formulář či tabulka. K tomu slouží informativní metody inForm() či inBrowse().

· Pohybovat se pouze ve zjištěném kontextu, tj. volat pouze ty manipulační metody (metody pracující s obsahem ovl. prvků formuláře či tabulky), které v daném kontextu mají smysl.

Členské proměnné

protected cForm form;

reference na formulář. Platná, probíhá-li validace ovládacího prvku formuláře anebo volání některé notifikační metody pro formulář (onCreate, onLoad…)

protected cBrowse browse;

reference na editační tabulku. Platná, probíhá-li validace sloupce tabulky anebo volání některé notifikační metody pro tabulku (onLoad…)

protected cApplet applet;

reference na vlastní aplet

protected cSql sql;

reference na SQL objekt

Rozhraní validátoru - validace formuláře a tabulky
Libovolnou z metod popsaných v následující tabulce může validátor překrýt. Platí pravidlo, že v překryté metodě se vždy nejprve volá metoda předka. Pokud metoda vrací boolean a volání předka vrátí false (např. onValidate), vrací se vždy false.

Metoda	Formulář	Tabulka
public void onCreate( String objName ) metoda volaná bezprostředně po vytvoření objektu včetně jeho dětí (ovl. prvků). Parametrem je jméno vytvořeného objektu.	*	*
public void onNew() metoda volaná po vyprázdnění formuláře metodou clear() anebo po vložení nové řádky do edit. tabulky	*	*
public void onLoad() metoda volaná po načtení dat do formuláře metodou load() anebo po načtení řádky dat z databáze do edit. tabulky	*	*
public boolean onValidate( String itemName ) stěžejní metoda volaná při každé validaci ovládacího prvku formuláře anebo sloupce tabulky. Parametrem je jméno ovládacího prvku, případně sloupce tabulky. Vrátí-li false, přesune se fokus do validovaného prvku.	*	*
public boolean canSave() metoda volaná před spuštěním ukládání dat formuláře či tabulky. Vrátí-li false, ukládání je odvoláno.	*	*
public boolean onMenu( cMenu menu ) metoda volaná při vyvolání některé položky menu. Kód akce je uložen v proměnné menu.menuId, variantní parametr menu je dostupný voláním menu.getVariant().	*
public void onShowTab( int tabIndex ) metoda volaná při přepnutí aktivní záložky formuláře (cTabForm, cWFXForm).	*
public boolean onCustomSave() metoda volaná v případě, že formulář nemá definován saveCommand (tj. FastX příkaz pro ukládání dat) ani připojený X modul. Používá se například při zápisu dat z formuláře do formuláře či tabulky.	*
public void onDeleteRow( boolean unDelete ) metoda volaná při změně stavu zrušení řádky tabulky.		*
public boolean onRowValidate() metoda volaná při změně aktivní řádky tabulky, před kterou došlo k modifikaci obsahu některé buňky.
public boolean onRowHeaderClick(MouseEvent e, long rowNumber ) metoda volaná při poklepání na záhlaví řádky tabulky. Vrátí-li true, je potlačena implicitní akce.		*
public boolean onColumnHeaderClick(MouseEvent e, int columnId ) metoda volaná při poklepání na záhlaví sloupce tabulky. Vrátí-li true, je potlačena implicitní akce.		*
public boolean forEachFunction() metoda volaná iteračními metodami třídy cBrowse		*

Manipulační metody – čtení a zápis ovládacích prvků a sloupců tabulky

Metoda

public String getText( String itemName)
public long getLong( String itemName)
public double getDouble( String itemName)
public ctDateTime getDateTime( String itemName)

metody vrací obsah ovládacího prvku anebo sloupce tabulky (dle kontextu) identifikovaného jménem. Liší se typem návratové hodnoty a konverzí.

public void setText( String itemName, String text)
public void setLong( String itemName, long lValue)
public void setDouble( String itemName, double dValue)
public void setDateTime( String itemName, ctDateTime dateTime)

metody nastaví obsah ovládacího prvku anebo sloupce tabulky (dle kontextu) identifikovaného jménem. Liší se typem zapisované hodnoty a konverzí.

Speciální manipulační metody – čtení a zápis ovládacích prvků formuláře
Následující metody pracují vždy nad ovládacím prvky formuláře – tedy i v kontextu validace tabulky. Slouží k jednoduchému zpřístupnění ovládacích prvků i z kontextu tabulky, což je dost často zapotřebí.

Metoda

public String getFormText( String itemName)
public long getFormLong( String itemName)
public double getFormDouble( String itemName)
public ctDateTime getFormDateTime( String itemName)

metody vrací obsah ovládacího prvku identifikovaného jménem. Liší se typem návratové hodnoty a konverzí.

public cControl getFormControl ( String itemName )

metoda vrátí referenci na objekt ovládacího prvku identifikovaného jménem.

public void setFormText( String itemName, String text)
public void setFormLong( String itemName, long lValue)
public void setFormDouble( String itemName, double dValue)
public void setFormDateTime( String itemName, ctDateTime dateTime)

metody nastaví obsah ovládacího prvku identifikovaného jménem. Liší se typem zapisované hodnoty a konverzí.

Metody zpřístupňující ovládací prvky (kontext formuláře)

public cControl getControl( String itemName )

metoda vrátí odkaz na jmenovaný ovládací prvek anebo null, pokud nebyl nalezen. Je-li ovládací prvek jiného typu (cEdit, cChoice,...), lze výsledek přetypovat.

public cBrowse getBrowse( String itemName )

metoda vrátí odkaz na jmenovanou edit. tabulku ovládací prvek anebo null, pokud nebyla nalezena. Metoda je identická s getControl() s tím rozdílem, že výsledek přetypovává na cBrowse.

Metody nastavující kontext

Následující metody pracují s kontextem validátoru. Používají se v pouze ve výjimečných případech, nikoli ve standardních metodách on*, které popisuje tento dokument. Kupříkladu chceme-li volat get* /set* metody z jiné metody, například nějakého rozhraní. Typický případ: validátor implementuje rozhraní iEditNotification a metodu iEdited. V této metodě chceme volat metody getText..., setText... apod. Musíme tedy explicitně nastavit kontext validátoru a na konci jej opět zrušit.

public void setForm( cForm f )

metoda nastaví kontext validátoru na daný formulář. Všechny metody pracující s ovládacími prvky a jejich hodnotami se vztahují k tomuto formuláři. Po skončení práce musí být kontext uvolněn metodou endAction().

public void setBrowse( cBrowse b )

metoda nastaví kontext validátoru na daný browse - edit. tabulku. Všechny metody pracující s ovládacími prvky a jejich hodnotami se vztahují k tomuto browsu. Po skončení práce musí být kontext uvolněn metodou endAction().

public void endAction()

metoda uvolní kontext validátoru alokovaný některou z metod setForm(), setBrowse().

Code Sample

Další metody

public boolean checkFormSaved()

metoda zjistí, zda změny provedené uživatelem byly uloženy. Pokud ne, spustí proceduru ukládání dat. Vrací false, pokud ukládání dat selže.

public static String par( String parName, String value )

metoda vrací formátovaný parametr pro FastX server ( |<parName>=<value> ). Slouží k přehlednému sestavování parametrů FastX příkazů. spouštěných metodami jako <cRequester>.fastx(), applet.openFastXDocument(),applet.openFastXDocumentIn(), applet.wro() apod. Metoda je identická s cApplet.par().

Příklady:

applet.openFastXDocument( "x", par( "Name", "xmodule1" ) + par( "ID", "1" ) + par( "DATE", "1.1.2001" ) );
applet.wro( "report1.wro" + par( "PARTNER", "%" ) + par( "DATE", "1.1.2001" ) );
applet.hp( "homepage.hp" + par( "USER", "?" ) + par( "DATE", "1.1.2001" ) );

public static String parDouble( String parName, double value )

metoda podobná metodě par(). Pracuje s proměnnou typu double.

public static String parList( String parNameList, String valueList, String valDelimiter )

metoda podobná metodě par(). Pracuje se sezname jmen parametrů oddělených čárkou (parNameList) a hodnotami parametrů (valueList) oddělenými znakem valDelimiter. Metoda slouží k hromadnému předávání parametrů.

public String ctlPar( String ctlName )

metoda vrací formátovaný parametr pro FastX server ( |<ctlName>=getText(<value>) ). Narozdíl od par() pracuje s pojmenovaným ovládacím prvkem formuláře (případně sloupcem editační tabulky, je-li volána v kontextu browse). Slouží k přehlednému sestavování parametrů FastX příkazů. spouštěných metodami jako <cRequester>.fastx(), applet.openFastXDocument(),applet.openFastXDocumentIn(), applet.wro() apod.

Příklady:

applet.openFastXDocument( "x", ctlPar( "NAME" ) + ctlPar( "ID" ) + par( "DATE", "1.1.2001" ) );
applet.wro( "report1.wro" + ctlPar( "PARTNER" ) + par( "DATE", "1.1.2001" ) );

public boolean setLimitsBySqlQuery( String query, String editList ) /* kontext formuláře */

metoda zjistí délky sloupců v zadaném SQL SELECT příkazu query a omezí jimi editační délku editačních polí, jejichž jmenný seznam (oddělený čárkami) obsahuje parametr editList. Volá se zpravidla v onCreate().

public boolean setLimitsBySql( String table, String columns, String editList ) /* kontext formuláře */

metoda sestaví SELECT příkaz ze jména tabulky a seznamu sloupců (výrazů). Poté zjistí délky sloupců v SELECT příkazu a omezí jimi editační délku editačních polí, jejichž jmenný seznam (oddělený čárkami) obsahuje parametr editList. Volá se zpravidla v onCreate().

Code Sample