EPOC32 file converted by psiconv

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

! !

! README TEXT FILE FOR POPUP v2.4 !

! !

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

========================================================

This module is 100% FREE for use in your applications.

For other psion software, visit my website at:

http://www.i27.com

========================================================

# CONTENTS:

===========

I. !!!IMPORTANT CHANGES TO POPUP v2.32!!!

1. HOW TO USE POPUP

2. DATABASE

3. DISPLAYING A "FIND" EXAMPLE FROM YOUR DATABASE

4. FONTS

5. SYSTEM COMMAND RETURNS WHILST POPUP IS ACTIVE

6. CTRL SHIFT FN MENU CALLBACKS WITH EXAMPLE

#I !!!IMPORTANT CHANGES TO POPUP v2.32!!!

=========================================

PopUp.OPM and Scroll.mbm will now automatically be placed into

"!\System\OPM\". All other relevant files are placed in

"C:\PopUp\".

#1 HOW TO USE POPUP:

====================

1. Place the following text at the top of the first procedure

in your app (the following code assumes that PopUp has been

installed to the C: drive - see "example.opl" for a demonstration

on how to check which drive PopUp has been installed to):

LOADM "C:\System\OPM\PopUp.OPM"

2. Specify a string variable, such as p$(255) and an integer

such as i% (if the returned value is to be the record position).

3. Call the PopUp procedure, and return the PopUp result into the

string variable:

p$=PUCreatePopup$:(xPos%,yPos%,place%,hi%,dat$,ans%,fontn%)

where:

xPos% = distance from left/right edge of screen in pixels

yPos% = distance from top of screen in pixels

place% = specifies xPos% to be taken from right(1) or left(0)

any other number will center the PopUp in the screen.

hi% = PopUp height in pixels - (0) specifies MIN height

minimum height = 80 pixels (4 displayed lines)

dat$ = the data to be displayed - see DATABASE below

ans% = specifies whether the returned answer should be:

(0) a numerical representation of the record position

(1) a string representation of the selected record.

If (0) is selected, the answer must be converted

into a number. This can be done by using i%=VAL(p$)

fontn% = specifies which font to be used to display the results.

See FONTS below for further information.

For example:

p$=PUCreatePopup$:(0,0,0,0,"example.dat",1,0)

PRINT p$

would create a PopUp at co-ordinates 0,0 at the left

of the screen. "example.dat" is the data source, and p$

will be a string representation of the selected record.

The height of the PopUp is MIN, and the default font is

used. The result is then displayed.

Similarly:

p$=PUCreatePopup$:(120,0,1,100,"example2.dat",0,9)

i%=VAL(p$)

PRINT i%

would create a PopUp 120 pixels from the right of the screen.

"example2.dat" is the data source, and p$ will be a numerical

representation of the selected record. The height of the PopUp

is 100 pixels, and Times 13 Normal is the selected font. The

result is then converted and displayed.

Or:

gUSE 1

p$=PUCreatePopup$:(0,0,2,gHEIGHT-5,"example3.dat",0,9)

i%=VAL(p$)

PRINT i%

would create a PopUp in the middle of the screen. "example3.dat"

is the data source, and p$ will be a numerical representation of

the selected record. The height of the PopUp is the screen

height, and Times 13 Normal is the selected font. The

result is then converted and displayed.

#2 DATABASE:

============

The PopUp gets its data from a simple database. There is only

one REQUIRED field, and it MUST be the first field in the

database, and it must be a STRING field.

You can also use databases that have been created by the S5's

own DATA application!!

For example, if you had a database called "address.dat" with

the following fields - name$,tel$,address$,email$ - then

the contents of name$ will be displayed in the PopUp since it

is the FIRST field.

To do a "FIND" items in a database, you must create a TEMPORARY

database, and a complete example of this is given below. PopUp

does NOT SORT the temporary database, since there may be instances

in YOUR apps where sorting is NOT required. To sort the TEMPORARY

database, you must basically, sort your main database to how you want.

#3 DISPLAYING A "FIND" EXAMPLE FROM YOUR DATABASE

=================================================

To display a PopUp of records that match a search in a database

called "dbmain", you could use the following code:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

! !

! POPUP EXAMPLE !

! !

! FREE FOR USE - TO BE TAKEN "AS IS" !

! !

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

REM ****************************Start****************************

PROC start:

LOADM "C:\System\OPM\PopUp.OPM" REM load the PopUp module!!

example: REM go to the procedure named "example:"

ENDP

REM ***************************Example***************************

PROC example:

LOCAL f%,word$(30),p$(255)

