mozilla
Your Search Results

    Preferences

    This document attempts to explaing the guide line of naming rules of preferences and accessing them.

    This document is still under discussion.

    Naming guidelines

    By convention, preference names are period separated. Preferences for a feature are grouped together with a common prefix. For example:

    foo.bar.enabled
    foo.bar.baz_range.min
    foo.bar.baz_range.max
    

    If code may want to observe preference changes for a group of preferences, they should be grouped together with a common prefix to improve observer performane.

    Preferences which enable or disable a feature should be named <root>.featurename.enabled with a boolean type. If an "enabled" pref does not always enable or disable the feature, you may need to add another pref which enables or disables the feature forcibly (i.e., ignoring the condition). The pref name should be "force_disable" or "force_enable".

    Preference names should be easy to understand. It's better to use a long name such as "use_it_only_when_it_is_available" than a cryptic name which might cause confusion.

    When to use preferences

    Prefs may/should be used in the following situations:

    • To store a user-visible preference setting. Preferences of this type require UX review.
    • To enable release drivers to turn a feature off easily if there is a problem found during the release process. Once a feature has shipped, this preference type should probably be removed.
    • To control features which are experimental or not ready to ship to our release users. Per-channel defaults control which experimental features are enabled for each prerelease population.
    • Other internal usage: for example to facilitate A/B testing via telemetry experiments, or to control automated test behavior. In these cases consider whether it would be better to use a runtime setting instead of a persistent preference to control the behavior.

    Preferences should not be used to expose features to power users via about:config settings. In order to make support better, it is far better for these users to install an addon to change the default behavior, even if the addon simply changes a runtime flag. This allows us to see non-default settings in about:support, Firefox Health Report, and crash-stats, and they are properly disabled when running in Firefox safe mode.

    How to add new preference

    If a preference is used by core platform/Gecko code, a default value should normally be added to modules/libpref/src/init/all.js. This default is shared all Mozilla products such as Firefox, Thunderbird, Firefox for Android and Firefox OS. If you need to set different initial value for specific product, you can use browser/app/profile/firefox.js, mailnews/mailnews.js, mobile/android/app/mobile.js and/or b2g/app/b2g.js.

    If a preference is used only by application-specific code, the default should live in the relevant app-specific default file.

    Guidelines of getting preference in C++ code

    When you're hacking internal code of libxul, you can use API defined in modules/libpref/public/Preferences.h.

    If you need to get a preference value at very hot path, you shouldn't use Preferences::Get*(). Instead of that there are two kinds of API sets.

    One is Preferences::Add*VarCache(). This API modifies registed static variable to the latest preference value automatically. Therefore, this is very useful if you don't need to reinitialize someting when the pref is changed.

    The other is Preferences::RegisterCallback(). You can register a call back method for preferences which you want to observe the changes. If you use this, you need to call Preferences::UnregisterCallback() when you don't need it anymore. If you need a whole time while our process is running, you should call it at shutting down XPCOM. Most modules have an observer of XPCOM shudown and calls Shutdown() method of a lot of classes. See nsLayoutStatics::Shutdown() (layout/build/nsLayoutStatics.cpp) for the example.

    Float values

    The prerefences system doesn't support float types natively. One workaround is to use integer preference whose value is mutilplied by 10, 100 or 1000. You should explain the value meaning in modules/libpref/src/init/all.js if you define its initial value. The other is to use string preference and convert to float using parseFloat (JavaScript) or atof (C++).

    Document Tags and Contributors

    Contributors to this page: BenjaminSmedberg, Masayuki
    Last updated by: BenjaminSmedberg,