home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / MagicWB / scx-cwb.lha / utilities / ProcurePens.doc < prev    next >
Encoding:
Text File  |  1994-03-16  |  6.5 KB  |  175 lines
  1.  
  2. PROCUREPENS and SETPENS
  3. ~~~~~~~~~~~~~~~~~~~~~~~
  4. Color setting software for AGA and Workbench release 3.0 (V39) or higher.
  5.  
  6.  
  7. Copyright ©1993 by Joseph Luk.  All rights reserved.
  8.  
  9. ----------------------------------------------------------- MAIN DOCUMENTATION
  10.  
  11.  
  12. Note: please see Readme file for release history and important announcements.
  13.  
  14.  
  15. Introduction
  16. ~~~~~~~~~~~~
  17. With the release of the AGA systems, Commodore included a wonderful new
  18. version of the operating system which took advantage of the new chips'
  19. extended color selection.  Workbench 3.0 is able to open the screen in
  20. any number of colors from 2 to 256, but it only allows eight of them
  21. to be defined for its use (for icons, etc).  Workbench 2.0 to 2.1 allowed
  22. you to define sixteen.  Go figure.
  23.  
  24. Anyway, the only thing really preventing you from using more than eight
  25. colors is the fact that the Palette Preferences only defines that number.
  26. The rest are left over for other programs to use in Workbench 3.0's palette
  27. sharing scheme.  This is where ProcurePens and the related SetPens comes in.
  28.  
  29.  
  30. What ProcurePens does
  31. ~~~~~~~~~~~~~~~~~~~~~
  32. ProcurePens uses the V39 graphics.library function ObtainPen() to lock, or
  33. procure, a pen.  The idea here is that you call this program from your
  34. user-startup, so that it gets run every time you boot.  This way, you can
  35. have a standard setup for colors beyond the eight that Palette Preferences
  36. allows.  You can lock all available pens for exclusive use, if you wanted to.
  37.  
  38. With the pens locked and set on startup, you can use those extra colors
  39. in Workbench icons (though you may have to use IconEdit 2.x to get them
  40. to work in 16 colors), Dock icons, console escape colors (multicolor CLI
  41. prompts), and other cool stuff.
  42.  
  43. What SetPens does
  44. ~~~~~~~~~~~~~~~~~
  45. SetPens is a somewhat stripped-down version of ProcurePens which does not
  46. lock pens.  Instead, it uses SetRGB32() which simply sets the pen colors.
  47. It reads the same config file as ProcurePens, but, as stated above, merely
  48. sets the colors and does not lock them in any way.  It also doesn't observe
  49. locking rules when it sets the pens; it can redefine colors that are in
  50. use by some other program, so use cautiously.
  51.  
  52. Quick Start
  53. ~~~~~~~~~~~
  54. Okay, enough talk for now.  Open your Workbench in 16 or more colors, pop
  55. a CLI, go to the directory which you extracted this archive in, and type:
  56.  
  57. ProcurePens SampleConfig
  58.  
  59. If pens 4, 5, 6, or 7 are available (not locked by another program),
  60. ProcurePens should tell you that it has set all the pens to the colors
  61. specified in the config file.  Hit [CTRL-C] to remove the program and
  62. its locks.
  63.  
  64.  
  65. Usage
  66. ~~~~~
  67. Typing ProcurePens ? will give you its template:
  68.  
  69.    CONFIGFILE/A,HEX/S,EXCLUSIVE/S,PUBSCREEN/K,VERBOSE/S,NOTIFYNAMES/M:
  70.    
  71.    (Note: for version 1.14, a QUIET option also appears.  This is meant for
  72.     the next version and does nothing here.  Sorry! )
  73.    
  74. Items are as follows:
  75.    
  76.    CONFIGFILE - filename of the required configuration file.  The format is
  77.       as follows:
  78.          Header Line: "ProcurePens Config File"
  79.          
  80.          Line 1: pen number to lock
  81.          Line 2: 8-bit red value (defaults to decimal)
  82.          Line 3: 8-bit green value
  83.          Line 4: 8-bit blue value
  84.          Line 5: delimeter (---)
  85.          
  86.          Lines 1-5 define a specifier that ProcurePens will use to lock and
  87.          set the pen.  These repeat until you place "END" as the final
  88.          delimeter.  (see the SampleConfig for an example)
  89.          
  90.    HEX/S - Specify this keyword to indicate that the 8-bit color values
  91.       in the config file are hexadecimal numbers.
  92.       
  93.    EXCLUSIVE/S - Specify this to lock the pens in "exclusive" mode.  Not really
  94.       useful, since all this means is that another program requesting the
  95.       same or a close color won't be able to use the pen.
  96.       
  97.    PUBSCREEN/K - Name of the public screen to perform the operation on.
  98.       Defaults to "Workbench".
  99.       
  100.       Example: PUBSCREEN=SomebodysScreen1
  101.       
  102.    VERBOSE/S - Old versions of ProcurePens displayed the colors that
  103.       was allocating, and the status of each allocation (whether it worked
  104.       or failed).  Specify this option to show that information.
  105.    
  106.    NOTIFYNAMES/M - Specify additional DOS names of files which when modified,
  107.       may cause the Workbench screen (and its palette) to be reset.  Normally
  108.       you won't have to use this option, because ProcurePens already watches
  109.       the default IPrefs files which cause the screen to be reset:
  110.       
  111.       ENV:Sys/ScreenMode.prefs
  112.       ENV:Sys/Font.prefs
  113.       ENV:Sys/Palette.prefs
  114.       
  115.       When one of these files is modified by another program (the ScreenMode
  116.       Preferences editor, for example), ProcurePens temporarily releases
  117.       all locks it has put on the screen (including pens), then waits for
  118.       a chance to reinstate them after the screen has been reopened.  This
  119.       prevents your pen settings from being wiped away if the screen is
  120.       reopened.   (thanks Martin "XEN" for reporting this bug!)
  121.       
  122.       If you find any other system files which can cause a Workbench
  123.       reset, please let me know!
  124.  
  125.  
  126. More often than not, you will want to call ProcurePens from your user-startup
  127. or at the end of your startup-sequence.  In this case, simply launch the 
  128. program as a seperate task:
  129.    
  130.    run >NIL: ProcurePens <config-file> <options>
  131.    
  132. Note that all console output from the program is supressed in this form,
  133. so errors won't be reported.  Best advice is to try it out before dropping
  134. it in your user-startup.
  135.  
  136. To remove it (normally you'd leave ProcurePens alone since removing it can
  137. subject your onscreen colors to change), simply find its process number
  138. (use Status), and Break it.
  139.  
  140. Example: Break 3
  141. (if ProcurePens is process 3)
  142.  
  143. --
  144.  
  145. SetPens works similarly, except it doesn't stay resident because it doesn't
  146. retain locks on the colors.  As such, you won't need the NOTIFYNAMES feature.
  147. Furthermore, it doesn't lock pens, so there's no EXCLUSIVE switch either.
  148. It was also written later, so DEBUG and VERBOSE have been pruned too.  :>
  149.  
  150. Note that SetPens uses the same config file as ProcurePens, and this
  151. file must begin with "ProcurePens Config File".
  152.  
  153.  
  154.  
  155. Et Al
  156. ~~~~~
  157.  
  158. I hope you find these programs useful.  They're all set to localize, so if
  159. anyone wants to see them use locale.library, I'd be happy to do it.  Bug
  160. reports, suggestions, fan mail, secrets of the Universe, etc should be
  161. sent to:
  162.  
  163. Joseph Luk
  164.  
  165. Internet: jluk@ctp.org
  166. GEnie: J.LUK
  167.  
  168. S-mail: P.O. Box 884401, San Francisco, CA 94188-4401 U.S.A.
  169.  
  170.  
  171. BTW, in case you're wondering, this is my gift to you.  If you use these
  172. programs regularly, I'd *LOVE* to get a postcard from you though!  :>
  173.  
  174. --
  175.