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/widget/ThemeChangeKind.h"
  18
  19 struct gfxFontStyle;
  20
  21 namespace mozilla {
  22
  23 namespace widget {
  24 class FullLookAndFeel;
  25 class LookAndFeelCache;
  26 }  // namespace widget
  27
  28 enum class StyleSystemColor : uint8_t;
  29
  30 class LookAndFeel {
  31  public:
  32   using ColorID = StyleSystemColor;
  33
  34   // When modifying this list, also modify nsXPLookAndFeel::sIntPrefs
  35   // in widget/xpwidgts/nsXPLookAndFeel.cpp.
  36   enum class IntID {
  37     // default, may be overriden by OS
  38     CaretBlinkTime,
  39     // pixel width of caret
  40     CaretWidth,
  41     // show the caret when text is selected?
  42     ShowCaretDuringSelection,
  43     // select textfields when focused via tab/accesskey?
  44     SelectTextfieldsOnKeyFocus,
  45     // delay before submenus open
  46     SubmenuDelay,
  47     // can popups overlap menu/task bar?
  48     MenusCanOverlapOSBar,
  49     // should overlay scrollbars be used?
  50     UseOverlayScrollbars,
  51     // allow H and V overlay scrollbars to overlap?
  52     AllowOverlayScrollbarsOverlap,
  53     // show/hide scrollbars based on activity
  54     ShowHideScrollbars,
  55     // skip navigating to disabled menu item?
  56     SkipNavigatingDisabledMenuItem,
  57     // begin a drag if the mouse is moved further than the threshold while the
  58     // button is down
  59     DragThresholdX,
  60     DragThresholdY,
  61     // Accessibility theme being used?
  62     UseAccessibilityTheme,
  63
  64     // position of scroll arrows in a scrollbar
  65     ScrollArrowStyle,
  66     // is scroll thumb proportional or fixed?
  67     ScrollSliderStyle,
  68
  69     // each button can take one of four values:
  70     ScrollButtonLeftMouseButtonAction,
  71     // 0 - scrolls one  line, 1 - scrolls one page
  72     ScrollButtonMiddleMouseButtonAction,
  73     // 2 - scrolls to end, 3 - button ignored
  74     ScrollButtonRightMouseButtonAction,
  75
  76     // delay for opening spring loaded folders
  77     TreeOpenDelay,
  78     // delay for closing spring loaded folders
  79     TreeCloseDelay,
  80     // delay for triggering the tree scrolling
  81     TreeLazyScrollDelay,
  82     // delay for scrolling the tree
  83     TreeScrollDelay,
  84     // the maximum number of lines to be scrolled at ones
  85     TreeScrollLinesMax,
  86     // What type of tab-order to use
  87     TabFocusModel,
  88     // Should menu items blink when they're chosen?
  89     ChosenMenuItemsShouldBlink,
  90
  91     /*
  92      * A Boolean value to determine whether the Windows accent color
  93      * should be applied to the title bar.
  94      *
  95      * The value of this metric is not used on other platforms. These platforms
  96      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
  97      */
  98     WindowsAccentColorInTitlebar,
  99
 100     /*
 101      * A Boolean value to determine whether the Windows default theme is
 102      * being used.
 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     WindowsDefaultTheme,
 108
 109     /*
 110      * A Boolean value to determine whether the DWM compositor is being used
 111      *
 112      * This metric is not used on non-Windows platforms. These platforms
 113      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 114      */
 115     DWMCompositor,
 116
 117     /*
 118      * A Boolean value to determine whether Windows is themed (Classic vs.
 119      * uxtheme)
 120      *
 121      * This is Windows-specific and is not implemented on other platforms
 122      * (will return the default of NS_ERROR_FAILURE).
 123      */
 124     WindowsClassic,
 125
 126     /*
 127      * A Boolean value to determine whether the current Windows desktop theme
 128      * supports Aero Glass.
 129      *
 130      * This is Windows-specific and is not implemented on other platforms
 131      * (will return the default of NS_ERROR_FAILURE).
 132      */
 133     WindowsGlass,
 134
 135     /*
 136      * A Boolean value to determine whether the device is a touch enabled
 137      * device. Currently this is only supported by the Windows 7 Touch API.
 138      *
 139      * Platforms that do not support this metric should return
 140      * NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 141      */
 142     TouchEnabled,
 143
 144     /*
 145      * A Boolean value to determine whether the Mac graphite theme is
 146      * being used.
 147      *
 148      * The value of this metric is not used on other platforms. These platforms
 149      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 150      */
 151     MacGraphiteTheme,
 152
 153     /*
 154      * A Boolean value to determine whether the macOS Big Sur-specific
 155      * theming should be used.
 156      *
 157      * The value of this metric is not used on non-Mac platforms. These
 158      * platforms should return NS_ERROR_NOT_IMPLEMENTED when queried for this
 159      * metric.
 160      */
 161     MacBigSurTheme,
 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      * Return the appropriate WindowsThemeIdentifier for the current theme.
 204      */
 205     WindowsThemeIdentifier,
 206     /**
 207      * Return an appropriate os version identifier.
 208      */
 209     OperatingSystemVersionIdentifier,
 210     /**
 211      * 0: scrollbar button repeats to scroll only when cursor is on the button.
 212      * 1: scrollbar button repeats to scroll even if cursor is outside of it.
 213      */
 214     ScrollbarButtonAutoRepeatBehavior,
 215     /**
 216      * Delay before showing a tooltip.
 217      */
 218     TooltipDelay,
 219     /*
 220      * A Boolean value to determine whether Mac OS X Lion style swipe animations
 221      * should be used.
 222      */
 223     SwipeAnimationEnabled,
 224
 225     /*
 226      * Controls whether overlay scrollbars display when the user moves
 227      * the mouse in a scrollable frame.
 228      */
 229     ScrollbarDisplayOnMouseMove,
 230
 231     /*
 232      * Overlay scrollbar animation constants.
 233      */
 234     ScrollbarFadeBeginDelay,
 235     ScrollbarFadeDuration,
 236
 237     /**
 238      * Distance in pixels to offset the context menu from the cursor
 239      * on open.
 240      */
 241     ContextMenuOffsetVertical,
 242     ContextMenuOffsetHorizontal,
 243
 244     /*
 245      * A boolean value indicating whether client-side decorations are
 246      * supported by the user's GTK version.
 247      */
 248     GTKCSDAvailable,
 249
 250     /*
 251      * A boolean value indicating whether GTK+ system titlebar should be
 252      * disabled by default.
 253      */
 254     GTKCSDHideTitlebarByDefault,
 255
 256     /*
 257      * A boolean value indicating whether client-side decorations should
 258      * have transparent background.
 259      */
 260     GTKCSDTransparentBackground,
 261
 262     /*
 263      * A boolean value indicating whether client-side decorations should
 264      * contain a minimize button.
 265      */
 266     GTKCSDMinimizeButton,
 267
 268     /*
 269      * A boolean value indicating whether client-side decorations should
 270      * contain a maximize button.
 271      */
 272     GTKCSDMaximizeButton,
 273
 274     /*
 275      * A boolean value indicating whether client-side decorations should
 276      * contain a close button.
 277      */
 278     GTKCSDCloseButton,
 279
 280     /*
 281      * A boolean value indicating whether titlebar buttons are located
 282      * in left titlebar corner.
 283      */
 284     GTKCSDReversedPlacement,
 285
 286     /*
 287      * A boolean value indicating whether or not the OS is using a dark theme,
 288      * which we may want to switch to as well if not overridden by the user.
 289      */
 290     SystemUsesDarkTheme,
 291
 292     /**
 293      * Corresponding to prefers-reduced-motion.
 294      * https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-motion
 295      * 0: no-preference
 296      * 1: reduce
 297      */
 298
 299     PrefersReducedMotion,
 300     /**
 301      * Corresponding to PointerCapabilities in ServoTypes.h
 302      * 0: None
 303      * 1: Coarse
 304      * 2: Fine
 305      * 4: Hover
 306      */
 307     PrimaryPointerCapabilities,
 308     /**
 309      * Corresponding to union of PointerCapabilities values in ServoTypes.h
 310      * E.g. if there is a mouse and a digitizer, the value will be
 311      * 'Coarse | Fine | Hover'.
 312      */
 313     AllPointerCapabilities,
 314     /**
 315      * An Integer value that will represent the position of the Close button
 316      * in GTK Client side decoration header. Its value will be between 0 and 2
 317      * if it is on the left side of the tabbar, otherwise it will be between
 318      * 3 and 5.
 319      */
 320     GTKCSDCloseButtonPosition,
 321
 322     /**
 323      * An Integer value that will represent the position of the Minimize button
 324      * in GTK Client side decoration header. Its value will be between 0 and 2
 325      * if it is on the left side of the tabbar, otherwise it will be between
 326      * 3 and 5.
 327      */
 328     GTKCSDMinimizeButtonPosition,
 329
 330     /**
 331      * An Integer value that will represent the position of the Maximize button
 332      * in GTK Client side decoration header. Its value will be between 0 and 2
 333      * if it is on the left side of the tabbar, otherwise it will be between
 334      * 3 and 5.
 335      */
 336     GTKCSDMaximizeButtonPosition,
 337
 338     /*
 339      * Not an ID; used to define the range of valid IDs.  Must be last.
 340      */
 341     End,
 342   };
 343
 344   /**
 345    * Windows themes we currently detect.
 346    */
 347   enum WindowsTheme {
 348     eWindowsTheme_Generic = 0,  // unrecognized theme
 349     eWindowsTheme_Classic,
 350     eWindowsTheme_Aero,
 351     eWindowsTheme_LunaBlue,
 352     eWindowsTheme_LunaOlive,
 353     eWindowsTheme_LunaSilver,
 354     eWindowsTheme_Royale,
 355     eWindowsTheme_Zune,
 356     eWindowsTheme_AeroLite
 357   };
 358
 359   /**
 360    * Operating system versions.
 361    */
 362   enum class OperatingSystemVersion {
 363     Windows7 = 2,
 364     Windows8,
 365     Windows10,
 366     Unknown
 367   };
 368
 369   enum {
 370     eScrollArrow_None = 0,
 371     eScrollArrow_StartBackward = 0x1000,
 372     eScrollArrow_StartForward = 0x0100,
 373     eScrollArrow_EndBackward = 0x0010,
 374     eScrollArrow_EndForward = 0x0001
 375   };
 376
 377   enum {
 378     // single arrow at each end
 379     eScrollArrowStyle_Single =
 380         eScrollArrow_StartBackward | eScrollArrow_EndForward,
 381     // both arrows at bottom/right, none at top/left
 382     eScrollArrowStyle_BothAtBottom =
 383         eScrollArrow_EndBackward | eScrollArrow_EndForward,
 384     // both arrows at both ends
 385     eScrollArrowStyle_BothAtEachEnd =
 386         eScrollArrow_EndBackward | eScrollArrow_EndForward |
 387         eScrollArrow_StartBackward | eScrollArrow_StartForward,
 388     // both arrows at top/left, none at bottom/right
 389     eScrollArrowStyle_BothAtTop =
 390         eScrollArrow_StartBackward | eScrollArrow_StartForward
 391   };
 392
 393   enum { eScrollThumbStyle_Normal, eScrollThumbStyle_Proportional };
 394
 395   // When modifying this list, also modify nsXPLookAndFeel::sFloatPrefs
 396   // in widget/nsXPLookAndFeel.cpp.
 397   enum class FloatID {
 398     IMEUnderlineRelativeSize,
 399     SpellCheckerUnderlineRelativeSize,
 400
 401     // The width/height ratio of the cursor. If used, the CaretWidth int metric
 402     // should be added to the calculated caret width.
 403     CaretAspectRatio,
 404
 405     // Not an ID; used to define the range of valid IDs.  Must be last.
 406     End,
 407   };
 408
 409   // These constants must be kept in 1:1 correspondence with the
 410   // NS_STYLE_FONT_* system font constants.
 411   enum class FontID {
 412     Caption = 1,  // css2
 413     MINIMUM = Caption,
 414     Icon,
 415     Menu,
 416     MessageBox,
 417     SmallCaption,
 418     StatusBar,
 419
 420     Window,  // css3
 421     Document,
 422     Workspace,
 423     Desktop,
 424     Info,
 425     Dialog,
 426     Button,
 427     PullDownMenu,
 428     List,
 429     Field,
 430
 431     Tooltips,  // moz
 432     Widget,
 433     MAXIMUM = Widget,
 434   };
 435
 436   /**
 437    * GetColor() return a native color value (might be overwritten by prefs) for
 438    * aID.  Some platforms don't return an error even if the index doesn't
 439    * match any system colors.  And also some platforms may initialize the
 440    * return value even when it returns an error.  Therefore, if you want to
 441    * use a color for the default value, you should use the other GetColor()
 442    * which returns nscolor directly.
 443    *
 444    * NOTE:
 445    *   ColorID::TextSelectForeground might return NS_DONT_CHANGE_COLOR.
 446    *   ColorID::IME* might return NS_TRANSPARENT, NS_SAME_AS_FOREGROUND_COLOR or
 447    *   NS_40PERCENT_FOREGROUND_COLOR.
 448    *   These values have particular meaning.  Then, they are not an actual
 449    *   color value.
 450    */
 451   static nsresult GetColor(ColorID aID, nscolor* aResult);
 452
 453   /**
 454    * This variant of GetColor() takes an extra Boolean parameter that allows
 455    * the caller to ask that hard-coded color values be substituted for
 456    * native colors (used when it is desireable to hide system colors to
 457    * avoid system fingerprinting).
 458    */
 459   static nsresult GetColor(ColorID aID, bool aUseStandinsForNativeColors,
 460                            nscolor* aResult);
 461
 462   /**
 463    * GetInt() and GetFloat() return a int or float value for aID.  The result
 464    * might be distance, time, some flags or a int value which has particular
 465    * meaning.  See each document at definition of each ID for the detail.
 466    * The result is always 0 when they return error.  Therefore, if you want to
 467    * use a value for the default value, you should use the other method which
 468    * returns int or float directly.
 469    */
 470   static nsresult GetInt(IntID aID, int32_t* aResult);
 471   static nsresult GetFloat(FloatID aID, float* aResult);
 472
 473   static nscolor GetColor(ColorID aID, nscolor aDefault = NS_RGB(0, 0, 0)) {
 474     nscolor result = NS_RGB(0, 0, 0);
 475     if (NS_FAILED(GetColor(aID, &result))) {
 476       return aDefault;
 477     }
 478     return result;
 479   }
 480
 481   static nscolor GetColorUsingStandins(ColorID aID,
 482                                        nscolor aDefault = NS_RGB(0, 0, 0)) {
 483     nscolor result = NS_RGB(0, 0, 0);
 484     if (NS_FAILED(GetColor(aID,
 485                            true,  // aUseStandinsForNativeColors
 486                            &result))) {
 487       return aDefault;
 488     }
 489     return result;
 490   }
 491
 492   static int32_t GetInt(IntID aID, int32_t aDefault = 0) {
 493     int32_t result;
 494     if (NS_FAILED(GetInt(aID, &result))) {
 495       return aDefault;
 496     }
 497     return result;
 498   }
 499
 500   static float GetFloat(FloatID aID, float aDefault = 0.0f) {
 501     float result;
 502     if (NS_FAILED(GetFloat(aID, &result))) {
 503       return aDefault;
 504     }
 505     return result;
 506   }
 507
 508   /**
 509    * Retrieve the name and style of a system-theme font.  Returns true
 510    * if the system theme specifies this font, false if a default should
 511    * be used.  In the latter case neither aName nor aStyle is modified.
 512    *
 513    * Size of the font should be in CSS pixels, not device pixels.
 514    *
 515    * @param aID    Which system-theme font is wanted.
 516    * @param aName  The name of the font to use.
 517    * @param aStyle Styling to apply to the font.
 518    */
 519   static bool GetFont(FontID aID, nsString& aName, gfxFontStyle& aStyle);
 520
 521   /**
 522    * GetPasswordCharacter() returns a unicode character which should be used
 523    * for a masked character in password editor.  E.g., '*'.
 524    */
 525   static char16_t GetPasswordCharacter();
 526
 527   /**
 528    * If the latest character in password field shouldn't be hidden by the
 529    * result of GetPasswordCharacter(), GetEchoPassword() returns TRUE.
 530    * Otherwise, FALSE.
 531    */
 532   static bool GetEchoPassword();
 533
 534   /**
 535    * The millisecond to mask password value.
 536    * This value is only valid when GetEchoPassword() returns true.
 537    */
 538   static uint32_t GetPasswordMaskDelay();
 539
 540   /**
 541    * When system look and feel is changed, Refresh() must be called.  Then,
 542    * cached data would be released.
 543    */
 544   static void Refresh();
 545
 546   /**
 547    * GTK's initialization code can't be run off main thread, call this
 548    * if you plan on using LookAndFeel off main thread later.
 549    *
 550    * This initialized state may get reset due to theme changes, so it
 551    * must be called prior to each potential off-main-thread LookAndFeel
 552    * call, not just once.
 553    */
 554   static void NativeInit();
 555
 556   /**
 557    * If the implementation is caching values, these accessors allow the
 558    * cache to be exported and imported.
 559    */
 560   static widget::LookAndFeelCache GetCache();
 561   static void SetCache(const widget::LookAndFeelCache& aCache);
 562   static void SetData(widget::FullLookAndFeel&& aTables);
 563   static void NotifyChangedAllWindows(widget::ThemeChangeKind);
 564 };
 565
 566 }  // namespace mozilla
 567
 568 // On the Mac, GetColor(ColorID::TextSelectForeground, color) returns this
 569 // constant to specify that the foreground color should not be changed
 570 // (ie. a colored text keeps its colors  when selected).
 571 // Of course if other plaforms work like the Mac, they can use it too.
 572 #define NS_DONT_CHANGE_COLOR NS_RGB(0x01, 0x01, 0x01)
 573
 574 // Similar with NS_DONT_CHANGE_COLOR, except NS_DONT_CHANGE_COLOR would returns
 575 // complementary color if fg color is same as bg color.
 576 // NS_CHANGE_COLOR_IF_SAME_AS_BG would returns
 577 // ColorID::TextSelectForegroundCustom if fg and bg color are the same.
 578 #define NS_CHANGE_COLOR_IF_SAME_AS_BG NS_RGB(0x02, 0x02, 0x02)
 579
 580 // ---------------------------------------------------------------------
 581 //  Special colors for ColorID::IME* and ColorID::SpellCheckerUnderline
 582 // ---------------------------------------------------------------------
 583
 584 // For background color only.
 585 #define NS_TRANSPARENT NS_RGBA(0x01, 0x00, 0x00, 0x00)
 586 // For foreground color only.
 587 #define NS_SAME_AS_FOREGROUND_COLOR NS_RGBA(0x02, 0x00, 0x00, 0x00)
 588 #define NS_40PERCENT_FOREGROUND_COLOR NS_RGBA(0x03, 0x00, 0x00, 0x00)
 589
 590 #define NS_IS_SELECTION_SPECIAL_COLOR(c)                          \
 591   ((c) == NS_TRANSPARENT || (c) == NS_SAME_AS_FOREGROUND_COLOR || \
 592    (c) == NS_40PERCENT_FOREGROUND_COLOR)
 593
 594 // ------------------------------------------
 595 //  Bits for IntID::AlertNotificationOrigin
 596 // ------------------------------------------
 597
 598 #define NS_ALERT_HORIZONTAL 1
 599 #define NS_ALERT_LEFT 2
 600 #define NS_ALERT_TOP 4
 601
 602 #endif /* __LookAndFeel */