home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / xbase / library / clipper / screen / fxcolor.doc < prev    next >
Text File  |  1992-04-15  |  33KB  |  907 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.             ▓▓▓▓▓  ▓   ▓  ▓▓▓▓▓  ▓▓▓▓▓  ▓      ▓▓▓▓▓  ▓▓▓▓▓
  10.             ▓       ▓ ▓   ▓      ▓   ▓  ▓      ▓   ▓  ▓   ▓
  11.             ▓▓▓      ▓    ▓      ▓   ▓  ▓      ▓   ▓  ▓▓▓▓▓
  12.             ▓       ▓ ▓   ▓      ▓   ▓  ▓      ▓   ▓  ▓  ▓
  13.             ▓      ▓   ▓  ▓▓▓▓▓  ▓▓▓▓▓  ▓▓▓▓▓  ▓▓▓▓▓  ▓   ▓
  14.  
  15.                             User Reference
  16.  
  17.                          FXCOLOR DOCUMENTATION
  18.       Special Color Effects For The VGA System Using Clipper 5.01
  19.  
  20.                          Written by Jim Fowler
  21.                             April 16, 1992
  22.  
  23.  
  24. While recently developing an application in Clipper 5.01 for a client, I
  25. was asked by the client why he was "stuck" with the sixteen basic
  26. colors.  After all, he had paid a lot of money for a first-class VGA
  27. system, so he figured he should be receiving an application that took
  28. advantage of the color capabilities of the VGA.  I explained that a
  29. text-based application is limited to 16 displayable colors by DOS, and
  30. that Clipper only uses the "standard" colors.  "I've seen other Clipper
  31. applications and they use other than the 16 standard colors", he replied.
  32. Thus began my search for a palette editing function for Clipper.
  33.  
  34. Several third-party libraries have such a function.  However, I am no
  35. longer in the mood to spend a couple of hundred dollars every time I
  36. need a function.
  37.  
  38. SOAPBOX( ON )
  39. Clipper 5.01 is the best development language I have used.  It is also
  40. the most expensive.  I paid $500 to purchase Clipper 5.0 about a year
  41. ago.  Since, I have spent nearly $1,600 for third-party products to
  42. enhance Clipper.  I fear the day when the next version of Clipper is
  43. released.  I'll probably have to come up with a couple hundred dollars
  44. to upgrade Clipper, and maybe a thousand dollars to upgrade the
  45. third-party libraries.
  46.  
  47. My #1 complaint with Clipper is that it is not a full-development
  48. product.  Clipper provides a "base" of functions, but not the functions
  49. needed to really make your product shine.  You have to get these from
  50. third-party developers.  In my opinion, if all you use is Clipper's
  51. "base" functions, you have nothing more than a better way of executing
  52. dBase code.  In addition, Clipper provides no editing environment
  53. (PE.EXE is a joke), and a very poor database utility (DBU.EXE).  The
  54. debugger, CLD.EXE, is an improvement, but still sadly lacking.  Ever
  55. tried "auto-stepping" through the code?  And where's the mouse
  56. interface?
  57.  
  58. A GREAT majority of my clients still perceive Clipper as a dBase
  59. compiler.  Nantucket has apparently done little (or have been
  60. ineffective) in changing this perception.  Now that Borland owns dBase,
  61. and with their reputation for programming languages, a dBase with a
  62. dBase compiler is surely at hand.  I wonder if most of those clients
  63. will still believe they need Clipper.
  64. SOAPBOX( OFF )
  65.  
  66. Not wanting to spend more money on, yet, another library just to get a
  67. function, I began searching for something in the public domain.  I
  68. didn't find a function specifically for Clipper, but I did find a great
  69. little program written by Chris Dunford.  Unfortunately, it was written
  70. in assembly and my knowledge of assembly is limited.  It appeared quite
  71. a few modifications would be required to make it work with Clipper.
  72. Nevertheless, having more pride and principles than money, I thought I'd
  73. give it a try.  FXCOLOR is the result.
  74.  
  75. CREDITS
  76. -------
  77. Chris Dunford deserves credit for writing the code upon which FXCOLOR is
  78. based.  Without his code to go by, and his methodology, I doubt I could
  79. have written FXCOLOR.  Although a great majority of the code in
  80. FXCOLOR.ASM was written by me, portions of the code were taken directly
  81. from Chris's program.  The document VGA.DOC was written by Chris and
  82. edited by me for inclusion with this package.  It is one of the better
  83. explanations of the VGA and DOS color system I have seen.
  84.  
  85. Your comments, suggestions, and criticisms concerning FXCOLOR are
  86. welcome and should be addressed to me -- Jim Fowler, CompuServe ID#
  87. 73340,3425.
  88.  
  89. I am releasing FXCOLOR to the public domain for reasons stated in my
  90. soapbox diatribe.  Maybe it will save a few dollars for someone else
  91. who, like me, doesn't want to continue to spend hundreds of dollars just
  92. to produce a quality program.
  93.  
  94.  
  95. DISCLAIMER & DISTRIBUTION RIGHTS
  96. --------------------------------
  97. Neither Jim Fowler, or Chris Dunford, make any guarantees of any kind
  98. about this product.  By using it, you agree that they will not be held
  99. liable for any damage caused by the use of this product.  USE IT AT
  100. YOUR OWN RISK.  If your screen displays some wierd colors or patterns,
  101. or your computer sizzles, or for any other catastrophe, it is YOUR
  102. problem, not ours.
  103.  
  104. This product is released to the public domain.  It may be copied and
  105. distributed for free.  You may not charge any fee for its distribution
  106. other than a small charge for postage and diskette(s).  You may use this
  107. product in the development of applications without fee or royalty to the
  108. author.  You MAY NOT use this product in the development of commercial
  109. libraries for resale without the permission of the author.
  110.  
  111. If you distribute this product, you must include all of the following
  112. files, unedited:
  113.      README.1ST    ->  Text file containing instructions and latest info
  114.      MAKEDEMO.BAT  ->  Batch file for compiling the demo program
  115.      FXDEMO.PRG    ->  Source code for the demo program
  116.      FXCOLOR.ASM   ->  The source code for this product
  117.      FXCOLOR.OBJ   ->  The compiled object file
  118.      FXCOLOR.DOC   ->  Documentation of the product (this file)
  119.      VGA.DOC       ->  Document file describing the VGA color system
  120.  
  121. The file VGA.DOC is an edited version of a copyrighted document by Chris
  122. Dunford.  The contents of that file may not be republished without the
  123. written permission of Jim Fowler and Chris Dunford.  The original
  124. document by Chris Dunford can be obtained by contacting him.
  125.  
  126. USING FXCOLOR WITH CLIPPER
  127. --------------------------
  128. FXCOLOR is designed for Clipper version 5.01.  It has not been tested
  129. with other versions and may or may not be compatible.  It requires a VGA
  130. system and will not install itself unless a VGA is detected.  It is
  131. designed to work with color systems.  The effects on a non-color system
  132. has not been tested.
  133.  
  134. FXCOLOR must be installed before it can be used.  The command
  135. fx_Enable() is used to install FXCOLOR.  None of the commands (except
  136. fx_IsFxOn() and fx_IsVGA() - see docs for those commands) will perform
  137. any action and will probably return meaningless values if called while
  138. FXCOLOR is NOT installed.
  139.  
  140. FXCOLOR must be uninstalled before exiting your application.  The
  141. command fx_Disable() is used to uninstall FXCOLOR.  Although FXCOLOR
  142. includes detection for program termination and will uninstall itself if
  143. program termination is detected, this should not be relied upon.  You
  144. should use the fx_Disable() command.
  145.  
  146. When FXCOLOR is installed, it hooks the timer interrupt 1Ch and
  147. interrupt 21h.  These remain active until uninstalled.  If your
  148. application uses other intercept routines, you should be sure to nest
  149. those routines.  An example is below:
  150.  
  151.      fx_Enable()              <- FXCOLOR timer intercept is installed
  152.         OtherTimer( ON )      <- another timer intercept is installed
  153.         ....                  <- other application code
  154.         OtherTimer( OFF )     <- another timer intercept is uninstalled
  155.      fx_Disable()             <- FXCOLOR timer intercept is uninstalled
  156.  
  157. Failure to nest intercept routines will undoubtedly cause you great
  158. suffering.
  159.  
  160. FXCOLOR also disables the hardware blinking bit when installed and
  161. re-enables it when uninstalled.  When the hardware blinking bit is
  162. disabled, high-intensity background colors are allowed.  The Clipper
  163. SetBlink() command performs the same function.  You may use the
  164. SetBlink() command while FXCOLOR is installed to set hardware blinking
  165. ON or OFF.  Remember though, if any high-intensity background colors are
  166. currently displayed, they will revert to normal and the foreground text
  167. will begin blinking.
  168.  
  169. With hardware blinking OFF, if you want to display a high-intensity
  170. background color, you should use an asterisk "*" instead of a plus-sign
  171. "+" for the background color in the CLIPPER color string:
  172.  
  173.      "r/bg*"  <- Ok
  174.      "r/bg+"  <- Does not work
  175.  
  176. For FXCOLOR parameters however, you must use the plus-sign "+" to denote
  177. high-intensity colors:
  178.  
  179.      fx_Blink( "r", "bg+" )  <- Ok
  180.      fx_Blink( "r", "bg*" )  <- Does not work
  181.  
  182. CHANGING SCREEN MODES
  183. ---------------------
  184. When your computer is booted, it defaults to a "mode 0" which configures
  185. the video to 4 palettes of 64 colors each for text mode.  FXCOLOR
  186. changes to "mode 1" which configures the video to 16 palettes of 16
  187. colors each for text mode (see VGA.DOC for more info).  If you change
  188. screen modes during your application (i.e. say from a 25 row screen to a
  189. 43 row screen), the video is reconfigured to "mode 0".  This would
  190. result in some odd results for your video.  Therefore, when changing
  191. screen modes, it is recommended that you uninstall FXCOLOR (with
  192. fx_Disable()) and then reinstall (with fx_Enable()) after you have
  193. changed screen modes.  Unfortunately, all of your color definitions will
  194. be lost and will have to be redefined.
  195.  
  196.  
  197. ATTRIBUTES, PALETTES, AND RGB VALUES
  198. ------------------------------------
  199. When using FXCOLOR, you should think in terms of attributes rather than
  200. colors.  Normally, they are the same thing.  However, if you change
  201. attribute 1, blue, to the color orange, it no longer has anything to do
  202. with blue.  Unfortunately, in Clipper, you must still refer to this
  203. attribute by the color symbol "b".  It would be much better if you could
  204. refer to it by attribute number rather than color symbol.  In that were
  205. the case, if you preferred the symbols, you could always use
  206. pre-processor #DEFINE's.  To maintain consistentcy with Clipper however,
  207. FXCOLOR will only accept the color symbols.  To do otherwise would just
  208. cause more confusion on top of the confusion you will encounter trying
  209. to remember what color symbol produces what color you've defined.
  210.  
  211. As mentioned earlier, FXCOLOR uses 16 palettes of 16 attributes each.
  212. The palettes are referred to by the values 0 to 15.  Palette 0 is the
  213. primary palette used to determine the RGB definitions of attributes
  214. for those commands creating special effects.  For example, the command
  215. fx_Fade( "g" , "b" ) means to fade the RGB values of attribute 2 ("g")
  216. to the RGB values of attribute 1 ("b").  The RGB values for both
  217. attributes are taken from palette 0.  Thus, the RGB value of attribute
  218. 2, as defined in palette 0, will fade to the RGB value of attribute 1,
  219. as defined in palette 0.
  220.  
  221. RGB values are the RED, GREEN, and BLUE values that, when mixed in
  222. different proportions, produces colors on your monitor (refer to VGA.DOC
  223. for more info).  RGB values are specified in the range 0 to 63 and refer
  224. to the intensity of a particular primary color.
  225.  
  226.  
  227. CONVENTIONS USED
  228. ----------------
  229. Arguments to commands which are enclosed in brackets "[]" are optional
  230. to the command.
  231.  
  232. All variable argument names are prefaced by a lower case letter.  This
  233. letter denotes the type of variable:
  234.  
  235.      "c" denotes a character string
  236.      "n" denotes a numeric value
  237.      "l" denotes a logical (.T./.F.) value
  238.  
  239. fx_Attr()
  240. ---------
  241. Gets/sets the RGB values of a single attribute for all palettes.
  242.  
  243. Syntax:
  244.      fx_Attr( <cBaseAttr>, [<cRGBString>] )   ->   cRGBString
  245.  
  246. Arguments:
  247.      <cBaseAttr> is a character string containing an attribute symbol
  248.      whose RGB values are to be get/set.  The attribute symbol must be
  249.      one of the following color symbols supported by Clipper:
  250.  
  251.      "N", "B", "G", "BG", "R", "RB", "GR", "W", "N+", "B+", "G+", "BG+",
  252.      "R+", "RB+", "GR+", or "W+".  (Case is not important.)
  253.  
  254.      <cRGBString> is a 48-byte character string with each byte
  255.      containing an ASCII value representing the RGB values of the
  256.      attribute for all 16 palettes.  The first three bytes represent the
  257.      RED/GREEN/BLUE (RGB) values for the attribute in palette 0, the
  258.      fourth through sixth bytes represent palette 1, and so forth.  In
  259.      chart form:
  260.  
  261.                         Palette 0                   Palette 15
  262.                      Red  Green  Blue            Red  Green  Blue
  263.           Byte # ->   1     2     3     .....     46    47    48
  264.  
  265. Returns:
  266.      Returns the current RGB settings for the attribute in a 48-byte
  267.      character string where each byte of the string is an ASCII value
  268.      representing the RGB values of the attribute across each of the 16
  269.      palettes.  If an undefined attribute symbol is specified or the
  270.      string is not exactly 48 bytes in length (when specified) or an
  271.      error occurs, an empty string is returned.
  272.  
  273. Description:
  274.      fx_Attr() is a function that allows you to get or set the RGB
  275.      values of an attribute for all 16 palettes.  When <cRGBString> is
  276.      specified, it sets the new RGB values contained in the character
  277.      string for <cBaseAttr>.  If the ASCII value is outside the range 0
  278.      to 63, that particular RGB value is skipped.
  279.  
  280. Examples:
  281.      // Replaces the RGB values for attribute "g" in palette 4
  282.      // with the RGB values for high-intensity red.
  283.      IF .NOT. EMPTY( cColor := fx_Attr( "g" ) )
  284.         cColor := STUFF( cColor, 13, 3, CHR(63) + CHR(0) + CHR(0) )
  285.         fx_Attr( "g", cColor )
  286.      ENDIF
  287.  
  288.      // Makes the attribute "w" equal to the attribute "n"
  289.      // in all palettes.
  290.      cColor := fx_Attr( "n" )
  291.      fx_Attr( "w", cColor )
  292.  
  293. See Also:
  294.      fx_AttrAll(), fx_PalAll(), fx_Palette()
  295.  
  296. fx_AttrAll()
  297. ------------
  298. Gets/sets the RGB values of all attributes for all palettes.
  299.  
  300. Syntax:
  301.      fx_AttrAll( [<cRGBString>] )   ->   cRGBString
  302.  
  303. Arguments:
  304.      <cRGBString> is a 768-byte character string with each byte
  305.      containing an ASCII value representing the RGB values for each
  306.      attribute for all palettes.  The first forty-eight bytes represent
  307.      the RED/GREEN/BLUE (RGB) values for attribute 0 for all palettes,
  308.      the next 48 bytes represent the next attribute, and so forth.  In
  309.      chart form:
  310.  
  311.                                Palette 0                   Palette 15
  312.                             Red  Green  Blue            Red  Green  Blue
  313.           Attribute  0  ->    1     2     3    .....     46    47    48
  314.                 ...     ->  ...   ...   ...    .....    ...   ...   ...
  315.           Attribute 15  ->  721   722   723    .....    766   767   768
  316.                 Byte # ------^-----^-----^---------------^-----^-----^
  317.  
  318. Returns:
  319.      Returns the current RGB settings for all attributes in a 768-byte
  320.      character string where each byte of the string is an ASCII value
  321.      representing the RGB values of each attribute foe each of the 16
  322.      palettes.  The string is in attribute order.  If the string is not
  323.      exactly 768 bytes in length (when specified) or an error occurs, an
  324.      empty string is returned.
  325.  
  326. Description:
  327.      fx_AttrAll() is a function that allows you to get or set the RGB
  328.      values of all attributes for all palettes.  When <cRGBString> is
  329.      specified, it sets the new RGB values contained in the character
  330.      string for <cBaseAttr>.  If the ASCII value is outside the range 0
  331.      to 63, that particular RGB value is skipped.
  332.  
  333. Examples:
  334.      // Prints the RGB values of all attributes in attribute order.
  335.      cAttr := fx_AttrAll()
  336.      ? "Attribute  Pal_0  Pal_1  Pal_2  ...  Pal_15"
  337.      FOR nLoop = 1 to 768
  338.         IF nLoop % 48 == 1
  339.            ?? CHR(13) + CHR(10)
  340.            ?? STR( nLoop, 3 ) + SPACE( 8 )
  341.         ENDIF
  342.         ?? STR( ASC( SUBSTR( cAttr, nLoop, 1 ) ), 2 ) + SPACE ( 5 )
  343.      NEXT
  344.  
  345.      // Saves and restores the RGB values in attribute order.
  346.      cSaveAttr := fx_AttrAll()
  347.      ...     // (your code)
  348.      fx_AttrAll( cSaveAttr )
  349.  
  350. See Also:
  351.      fx_Attr(), fx_PalAll(), fx_Palette()
  352.  
  353. fx_Blink()
  354. ----------
  355. Produces a blinking effect.
  356.  
  357. Syntax:
  358.      fx_Blink( <cBaseAttr>, <cSecondAttr>, [<lSoftBlink>] )   ->   NIL
  359.  
  360. Arguments:
  361.      <cBaseAttr> is a character string containing an attribute symbol
  362.      to blink FROM.  The attribute symbol must be one of the following
  363.      color symbols supported by Clipper:
  364.  
  365.      "N", "B", "G", "BG", "R", "RB", "GR", "W", "N+", "B+", "G+", "BG+",
  366.      "R+", "RB+", "GR+", or "W+".  (Case is not important.)
  367.  
  368.      <cSecondAttr> is also a character string containing an attribute
  369.      symbol to blink TO.  The attribute symbol must also be one of the
  370.      color symbols supported by Clipper.
  371.  
  372.      <lSoftBlink> is a logical TRUE or FALSE (.T./.F.).  When TRUE, the
  373.      blinking effect is "softened" by fading <cSecondAttr>.  The default
  374.      value is FALSE.
  375.  
  376. Returns:
  377.      Always returns a NIL value.
  378.  
  379. Description:
  380.      fx_Blink() produces a blinking effect by alternating <cBaseAttr>
  381.      and <cSecondAttr> repeatedly thus creating an on/off effect.  If an
  382.      undefined attribute symbol is specified or an error occurs, the
  383.      effect will not occur.  Usually <cBaseAttr> is a foreground
  384.      attribute and <cSecondAttr> is a background attribute, but this
  385.      does not have to be the case.
  386.  
  387. Examples:
  388.      // Blinks attribute "r" to attribute "g".
  389.      fx_Blink( "r", "g" )
  390.  
  391.      // Blinks attribute "w" to attribute "n" with a softened effect.
  392.      fx_Blink( "w", "n", .T. )
  393.  
  394. See Also:
  395.      fx_IntRate(), fx_PalRate(), fx_SetFix()
  396.  
  397. fx_Disable()
  398. ------------
  399. Uninstalls the color effects system.
  400.  
  401. Syntax:
  402.      fx_Disable()   ->   NIL
  403.  
  404. Arguments:
  405.      None.
  406.  
  407. Returns:
  408.      Always returns NIL value.
  409.  
  410. Description:
  411.      fx_Disable() must be called prior to termination of the application
  412.      program.  It may however, be called at any time within the program
  413.      when it is desirable to uninstall the color effects system.  It
  414.      should also be called prior to switching screen modes.  When
  415.      called, all settings are cleared and lost.  Calling fx_Disable()
  416.      when the color effects system has not been installed has no effect.
  417.  
  418. Example:
  419.      // Installs and uninstalls the color effects system.
  420.      IF fx_Enable()
  421.         ? "Color effects system installed, now uninstalling".
  422.         fx_Disable()
  423.      ENDIF
  424.  
  425. See Also:
  426.      fx_Enable(), fx_IsFxOn()
  427.  
  428. fx_Enable()
  429. -----------
  430. Installs the color effects system.
  431.  
  432. Syntax:
  433.      fx_Enable()   ->   lSuccess
  434.  
  435. Arguments:
  436.      None.
  437.  
  438. Returns:
  439.      Returns a logical TRUE or FALSE (.T./.F.) indicating whether or not
  440.      the color effects system was installed.
  441.  
  442. Description:
  443.      fx_Enable() must be called prior to using any of the color effects
  444.      system commands except fx_IsFxOn() and fx_IsVGA(), and to reinstall
  445.      the color effects system after a fx_Disable() command.  Subsequent
  446.      calls to fx_Enable() after it is already installed return a logical
  447.      TRUE value.  fx_Enable() will return a FALSE value if a VGA system
  448.      is not detected.  The command fx_IsVGA() can be used to test for a
  449.      VGA.  To test whether or not the color effects system is installed
  450.      without actually installing it, use the command fx_IsFxOn().
  451.  
  452. Example:
  453.      // Installs the color effects system if there is no error.
  454.      IF fx_Enable()
  455.         ? "Color effects system installed."
  456.      ELSE
  457.         ? "Color effects system NOT installed."
  458.      ENDIF
  459.  
  460. See Also:
  461.      fx_Disable(), fx_IsFxOn(), fx_IsVGA()
  462.  
  463. fx_Fade()
  464. ---------
  465. Produces a fading effect.
  466.  
  467. Syntax:
  468.      fx_Fade( <cBaseAttr>, <cSecondAttr> )   ->   NIL
  469.  
  470. Arguments:
  471.      <cBaseAttr> is a character string containing an attribute symbol
  472.      to fade FROM.  The attribute symbol must be one of the following
  473.      color symbols supported by Clipper:
  474.  
  475.      "N", "B", "G", "BG", "R", "RB", "GR", "W", "N+", "B+", "G+", "BG+",
  476.      "R+", "RB+", "GR+", or "W+".  (Case is not important.)
  477.  
  478.      <cSecondAttr> is also a character string containing an attribute
  479.      symbol to fade TO.  The attribute symbol must also be one of the
  480.      color symbols supported by Clipper.
  481.  
  482. Returns:
  483.      Always returns a NIL value.
  484.  
  485. Description:
  486.      fx_Fade() produces a fading effect by gradually changing the RGB
  487.      values for <cBaseAttr> into the RGB values for <cSecondAttr> and
  488.      back again.  If an undefined attribute symbol is specified or an
  489.      error occurs, the effect will not occur.
  490.  
  491. Examples:
  492.      // Fades attribute "b" to attribute "r+".
  493.      fx_Fade( "b", "r+" )
  494.  
  495.      // Fades attribute "bg+" to attribute "n".
  496.      fx_Fade( "bg+", "n", .T. )
  497.  
  498. See Also:
  499.      fx_IntRate(), fx_PalRate(), fx_SetFix()
  500.  
  501. fx_IntRate()
  502. ------------
  503. Gets/sets the timer tick interval period.
  504.  
  505. Syntax:
  506.      fx_IntRate( [<nInterval>] )   ->   nInterval
  507.  
  508. Arguments:
  509.      <nInterval> is an integer value in the range 1 to 32767.  This
  510.      value determines the number of timer ticks (18.2 per second) to
  511.      SKIP before incrementing (rotating) the current palette.
  512.  
  513. Returns:
  514.      Returns the current setting as an integer value.
  515.  
  516. Description:
  517.      fx_IntRate() is primarily used to DECREASE the speed of the fading,
  518.      pulsing, and blinking effects.
  519.  
  520. Example:
  521.     // Print the current setting and reset a new rate.
  522.     ? fx_IntRate( 2 )
  523.  
  524. See Also:
  525.      fx_PalRate(), fx_SetFix()
  526.  
  527. fx_IsFxOn()
  528. -----------
  529. Tests for installation of the color effects system.
  530.  
  531. Syntax:
  532.      fx_IsFxOn()   ->   lInstalled
  533.  
  534. Arguments:
  535.      None.
  536.  
  537. Returns:
  538.      Returns a logical TRUE or FALSE value (.T./.F.) indicating whether
  539.      or not the color effects system is installed.
  540.  
  541. Description:
  542.      fx_IsFxOn() can be used to determine if the color effects system is
  543.      installed without actually installing it.  This command may be used
  544.      at any time.
  545.  
  546. Example:
  547.      // If the color effects system is installed,
  548.      // then fade some attributes.
  549.      IF fx_IsFxOn()
  550.         fx_Fade( "n", "w" )
  551.      ENDIF
  552.  
  553. See Also:
  554.      fx_Disable(), fx_Enable()
  555.  
  556. fx_IsVGA()
  557. ----------
  558. Tests for installation of a VGA.
  559.  
  560. Syntax:
  561.      fx_IsVGA()   ->   lInstalled
  562.  
  563. Arguments:
  564.      None.
  565.  
  566. Returns:
  567.      Returns a logical TRUE or FALSE value (.T./.F.) indicating whether
  568.      or not a VGA system is installed.
  569.  
  570. Description:
  571.      fx_IsVGA() can be used to determine if a VGA system is installed.
  572.      A VGA is required to install the color effects system.  This
  573.      command may be used at any time.
  574.  
  575. Examples:
  576.      // If a VGA is installed, then install the color effects system.
  577.      IF fx_IsVGA()
  578.         fx_Enable()
  579.      ENDIF
  580.  
  581. See Also:
  582.      fx_Enable()
  583.  
  584. fx_PalAll()
  585. -----------
  586. Gets/sets the RGB values of all palettes for all attributes.
  587.  
  588. Syntax:
  589.      fx_PalAll( [<cRGBString>] )   ->   cRGBString
  590.  
  591. Arguments:
  592.      <cRGBString> is a 768-byte character string with each byte
  593.      containing an ASCII value representing the RGB values for attribute
  594.      in each palette.  The first forty-eight bytes represent the
  595.      RED/GREEN/BLUE (RGB) values for palette 0 for all attributes, the
  596.      next 48 bytes represent the next palette, and so forth.  In chart
  597.      form:
  598.  
  599.                             Attribute 0                 Attribute 15
  600.                           Red  Green  Blue            Red  Green  Blue
  601.         Palette    0  ->    1     2     3    .....     46    47    48
  602.               ...     ->  ...   ...   ...    .....    ...   ...   ...
  603.         Palette   15  ->  721   722   723    .....    766   767   768
  604.               Byte # ------^-----^-----^---------------^-----^-----^
  605.  
  606. Returns:
  607.      Returns the current RGB settings for all attributes in a 768-byte
  608.      character string where each byte of the string is an ASCII value
  609.      representing the RGB values of each attribute in each palette.  The
  610.      string is in palette order.  If the string is not exactly 768 bytes
  611.      in length (when specified) or an error occurs, an empty string is
  612.      returned.
  613.  
  614. Description:
  615.      fx_PalAll() is a function that allows you to get or set the RGB
  616.      values of all attributes for all palettes.  When <cRGBString> is
  617.      specified, it sets the new RGB values contained in the character
  618.      string for <cBaseAttr>.  If the ASCII value is outside the range 0
  619.      to 63, that particular RGB value is skipped.
  620.  
  621. Examples:
  622.      // Print the RGB values of all attributes in palette order.
  623.      cPals := fx_PalAll()
  624.  
  625.      ? "Palette  Attr_0  Attr_1  Attr_2  ...  Attr_15"
  626.      FOR nLoop = 1 to 768
  627.         IF nLoop % 48 == 1
  628.            ?? CHR(13) + CHR(10)
  629.            ?? STR( nLoop, 3 ) + SPACE( 6 )
  630.         ENDIF
  631.         ?? STR( ASC( SUBSTR( cPals, nLoop, 1 ) ), 2 ) + SPACE ( 6 )
  632.      NEXT
  633.  
  634.      // Save and restore the RGB values in palette order.
  635.      cSavePals := fx_PalAll()
  636.      ...     // (your code)
  637.      fx_PalAll( cSavePals )
  638.  
  639. See Also:
  640.      fx_Attr(), fx_AttrAll(), fx_Palette()
  641.  
  642. fx_Palette()
  643. ------------
  644. Gets/sets the RGB values of all attributes in a single palette.
  645.  
  646. Syntax:
  647.      fx_Palette( <nPalette>, [<cRGBString>] )   ->   cRGBString
  648.  
  649. Arguments:
  650.      <nPalette> is an integer value in the range 0 to 15 representing
  651.      the palette number to get/set.
  652.  
  653.      <cRGBString> is a 48-byte character string with each byte
  654.      containing an ASCII value representing the RGB values of each
  655.      attribute for all attributes in the palette.  The first three bytes
  656.      represent the RED/GREEN/BLUE (RGB) values for attribute 0, the
  657.      fourth through sixth bytes represent attribute 1, and so forth.
  658.      In chart form:
  659.  
  660.                        Attribute 0                 Attribute 15
  661.                      Red  Green  Blue            Red  Green  Blue
  662.           Byte # ->   1     2     3     .....     46    47    48
  663.  
  664. Returns:
  665.      Returns the current RGB settings for each attribute in a 48 byte
  666.      character string where each byte of the string is an ASCII
  667.      value representing the RGB values of all the attributes in the
  668.      the palette.  If an undefined palette is specified or the string
  669.      is not exactly 48 bytes in length (when specified) or an error
  670.      occurs, an empty string is returned.
  671.  
  672. Description:
  673.      fx_Palette() is a function that allows you to get or set the RGB
  674.      values of all attributes in a palette.  When <cRGBString> is
  675.      specified, it sets the new RGB values for all attributes in
  676.      <nPalette>.  If the ASCII value is outside the range 0  to 63, that
  677.      particular RGB value is skipped.
  678.  
  679. Examples:
  680.      // Replace the RGB values for attribute "gr+" in palette 7
  681.      // with the RGB values for high-intensity blue.
  682.      IF .NOT. EMPTY( cPal := fx_Palette( 7 ) )
  683.         cPal := STUFF( cPal, 43, 3, CHR(0) + CHR(0) + CHR(63) )
  684.         fx_Palette( 7, cPal )
  685.      ENDIF
  686.  
  687.      // Make all high-intensity attributes equal to their normal
  688.      // intensity complementary attribute in palette 2.
  689.      cPal := fx_Palette( 2 )
  690.      cSub := SUBSTR( cPal, 1, 24 )
  691.      cPal := cSub + cSub
  692.      fx_Palette( 2, cPal )
  693.  
  694. See Also:
  695.      fx_Attr(), fx_AttrAll(), fx_PalAll()
  696.  
  697. fx_PalRate()
  698. ------------
  699. Gets/sets the palette rotation increment rate.
  700.  
  701. Syntax:
  702.      fx_PalRate( [<nIncrement>] )   ->   nIncrement
  703.  
  704. Arguments:
  705.      <nIncrement> is an integer value in the range 1 to 15.  This
  706.      value determines the number of palettes to SKIP when rotating the
  707.      current palette.
  708.  
  709. Returns:
  710.      Returns the current setting as an integer value.
  711.  
  712. Description:
  713.      fx_PalRate() is primarily used to INCREASE the speed of the fading,
  714.      pulsing, and blinking effects.  It does this by skipping palettes
  715.      when rotated by the timer intercept routine.  Please be aware that
  716.      skipping palettes may cause some palettes never to be shown (ex: an
  717.      even increment will never display an odd numbered palette).  This
  718.      could cause some effects to not occur as intended.
  719.  
  720. Example:
  721.     // Print the current setting and reset a new rate.
  722.     ? fx_PalRate( 3 )
  723.  
  724. See Also:
  725.      fx_IntRate(), fx_SetFix()
  726.  
  727. fx_Pulse()
  728. ----------
  729. Produces a pulsing effect.
  730.  
  731. Syntax:
  732.      fx_Pulse( <cBaseAttr> )   ->   NIL
  733.  
  734. Arguments:
  735.      <cBaseAttr> is a character string containing an attribute symbol
  736.      to pulse.  The attribute symbol must be one of the following color
  737.      symbols supported by Clipper:
  738.  
  739.      "N", "B", "G", "BG", "R", "RB", "GR", "W", "N+", "B+", "G+", "BG+",
  740.      "R+", "RB+", "GR+", or "W+".  (Case is not important.)
  741.  
  742. Returns:
  743.      Always returns a NIL value.
  744.  
  745. Description:
  746.      fx_Pulse() produces a pulsing effect by periodically and gradually
  747.      displaying the maximum high-intensity RGB value of an attribute.
  748.      If an undefined attribute symbol is specified or an error occurs,
  749.      the effect will not occur.
  750.  
  751. Examples:
  752.      // Pulse attribute "b" to maximum high-intensity.
  753.      fx_Pulse( "b" )
  754.  
  755.      // Pulse attribute "bg+" to maximum high-intensity.
  756.      fx_Pulse( "bg+" )
  757.  
  758. See Also:
  759.      fx_IntRate(), fx_PalRate(), fx_SetFix()
  760.  
  761. fx_RestAll()
  762. ------------
  763. Restores all attributes.
  764.  
  765. Syntax:
  766.      fx_RestAll()   ->   NIL
  767.  
  768. Arguments:
  769.      None.
  770.  
  771. Returns:
  772.      Always returns a NIL value.
  773.  
  774. Description:
  775.      fx_RestAll() restores all attributes to their default RGB values
  776.      when the color effects system was installed.  It also resets the
  777.      palette increment rate and the timer interval period back to their
  778.      default values.  It sets the current "fixed" palette back to
  779.      palette 0 but DOES NOT change the current palette mode from "fixed"
  780.      to "rotation" or vice-versa.  This function may be called at any
  781.      time.
  782.  
  783. Example:
  784.     // Create several special color effects and then
  785.     // cancel all of them when a key is pressed.
  786.     fx_Fade( "n+", "gr" )
  787.     fx_Blink( "w", "r", .T. )
  788.     fx_Pulse( "gr+" )
  789.     INKEY( 0 )
  790.     fx_RestAll()
  791.  
  792. See Also:
  793.     fx_Restore()
  794.  
  795. fx_Restore()
  796. ------------
  797. Restores a specified attribute.
  798.  
  799. Syntax:
  800.      fx_Restore( <cBaseAttr> )   ->   NIL
  801.  
  802. Arguments:
  803.      <cBaseAttr> is a character string containing an attribute symbol
  804.      to restore.  The attribute symbol must be one of the following
  805.      color symbols supported by Clipper:
  806.  
  807.      "N", "B", "G", "BG", "R", "RB", "GR", "W", "N+", "B+", "G+", "BG+",
  808.      "R+", "RB+", "GR+", or "W+".  (Case is not important.)
  809.  
  810. Returns:
  811.      Always returns a NIL value.
  812.  
  813. Description:
  814.      fx_Restore() restores the RGB values of an attribute to its default
  815.      RGB values when the color effects system was installed.
  816.  
  817. Example:
  818.     // Blink an attribute and then restore
  819.     // it when a key is pressed.
  820.     fx_Blink( "bg+", "n" )
  821.     INKEY( 0 )
  822.     fx_Restore( "bg+")
  823.  
  824. See Also:
  825.     fx_RestAll()
  826.  
  827. fx_SetFix()
  828. -----------
  829. Sets/cancels "fixed" palette mode.
  830.  
  831. Syntax:
  832.      fx_SetFix( [<lSetting>] )   ->   lSetting
  833.  
  834. Arguments:
  835.      <lSetting> is a logical TRUE or FALSE (.T./.F.) indicating whether
  836.      to enable or disable the "fixed" palette mode.  When <lSetting> is
  837.      TRUE, "fixed" mode is enabled.  When <lSetting> is FALSE, "fixed"
  838.      mode is disabled and palette rotations occur.
  839.  
  840. Returns:
  841.      Returns a logical TRUE/FALSE value (.T./.F.) indicating the current
  842.      palette mode setting, where TRUE indicates it is in "fixed" mode
  843.      and FALSE indicates "rotation" mode.
  844.  
  845. Description:
  846.      fx_SetFix() toggles the palette mode between "fixed" and
  847.      "rotation".  While in "fixed" mode, no palette changes are made by
  848.      the timer intercept routine.  This, in effect, suspends the
  849.      following commands:
  850.  
  851.           fx_PalRate()
  852.           fx_IntRate()
  853.           fx_Blink()
  854.           fx_Fade()
  855.           fx_Pulse()
  856.  
  857.      The commands are still "active", i.e. they will continue to behave
  858.      as normal except they will not be displayed.  Normally, "fixed"
  859.      mode is used only when a certain palette must be continuously
  860.      displayed, like when a color scheme has been defined for a
  861.      particular palette and needs to remain constant.
  862.  
  863. Examples:
  864.      // Suspend all color effects and display only
  865.      // the attributes in palette 5.
  866.      fx_SetFix( .T. )
  867.      fx_SetPal( 5 )
  868.  
  869.      // Restore all attributes to default RGB values
  870.      // and cancel "fixed" palette mode.
  871.      fx_RestAll()
  872.      fx_SetFix( .F. )
  873.  
  874. See Also:
  875.      fx_SetPal()
  876.  
  877. fx_SetPal()
  878. -----------
  879. Gets/sets the palette to display when "fixed" mode is enabled.
  880.  
  881. Syntax:
  882.      fx_SetPal( [<nPalette>] )   ->   nPalette
  883.  
  884. Arguments:
  885.      <nPalette> is an integer value in the range 0 to 15 representing
  886.      the palette number to get/set.
  887.  
  888. Returns:
  889.      Returns the integer number of the current palette displayed.
  890.  
  891. Description:
  892.      fx_SetPal() allows switching between palettes when "fixed" palette
  893.      mode is enabled.  If an undefined palette is specified or an error
  894.      occurs, no switching will occur.
  895.  
  896. Example:
  897.      // Save the current displayed palette and switch
  898.      // to palette 5.  When a key is pressed, return
  899.      // to the original palette.
  900.      nSavePal := fx_SetPal( 5 )
  901.      INKEY( 0 )
  902.      fx_SetPal( nSavePal )
  903.  
  904. See Also:
  905.      fx_FixPal()
  906.  
  907.