home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / utilsf / hypoc2 / HPIF.DOC < prev    next >
Text File  |  1994-11-05  |  22KB  |  555 lines
  1. HyperPoc program interface:
  2. ===================================================================
  3. Changes in Version 2.2
  4. -------------------------------------------------------------------
  5. OnTick     A timer tick is now guaranteed when the OnTick bit
  6.            is set and the interval can be specified (default 1/2 sec)
  7.  
  8. helpClue   new function to control help system.
  9. ===================================================================
  10.  
  11. HyperPoc V2 allows to define program objects. User written programs 
  12. can be executed on card open or on activation. 
  13. This interface, is however, unsupported. We cannot give information exceeding
  14. the information offered with this text.
  15.  
  16. Program objects can:
  17.  
  18. 1. Place any graphic information on the current card.
  19. 2. Display an own window
  20. 3. Manage events from keyboard and other devices
  21. 4. Access to other cards via predefined HyperPoc routines
  22. 5. Access to other files within the system
  23. 6. Create files
  24.  
  25. How to:
  26.  
  27.  
  28. 1. Installation
  29.    Make sure to include HCIF.OPA into the \APP\HYPERPOC folder.
  30.    If you do not plan to use Program objects, you don't need this module.
  31.  
  32. =======================================================================
  33.  
  34. 2. Creation of program object
  35.  
  36.    Write the required OPL module.
  37.    The module must start with
  38.  
  39.         APP HYPERPOC
  40.         ENDA
  41.  
  42.         PROC modnam%:(parm$)
  43.  
  44.   modnam must be identical with the name of the module.
  45.   On invocation parm$ will contain the parameter string as defined in HyperPoc.
  46.  
  47.   We suggest to store the program into the folder ...\APP\HYPERPOC\SUB\ .
  48.   However, it may be stored elsewhere, especially during debugging.
  49.  
  50.   If you are creating your program on a PC, you may want to use OPLLINT
  51.   to check your program for missing definitions. Use HPREF.OPL to support
  52.   this process:
  53.  
  54.     OPLLINT modnam hpref -imc -rmodnam
  55.  
  56. =======================================================================
  57.  
  58. 3. Define program object on card or background.
  59.    This is done in the HyperPoc Editor (PSION-E or PSION-B) and PSION-P.
  60.    You are asked for the module name (modnam) and a parameter string.
  61.    This string will be passed to the module on invocation (parm$).
  62.  
  63. =======================================================================
  64.  
  65. 4. Programming guidelines
  66.    a) Use never variable names starting with HY.
  67.    b) Use never subroutine names starting with HY.
  68.    c) Close any windows you have opened before returning control back
  69.       to HyperPoc.
  70.    d) !!!!!!!!!!!!!!!!!! Files !!!!!!!!!!!!!!!!!!!!
  71.       Never, never use file commands such as ERASE, UPDATE, APPEND
  72.       without preceeding them by a USE B/C/D statement.
  73.       Unsolicited use of these statements can cause the corruption of
  74.       your stacks.
  75.       The file handle A cannot be used because it is used by HyperPoc.
  76.       During the debugging stage make backup copies of all of your
  77.       stacks.
  78.    e) Stacks
  79.       Never access physically do stacks. Stack data structures may 
  80.       change during updates and are not published for this reason.
  81.       HCIF provides a set of specialised routines for stack access (see below).
  82.  
  83. =======================================================================
  84.  
  85. 5. Interface routines
  86.  
  87.       cardnum% = findCd%:(stack$,srchmod%,srch$,addr(handle&))
  88.  
  89.         This routine finds a card in the specified stack. Set handle& = 0 for
  90.         the first call. Subsequent calls will find other cards matching the
  91.         specified search criterion.
  92.         The function returns 0 when no (more) cards are found.
  93.  
  94.            stack$               stack name (full path name).          
  95.  
  96.            srchmod% = 1         card text
  97.                       2         card keywords
  98.                       3         card number
  99.  
  100.            srch$ =              Text string, Keyword, or number
  101.                                 For srchmod% = 1 or = 2 srch$ may contain 
  102.                                 wild cards (*,?)
  103.  
  104.            handle&              Card handle. To be used with other 
  105.                                 access routines.
  106.                                 It is possible to manage different
  107.                                 cards simultanously using different
  108.                                 handle& and stack$ variables.
  109.  
  110.           cardnum%              logical card number
  111.                                 0 = no card found
  112.                                 2 = home card
  113.                                 >2  other cards
  114.  
  115. ---------------------------------------------------------------------------
  116.  
  117.       findBg:(stack$,addr(handle&))
  118.  
  119.       This routine finds the background of the specified stack.
  120.  
  121.            stack$               stack name (full path name).    
  122.            
  123.            handle&              Background handle. To be used with other 
  124.                                 access routines.
  125.                                 It is possible to manage different
  126.                                 backgrounds simultanously using different
  127.                                 handle& and stack$ variables.
  128.  
  129.         The global variable ObjPar% will contain the hypertext emphasis
  130.         (gStyle format) of the specified stack.
  131.  
  132. ---------------------------------------------------------------------------
  133.  
  134.       obj% = CdObj%:(stack$,addr(handle&),ObjMsk&)
  135.  
  136.         This routine returns objects of the current card or background
  137.         one by one with each call. When no more objects can be returned,
  138.         the result is 0.
  139.         The routine sets the following global variables:
  140.  
  141.                 ObjX%, ObjY%, ObjW%, ObjH%
  142.                 ObjTxt$   (128)
  143.                 ObjAttr$  (70)
  144.                 ObjPar%
  145.  
  146.         ObjX%, ObjY%, ObjW%, ObjH% contain object position and dimension.
  147.         ObjTxt$, ObjAttr$, ObjPar% depend on the object type
  148.  
  149.  
  150.         stack$          stack name (full path name).
  151.  
  152.         handle&         Card or background handle.
  153.  
  154.         ObjMsk&         Selection mask for objects.
  155.                         2**obj% will select objects of type obj%
  156.                         Combinations are possible.
  157.                         E.g. 2**2+2**5 = 36 = &00000024 
  158.                              selects texts and phone numbers
  159.                         Specify &ffffffff for all objects.
  160.  
  161.         
  162.         obj%            =  object type
  163.                                         0 no (more) object found
  164.                                         1 Application           &00000002
  165.                                         2 Text                  &00000004
  166.                                         3 Card link             &00000008
  167.                                         4 Icon                  &00000010
  168.                                         5 Phone #               &00000020
  169.                                         6 Polyline              &00000040
  170.                                         7 unused
  171.                                         8 Rectangle             &00000100
  172.                                         9 Clock                 &00000200
  173.                                         10 Keywords             &00000400
  174.                                         11 Bitmap               &00000800
  175.                                         12 Music                &00001000
  176.                                         13 Menu function        &00002000
  177.                                         14 Round rectangle      &00004000
  178.                                         15 HotTab               &00008000
  179.                                         16 unused
  180.                                         17 Explainer            &00020000
  181.                                         18 unused
  182.                                         19 Program              &00080000
  183.  
  184.         Application:
  185.  
  186.                         ObjTxt$ =       File name (e.g. DATA.DAT)
  187.                         ObjAttr$ =      Application name (e.g. WORLD)
  188.  
  189.         Text:
  190.  
  191.                         ObjTxt$ =       character string
  192.  
  193.                                 any character code n% < 32 
  194.                                 represents a gap of n% pixels instead
  195.