programmable terminal color redefinition and theming SciTECO curses UI based on Scintilla styles

 * The first 16 colors of the terminal palette can be redefined
   using the 3EJ property - with all restrictions that ncurses
   and UNIX terminals impose on us.
   It is still important to be able to redefine the palette for
   some color schemes like Solarized since it may be difficult
   for users to set up the terminal emulator's palette manually.
   Also when using PDCurses, setting the palette is port-specific
   or only possible using init_color(). In order to allow color
   redefinitions across all curses ports it makes sense if SciTECO
   gives access to the color initialization of curses even if it can
   guarantee very little about its semantics in general.
 * 3EJ is completely ignored for GTK+
 * use the STYLE_DEFAULT of the current document to style the message line.
   Fg and bg colors are reversed to guarantee a good contrast to the
   Scintilla view.
   Errors are still hardcoded to a red background, warnings to yellow
   and info messages to green.
   This allows color-scheming more of SciTECO given that the
   red, yellow and green terminal colors are not changed fundamentally
   in the terminal's palette.
 * info line is now also styled using STYLE_DEFAULT (reverse colors).
   The Q-Register and buffer names are now written out using format_str()
   which means that control characters are written out in REVERSE just
   like in the command line.
   String::canonicalize_ctl() is still used to canonicalize window
   titles.
 * Command line is now modelled as a curses Pad and "blitted" to the
   command line window. This allowed simplification of the command line
   drawing code and introduction of format_str().
   The command line is now styled according to STYLE_DEFAULT (original
   fg and bg colors).
   The rubbed-out part of the command line can now longer be shown in
   bold black - or even bold light black - since that is not visible in
   all color themes. Instead it is now only shown in bold.
   Command line theming problems will be gone once we use a Scintilla
   view for the command line.
 * The popup widget is now styled according to STYLE_CALLTIP.
 * This means that all relevant parts of SciTECO's user interface
   can now be themed. This allows the creation of themes that redefine
   the terminal palette radically (e.g. Solarized) and the creation of
   "bright" themes (e.g. Solarized/bright).
 * theming of the non-scintilla-view parts of SciTECO is currently
   unsupported on GTK+. The reason is that both the popup widget
   and command line widgets have to be rewritten completely in GTK+
   and are work in progress, so adapting the current code would be
   a waste of time.
 * Added a manual section about the UI and theming.

1 files changed, 60 insertions, 3 deletions

diff --git a/src/parser.cpp b/src/parser.cpp
index 9ef3d64..1da6905 100644
--- a/src/parser.cpp
+++ b/src/parser.cpp
@@ -1989,6 +1989,7 @@ StateECommand::custom(gchar chr)
 	 * [key]EJ -> value -- Get and set system properties
 	 * -EJ -> value
 	 * value,keyEJ
+	 * rgb,color,3EJ
 	 *
 	 * This command may be used to get and set system
 	 * properties.
@@ -1997,8 +1998,9 @@ StateECommand::custom(gchar chr)
 	 * If \fIkey\fP is omitted, the prefix sign is implied
 	 * (1 or -1).
 	 * With two arguments, it sets property \fIkey\fP to
-	 * \fIvalue\fP and returns nothing. Properties may be
-	 * read-only.
+	 * \fIvalue\fP and returns nothing. Some property \fIkeys\fP
+	 * may require more than one value. Properties may be
+	 * write-only or read-only.
 	 *
 	 * The following property keys are defined:
 	 * .IP 0 4
@@ -2028,6 +2030,50 @@ StateECommand::custom(gchar chr)
 	 * is too large for the new limit \(em if this happens
 	 * you may have to clear your command-line first.
 	 * Undo stack memory limiting is enabled by default.
+	 * .IP 3
+	 * This \fBwrite-only\fP property allows redefining the
+	 * first 16 entries of the terminal color palette \(em a
+	 * feature required by some
+	 * color schemes when using the Curses user interface.
+	 * When setting this property, you are making a request
+	 * to define the terminal \fIcolor\fP as the Scintilla-compatible
+	 * RGB color value given in the \fIrgb\fP parameter.
+	 * \fIcolor\fP must be a value between 0 and 15
+	 * corresponding to black, red, green, yellow, blue, magenta,
+	 * cyan, white, bright black, bright red, etc. in that order.
+	 * The \fIrgb\fP value has the format 0xBBGGRR, i.e. the red
+	 * component is the least-significant byte and all other bytes
+	 * are ignored.
+	 * Note that on curses, RGB color values sent to Scintilla
+	 * are actually mapped to these 16 colors by the Scinterm port
+	 * and may represent colors with no resemblance to the \(lqRGB\(rq
+	 * value used (depending on the current palette) \(em they should
+	 * instead be viewed as placeholders for 16 standard terminal
+	 * color codes.
+	 * Please refer to the Scinterm manual for details on the allowed
+	 * \(lqRGB\(rq values and how they map to terminal colors.
+	 * This command provides a crude way to request exact RGB colors
+	 * for the first 16 terminal colors.
+	 * The color definition may be queued or be completely ignored
+	 * on other user interfaces and no feedback is given
+	 * if it fails. In fact feedback cannot be given reliably anyway.
+	 * Note that on 8 color terminals, only the first 8 colors
+	 * can be redefined (if you are lucky).
+	 * Note that due to restrictions of most terminal emulators
+	 * and some curses implementations, this command will not
+	 * and cannot restore the original palette entry or request
+	 * when rubbed out and should generally only be used in
+	 * \fIbatch-mode\fP \(em typically when loading a color scheme.
+	 * For the same reasons, palette changes may persist
+	 * after \*(ST terminates on most terminal emulators.
+	 * The only emulator which restores the palette on exit the
+	 * author is aware of is the Linux console driver.
+	 * Few other emulators like \fBxterm\fP(1) might support
+	 * palette resets but this cannot be done automatically
+	 * by \*(ST for technical and historical reasons.
+	 * Users might try to work around this by tweaking their
+	 * \fBterminfo\fP(5) database.
+	 * You have been warned. Good luck.
 	 */
 	case 'J': {
 		BEGIN_EXEC(&States::start);
@@ -2035,7 +2081,8 @@ StateECommand::custom(gchar chr)
 		enum {
 			EJ_USER_INTERFACE = 0,
 			EJ_BUFFERS,
-			EJ_UNDO_MEMORY_LIMIT
+			EJ_UNDO_MEMORY_LIMIT,
+			EJ_INIT_COLOR
 		};
 		tecoInt property;
 
@@ -2050,6 +2097,16 @@ StateECommand::custom(gchar chr)
 				undo.set_memory_limit(MAX(0, value));
 				break;
 
+			case EJ_INIT_COLOR:
+				if (value < 0 || value >= 16)
+					throw Error("Invalid color code %" TECO_INTEGER_FORMAT
+					            " specified for <EJ>", value);
+				if (!expressions.args())
+					throw ArgExpectedError("EJ");
+				interface.init_color((guint)value,
+				                     (guint32)expressions.pop_num_calc());
+				break;
+
 			default:
 				throw Error("Cannot set property %" TECO_INTEGER_FORMAT
 				            " for <EJ>", property);