1  /**************************************************************************
  2  *  Copyright (C) 1993 - see 'license.doc' for complete information.       *
  3  **************************************************************************/
  4  
  5  			USING COLOR IN CIRCLEMUD
  6   			       "color.doc"
  7  
  8  CircleMUD allows you to create colorful messages by using ANSI control
  9  sequences.  Each player may select what "level" of color he/she desires
 10  from the four levels "off", "sparse", "normal", and "complete."  Each
 11  player can select his/her color level by using the COLOR command from
 12  within the MUD; you as the programmer must decide which messages will be
 13  colored for each of the color levels.
 14  
 15  All files in which you wish to use color must have the line:
 16  
 17  #include "screen.h"
 18  
 19  after all other includes in the beginning of the file.
 20  
 21  There are 8 colors available -- "normal", red, green, yellow, blue, magenta,
 22  cyan and white.  They are accessible by sending control sequences as part of
 23  another string, for example:
 24  
 25  sprintf(buf, "If you're %shappy%s and you know it clap %d of your hands.\n\r",
 26  	x, y, num_of_hands);
 27  send_to_char(buf, ch);
 28  
 29  In this example, x and y are the "on" and "off" sequences for the color you
 30  want.  There are 2 main series of color macros available for you to use
 31  (don't actually use "x" and "y", of course!): the K series and the CC series.
 32  The CC (Conditional Color) series is recommended for most general use.
 33  
 34  The name of the actual sequence starts with the name of its series, plus
 35  a 3-letter color code, as follows:
 36  
 37  Normal : NRM
 38  Red    : RED
 39  Yellow : YEL
 40  Green  : GRN
 41  Blue   : BLU
 42  Magenta: MAG
 43  Cyan   : CYN
 44  White  : WHT
 45  
 46  For example, white in the K series is KWHT; blue in the CC series
 47  is CCBLU() (arguments defined below).
 48  
 49  The K series requires no arguments, and is simply a macro to the ANSI
 50  color code.  Therefore, if you use a K-series color code, the color will
 51  ALWAYS be sent, even if the person you're sending it to has color off.
 52  This is very bad -- people who do not have ANSI-compatible terminals
 53  will see garbage characters instead of colors.  The K series is mainly
 54  used to print colors to a string if the player's color level will later
 55  be tested manually (for an example, see do_gen_com in act.comm.c).
 56  
 57  The recommended series is the CC series (i.e. CCNRM(), CCRED(), etc.)
 58  The CC series macros require two arguments -- a pointer to the character
 59  to whom the string is being sent, and the minimum color level the player
 60  must be set to in order to see the color.  Color sent as 'sparse' (C_SPR)
 61  will be seen by people with color set to sparse, normal, or complete;
 62  color sent as 'normal' (C_NRM) will be seen only by people with color
 63  set to normal or complete; color sent as 'complete' (C_CMP) will be seen
 64  only by people with color set to complete.
 65  
 66  To illustrate the above, an example is in order:
 67  
 68  #include "screen.h" /* include screen.h in all files that you use color in */
 69  
 70  ACMD(do_showcolor)
 71  {
 72      char buf[300];
 73  
 74      sprintf(buf, "Don't you just love %scolor%s, %scolor%s, %sCOLOR%s!\n\r",
 75  	CCBLU(ch, C_CMP), CCNRM(ch, C_CMP),
 76  	CCYEL(ch, C_NRM), CCNRM(ch, C_NRM),
 77  	CCRED(ch, C_SPR), CCNRM(ch, C_SPR));
 78      send_to_char(buf, ch);
 79  }
 80  
 81  What does this do?  For people with color set to Complete, it prints:
 82  
 83  	Don't you just love color, color, COLOR!
 84  			   (blue) (yellow) (red)
 85  
 86  People who have color set to Normal will see:
 87  
 88  	Don't you just love color, color, COLOR!
 89  		                  (yellow) (red)
 90  
 91  People who have color set to Sparse will see:
 92  
 93  	Don't you just love color, color, COLOR!
 94  		                           (red)
 95  
 96  People who have color set to Off will see:
 97  
 98  	Don't you just love color, color, COLOR!
 99  			(no color, as you'd expect)
100  
101  
102  There are several common pitfalls with using the CC series of color macros:
103  
104  *  Do not confuse CCNRM with C_NRM.  CCNRM() is a macro to turn the color
105     back to normal; C_NRM is a color level of "normal".
106  
107  *  Always make sure that every pair of "on" and "off" codes are at the
108     same color level.  For example:
109  
110     WRONG:  sprintf(buf, "%sCOLOR%s\n\r", CCBLU(ch, C_NRM), CCNRM(ch, C_CMP));
111  
112     This is wrong because if someone has their color level set to Normal,
113     the CCBLU code will be sent but the CCNRM command will not, causing all
114     subsequent output to be blue.
115  
116     WRONG:  sprintf(buf, "%sCOLOR%s\n\r", CCBLU(ch, C_CMP), CCNRM(ch, C_NRM));
117  
118     The above statement is also wrong, although not as bad.  In this case,
119     someone with color set to Normal will (correctly) not get the CCBLU code,
120     but will then unnecessarily get the CCNRM code.  Never send a color code if
121     you don't have to -- the codes are several bytes long, and cause a noticable
122     pause at 2400 baud.
123  
124  *  This should go without saying, but don't ever send color at the C_OFF
125     level.
126  
127  *  Special precautions must be taken when sending a colored string to a
128     large group of people -- you can't use the color level of "ch" (the
129     person sending the string) -- each person receiving the string must
130     get a string appropriately colored for his/her level.  In such cases,
131     it's usually best to set up two strings (one colored and one not),
132     and test each player's color level individually (see do_gen_com in
133     act.comm.c for an example).
134