TrashFlash - a line-by-line explanation
TrashFlash is a small freeware template which will be used to illustrate the principles
of a control template. The purpose of TrashFlash is to allow a browse item to be
dragged over to a trash can icon and deleted. The source code and a demo EXE are
available - click here to
download. (compatible with all versions from CW2002 to C5)
The line numbers down the left hand side will be used to explain each line.
1 #TEMPLATE (TrashABC, 'TrashFlash (ABC) - Sterling Data'),FAMILY('ABC')
2 #!
3 #!
4 #! To use in your own apps:
5 #! 1) Register TRASHABC.TPL (or TRASHLEG.TPL legacy)
6 #! 2) In the Window Formatter select Populate/Control Template
7 #! 3) Click twice where you want the trash can to appear
8 #! 1st click is a region box and 2nd is TRASH01.ICO which should be inside the
region
9 #! 4) If you need any help email me on mike@sterlingdata.com
10 #!
11 #! Mike McLoughlin, October 1999
12 #!
13 #CONTROL (TrashImage, 'TrashFlash Image'), DESCRIPTION('TrashFlash
Image/Region'), WINDOW
14 CONTROLS
15 REGION,AT(,,29,25),USE(?RegionTF),DROPID('TRASHID')
16 IMAGE('Trash01.ico'),AT(,),USE(?ImageTF),CENTERED
17 END
18 #DISPLAY ('')
19 #DISPLAY ('')
20 #DISPLAY('TrashFlash - Copyright 1999 Sterling Data')
21 #DISPLAY('For more products, freeware and demos visit:')
22 #DISPLAY('www.sterlingdata.com')
23 #DISPLAY ('')
24 #DISPLAY ('IMPORTANT: make sure you have set the browse drag ID')
25 #DISPLAY (' to TRASHID. In the Window Formatter right click on ')
26 #DISPLAY (' the list, select properties, Extra Tab.')
27 #DISPLAY ('')
28 #DISPLAY ('')
29 #DISPLAY ('')
30 #PROMPT('Delete Button for browse:',FROM(%Control,%ControlType =
'BUTTON')),%TFDeleteButton,DEFAULT('?Delete:2'),REQ
31 #DISPLAY ('')
32 #DISPLAY ('***** Other templates from Sterling Data *****')
33 #DISPLAY ('')
34 #DISPLAY ('BackFlash - data backup module for your apps')
35 #DISPLAY ('SearchFlash - search,tag and QBE ')
36 #DISPLAY ('CopyFlash - copy records')
37 #DISPLAY ('LogFlash - activity logging and audit trail')
38 #DISPLAY ('IMPEX - data import and export')
39 #DISPLAY ('')
40
41
42
43 #AT (%WindowManagerMethodCodeSection, 'TakeFieldEvent','(),BYTE'), PRIORITY(3060)
44
45 OF ?RegionTF
46 IF event()=EVENT:Drop
47 POST(EVENT:Accepted,%TFDeleteButton)
48 END
49 #ENDAT
Line 1 : Every type of template needs this line. The name (in
this case TrashABC) must be unique and the description following the name is what will
show up in the template registry. FAMILY('ABC') distinguishes it
from the old type of templates (called Legacy or Clarion) which would have FAMILY('CW20')
Lines 2 to 12 : these lines beginning with #! are
comments and will not show up in the window properties of any procedure in which the
template is used. Typically they contain copyright or version information.
Line 13: #CONTROL means it is a template which is
placed from within the Window Formatter by using Populate/Control Template. A
control being any visible screen object such as a button, list, radio buttons etc.
Again, it should have a unique name (TrashImage).
Line 14: A list of the actual controls follows - terminated by END
(line17)
Line 15: An image cannot have a Drop ID attached to it. So
this REGION control (covering an area slightly greater than the icon) is used. The DropID
(TRASHID) must be exactly the same as the DragID specified for the browse(list) control.
AT( ) contains the default location and width/height. In this case the first
two parameters are empty which allows the user to "drop" the control wherever
they want. A USE variable is a handle which can be used later on in the code of the
procedure for changing properties. Example: ?ImageTF{PROP:Text}='Trash01.ico'
- this assigns the named icon to this image control.
Line 16: When populating the template the second mouse click will
place the image. (for legacy template users - the icon will need resizing within
the region. The CENTERED attribute means this is done automatically for ABC users).
Notice that here the AT(, ) has no parameters - this means it will take them from
the previously placed control (the region).
Lines 18 to 39: These lines will appear in the AppGen procedure where a
template is used. #DISPLAY('') just shows a blank line - handy for
spacing out your text and making it more readable.
Line 30: This asks for the name you used for the delete button in
case you have renamed it from the default of ?Delete:2. #PROMPT is
used to get input from the developer using the template. The text inside the quotes
is what is shown on the screen and after this there can be a variety of options.
Such as KEY to enable choosing from a picklist of file keys, or FIELD
which brings up a list of fields to select from. The FROM used here
enables a list of the controls (template symbol %control) of the type
'BUTTON'. REQ means this field cannot be left blank or empty.
Line 43: #AT is a very powerful statement and will
place code of your choice at any embed point. In this example it uses a common
location - the code section of the Window Manager class, TakeFieldEvent. In other
words, where the events for each field are processed. PRIORITY()
gives you even more control over exactly where the code will be placed. Some trial
and error is often needed to get this right. The Embeditor is the best place to
check where your code is appearing. The section '(),BYTE' is
the prototype and means that no params are passed and a BYTE value is returned.
Study of the standard Clarion ABC templates will give good info on the exact layout to be
used with various #AT statements.
Lines 45 to 47: standard Clarion code which checks for the Drop Event for
the region (is someone trying to drop a dragged item on to the region?) and if so it will
POST the accepted event to the delete button. The delete button will then operate
normally as if you had clicked on it.
Line 49: Every #AT must be followed by a matching #ENDAT
If you write any templates yourself please share them with other
developers - send them to me and I will make
them available for download here.
1 Nov, 99 : John Morter of
Flat Chat Solutions (Australia) has sent
me a template which is a nice variation on the above. It
allows drag and drop changes and deletes by using the standard browse buttons as
"drop zones". Click
here to download the template.
December 1999: Jim Dennison has also kindly sent in a modified
TrashFlash template - this one plays sounds effects! And also the drag ID is auto
set and the X & Y position added to the icon file for one step control
placement. Click Here
to download Jim's template.
If you have already downloaded the full TrashFlash demo you can try out the above
modified templates by just registering them, removing the trash icon in the Window
Formatter and re-adding the control template from Populate Control Template.
|