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