Adjust the way dark mode works and its interaction with colorschemes

In particular, we no longer keep a preference that is "the current
color scheme".  Instead, we keep two preferences with a slightly
different meaning: "the name of the preferred dark-mode color scheme"
and "the name of the preferred light-mode color scheme". This subtle
shift in the meaning of color schemes cleans up a number of things in
the code. The "current color scheme" is now an emergent property of
what the colors happen to be.

We also add a new preference that tells us if we're paying attention
to the underlying OS's dark mode setting or not (and, if we're not, do
we want to be in dark mode or light mode).

Also, the color preferences dialog now has checkboxes saying which
color scheme to use in dark mode and which one to use in light mode
instead of buttons that set the color scheme. Choosing the chcekboxes
might still trigger a change in the colorscheme (if we're in the
corresponding mode)

As part of this, code should be using
color-prefs:white-on-black-color-scheme? to determine if it should
draw in dark or light mode now instead of other ways. Also, this
points to a future improvement: there is code that shouldn't depend on
the framework that might want to pay attention to dark or light mode,
so the color schemes should probably move into mrlib/ somewhere,
someday.

related to racket/drracket#469

Author: rfindler

gui-doc/scribblings/framework/editor-snip.scrbl

@@ -33,7 +33,7 @@
   }
   @defmethod[(get-color) (or/c string? (is-a?/c color%))]{
      Returns @racketblock[
-       (if (preferences:get 'framework:white-on-black?)
+       (if (color-prefs:white-on-black-color-scheme?)
            "white" 
            "black")]
   }

gui-lib/framework/main.rkt

@@ -31,7 +31,7 @@
 
 (require (for-doc racket/base scribble/manual framework/private/mapdesc
                   setup/getinfo racket/pretty string-constants
-                  (for-label string-constants racket/pretty)))
+                  (for-label racket/file string-constants racket/pretty)))
 
 (provide-signature-elements
  (prefix application: framework:application-class^)
@@ -2069,7 +2069,7 @@ are currently open in tabs.
       void?)
   (pref-sym black-on-white-color white-on-black-color)
   @{Registers a preference whose value will be updated when the user clicks on
-    one of the color scheme default settings in the preferences dialog, but
+    one of the @tech{color scheme} default settings in the preferences dialog, but
     does not give it a name that can be configured by a color scheme; consider using
     @racket[color-prefs:add-color-scheme-entry] instead.
 
@@ -2087,7 +2087,7 @@ are currently open in tabs.
    ((white-on-black-color #f)
     (background #f)))
   @{This function registers a color preference but does not give it
-    a name that can be configured by a color scheme; consider using
+    a name that can be configured by a @tech{color scheme}; consider using
     @racket[color-prefs:add-color-scheme-entry] instead.
 
     This function calls @racket[preferences:set-default] and
@@ -2180,6 +2180,26 @@ the color selection buttons all have the same size.
   @{Builds a style delta from its printed representation.  Returns @racket[#f]
     if the printed form cannot be parsed.})
 
+ (proc-doc/names
+  color-prefs:white-on-black-color-scheme?
+  (-> boolean?)
+  ()
+  @{
+
+Returns @racket[#true] if the current @tech{color scheme} is in dark mode
+(i.e. has a light foreground with a dark background) and
+@racket[#false] if it is in light mode (i.e. a dark foreground with
+a light background).
+
+This function uses the @racket['framework:white-on-black-mode?] preference;
+returning its value if it is a boolean and using @racket[white-on-black-panel-scheme?] if
+it is set to @racket['platform]. This function is intended
+to be used in place of @racket[white-on-black-panel-scheme?]
+for code that supports @tech{color scheme}s.
+
+@history[#:added "1.79"]
+})
+
  (proc-doc/names
   color-prefs:white-on-black
   (-> any)
@@ -2211,7 +2231,7 @@ the color selection buttons all have the same size.
                         #f)])
        [result void?])
   (#f #f #f #f #f)
-  @{Registers a new color or style named @racket[name] for use in the color schemes. 
+  @{Registers a new color or style named @racket[name] for use in the @tech{color schemes}.
     If @racket[style] is not @racket[#f], a new style is registered; if not a color is
     registered.
 
@@ -2229,7 +2249,7 @@ the color selection buttons all have the same size.
   (() ((extras void)))
   @{Adds a panel for choosing a color-scheme to the preferences dialog.
 
-    The @racket[extras] argument is called after the color schemes have been added
+    The @racket[extras] argument is called after the @tech{color schemes} have been added
     to the preferences panel. It is passed the panel containing the color schemes
     and can add items to it.})
 
@@ -2241,7 +2261,7 @@ the color selection buttons all have the same size.
     @index{framework:color-schemes}
     @racket['framework:color-schemes]. Each definition must bind
     a list of hash tables, each of which introduces a new
-    color scheme. Each hash table should have keys that specify
+    @deftech{color scheme}. Each hash table should have keys that specify
     details of the color scheme, as follows:
     @itemlist[@item{@racket['name]: must be either a string or a symbol;
                      it names the entire color scheme.
@@ -2322,22 +2342,26 @@ the color selection buttons all have the same size.
   color-prefs:set-current-color-scheme
   (-> symbol? void?)
   (name)
-  @{Sets
-    the current color scheme to the scheme named @racket[name], 
-    if @racket[name] is one of the color schemes.
-    Otherwise, sets the color scheme to the default color scheme.})
+  @{
+Set's the user's preferred @tech{color scheme} to
+the one whose name is @racket[name].
+Also, updates the colors in DrRacket's GUI to the colors in
+that color scheme if the named color scheme matches the
+dark/light mode that the GUI is in.
+})
 
- (proc-doc
+ (proc-doc/names
   color-prefs:get-current-color-scheme-name
-  (-> symbol?)
-  @{Returns the current color scheme's name.})
+  (->* () (#:wob? boolean?) symbol?)
+  (() ((wob? (white-on-black-color-scheme?))))
+  @{Returns the name of either the user's preferred dark mode or light mode @tech{color scheme}.})
 
  (proc-doc/names
   color-prefs:known-color-scheme-name?
   (-> any/c boolean?)
   (name)
   @{Returns @racket[#t] if the input is a @racket[symbol?] that names
- a color or style that is an entry in the current color scheme.
+ a color or style that is an entry in the current @tech{color scheme}.
 
  In order to return @racket[#t], @racket[name] must have been
  passed as the first argument to @racket[color-prefs:add-color-scheme-entry].})
@@ -2347,7 +2371,7 @@ the color selection buttons all have the same size.
   (-> symbol? (or/c #f symbol?))
   (name)
   @{
-Returns the inverted-base color scheme name
+Returns the inverted-base @tech{color scheme} name
 of color scheme named @racket[name], if it has one.
 
 @history[#:added "1.68"]
@@ -2357,7 +2381,7 @@ of color scheme named @racket[name], if it has one.
   color-prefs:color-scheme-style-name?
   (-> any/c boolean?)
   (name)
-  @{Returns @racket[#t] if @racket[name] is a known color scheme name,
+  @{Returns @racket[#t] if @racket[name] is a known @tech{color scheme} name,
             and is connected to a style. 
 
             In order to return @racket[#t], @racket[name] must have been
@@ -2368,21 +2392,22 @@ of color scheme named @racket[name], if it has one.
   color-prefs:color-scheme-color-name?
   (-> any/c boolean?)
   (name)
-  @{Returns @racket[#t] if @racket[name] is a known color scheme name,
+  @{Returns @racket[#t] if @racket[name] is a known @tech{color scheme} name,
             and is connected to a color. 
 
             In order to return @racket[#t], @racket[name] must have been
             passed as the first argument to @racket[color-prefs:add-color-scheme-entry]
             and the @racket[#:style] argument must have also been omitted or be @racket[#f].})
 
- (proc-doc 
+ (proc-doc
   color-prefs:lookup-in-color-scheme
   (->i ([name color-prefs:known-color-scheme-name?])
-       ()
+       (#:wob? [wob boolean?])
        [result (name)
                (if (color-prefs:color-scheme-style-name? name)
                    (is-a?/c style-delta%)
                    (is-a?/c color%))])
+  ((white-on-black-color-scheme?))
   @{Returns the current style delta or color associated with @racket[name].})
 
  (proc-doc
@@ -2395,7 +2420,7 @@ of color scheme named @racket[name], if it has one.
        ()
        [result void?])
   @{Updates the current color or style delta associated with 
-    @racket[name] in the current color scheme.})
+    @racket[name] in the current @tech{color scheme}.})
 
  (proc-doc
   color-prefs:register-color-scheme-entry-change-callback
@@ -2431,8 +2456,8 @@ of color scheme named @racket[name], if it has one.
  (proc-doc
   color-prefs:get-color-scheme-names
   (-> (values set? set?))
-  @{Returns two sets; the first is the known color scheme names that are just colors
-    and the second is the known color scheme names that are styles.
+  @{Returns two sets; the first is the known @tech{color scheme} names that are just colors
+    and the second is the known @tech{color scheme} names that are styles.
 
     These are all of the names that have been passed to @racket[color-prefs:add-color-scheme-entry].})
  )