home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / source / colorw.lha / Color.doc < prev    next >
Text File  |  1987-10-12  |  4KB  |  104 lines
  1.  
  2. ColorWindow Programmer Manual
  3. From the Amiga Programmer's Suite Book 1, by RJ Mical
  4. Copyright (C) 1987, Robert J. Mical
  5.  
  6.  
  7.  
  8.  
  9.  
  10. *** DoColorWindow() ******************************************************
  11.  
  12. NAME
  13.     DoColorWindow  --  Allows the user to change a screen's colors
  14.  
  15.  
  16. SYNOPSIS
  17.     BOOL DoColorWindow(Screen, Left, Top, FirstPen, UseRGB);
  18.  
  19.  
  20. FUNCTION
  21.     This routine creates a window, called the ColorWindow, which has 
  22.     gadgets that allow the user to change the colors of any screen.  
  23.     After opening the ColorWindow, this routine interacts with the 
  24.     user until the user is satisfied with the current colors, at which 
  25.     time the window is closed and control is returned to you.  
  26.  
  27.     The ColorWindow will open in the specified Screen.  The Screen 
  28.     argument can be equal to NULL; if it is, the ColorWindow will be 
  29.     opened in the Workbench screen.  The ColorWindow automatically 
  30.     adapts itself to any screen.  
  31.  
  32.     With the Top and Left arguments you specify the position of the 
  33.     ColorWindow's top-left corner.  Note that no position-error 
  34.     checking is done, so you must take care to not place the window 
  35.     outside of the bounds of your screen.  Currently, the Left argument 
  36.     can range from 0 to 88 on low-resolution screens, and 0 to 408 
  37.     on high-resolution screens.  The Top argument can range from 
  38.     0 to 109 on a 200-line screen, and 0 to 309 on an interlaced screen.  
  39.     These figures don't include overscan, which most programmers 
  40.     don't use.  The width and height of the ColorWindow are defined 
  41.     by the constants COLORWINDOW_WIDTH and COLORWINDOW_HEIGHT in the 
  42.     color.h file.  
  43.  
  44.     The FirstPen argument is used to initialize the color that's 
  45.     displayed when the ColorWindow is first created.  
  46.  
  47.     The ColorWindow is capable of allowing the user to modify the 
  48.     colors using either an RGB or an HSL technique.  The RGB technique 
  49.     involves three proportional gadgets, one for each of Red, Green 
  50.     and Blue.  By adjusting one of these gadgets, the user adjusts 
  51.     the amount of the associated color component in the final color.  
  52.     Some people feel that this is the most intuitive way to change 
  53.     colors on the Amiga, as this is how colors are represented 
  54.     internally by the Amiga.  The other technique, HSL, allows the 
  55.     user to adjust the Hue, Saturation and Luminance of the final color.  
  56.     Some people feel that *this* is the most intuitive way for users 
  57.     to change color, because it's based on color theory and because 
  58.     these are the types of controls that people used on their 
  59.     color televisions in the old days.  
  60.  
  61.     You decide which mode is first used when the ColorWindow is created 
  62.     by setting the UseRGB argument to TRUE or FALSE.  If TRUE, 
  63.     the RGB technique will be used.  If FALSE, HSL is used.  
  64.  
  65.     But regardless of which technique you specify, the user can switch 
  66.     to using the other technique by clicking on the RGB / HSL characters 
  67.     that appear to the left of the proportional gadgets.  
  68.  
  69.     On return from this function, this routine returns TRUE if all 
  70.     went well.  If anything went wrong (usually out of memory) and 
  71.     the ColorWindow was never created, this routine returns FALSE.  
  72.  
  73.     NOTE:  This routine is not re-entrant.  What this means 
  74.     is that if you have created a program that has more than one task,
  75.     this routine cannot be called by more than one task at a time.
  76.     This was done for the sake of memory efficiency.
  77.     This restriction is not a problem for the grand majority of programs.
  78.     But if you have some application that would require calling this 
  79.     routine asynchronously from multiple tasks, you'll have to 
  80.     implement some quick semaphore arrangement to avoid collisions.
  81.     No big deal, actually.  See Exec semaphores for everything you need.
  82.  
  83.  
  84. INPUTS
  85.     Screen = address of the screen in which the ColorWindow will open.
  86.         Can be NULL; if so, the ColorWindow will open in the Workbench
  87.  
  88.     Left = position of the left edge when the ColorWindow opens
  89.  
  90.     Top = position of the top edge when the ColorWindow opens
  91.  
  92.     FirstPen = pen number of the color displayed when the ColorWindow
  93.         first opens
  94.  
  95.     UseRGB = TRUE if you want the RGB technique displayed first, 
  96.         FALSE if you want the HSL technqiue.  See the discussion above
  97.  
  98.  
  99. RESULT
  100.     Returns TRUE if all went well.  If the window couldn't be opened for
  101.     any reason, returns FALSE.
  102.  
  103.  
  104.