home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / mac / misc / update / foxscrol.sit / XScrollList.README < prev   
Encoding:
Text File  |  1992-09-27  |  13.3 KB  |  369 lines
  1. /* XScrollList version 1.0.5, 27-SEP-1992 ⌐1992 A.D. Software
  2.  
  3. THIS IS NOT FREE - see Shareware Details at end.
  4.  
  5. OVERVIEW
  6.  
  7. XFCN for presenting dialog boxes with a single list of items, for FoxBase+/Mac.
  8.  
  9. ALSO A "Dump" feature is incorporated ╤ the array loaded can be dumped to a
  10. text file at very high speed. Carriage returns are used to separate items and
  11. so this may be useful as an fast export facility that allows export of TRIMMED
  12. fields & expressions.
  13.  
  14.  
  15. Multiple fields can be specified, using expressions, allowing combinations of
  16. related fields. eg:
  17. "trim(sample->name-"-chr(34)-":"-chr(34)-"-code)"
  18. which combines the fields sample->name and code with a colon between them and
  19. all trailing spaces removed.
  20.  
  21. Tabs are used to align items into separate columns; tabs in a single field
  22. will have the same effect.
  23.  
  24.    Selection can be made by:
  25.    
  26.    1. double-clicking on a line.
  27.    2. single-clicking on a line, then pressing the OK button.
  28.    3. single-clicking on a line, then pressing the Return key.
  29.    4. typing the first letter(s) of a selection, then doing 1,2, or 3.
  30.       (Note: type selection assumes that the lines are ordered alphabetically)
  31.    5. scrolling with up and down arrow keys, then doing 1,2 or 3.
  32.    
  33.    Multiple Selections can be added by:
  34.    1. shift-click to mark all between original and shift-clicked selection
  35.    2. command-click to select or de-select individual items
  36.  
  37.  
  38. IMPORTANT
  39. For a comprehensive list of which of the following features are yet to be
  40. implemented, see the bottom of the document. I am releasing the product in its
  41. current state as it satisfies most needs (including my current app) and I want
  42. some shareware return before I can justify the time to complete the remaining features.
  43.  
  44. PERFORMANCE HINTS
  45. The Record Number option on the Load (necessary to support returning
  46. record numbers) will slow down the load. If you are loading an indexed field
  47. it may be faster to specify a variable for the Display option to return the
  48. entry text, and use that text in a SEEK.
  49.  
  50. Depending on your data, it may be faster to use field expressions without
  51. TRIM or use field numbers which perform no trimming. The bottleneck seems to
  52. be FoxBase, but it obviously costs you more memory to leave the blanks at the
  53. end of fields.
  54.  
  55. Underestimating the number of records and/or average record size will have a
  56. direct impact on Load performance, as it has to expand handles for each record!
  57.  
  58. If you are loading a file that has relations to other files, turning off
  59. relations will speed up the Load. You can turn them back on immediately after.
  60.  
  61. Display is faster if the tabbing facility is not used.
  62.  
  63.  
  64. COMMON CAUSES OF ERRORS and SUDDEN CRASHES (Bus Errors, etc.)
  65. Specifying a Fox expression in the Load that doesn't actually work.
  66.  
  67. Changing the numbering of the first four items of the dialog resource
  68. (See the "D" case for details on how these items are used).
  69.  
  70.  
  71. DETAILS OF USE
  72.  
  73. SUMMARY OF ERROR RETURNS
  74.     -1 = unspecified error
  75.     -2 = unable to allocate memory
  76.     -3 = no dialog resource
  77.     -4 = specified array doesn't exist
  78.     -5 = not enough parameters for this option
  79.     -6 = unknown case
  80.     -7 = unable to create text file
  81.     NOTE: the return status is a CHARACTER variable - evaluate with val(status)
  82.     
  83.  
  84.  DETAILS OF DIALOG RESOURCE
  85.  
  86.  The resource is not re-sized or re-positioned in any way from your definition (note the System
  87.  7 capabilities for auto-positioning, able to be set by ResEdit 2.1).
  88.  
  89.  Certain basic elements are presumed to be present (note the Apple guidelines say the OK button
  90.  should be on the RHS of the dialog, with Cancel to its left, on English script systems):
  91.  1    OK button        (name unimportant, outlined & activated by Return or Enter)
  92.  2    Cancel button    (name unimportant, activated by command-period or esc)
  93.  3    Runtime-replaceable title (if parameter not specified, is left as is)
  94.  4    User item for list
  95.  
  96.  
  97.  DETAILS OF FUNCTIONS
  98.  
  99.  COMMON PARAMETERS
  100.  1 = Function switch value in first character
  101.                   I Init XCMD (perform ONCE)
  102.                   C Cleanup array (perform at least ONCE, possibly more)
  103.                   L Load Array
  104.                   D Display Dialog
  105.                   F File the data in a text file
  106.                   
  107.  2 = array number (if storing multiple arrays), omit or zero if using default
  108.  (except for where specified)
  109.               
  110.  Other parameters vary according to switch. Some options will also have Modifier characters following the
  111.  switch character. Neither the Function switch or Modifiers are case sensitive.
  112.  
  113. Note: declare the result variable in advance (eg: res = 0)
  114.  
  115. Case I - Init XCMD
  116.  PARAMETERS
  117.  2 = (optional) number of arrays you will need - saves a bit of memory movement later
  118.  
  119.  RESULT size (bytes) of array
  120.  ERROR RESULTS  -1 = unspecified error
  121.                 -2 = unable to allocate memory
  122.  
  123.  
  124. Case C - Cleanup
  125.  2 = array number (omit to cleanup all)
  126.  
  127.  RESULT undefined
  128.  ERROR RESULTS  -1 = unspecified error
  129.                 -4 = specified array doesn't exist
  130.  
  131.  
  132. Case L - Load Array
  133.  ASSUMPTIONS
  134.  - current file (or related files if using field expressions) is/are
  135.    positioned at the 1st rec to load
  136.    
  137.  - if loading record numbers, it is only for the current file. The record
  138.    number is retrieved BEFORE the field expression, in case the field
  139.    expression has side-effects.
  140.    
  141.  MODIFIERS
  142.           R - load record numbers (needed to support returning record number
  143.             from dialog) creates a second array and loads the record numbers
  144.             at the same time as loading the fields.
  145.         > - Sort ascending
  146.         < - Sort descending (mutually exclusive)
  147.         # - Sort numerically instead of alphabetically
  148.             
  149.  NOTES
  150.  The load process starts from the beginning of the array and expands to fit
  151.  but doesn't shrink the memory already allocated (if allocated at an
  152.  earlier Load). Call the Cleanup with this array number to remove the array.
  153.                 
  154.  You can significantly improve the performance of the load by specifying the
  155.  number of recs to load, as well as the optional "estimated record size". This
  156.  enables the load function to pre-allocate the space rather than having to
  157.  expand the array space as each record is loaded - a time-consuming overhead!
  158.  
  159.  PARAMETERS
  160.  2 = array number
  161.  3 = number of recs to load, zero = load to EOF
  162.  4 = estimated average record size (used to increase performance)
  163.  5 = command to skip to the next record (eg: "SKIP", "SKIP 10", "CONTINUE")
  164.  6 = field number from which to load array (in current file)
  165.                       OR
  166.      field expression
  167.       eg1: "otherFile->Name"
  168.       eg2: "trim(surname-"+chr(34)+", "+chr(34)+"-othername)"     && trim max spaces
  169.       eg3: "code+chr(9)+trim(descr)"      && tab to always indent descr same amount
  170.           
  171.  RESULT  zero = loaded OK
  172.             or
  173.         size (bytes) of array needed that failed to be allocated in expanding
  174.         (note that this could be a recno or data array, if using "R" modifier)
  175.  ERROR RESULTS  -1 = unspecified error
  176.                 -2 = unable to allocate memory
  177.  
  178.  
  179.  
  180. Case F - File to text file  (*** ,maybe buggy - see end)
  181.  2 = array number
  182.  3 = name of text file
  183.  4 = signature of text file creator (eg: 'McSk')
  184.  
  185.  NOTE
  186.  Overwrites the file without warning.
  187.  
  188.  RESULT undefined
  189.  ERROR RESULTS  -1 = unspecified error
  190.                 -4 = specified array doesn't exist
  191.                 -7 = unable to create text file
  192.  
  193.  
  194.  
  195. Case D - display dialog
  196. MODIFIERS
  197.         > - Sort ascending
  198.         < - Sort descending (mutually exclusive)
  199.         # - Sort numerically instead of alphabetically
  200.          M - multiple selections
  201.          R - retain previous selections (ie: ignore a blank param 4)
  202.         E - return only elements of a tabbed display (eg: E1 returns the text of the
  203.             element(s) up to the first tab, E2 between the 1st & 2nd tabs etc.)
  204.          T - tab size in pixels for regular tab stops (eg: T40)
  205.          F - Font name & size for list contents (eg: F'Helvetica'8) default is Chicago 12
  206.  
  207.  PARAMETERS
  208.  2 = array number
  209.  3 = dialog resource id (eg: 1001)
  210.  4 = text to match for first item selected
  211.      OR
  212.      name of array containing multiple items to match
  213.      OR
  214.      leave blank to clear current selection & start with no selection (see flag R)
  215.      
  216.  5 = text to substitute into dialog field number 3 (reserved for user-defined
  217.      prompt)
  218.  6 = quoted name of optional variable to receive name of button pressed
  219.  7 = quoted name of optional variable to receive text of entry selected
  220.      (receives an array if the Multiple selection option on)
  221.  8 = quoted name of optional variable to receive record number of entry selected
  222.      (assuming the "R" modifier on the Load to also load record numbers, receives
  223.       an array if the Multiple selection option on)
  224.  
  225. eg:
  226. CALL xscrolllist TO res WITH "D" , 0 , 1001 , "c" , "The Title" , "btnVar" , "entryVar" , "recVar"
  227.  
  228.  
  229. NOTES
  230. SORTING
  231. If a sort is specified in the Load then there is no need to specify again at dialog display
  232. time, unless you want to sort in a different order. (eg: you could have a button on the
  233. dialog used to flip the sort order between ascending and descending, so you would call the
  234. dialog again after the user hit the button, with the opposite sort order).
  235.  
  236. ELEMENT return
  237. If your element is an odd number of characters then there is a bug in FoxBase that
  238. will return an extra character, you may need to use code like:
  239. entryvar=iif(right(entryvar,1)=chr(9),left(entryvar,len(entryvar)-1),entryvar)
  240. or just
  241. entryvar = left(entryvar,3)   && hardcoded item length
  242.  
  243.  
  244.  RESULT number of item chosen, zero if none or Cancel
  245.              OR
  246.          number of selections (if Modifier M)
  247.  ERROR RESULTS  -1 = unspecified error
  248.                 -3 = no dialog resource
  249.                 -4 = specified array doesn't exist
  250.  
  251.  
  252.  
  253.  
  254. Case G -   (*** not yet implemented - see end)
  255.            get value(s) from list, using same match criteria as Dialog selection
  256.           (returns data exactly as if the user just OK'd the initial selection)
  257. MODIFIERS
  258.          M - multiple values
  259.         E - return only elements of a tabbed display 
  260.  
  261.  PARAMETERS
  262.  2 = array number
  263.  3 = text to match for first item selected
  264.      OR
  265.      name of array containing multiple items to match
  266.  4 = quoted name of variable to receive text of entry selected
  267.      (receives an array if the Multiple selection option on)
  268.  5 = quoted name of optional variable to receive record number of entry selected
  269.      (assuming the "R" modifier on the Load to also load record numbers, receives
  270.       an array if the Multiple selection option on)
  271.  
  272. WARNING (may not apply - check when I implement!)
  273. Destroys current selection in list - the items matched in this operation are left
  274. selected.
  275.  
  276. ELEMENT return
  277. See notes under Case D - Dialog display
  278.  
  279.  RESULT number of item found, zero if none or Cancel
  280.              OR
  281.          number of selections (if Modifier M)
  282.  ERROR RESULTS  -1 = unspecified error
  283.                 -4 = specified array doesn't exist
  284.  
  285.                  
  286.                   
  287. ***************************************************************************
  288.  
  289. YET TO BE IMPLEMENTED
  290.  
  291. Case D - display dialog Modifiers
  292. MODIFIERS
  293.          F - Font name & size for list contents (eg: F'Helvetica'8) default is Chicago 12
  294.          R - retain previous selections (ie: ignore a blank param 4)
  295.      
  296. setting initial values in case M multiple selection
  297.  
  298.  
  299. Case F - File to text file
  300. may have some bugs, hasn't been tested since MAJOR changes
  301.  
  302.  
  303. Case G - get value(s) from list
  304. not yet implemented
  305.  
  306.  
  307. FUTURE IDEAS (please give your feedback)
  308. A form of Quick dialog which allows specification of the item names via
  309. a Fox array, or character string, to save on the complexity of managing arrays.
  310.  
  311. Buttons and/or keystrokes that jump to the prev/next marked element on a
  312. multiple - selection list.
  313.  
  314. Updates in-place of single array items.
  315.  
  316. Control over list colour.
  317.  
  318. Control over list style.
  319.  
  320. User-written comparison & search functions (C or Pascal, compiled as "pure
  321. code resources").
  322.  
  323. ***************************************************************************
  324.  
  325.  
  326. SHAREWARE DETAILS
  327. Godfather Holdings Pty Ltd as trustee for the Dent Family
  328. Trust Trading as A.D. Software
  329. Australian Company Number    009 453 007
  330.  
  331. Contact: Andy Dent BSc, MACS
  332. 94 Bermuda Drive, Ballajura  Western Australia 6066
  333. Phone/Fax:        (09) 249 2719
  334. International:    61 9 249 2719
  335. CompuServe:     100033, 3241
  336. Internet:        dent@dialix.oz.au
  337.  
  338. PAYMENT VIA
  339. International Money Orders
  340. Australian dollars cash
  341. Australian bank or personal cheques (made out to A.D. Software)
  342. Visa, Mastercard or Australian Bankcard
  343. **CompuServe users - I will be registering this software under SWREG, which enables you
  344. to pay me by CompuServe (GO SWREG for details).
  345.  
  346. FEE & UPDATE DETAILS
  347. The fee is $50 Australian (due to our rotten exchange rate this is about $36 US).
  348. Registered users will receive free upgrades with notices mailed (electronically
  349. where possible) of new versions being uploaded, and available on disk for a
  350. nominal shipping fee, on request.
  351.  
  352. A second fee (same amount) is requested for the use of the source code (registered
  353. users get the right to ask "why the !@#$ did you do it that way!?!") :-)
  354.  
  355. OTHER FOXBASE XCMDS
  356. XBrowse2Click - provides trapping of double-click, Tab, Enter & Return keys to generate
  357. a command key of your choice. Perfect for adding double-clicking etc. to your BROWSE!
  358.  
  359. XGetDepth - returns the pixel depth (ie 2, 4, 8, 16 or 32) of the screen (freebie)
  360.  
  361.  
  362. OTHER PRODUCTS & SERVICES
  363. A.D. Software is a custom software development house ╤ if you have any other
  364. XCMD or other programming requirements, please contact me for further information.
  365.  
  366. Major products include a FORTRAN->Pascal translator and multi-user classified
  367. advertisement publishing system.
  368. ---------------------------------------------------------------------------------*/
  369.