SETPATH CMD$(1) REM set the path to from where the app was run

REM open the main database and sort the field "name" by ascending order

REM we'll assume that the database contains "telephone" and "e-mail"

REM fields also:

OPEN "dbmain FOLDED SELECT * FROM Table1 ORDER BY name ASC",A,name$,tel%,email$

PRINT "Enter search word"

INPUT word$

FIRST

f%=FIND("*"+word$+"*") REM search for all instances of the search word.

REM To find only results that match the search word

REM EXACTLY, omit the "*" to leave f%=FIND(word$)

TRAP DELETE("temp.dat") REM delete the temporary database - if it exists

CREATE "temp.dat",B,item$ REM create the temporary database. You may create

REM other fields if need be, but item$ MUST be the

REM initial field and will be the one that is listed

REM in the PopUp.

USE B :BEGINTRANS

USE A

IF f%<>0 REM results found

FIRST

WHILE FIND("*"+word$+"*")

USE B :INSERT REM add a record to the temp file

B.item$=A.name$ REM place each found record into the temporary database

PUT

USE A :NEXT

ENDWH

REM save ALL found words into the temporary database

IF INTRANS :COMMITTRANS :ENDIF

ELSE REM no results

gIPRINT "No matching records"

PAUSE 80

STOP

ENDIF

TRAP USE A :TRAP CLOSE REM close the original database

TRAP USE B :TRAP CLOSE REM close the temporary database

REM IMPORTANT: the temporary database MUST be closed

REM before calling the PopUp procedure...

p$=PUCreatePopup$:(0,0,0,0,"temp.dat",1,0) REM create PopUp window

PRINT "You selected:",p$ REM display result from PopUp

GET

ENDP

#4 FONTS

========

PopUp can display its list in a choice of 18 fonts! Below

are the numerical codes to enter into fontn%:

fontn% FONT NAME SIZE WEIGHT

------ --------- ---- ------

0 Arial 15 Normal (Default Font)

1 Arial 11 Normal

2 Arial 11 Bold

3 Arial 13 Normal

4 Arial 13 Bold

5 Arial 15 Normal

6 Arial 18 Normal

7 Times 11 Normal

8 Times 11 Bold

9 Times 13 Normal

10 Times 13 Bold

11 Times 15 Normal

12 Times 18 Normal

13 Courier 11 Normal

14 Courier 11 Bold

15 Courier 13 Normal

16 Courier 13 Bold

17 Courier 15 Normal

18 Courier 18 Normal

#5 SYSTEM COMMAND RETURNS WHILST POPUP IS ACTIVE

================================================

PopUp v2.4 can also return the System Command letters that

are normally returned in GETCMD$ - see ADVANCED TOPICS in

the OPL Programming Manual for further details.

These commands are represented as returned values from p$,

and their codes are given below:

1. "_PUSysCommand_C_" - close the current document, and

create the specified new file.

2. "_PUSysCommand_O_" - close the current document, and

open the specified existing file.

3. "_PUSysCommand_X_" - save the name of the current document

(if any) to the .INI file, close the

current document and quit the application.

also,

4. "_PUSysFocusLost_" - returns when PopUp is sent to the background

or another program comes to the foreground.

How you use these returned values (if at all) is entirely

up to you - but at least you have the option...

#6 CTRL SHIFT FN MENU CALLBACKS WITH EXAMPLE

============================================

PopUp v2.4 can now return key callbacks such as CTRL+FN+W or

SHIFT+CTRL+FN+T etc. These are returned as follows:

1. "_PUSysCTRL+FN_W_" - for CTRL+FN+W

2. "_PUSysCTRL+SHIFT+FN_T_" - for SHIFT+CTRL+FN+T etc.

For discovering other key callback combinations, run "callbacks.opo",

press the desired key combination and note down the return code.

To handle callbacks correctly you should use the following code in

you apps: (we'll presume you need CTRL+E and System Shutdown callbacks

to run a procedure named "Shutdown:", and CTRL+T to toggle a toolbar)

LOADM "C:\System\OPM\PopUp.OPM"

p$=PUCreatePopup$:(0,0,0,0,"example.dat",1,0)

UNLOADM "C:\System\OPM\PopUp.OPM"

IF p$="_PUSysCTRL_T_"

ToggleToolbar:

ELSEIF p$="_PUSysCTRL_E_" OR p$="PUSysCommand_X_"

Shutdown:

ELSE

IF p$>"" AND LEFT$(p$,1)<>"_" REM no more callbacks

PRINT p$

ENDIF

Thanks for trying out PopUp v2.4!

Mark. :-)