widget/LookAndFeel.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef __LookAndFeel
   7 #define __LookAndFeel
   8
   9 #ifndef MOZILLA_INTERNAL_API
  10 #  error "This header is only usable from within libxul (MOZILLA_INTERNAL_API)."
  11 #endif
  12
  13 #include "nsDebug.h"
  14 #include "nsColor.h"
  15 #include "nsString.h"
  16 #include "nsTArray.h"
  17 #include "mozilla/Maybe.h"
  18 #include "mozilla/widget/ThemeChangeKind.h"
  19 #include "mozilla/ColorScheme.h"
  20
  21 struct gfxFontStyle;
  22
  23 class nsIFrame;
  24
  25 namespace mozilla {
  26
  27 using Modifiers = uint16_t;
  28 struct StyleColorSchemeFlags;
  29
  30 namespace dom {
  31 class Document;
  32 }
  33
  34 namespace widget {
  35 class FullLookAndFeel;
  36 }  // namespace widget
  37
  38 enum class StyleSystemColor : uint8_t;
  39 enum class StyleSystemColorScheme : uint8_t;
  40 enum class StyleSystemFont : uint8_t;
  41
  42 class LookAndFeel {
  43  public:
  44   using ColorID = StyleSystemColor;
  45   using ColorScheme = mozilla::ColorScheme;
  46
  47   // When modifying this list, also modify nsXPLookAndFeel::sIntPrefs
  48   // in widget/xpwidgts/nsXPLookAndFeel.cpp.
  49   enum class IntID {
  50     // default, may be overriden by OS
  51     CaretBlinkTime,
  52     // Amount of blinks that happen before the caret stops blinking.
  53     CaretBlinkCount,
  54     // pixel width of caret
  55     CaretWidth,
  56     // show the caret when text is selected?
  57     ShowCaretDuringSelection,
  58     // select textfields when focused via tab/accesskey?
  59     SelectTextfieldsOnKeyFocus,
  60     // delay before submenus open
  61     SubmenuDelay,
  62     // can popups overlap menu/task bar?
  63     MenusCanOverlapOSBar,
  64     // should overlay scrollbars be used?
  65     UseOverlayScrollbars,
  66     // allow H and V overlay scrollbars to overlap?
  67     AllowOverlayScrollbarsOverlap,
  68     // skip navigating to disabled menu item?
  69     SkipNavigatingDisabledMenuItem,
  70     // begin a drag if the mouse is moved further than the threshold while the
  71     // button is down
  72     DragThresholdX,
  73     DragThresholdY,
  74     // Accessibility theme being used?
  75     UseAccessibilityTheme,
  76
  77     // position of scroll arrows in a scrollbar
  78     ScrollArrowStyle,
  79
  80     // each button can take one of four values:
  81     ScrollButtonLeftMouseButtonAction,
  82     // 0 - scrolls one  line, 1 - scrolls one page
  83     ScrollButtonMiddleMouseButtonAction,
  84     // 2 - scrolls to end, 3 - button ignored
  85     ScrollButtonRightMouseButtonAction,
  86
  87     // delay for opening spring loaded folders
  88     TreeOpenDelay,
  89     // delay for closing spring loaded folders
  90     TreeCloseDelay,
  91     // delay for triggering the tree scrolling
  92     TreeLazyScrollDelay,
  93     // delay for scrolling the tree
  94     TreeScrollDelay,
  95     // the maximum number of lines to be scrolled at ones
  96     TreeScrollLinesMax,
  97     // What type of tab-order to use
  98     TabFocusModel,
  99     // Should menu items blink when they're chosen?
 100     ChosenMenuItemsShouldBlink,
 101
 102     /*
 103      * A Boolean value to determine whether the Windows accent color
 104      * should be applied to the title bar.
 105      *
 106      * The value of this metric is not used on other platforms. These platforms
 107      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 108      */
 109     WindowsAccentColorInTitlebar,
 110
 111     /*
 112      * A Boolean value to determine whether the Windows default theme is
 113      * being used.
 114      *
 115      * The value of this metric is not used on other platforms. These platforms
 116      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 117      */
 118     WindowsDefaultTheme,
 119
 120     /*
 121      * A Boolean value to determine whether the DWM compositor is being used
 122      *
 123      * This metric is not used on non-Windows platforms. These platforms
 124      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 125      */
 126     DWMCompositor,
 127
 128     /*
 129      * A Boolean value to determine whether Windows is themed (Classic vs.
 130      * uxtheme)
 131      *
 132      * This is Windows-specific and is not implemented on other platforms
 133      * (will return the default of NS_ERROR_FAILURE).
 134      */
 135     WindowsClassic,
 136
 137     /*
 138      * A Boolean value to determine whether the current Windows desktop theme
 139      * supports Aero Glass.
 140      *
 141      * This is Windows-specific and is not implemented on other platforms
 142      * (will return the default of NS_ERROR_FAILURE).
 143      */
 144     WindowsGlass,
 145
 146     /*
 147      * A Boolean value to determine whether the Mac graphite theme is
 148      * being used.
 149      */
 150     MacGraphiteTheme,
 151
 152     /*
 153      * A Boolean value to determine whether the macOS Big Sur-specific
 154      * theming should be used.
 155      */
 156     MacBigSurTheme,
 157
 158     /*
 159      * A Boolean value to determine whether macOS is in RTL mode or not.
 160      */
 161     MacRTL,
 162
 163     /*
 164      * AlertNotificationOrigin indicates from which corner of the
 165      * screen alerts slide in, and from which direction (horizontal/vertical).
 166      * 0, the default, represents bottom right, sliding vertically.
 167      * Use any bitwise combination of the following constants:
 168      * NS_ALERT_HORIZONTAL (1), NS_ALERT_LEFT (2), NS_ALERT_TOP (4).
 169      *
 170      *       6       4
 171      *     +-----------+
 172      *    7|           |5
 173      *     |           |
 174      *    3|           |1
 175      *     +-----------+
 176      *       2       0
 177      */
 178     AlertNotificationOrigin,
 179
 180     /**
 181      * If true, clicking on a scrollbar (not as in dragging the thumb) defaults
 182      * to scrolling the view corresponding to the clicked point. Otherwise, we
 183      * only do so if the scrollbar is clicked using the middle mouse button or
 184      * if shift is pressed when the scrollbar is clicked.
 185      */
 186     ScrollToClick,
 187
 188     /**
 189      * IME and spell checker underline styles, the values should be
 190      * NS_DECORATION_LINE_STYLE_*.  They are defined below.
 191      */
 192     IMERawInputUnderlineStyle,
 193     IMESelectedRawTextUnderlineStyle,
 194     IMEConvertedTextUnderlineStyle,
 195     IMESelectedConvertedTextUnderline,
 196     SpellCheckerUnderlineStyle,
 197
 198     /**
 199      * If this metric != 0, support window dragging on the menubar.
 200      */
 201     MenuBarDrag,
 202     /**
 203      * 0: scrollbar button repeats to scroll only when cursor is on the button.
 204      * 1: scrollbar button repeats to scroll even if cursor is outside of it.
 205      */
 206     ScrollbarButtonAutoRepeatBehavior,
 207     /**
 208      * Delay before showing a tooltip.
 209      */
 210     TooltipDelay,
 211     /*
 212      * A Boolean value to determine whether swipe animations should be used.
 213      */
 214     SwipeAnimationEnabled,
 215
 216     /*
 217      * Controls whether overlay scrollbars display when the user moves
 218      * the mouse in a scrollable frame.
 219      */
 220     ScrollbarDisplayOnMouseMove,
 221
 222     /*
 223      * Overlay scrollbar animation constants.
 224      */
 225     ScrollbarFadeBeginDelay,
 226     ScrollbarFadeDuration,
 227
 228     /**
 229      * Distance in pixels to offset the context menu from the cursor
 230      * on open.
 231      */
 232     ContextMenuOffsetVertical,
 233     ContextMenuOffsetHorizontal,
 234
 235     /*
 236      * A boolean value indicating whether client-side decorations are
 237      * supported by the user's GTK version.
 238      */
 239     GTKCSDAvailable,
 240
 241     /*
 242      * A boolean value indicating whether client-side decorations should
 243      * contain a minimize button.
 244      */
 245     GTKCSDMinimizeButton,
 246
 247     /*
 248      * A boolean value indicating whether client-side decorations should
 249      * contain a maximize button.
 250      */
 251     GTKCSDMaximizeButton,
 252
 253     /*
 254      * A boolean value indicating whether client-side decorations should
 255      * contain a close button.
 256      */
 257     GTKCSDCloseButton,
 258
 259     /**
 260      * An Integer value that will represent the position of the Minimize button
 261      * in GTK Client side decoration header.
 262      */
 263     GTKCSDMinimizeButtonPosition,
 264
 265     /**
 266      * An Integer value that will represent the position of the Maximize button
 267      * in GTK Client side decoration header.
 268      */
 269     GTKCSDMaximizeButtonPosition,
 270
 271     /**
 272      * An Integer value that will represent the position of the Close button
 273      * in GTK Client side decoration header.
 274      */
 275     GTKCSDCloseButtonPosition,
 276
 277     /*
 278      * A boolean value indicating whether titlebar buttons are located
 279      * in left titlebar corner.
 280      */
 281     GTKCSDReversedPlacement,
 282
 283     /*
 284      * A boolean value indicating whether or not the OS is using a dark theme,
 285      * which we may want to switch to as well if not overridden by the user.
 286      */
 287     SystemUsesDarkTheme,
 288
 289     /**
 290      * Corresponding to prefers-reduced-motion.
 291      * https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-motion
 292      * 0: no-preference
 293      * 1: reduce
 294      */
 295     PrefersReducedMotion,
 296
 297     /**
 298      * Corresponding to prefers-reduced-transparency.
 299      * https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-transparency
 300      * 0: no-preference
 301      * 1: reduce
 302      */
 303     PrefersReducedTransparency,
 304
 305     /**
 306      * Corresponding to inverted-colors.
 307      * https://drafts.csswg.org/mediaqueries-5/#inverted
 308      * 0: none
 309      * 1: inverted
 310      */
 311     InvertedColors,
 312
 313     /**
 314      * Corresponding to PointerCapabilities in ServoTypes.h
 315      * 0: None
 316      * 1: Coarse
 317      * 2: Fine
 318      * 4: Hover
 319      */
 320     PrimaryPointerCapabilities,
 321     /**
 322      * Corresponding to union of PointerCapabilities values in ServoTypes.h
 323      * E.g. if there is a mouse and a digitizer, the value will be
 324      * 'Coarse | Fine | Hover'.
 325      */
 326     AllPointerCapabilities,
 327
 328     /** The scrollbar size, in CSS pixels. */
 329     SystemScrollbarSize,
 330
 331     /** A boolean value to determine whether a touch device is present */
 332     TouchDeviceSupportPresent,
 333
 334     /** GTK titlebar radius */
 335     TitlebarRadius,
 336
 337     /**
 338      * Corresponding to dynamic-range.
 339      * https://drafts.csswg.org/mediaqueries-5/#dynamic-range
 340      * 0: Standard
 341      * 1: High
 342      */
 343     DynamicRange,
 344     VideoDynamicRange,
 345
 346     /** Whether XUL panel animations are enabled. */
 347     PanelAnimations,
 348
 349     /*
 350      * Not an ID; used to define the range of valid IDs.  Must be last.
 351      */
 352     End,
 353   };
 354
 355   // This is a common enough integer that seems worth the shortcut.
 356   static bool UseOverlayScrollbars() {
 357     return GetInt(IntID::UseOverlayScrollbars);
 358   }
 359
 360   // Returns keyCode value of a modifier key which is used for accesskey.
 361   // Returns 0 if the platform doesn't support access key.
 362   static uint32_t GetMenuAccessKey();
 363   // Modifier mask for the menu accesskey.
 364   static Modifiers GetMenuAccessKeyModifiers();
 365
 366   enum {
 367     eScrollArrow_None = 0,
 368     eScrollArrow_StartBackward = 0x1000,
 369     eScrollArrow_StartForward = 0x0100,
 370     eScrollArrow_EndBackward = 0x0010,
 371     eScrollArrow_EndForward = 0x0001
 372   };
 373
 374   enum {
 375     // single arrow at each end
 376     eScrollArrowStyle_Single =
 377         eScrollArrow_StartBackward | eScrollArrow_EndForward,
 378     // both arrows at bottom/right, none at top/left
 379     eScrollArrowStyle_BothAtBottom =
 380         eScrollArrow_EndBackward | eScrollArrow_EndForward,
 381     // both arrows at both ends
 382     eScrollArrowStyle_BothAtEachEnd =
 383         eScrollArrow_EndBackward | eScrollArrow_EndForward |
 384         eScrollArrow_StartBackward | eScrollArrow_StartForward,
 385     // both arrows at top/left, none at bottom/right
 386     eScrollArrowStyle_BothAtTop =
 387         eScrollArrow_StartBackward | eScrollArrow_StartForward
 388   };
 389
 390   // When modifying this list, also modify nsXPLookAndFeel::sFloatPrefs
 391   // in widget/nsXPLookAndFeel.cpp.
 392   enum class FloatID {
 393     IMEUnderlineRelativeSize,
 394     SpellCheckerUnderlineRelativeSize,
 395
 396     // The width/height ratio of the cursor. If used, the CaretWidth int metric
 397     // should be added to the calculated caret width.
 398     CaretAspectRatio,
 399
 400     // GTK text scale factor.
 401     TextScaleFactor,
 402
 403     // Mouse pointer scaling factor.
 404     CursorScale,
 405
 406     // Not an ID; used to define the range of valid IDs.  Must be last.
 407     End,
 408   };
 409
 410   using FontID = mozilla::StyleSystemFont;
 411
 412   static bool WindowsNonNativeMenusEnabled();
 413
 414   static ColorScheme SystemColorScheme() {
 415     return GetInt(IntID::SystemUsesDarkTheme) ? ColorScheme::Dark
 416                                               : ColorScheme::Light;
 417   }
 418
 419   static bool IsDarkColor(nscolor);
 420
 421   enum class ChromeColorSchemeSetting { Light, Dark, System };
 422   static ChromeColorSchemeSetting ColorSchemeSettingForChrome();
 423   static ColorScheme ThemeDerivedColorSchemeForContent();
 424
 425   static ColorScheme ColorSchemeForChrome() {
 426     MOZ_ASSERT(sColorSchemeInitialized);
 427     return sChromeColorScheme;
 428   }
 429   static ColorScheme PreferredColorSchemeForContent() {
 430     MOZ_ASSERT(sColorSchemeInitialized);
 431     return sContentColorScheme;
 432   }
 433
 434   static ColorScheme ColorSchemeForStyle(
 435       const dom::Document&, const StyleColorSchemeFlags&,
 436       ColorSchemeMode = ColorSchemeMode::Used);
 437   static ColorScheme ColorSchemeForFrame(
 438       const nsIFrame*, ColorSchemeMode = ColorSchemeMode::Used);
 439
 440   // Whether standins for native colors should be used (that is, colors faked,
 441   // taken from win7, mostly). This forces light appearance, effectively.
 442   enum class UseStandins : bool { No, Yes };
 443   static UseStandins ShouldUseStandins(const dom::Document&, ColorID);
 444
 445   // Returns a native color value (might be overwritten by prefs) for a given
 446   // color id.
 447   //
 448   // NOTE:
 449   //   ColorID::TextSelectForeground might return NS_SAME_AS_FOREGROUND_COLOR.
 450   //   ColorID::IME* might return NS_TRANSPARENT, NS_SAME_AS_FOREGROUND_COLOR or
 451   //   NS_40PERCENT_FOREGROUND_COLOR.
 452   //   These values have particular meaning.  Then, they are not an actual
 453   //   color value.
 454   static Maybe<nscolor> GetColor(ColorID, ColorScheme, UseStandins);
 455
 456   // Gets the color with appropriate defaults for UseStandins, ColorScheme etc
 457   // for a given frame.
 458   static Maybe<nscolor> GetColor(ColorID, const nsIFrame*);
 459
 460   // Versions of the above which returns the color if found, or a default (which
 461   // defaults to opaque black) otherwise.
 462   static nscolor Color(ColorID aId, ColorScheme aScheme,
 463                        UseStandins aUseStandins,
 464                        nscolor aDefault = NS_RGB(0, 0, 0)) {
 465     return GetColor(aId, aScheme, aUseStandins).valueOr(aDefault);
 466   }
 467
 468   static nscolor Color(ColorID aId, nsIFrame* aFrame,
 469                        nscolor aDefault = NS_RGB(0, 0, 0)) {
 470     return GetColor(aId, aFrame).valueOr(aDefault);
 471   }
 472
 473   static float GetTextScaleFactor() {
 474     float f = GetFloat(FloatID::TextScaleFactor, 1.0f);
 475     if (MOZ_UNLIKELY(f <= 0.0f)) {
 476       return 1.0f;
 477     }
 478     return f;
 479   }
 480
 481   struct ZoomSettings {
 482     float mFullZoom = 1.0f;
 483     float mTextZoom = 1.0f;
 484   };
 485
 486   static ZoomSettings SystemZoomSettings();
 487
 488   /**
 489    * GetInt() and GetFloat() return a int or float value for aID.  The result
 490    * might be distance, time, some flags or a int value which has particular
 491    * meaning.  See each document at definition of each ID for the detail.
 492    * The result is always 0 when they return error.  Therefore, if you want to
 493    * use a value for the default value, you should use the other method which
 494    * returns int or float directly.
 495    */
 496   static nsresult GetInt(IntID, int32_t* aResult);
 497   static nsresult GetFloat(FloatID aID, float* aResult);
 498
 499   static int32_t GetInt(IntID aID, int32_t aDefault = 0) {
 500     int32_t result;
 501     if (NS_FAILED(GetInt(aID, &result))) {
 502       return aDefault;
 503     }
 504     return result;
 505   }
 506
 507   static float GetFloat(FloatID aID, float aDefault = 0.0f) {
 508     float result;
 509     if (NS_FAILED(GetFloat(aID, &result))) {
 510       return aDefault;
 511     }
 512     return result;
 513   }
 514
 515   /**
 516    * Retrieve the name and style of a system-theme font.  Returns true
 517    * if the system theme specifies this font, false if a default should
 518    * be used.  In the latter case neither aName nor aStyle is modified.
 519    *
 520    * Size of the font should be in CSS pixels, not device pixels.
 521    *
 522    * @param aID    Which system-theme font is wanted.
 523    * @param aName  The name of the font to use.
 524    * @param aStyle Styling to apply to the font.
 525    */
 526   static bool GetFont(FontID aID, nsString& aName, gfxFontStyle& aStyle);
 527
 528   /**
 529    * GetPasswordCharacter() returns a unicode character which should be used
 530    * for a masked character in password editor.  E.g., '*'.
 531    */
 532   static char16_t GetPasswordCharacter();
 533
 534   /**
 535    * If the latest character in password field shouldn't be hidden by the
 536    * result of GetPasswordCharacter(), GetEchoPassword() returns TRUE.
 537    * Otherwise, FALSE.
 538    */
 539   static bool GetEchoPassword();
 540
 541   /**
 542    * Whether we should be drawing in the titlebar by default.
 543    */
 544   static bool DrawInTitlebar();
 545
 546   /**
 547    * The millisecond to mask password value.
 548    * This value is only valid when GetEchoPassword() returns true.
 549    */
 550   static uint32_t GetPasswordMaskDelay();
 551
 552   /** Gets theme information for about:support */
 553   static void GetThemeInfo(nsACString&);
 554
 555   /**
 556    * When system look and feel is changed, Refresh() must be called.  Then,
 557    * cached data would be released.
 558    */
 559   static void Refresh();
 560
 561   /**
 562    * GTK's initialization code can't be run off main thread, call this
 563    * if you plan on using LookAndFeel off main thread later.
 564    *
 565    * This initialized state may get reset due to theme changes, so it
 566    * must be called prior to each potential off-main-thread LookAndFeel
 567    * call, not just once.
 568    */
 569   static void NativeInit();
 570
 571   static void SetData(widget::FullLookAndFeel&& aTables);
 572   static void NotifyChangedAllWindows(widget::ThemeChangeKind);
 573   static bool HasPendingGlobalThemeChange() { return sGlobalThemeChanged; }
 574   static void HandleGlobalThemeChange() {
 575     if (MOZ_UNLIKELY(HasPendingGlobalThemeChange())) {
 576       DoHandleGlobalThemeChange();
 577     }
 578   }
 579   static void EnsureColorSchemesInitialized() {
 580     if (!sColorSchemeInitialized) {
 581       RecomputeColorSchemes();
 582     }
 583     MOZ_ASSERT(sColorSchemeInitialized);
 584   }
 585
 586   static ColorScheme sChromeColorScheme;
 587   static ColorScheme sContentColorScheme;
 588
 589  protected:
 590   static void RecomputeColorSchemes();
 591   static bool sColorSchemeInitialized;
 592
 593   static void DoHandleGlobalThemeChange();
 594   // Set to true when ThemeChanged needs to be called on mTheme (and other
 595   // global LookAndFeel.  This is used because mTheme is a service, so there's
 596   // no need to notify it from more than one prescontext.
 597   static bool sGlobalThemeChanged;
 598 };
 599
 600 }  // namespace mozilla
 601
 602 // ---------------------------------------------------------------------
 603 //  Special colors for ColorID::IME* and ColorID::SpellCheckerUnderline
 604 // ---------------------------------------------------------------------
 605
 606 // For background color only.
 607 constexpr nscolor NS_TRANSPARENT = NS_RGBA(0x01, 0x00, 0x00, 0x00);
 608 // For foreground color only.
 609 constexpr nscolor NS_SAME_AS_FOREGROUND_COLOR = NS_RGBA(0x02, 0x00, 0x00, 0x00);
 610 constexpr nscolor NS_40PERCENT_FOREGROUND_COLOR =
 611     NS_RGBA(0x03, 0x00, 0x00, 0x00);
 612
 613 #define NS_IS_SELECTION_SPECIAL_COLOR(c)                          \
 614   ((c) == NS_TRANSPARENT || (c) == NS_SAME_AS_FOREGROUND_COLOR || \
 615    (c) == NS_40PERCENT_FOREGROUND_COLOR)
 616
 617 // ------------------------------------------
 618 //  Bits for IntID::AlertNotificationOrigin
 619 // ------------------------------------------
 620
 621 #define NS_ALERT_HORIZONTAL 1
 622 #define NS_ALERT_LEFT 2
 623 #define NS_ALERT_TOP 4
 624
 625 #endif /* __LookAndFeel */