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