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