PDA Software Library

home *** CD-ROM | disk | FTP | other *** search

/ PDA Software Library / pdasoftwarelib.iso / PSION / MISC / HYPOC / HPIF.DOC < prev next >

Wrap

Text File | 1994-11-05 | 21.0 KB | 555 lines

HyperPoc program interface: =================================================================== Changes in Version 2.2 ------------------------------------------------------------------- OnTick A timer tick is now guaranteed when the OnTick bit is set and the interval can be specified (default 1/2 sec) helpClue new function to control help system. =================================================================== HyperPoc V2 allows to define program objects. User written programs can be executed on card open or on activation. This interface, is however, unsupported. We cannot give information exceeding the information offered with this text. Program objects can: 1. Place any graphic information on the current card. 2. Display an own window 3. Manage events from keyboard and other devices 4. Access to other cards via predefined HyperPoc routines 5. Access to other files within the system 6. Create files How to: 1. Installation Make sure to include HCIF.OPA into the \APP\HYPERPOC folder. If you do not plan to use Program objects, you don't need this module. ======================================================================= 2. Creation of program object Write the required OPL module. The module must start with APP HYPERPOC ENDA PROC modnam%:(parm$) modnam must be identical with the name of the module. On invocation parm$ will contain the parameter string as defined in HyperPoc. We suggest to store the program into the folder ...\APP\HYPERPOC\SUB\ . However, it may be stored elsewhere, especially during debugging. If you are creating your program on a PC, you may want to use OPLLINT to check your program for missing definitions. Use HPREF.OPL to support this process: OPLLINT modnam hpref -imc -rmodnam ======================================================================= 3. Define program object on card or background. This is done in the HyperPoc Editor (PSION-E or PSION-B) and PSION-P. You are asked for the module name (modnam) and a parameter string. This string will be passed to the module on invocation (parm$). ======================================================================= 4. Programming guidelines a) Use never variable names starting with HY. b) Use never subroutine names starting with HY. c) Close any windows you have opened before returning control back to HyperPoc. d) !!!!!!!!!!!!!!!!!! Files !!!!!!!!!!!!!!!!!!!! Never, never use file commands such as ERASE, UPDATE, APPEND without preceeding them by a USE B/C/D statement. Unsolicited use of these statements can cause the corruption of your stacks. The file handle A cannot be used because it is used by HyperPoc. During the debugging stage make backup copies of all of your stacks. e) Stacks Never access physically do stacks. Stack data structures may change during updates and are not published for this reason. HCIF provides a set of specialised routines for stack access (see below). ======================================================================= 5. Interface routines cardnum% = findCd%:(stack$,srchmod%,srch$,addr(handle&)) This routine finds a card in the specified stack. Set handle& = 0 for the first call. Subsequent calls will find other cards matching the specified search criterion. The function returns 0 when no (more) cards are found. stack$ stack name (full path name). srchmod% = 1 card text 2 card keywords 3 card number srch$ = Text string, Keyword, or number For srchmod% = 1 or = 2 srch$ may contain wild cards (*,?) handle& Card handle. To be used with other access routines. It is possible to manage different cards simultanously using different handle& and stack$ variables. cardnum% logical card number 0 = no card found 2 = home card >2 other cards --------------------------------------------------------------------------- findBg:(stack$,addr(handle&)) This routine finds the background of the specified stack. stack$ stack name (full path name). handle& Background handle. To be used with other access routines. It is possible to manage different backgrounds simultanously using different handle& and stack$ variables. The global variable ObjPar% will contain the hypertext emphasis (gStyle format) of the specified stack. --------------------------------------------------------------------------- obj% = CdObj%:(stack$,addr(handle&),ObjMsk&) This routine returns objects of the current card or background one by one with each call. When no more objects can be returned, the result is 0. The routine sets the following global variables: ObjX%, ObjY%, ObjW%, ObjH% ObjTxt$ (128) ObjAttr$ (70) ObjPar% ObjX%, ObjY%, ObjW%, ObjH% contain object position and dimension. ObjTxt$, ObjAttr$, ObjPar% depend on the object type stack$ stack name (full path name). handle& Card or background handle. ObjMsk& Selection mask for objects. 2**obj% will select objects of type obj% Combinations are possible. E.g. 2**2+2**5 = 36 = &00000024 selects texts and phone numbers Specify &ffffffff for all objects. obj% = object type 0 no (more) object found 1 Application &00000002 2 Text &00000004 3 Card link &00000008 4 Icon &00000010 5 Phone # &00000020 6 Polyline &00000040 7 unused 8 Rectangle &00000100 9 Clock &00000200 10 Keywords &00000400 11 Bitmap &00000800 12 Music &00001000 13 Menu function &00002000 14 Round rectangle &00004000 15 HotTab &00008000 16 unused 17 Explainer &00020000 18 unused 19 Program &00080000 Application: ObjTxt$ = File name (e.g. DATA.DAT) ObjAttr$ = Application name (e.g. WORLD) Text: ObjTxt$ = character string any character code n% < 32 represents a gap of n% pixels instead of a real character (created with TAB key). ObjAttr$ = attribute string ObjAttr$ is structured in the following way (dummy declarations only): att$(i%) = mid$(ObjAttr$,3*i%-2,3) for i% = 1 ... len(ObjAttr$)/3 is a single attribute for one text segment slen%(i%) = asc(att$(i%)) and 127 is the length of the text element in characters sind%(i%) = asc(att$(i%)) and 128 is an indicator if there are any character codes < 32 (TABS) in the text segment. font%(i%) = asc(mid$(att$(i%),2,1)) is the font number for the text segment Note: HyperPoc font numbers are not identical with gfont font id's. Use the function trfont%: to translate a HyperPoc font number into gfont font id's. style%(i%) = asc(right$(att$(i%),1)) is the gStyle setting for the text segment Card link: ObjTxt$ = stackname ObjPar% = cardnumber Icon: none Phone #: ObjTxt$ = phone number (dirty) Use strip$ (see below) for cleaning. ObjAttr$ = Header String ("",bh,ah,mb,pg,fx,em) (Language dependend) Polyline: none Rectangle: none Clock: none Keywords: ObjTxt$ = keywords separated by comma Bitmap: none Music: none Menu function: ObjPar% = Function code (= character code+512) Round rectangle: none HotTab: ObjPar% = object type associated with HotTab ObjTxt$ = name of HotTab Objects associated with HotTabs can be found by position: If the HotTab has a name: x+w+3 , y or x+w+3 , y+2 else x , y or x , y+2 Explainer: none Program: none ----------------------------------------------------------------------- c% = getKey%:(control%) Get a key code or event code. control% Control mask for animation 1 inhibit animation 2 inhibit music and sound 4 pass control on timer tick You have to provide a routine onTick: 8 pass control on idle You have to provide a routine onIdle: 16 Disable Help system during this getKey HelpKey is passed as result when pressed 32 Pass MENU key to user routine n*256 interval between timer ticks in 1/2 seconds (n = 1...127) Note that the routine onIdle: is only started when the system is waiting for an event. Animation or onTick: routines may lead to the situation that the system is never idle. Both onIdle: and onTick: may return a character code to getKey:, which is then passed to the caller of getKeY:. On receiving event codes (c% = 513...1023,1028) you must(!) close your routine and pass control back to HyperPoc. The event codes 1024,1025,1026,1027,1029 are not handled by HyperPoc, so you better handle them yourself. After closing your files and windows use RETURN c% to inform HyperPoc about the event. It is strongly recommended to use this routine instead of get or getevent. While waiting for the event, HyperPoc will continue to process animation, music and stop watches. It will also handle the menu key. Note: Do not use instructions such as get, key, getevent, pause, iow, ioa within these routines. As key modifier use the global variable km% instead of kmod. ----------------------------------------------------------------------- r% = showCd%:(stknam$,cdnum%) Opens the specified card of the specified stack and displays it. The specified card becomes the current card. This function allows the user program to navigate through cards. If successful the result is -1, else 0. curstk$ and cuCd% (see below) are modified by this function. This function cannot be used at card open time. When used during this time it will have no effect and will return 0. ======================================================================= 6. Utility functions Some useful subroutines that can be used in a user module: substr$ = extract$:(cslist$,i%) If cslist$ is a comma separated list, extract$ returns the i-th element of this list (empty if i% is out of range). ----------------------------------------------------------------------- o$ = Obj$:(o%) Returns the object type name for object type o%. ----------------------------------------------------------------------- file$ = shtName$:(path$) Extracts the 8-byte file name from a full path name. The first character of the file name will be upper case, the following characters will be lower case. ----------------------------------------------------------------------- prTim:(sec%) gprints a time specified in seconds (sec%) as hh:mm:ss ----------------------------------------------------------------------- atxt$ = asctxt$:(rawtxt$,len%,pat$) delivers the first len% bytes of rawtxt$ and replaces any character code < 32 by pat$ (e.g. chr$(9)). A typical call for text objects could be: asctxt$:(right$(spec$,len(spec$)-1),asc(spec$)," ") ----------------------------------------------------------------------- dial$ = strip$:(phone$) Removes all characters unfit for dialling from phone$. Translates also [country] into digits and processes +countrycode. An empty string is returned on invalid country code. ----------------------------------------------------------------------- dial:( dial$,out% ) Dials the specified dial string (dial$) using the preferences of the current stack. strip$ is applied to dial$ before actual dialling. out% <> 0 causes the dial-out string to be dialled first. ----------------------------------------------------------------------- ret% = setrs: Before you print to a line printer you should call this routine. The serial interface will be set to the values defined with printer setup (PSION-Y). This routine includes and LOPEN to the serial or parallel interface. The response code is unequal zero in case of success. ----------------------------------------------------------------------- warning:(Msg$,Sever%) flashes Msg$ in lower right corner of screen and beeps. Sever% indicates the severity (0..3) which is reflected in duration and pitch of the beep. 0 = Message (no beep) 1 = Operator errors (e.g. wrong input string, low pitch beep) 2 = Device errors (e.g. disk full, medium pitch beep) 3 = System and program errors( high pitch beep) ----------------------------------------------------------------------- helpClue:(Clue$) Sets a help clue (help keyword) for the help system to provide context sensitive help. Clue$ must be 1..9 characters. An empty string as Clue$ switches the help system off. ----------------------------------------------------------------------- gfnt% = trfont%:(hfnt%) Translates a HyperPoc Font number into a gfont font ID. Returns the stack default font ID if hfnt% is not valid. ======================================================================= 7. Variables: Never, never overwrite the following variables. curStk$ (128) = full path name of current stack stkFol$ (128) = path name of HyperPoc stack folder icnFol$ (128) = path name of HyperPoc icon folder appFol$ (128) = path name of HyperPoc module folder (...APP\HYPERPOC\) cuCd% = logical number of current card km% = key modifier (instead of kmod) sMod% = last search mode (1,2,3) sKey$ (32) = last search string onAct% = true if program was invoked on activation false if program was invoked on card open ======================================================================= 8. Permanent memory and semaphors The following variables are not used by HyperPoc and are dedicated to be used by user programs. You may use them, for instance, to remember logical card numbers or as semaphors. prVar1% prVar2% prVar3% prVar4% prStrng$(128) You should not try to remember background and card handles between program calls. Handles may change when a card is edited. Better remember the logical card number and find it again using findCd. ======================================================================= 9. Display media Programs can output into a) the current card. The current card is drawable 1. On program start, the global variables ObjX%, ObjY%, ObjW%, ObjH% contain the X- and Y-coordinates, width, and height of the current card. Always use graphic instructions like gprint to output into the card. b) A window created by the program. Use gcreate to create the window. Always close the window when leaving the program. ======================================================================= 10. Error handling Your routine should handle any errors. Specify an ONERR clause to pass control to an error label. Before you leave the routine close all you files and windows. Return the errorcode with RETURN r% (r% containing the error code). ======================================================================= 11. Creating a parameter string The size of the parameter string is limited to 50 characters. Normally you specify a parameter string when placing the program object onto the card. However, if the parameter syntax becomes complex, as in IMPDATA.OPL, you may want to support the input of the parameter string with a specialised dialogue box. To do so, define within the module a subroutine edParm$:(oldParm$) This subroutine is called when a program object is created or modified. oldParm$ contains the old parameter string (empty for a new object). The new parameter string is passed to HyperPoc as the result of edParm$. If HyperPoc does not find a subroutine edParm$ it will allow for the input of the raw parameter string. ======================================================================= 12. Tips It is possible to change search criteria between subsequent findCd% calls. e.g. findCd%:(curStk$,3,num$(cuCd%,5),addr(handle&)) findCd%:(curStk$,1,"elephant",addr(handle&)) positions first to the current card, then starts searching for text "elephant" with the next card until stack end. At program invocation time, the graphic cursor is always positioned at the top left corner of the program representation, so can use gX and gY to find out about the position of the program object. ======================================================================= 13. Examples PHLIST.OPL prints a phonelist from the address stack. BROWSE.OPL displays all cards of a stack. INDEX.OPL displays the sorted keywords of a stack. IMPDATA.OPL imports PSION database records.