Dit document beschrijft de progress class waarover het artikel Thermometertje aan de wand, vertel mij eens even de tussenstand, gepubliceerd in SDGN-Magazine nr. 60, werd geschreven.

De documentatie van de thermometer

Eerst zal een formobject moeten worden gecreëerd, op basis van de formclass frm_progress, met behulp van de createobject() functie. Bijvoorbeeld:

 

local loProgress

loProgress = createobject( 'frm_progress' )

*

*  Alhier diverse declaraties.

*  Zie verderop.

*

loProgress.show()

 

Zonder declaraties oogt het venster leeg. Er staan alleen 4 containers op en die hebben bovendien nog de minimum omvang. De containers (ook wel secties genoemd) zijn weer de thuisbasis voor de diverse soorten objecten die aan het venster toegevoegd kunnen worden. De containers zullen altijd onder elkaar, in een specifieke volgorde, worden gehouden. Die volgorde is ingegeven door mijn ideëen over wat gebruikers verwachten van de graphical user interface.

 

De 4 secties/containers:

1	Text	Ruimte voor een of meer tekstblokken.
2	Progress Items	Ruimte voor een of meer progress items.
3	Progress Bars	Ruimte voor een of meer progress bars.
4	Break	Fuimte en faciliteit voor onderbreken van het proces.

 

Deze secties worden hieronder nader uitgewerkt.

Sectie 1: Text

 

Op de volgende wijze kunnen aan de 'text' sectie een of meer teksten worden toegevoegd. (Normaal gesproken zal één tekst volstaan.)

               

local array loText[3]

loText[1] = loProgress.addText('tekst 1')

loText[2] = loProgress.addText('tekst 2',2)

loText[3] = loProgress.addText('tekst 3')

 

Standaard wordt ruimte voor één regel tekst gereserveerd. In het voorbeeld van de 2e declaratie geldt dat er 2 regels voor de tekst worden gereserveerd. De programmeur zal zelf moeten inschatten hoeveel regels de tekst  behoeft. De tekst              zal worden omkaderd.

 

De teksten zijn te manipuleren:

               

loText[1].text( 'Andere tekst' )

loText[1].edtText.<property> = <value>

loText[1].edtText.<method()>                 

 

In de eerste regel wordt de tekst gewoon vervangen. De tweede en derde regel geven aan dat diverse standaard editbox manipulaties mogelijk zijn.

 

Ook zijn de tekstblokken te verwijderen, volgens het LIFO-principe (last-in, first-out):

               

loProgress.removeText()

Sectie 2: Progress Items

 

Op de volgende wijze kunnen aan de 'progress items' sectie meerdere 'progress items' worden toegevoegd:

               

local array loItem[3]

loItem[1] = loProgress.addProgressItem('tekst 1')

loItem[2] = loProgress.addProgressItem('tekst 2', 2 )

loItem[3] = loProgress.addProgressItem('tekst 3')

 

Standaard wordt ruimte voor één regel itemtekst gereserveerd. In het voorbeeld van de 2e declaratie geldt dat er 2 regels voor de itemtekst worden gereserveerd. De programmeur zal zelf moeten inschatten hoeveel regels de itemtekst behoeft.

 

De items zijn te manipuleren:

                              

loItem[1].skip()	&& zal de tekst       lichtgrijs neerzetten
loItem[2].now()	&& zal de 2e tekst vet tonen, ter indicatie dat het item 'nu' wordt behandeld
loItem[3].now()	&& zal de 3e tekst vet tonen en de 2e tekst als 'gedaan' markeren
loItem[3].done()	&& zal de tekst als 'gedaan' markeren
loItem[3].failed()	&& zal de tekst als 'aktie mislukt' markeren

               

Aanvankelijk beginnen de items met de layout 'nog te doen'. Die layout is te herstellen met de aanroep:

               

loItem[3].soon()

 

Bij iedere status hoort een specifiek ikoon.

 

Ook zijn de items te verwijderen, volgens het LIFO-principe (last-in, first-out):

               

loProgress.removeProgressItem()

Sectie 3: Progress Bars

 

Op de volgende wijze kunnen aan de 'progress bars' sectie meerdere 'progress bars' worden toegevoegd:

               

local array loBar[3]

loBar[1] = loProgress.addProgressBar()

loBar[2] = loProgress.addProgressBar()

loBar[3] = loProgress.addProgressBar()

 

De bars zijn te manipuleren:

                              

loBar[1].update( <procent>, <tekst> )

               

De bar is te resetten:

               

loBar[1].reset()

 

Ook zijn de bars te verwijderen, volgens het LIFO-principe (last-in, first-out):

               

loProgress.removeProgressBar()

Sectie 4: Break

 

Op de volgende wijze kan aan de 'break' sectie een 'allow break' worden toegevoegd:

               

local loBreak

loBreak = loProgress.addAllowBreak()

 

Vanaf dat moment is te controleren of de gebruiker het proces wenst te onderbreken:

 

if loProgress.escaped()

   *  breek proces af

endif

 

De 'allow break' is uit te schakelen. Dat kan handig zijn als een gedeelte van het proces geen 'break' mag hebben.

               

loThermo.lAllowBreak = .F.

 

Ook is de 'allow break' weer te verwijderen:

               

loProgress.removeAllowBreak()

 

Vanaf dat moment zal de thermometer niet meer controleren op onderbreken.

Breedte

 

Standaard kent het venster een bepaalde breedte. Soms zijn er teveel teksten, items, etcetera, waardoor het geheel hoger is dan de monitor kan tonen. In dat geval kan met de volgende declaratie de breedte worden aangepast, waarbij nValue een waarde in pixels is:

 

loProgress.formwidth( <nValue> )

               

Hoewel de Formwidth method ook tussentijds kan worden aangeroepen, is het verstandiger de declaratie snel na de createobject() te verrichten.

Clickable Areas

 

De thermometer kent twee gebieden die met de muis aanklikbaar zijn, de titelbalk en de Onderbrekenknop.

               

Door de linkermuisknop ingedrukt te houden op de titelbalk en vervolgens te slepen kan de gebruiker de form verplaatsen.

               

De Onderbrekenknop is alleen beschikbaar als een 'allow break' is toegevoegd aan de 'break' sectie. Aanklikken van de Onderbrekenknop heeft hetzelfde effect als drukken op de ESC-knop. De caption van de nderbrekenknop is instelbaar:

 

loBreak._breakbutton.caption = <text>

               

Wel is het zo dat de class alleen kan controleren op de muispositie en -klik als het even de focus heeft gekregen door de aanroep loProgress.escaped() of loProgress.checkMouse(). Die laatste aanroep is nodig als het om een proces gaat waar een 'allow break' - en dus een loProgress.Escaped() - ongewenst is.

               

Wanneer de class merkt dat de mousepointer boven een 'clickable area' is, dan zal er een beperkt aantal seconden worden gewacht op een muisklik. Mocht die muisklik niet komen, dan zal de focus weer teruggegeven worden aan het proces. Bij de volgende focus wordt er door de thermometerclass niet opnieuw een aantal seconden gewacht als de mousepointer dan nog steeds op precies dezelfde plaats staat. De wachttijd (default is 2 seconden) is instelbaar met een property:

               

loProgress.nWait4Click = <value>