:right-sidebar: True

Feature
===================================================================

.. currentmodule:: gi.repository.WebKit


.. versionadded:: 2.42




.. class:: Feature(*args, **kwargs)
   :no-contents-entry:






Describes a web engine feature that may be toggled at runtime.

The WebKit web engine includes a set of features which may be toggled
programmatically, each one represented by a :obj:`~gi.repository.WebKit.Feature` that provides
information about it:

- A unique “identifier”: :obj:`~gi.repository.Feature.get_identifier`\.
- A “default value”, which indicates whether the option is enabled
  automatically: :obj:`~gi.repository.Feature.get_default_value`\.
- Its “status”, which determines whether it should be considered
  user-settable and its development stage (see :obj:`~gi.repository.WebKit.FeatureStatus`
  for details): :obj:`~gi.repository.Feature.get_status`\.
- A category, which may be used to group features together:
  :obj:`~gi.repository.Feature.get_category`\.
- An optional short “name” which can be presented to an user:
  :obj:`~gi.repository.Feature.get_name`\.
- An optional longer “detailed” description:
  :obj:`~gi.repository.Feature.get_details`\.


The lists of available features can be obtained with
:obj:`~gi.repository.Settings.get_all_features`\, :obj:`~gi.repository.Settings.get_experimental_features`\,
and :obj:`~gi.repository.Settings.get_development_features`\). As a rule of thumb,
applications which may want to allow users (i.e. web developers) to test
WebKit features should use the list of experimental features. Additionally,
applications might want to expose development features *when targeting
technically inclined users* for early testing of in-development features
(i.e. in “technology preview” or “canary” builds).

Applications **must not** expose the list of all features to end users
because they often lack descriptions and control parts of the web engine
which are either intended to be used during development of WebKit itself,
or in specific scenarios to tweak how WebKit integrates with the
application.




Methods
-------

.. rst-class:: interim-class

.. class:: Feature
   :no-index:


   .. method:: get_category() -> str

      Gets the category of the feature.

      Applications which include user interface to toggle features may want
      to use the category to group related features together.


      .. versionadded:: 2.42








   .. method:: get_default_value() -> bool

      Gets whether the feature is enabled by default.

      The default value may be used by applications which include user interface
      to toggle features to restore its settings to their defaults. Note that
      whether a feature is actually enabled must be checked with
      :obj:`~gi.repository.Settings.get_feature_enabled`\.


      .. versionadded:: 2.42








   .. method:: get_details() -> str | None

      Gets a description for the ``feature``\.

      The detailed description should be considered an additional clarification
      on the purpose of the feature, to be used as complementary aid to be
      displayed along the feature name returned by :obj:`~gi.repository.Feature.get_name`\.
      The returned string is suitable to be displayed to end users, but it
      should not be relied upon being localized.

      Note that some *features may not* have a detailed description, and ``NULL``
      is returned in this case.


      .. versionadded:: 2.42








   .. method:: get_identifier() -> str

      Gets a string that uniquely identifies the ``feature``\.


      .. versionadded:: 2.42








   .. method:: get_name() -> str | None

      Gets a short name for the ``feature``\.

      The returned string is suitable to be displayed to end users, but it
      should not be relied upon being localized.

      Note that some *features may not* have a short name, and ``NULL``
      is returned in this case.


      .. versionadded:: 2.42








   .. method:: get_status() -> ~gi.repository.WebKit.FeatureStatus

      Gets the status of the feature.


      .. versionadded:: 2.42