home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / PBAPI10.ZIP / APIDOCS.ZIP / UTIL.DOC < prev    next >
Text File  |  1998-02-21  |  12KB  |  244 lines
  1. Author....... : Gary Price
  2. Copyrighted by: Freejack's Software 1997-98
  3.  
  4. UTIL API for TriBBS v10.x/11.x written in PowerBasic v3.5
  5. ---------------------------------------------------------------------------
  6.  
  7. The UTIL unit can be used to manipulate data in any of the other data file
  8. API units or in your Main Program Design. The UTIL unit is declared in
  9. PBAPI10.INC as follows:
  10.  
  11.  
  12. FUNCTION InitialCaps(s AS STRING) AS STRING
  13. FUNCTION TrimString(s AS STRING) AS STRING
  14. FUNCTION HashIt(s AS STRING) AS LONG
  15. FUNCTION MenuBox (x1 AS INTEGER, y1 AS INTEGER, x2 AS INTEGER, y2 AS _
  16.          INTEGER, FColor AS INTEGER, BColor AS INTEGER, HeaderText AS STRING)
  17. FUNCTION LineInput(HideChar AS STRING, CharAllow AS STRING, PromptLine _
  18.          AS STRING, Row AS INTEGER, MaxLen AS INTEGER) AS STRING
  19. FUNCTION DateInput(PromptLine AS STRING, Row AS INTEGER) AS STRING
  20. SUB CalcByte(Attr AS INTEGER, LowByte AS INTEGER, HiByte AS INTEGER) 
  21. SUB MakeByte(Attr AS INTEGER, LowByte AS INTEGER, HiByte AS INTEGER) 
  22. SUB CheckBits(Attr AS INTEGER, BitOne AS INTEGER, BitTwo AS INTEGER, _
  23.               BitThree AS INTEGER, BitFour AS INTEGER, BitFive  AS INTEGER, _
  24.               BitSix AS INTEGER, BitSeven AS INTEGER, BitEight AS INTEGER) 
  25. FUNCTION VideoSeg() AS LONG
  26. SUB Browse(FileName AS STRING, Mouse AS INTEGER, TextColor AS INTEGER, _
  27.            TopRow AS INTEGER, LeftColumn AS INTEGER, BottomRow AS INTEGER, _
  28.            RightColumn AS INTEGER, Attr AS INTEGER, Shadow AS INTEGER, _
  29.            Border AS INTEGER) 
  30. SUB HiPrint(Text AS STRING, HiAttr AS INTEGER, Attr AS INTEGER) 
  31. SUB LinePrint(Text AS STRING, Row AS INTEGER, Col AS INTEGER, Wide AS INTEGER, _
  32.               Fill AS INTEGER, Attr AS INTEGER) 
  33. SUB CenterPrint(Text AS STRING, Row AS INTEGER, Wide AS INTEGER, Fill AS INTEGER, _
  34.                 Attr AS INTEGER) 
  35.  
  36. ---------------------------------------------------------------------------
  37. InitialCaps(s AS STRING) AS STRING
  38.   The InitialCaps functions will past a name string in 's' to the function and
  39.   receive back a string with proper cap letters of each word.
  40.  
  41.    Example:
  42.       NewString = InitialCaps("gary price")
  43.       NewString would now look like Gary Price
  44.  
  45. ---------------------------------------------------------------------------
  46. TrimString(s AS STRING) AS STRING
  47.  The TrimString function will past a string to the function as 's' and
  48.  then received it back fully trimmed of all it's padded spaces and any
  49.  CHR$(0) which may be on the end.
  50.  
  51. ---------------------------------------------------------------------------
  52. HashIt(s AS STRING) AS LONG
  53.  The HashIt function will allow you to past either a person's real name or
  54.  alias in 's' and have it return the Hash Value which TriBBS uses in many of
  55.  it's Data structures.  EXAMPLE: n& = HashIt("Gary Price")
  56.  
  57. ---------------------------------------------------------------------------
  58. MenuBox(x1 AS INTEGER, y1 AS INTEGER, x2 AS INTEGER, y2 AS INTEGER, _
  59.         FColor AS INTEGER, BColor AS INTEGER, HeaderText AS STRING)
  60.  
  61.  This MenuBox function will allow you to past x1, y1, x2, y2, FColor, BColor,
  62.  HeaderText to the function which will create a TriBBS on the fly menu.
  63.  
  64.     Parameters defined as shown:
  65.  
  66.         x1                  x2
  67.      y1 +-------------------+     BColor     = Back Ground Color of Menu 
  68.         |                   |     FColor     = Fore Ground Color of Menu
  69.         |                   |     HeaderText = Text to be printed at top of
  70.         |                   |                  menu. This will be Centered,
  71.      y2 +-------------------+                  and cannot be more that 78
  72.                                                characters in length.
  73.  
  74. ---------------------------------------------------------------------------
  75. FUNCTION LineInput(HideChar AS STRING, CharAllow AS STRING, PromptLine _
  76.          AS STRING, Row AS INTEGER, MaxLen AS INTEGER) AS STRING
  77.  
  78.  <Syntax>
  79.     ReturnString = LineInput(HideChar, CharAllow, PromptLine, Row, MaxLen)
  80.  
  81.  This function will allow greater control of a single input line when
  82.  prompting a user for general information.
  83.  
  84.     HideChar will allow you to pass any type charcter to the function to
  85.     hide the true input. This is great password word protection.
  86.  
  87.     CharAllow will allow you to pass any amount of charcters to the function
  88.     that you want to qualify as a legal key input. If the user enters a
  89.     character from the keyboard that is not defined in your CharAllow list,
  90.     then the function will simple ignore the input and continue loop as if
  91.     nothing was entered at all. Based on your ASCII Character Table, you can
  92.     enter any character that has values which falls between 32 to 254.
  93.  
  94.     PromptLine will allow you to pass a string to the function that you want
  95.     printed to the screen just prior to the key input await state.
  96.  
  97.     Row will allow you to pass an integer value (1 to 25) for screen position
  98.     you want the PromptLine to be printed and wait for input.
  99.     NOTE: Row will be set to '1' if Row < 1 OR > 25.
  100.  
  101.     MaxLen will allow you to pass an interger value to the function that will
  102.     only allow that many key inputs. Therefore, if you enter something like
  103.     30, then the user can only enter up to 30 characters.
  104.  
  105.     NOTE: The Length of (PrompLine + MaxLen) cannot equal greater than 80.
  106.     If the function finds a length greater than 80, the function will abort
  107.     and return a '-1' value. This is something you can use to test for as
  108.     you develop your programs with this function.
  109.  
  110. ---------------------------------------------------------------------------
  111. FUNCTION PhoneNumberInput(PromptLine AS STRING, Row AS INTEGER) AS STRING
  112.  
  113.  This function will allow strict control over US style format phone number
  114.  strings. The set format is, ###-###-###, and the function will automatically
  115.  send a "-" between the area code & prefix, and prefix & suffix as the user
  116.  inputs the phone number.
  117.  
  118.  <Syntax>
  119.     ReturnString = LineInput(PromptLine, Row)
  120.  
  121.     PromptLine will allow you to pass a string to the function that you want
  122.     printed to the screen just prior to the key input await state.
  123.  
  124.     Row will allow you to pass an integer value (1 to 25) for screen position
  125.     you want the PromptLine to be printed and wait for input.
  126.     NOTE: Row will be set to '1' if Row < 1 OR > 25.
  127.  
  128. ---------------------------------------------------------------------------
  129. FUNCTION DateInput(PromptLine AS STRING, Row AS INTEGER) AS STRING
  130.  
  131.  This function will allow strict control over US style date strings. The set
  132.  format is, MM/DD/YY, and the function will automatically send a "/" between
  133.  the MM, DD, and YY as the user inputs the date.
  134.  
  135.  <Syntax>
  136.     ReturnString = LineInput(PromptLine, Row)
  137.  
  138.     PromptLine will allow you to pass a string to the function that you want
  139.     printed to the screen just prior to the key input await state.
  140.  
  141.     Row will allow you to pass an integer value (1 to 25) for screen position
  142.     you want the PromptLine to be printed and wait for input.
  143.     NOTE: Row will be set to '1' if Row < 1 OR > 25.
  144.  
  145. ---------------------------------------------------------------------------
  146. FUNCTION YesNo(PromptString AS STRING, Row AS INTEGER, ResponseKey AS _
  147.          INTEGER) AS INTEGER
  148.  
  149.  This function will allow strict control over the Yes/No input responses.
  150.  
  151.  <Syntax> 
  152.     IF YesNo(PromptString, Row, ResponseKey) = <Return Value> THEN
  153.          <Statments>
  154.     ELSE
  155.          <Statements>
  156.     END IF
  157.  
  158.     PromptString will allow you to pass a string to the function that you
  159.     want printed to the screen just prior to the key input await state.
  160.  
  161.     Row will allow you to pass an integer value (1 to 25) for screen position
  162.     you want the PromptLine to be printed and wait for input.
  163.     NOTE: Row will be set to '1' if Row < 1 OR > 25.
  164.  
  165.     ResponseKey will allow you to set what response is the default key if
  166.     they just hit the Enter/Return key. This value can be either 0 or 1.
  167.     If ResponseKey is set to 0, then this would eqaul a false, <y/N> value
  168.     as the default key.  If ResponseKey is set to 1, then this would equal a
  169.     True, <Y/n> value as the default key.  When creating a PrompString, I
  170.     would include a choice for the users to see, examples, <Y/n> or <y/N> to
  171.     show them the default selection if they just hit the Enter/Return key.
  172.  
  173.     Return Value is either a 0 or 1 that will be returned from the function
  174.     to indicate what the user entered. This also works on the logical value
  175.     of 1 = True, and 0 = False. Based on the Return Value, you can then
  176.     arrange your following <statements> in the IF/THEN/ELSE condition to
  177.     preform the next task at hand.
  178.  
  179. ---------------------------------------------------------------------------
  180. SUB CalcByte(Attr AS INTEGER, LowByte AS INTEGER, HiByte AS INTEGER)
  181.  
  182.    This sub will take the value passed in Attr and break it down into
  183.    a lowbyte and hibyte color value.
  184.  
  185. ---------------------------------------------------------------------------
  186. SUB MakeByte(Attr AS INTEGER, LowByte AS INTEGER, HiByte AS INTEGER)
  187.  
  188.    This sub will accept color values passed in lowbyte, and hibyte and
  189.    return a calculated one integer color value in Attr.
  190.  
  191. ---------------------------------------------------------------------------
  192. SUB CheckBits(Attr AS INTEGER, BitOne AS INTEGER, BitTwo AS INTEGER, _
  193.               BitThree AS INTEGER, BitFour AS INTEGER, BitFive  AS INTEGER, _
  194.               BitSix AS INTEGER, BitSeven AS INTEGER, BitEight AS INTEGER) 
  195.  
  196.    This sub will accept a color attribute value passed in Attr, and return
  197.    8 bit levels of bit assignment for that color byte. This sub is mostly
  198.    used internally by the Main API.
  199.  
  200. ---------------------------------------------------------------------------
  201. FUNCTION VideoSeg() AS LONG
  202.  
  203.    Returns the address for the Video Segment.
  204.  
  205. ---------------------------------------------------------------------------
  206. SUB Browse(FileName AS STRING, Mouse AS INTEGER, TextColor AS INTEGER, _
  207.            TopRow AS INTEGER, LeftColumn AS INTEGER, BottomRow AS INTEGER, _
  208.            RightColumn AS INTEGER, Attr AS INTEGER, Shadow AS INTEGER, _
  209.            Border AS INTEGER) 
  210.  
  211.    This sub will open a text file and grab up to 32k of info at a time to
  212.    be displayed in a window size you define. This sub will also automatically
  213.    save a caption of the previous screen, open and display your text file and
  214.    when the window is closed, it will the restore the saved screen caption.
  215.    Great for displaying help files or whatever. You will need to set your
  216.    $STRING metastatment to 32k before calling this sub.
  217.  
  218. ---------------------------------------------------------------------------
  219. SUB HiPrint(Text AS STRING, HiAttr AS INTEGER, Attr AS INTEGER) 
  220.  
  221.    This sub will allow you to pass text strings with a hi and normal color
  222.    attribute. If the chosen word or group of words are inclosed between
  223.    > and < then whatever color value was passed in HiAttr will be used on that
  224.    word or group of words. All other words within the text file that are Not
  225.    inclosed between the > and < symbols, will use the color value Attr.
  226.    This could be used in something like a hyperSearch program to display
  227.    matching words found.
  228.  
  229. ---------------------------------------------------------------------------
  230. SUB LinePrint(Text AS STRING, Row AS INTEGER, Col AS INTEGER, Wide AS INTEGER, _
  231.               Fill AS INTEGER, Attr AS INTEGER) 
  232.  
  233.    This sub is great for allowing you to print the output of an inputted
  234.    line from a user in your program or from a predefined database field.
  235.    It will also fill all unused spaces with whatever ASCII character you
  236.    pass to it in the Fill.
  237.  
  238. ---------------------------------------------------------------------------
  239. SUB CenterPrint(Text AS STRING, Row AS INTEGER, Wide AS INTEGER, Fill AS INTEGER, _
  240.                 Attr AS INTEGER) 
  241.  
  242.    This sub will do like the Lineprint, except it will center the and print
  243.    the input.
  244.