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