| commit | df315b11eeaa67d79cfdd1565ffcc4f28de79dd3 | [log] [tgz] |
|---|---|---|
| author | Dorota Czaplejewicz <[email protected]> | Mon Jul 29 11:35:23 2019 |
| committer | Simon Ser <[email protected]> | Mon Dec 06 12:03:35 2021 |
| tree | 7da993f3d10feb56039a012f2e92ca4044fe265f | |
| parent | 155d5774e1ac9ccfbba694cc90383b36f1b0aa71 [diff] |
text-input: Add on_screen_input_provided hint The new hint is meant to indicate that the text input already provides an on-screen means to enter data, and that using the system provided input method may not be needed. It should be used when the client presents the user with a custom on-screen input method, like an on-screen keyboard, or perhaps a dropdown list. The new hint is meant to address the issue when the system input method is an on-screen keyboard. Without the hint, the input method would not know that it's not needed, unless the client refrained from using the input method protocol at all. With the hint, the input method can still be enabled, while not displaying a second on-screen keyboard. This allows for the system input method to still provide accessibility services, as well as text completion or prediction. Based on discussion in https://gitlab.gnome.org/GNOME/gtk/merge_requests/978 Signed-off-by: Dorota Czaplejewicz <[email protected]>
wayland-protocols contains Wayland protocols that add functionality not available in the Wayland core protocol. Such protocols either add completely new functionality, or extend the functionality of some other protocol either in Wayland core, or some other protocol in wayland-protocols.
A protocol in wayland-protocols consists of a directory containing a set of XML files containing the protocol specification, and a README file containing detailed state and a list of maintainers.
Protocols may be “stable”, “unstable” or “deprecated”, and the interface and protocol names as well as place in the directory tree will reflect this.
A stable protocol is a protocol which has been declared stable by the maintainers. Changes to such protocols will always be backward compatible.
An unstable protocol is a protocol currently under development and this will be reflected in the protocol and interface names. See Unstable naming convention.
A deprecated protocol is a protocol that has either been replaced by some other protocol, or declared undesirable for some other reason. No more changes will be made to a deprecated protocol.
Depending on which of the above states the protocol is in, the protocol is placed within the toplevel directory containing the protocols with the same state. Stable protocols are placed in the stable/ directory, unstable protocols are placed in the unstable/ directory, and deprecated protocols are placed in the deprecated/ directory.
To propose a new protocol, create a GitLab merge request adding the relevant files and Makefile.am entry to the repository with the explanation and motivation in the commit message. Protocols are organized in namespaces describing their scope (“wp”, “xdg” and “ext”). There are different requirements for each namespace, see GOVERNANCE section 2 for more information.
If the new protocol is just an idea, open an issue on the GitLab issue tracker. If the protocol isn't ready for complete review yet and is an RFC, create a merge request and add the “WIP:” prefix in the title.
To propose changes to existing protocols, create a GitLab merge request.
If the changes are backward incompatible changes to an unstable protocol, see Unstable protocol changes.
All protocols should avoid using generic namespaces or no namespaces in the protocol interface names in order to minimize risk that the generated C API collides with other C API. Interface names that may collide with interface names from other protocols should also be avoided.
For generic protocols not limited to certain configurations (such as specific desktop environment or operating system) the wp_ prefix should be used on all interfaces in the protocol.
For protocols allowing clients to configure how their windows are managed, the xdg_ prefix should be used.
For operating system specific protocols, the interfaces should be prefixed with both wp_ and the operating system, for example wp_linux_, or wp_freebsd_, etc.
For more information about namespaces, see GOVERNANCE section 2.1 .
Unstable protocols have a special naming convention in order to make it possible to make discoverable backward incompatible changes.
An unstable protocol has at least two versions: the major version, which represents backward incompatible changes, and the minor version, which represents backward compatible changes to the interfaces in the protocol.
The major version is part of the XML file name, the protocol name in the XML, and interface names in the protocol.
Minor versions are the version attributes of the interfaces in the XML. There may be more than one minor version per protocol, if there are more than one global.
The XML file and protocol name also has the word ‘unstable’ in them, and all of the interfaces in the protocol are prefixed with z and suffixed with the major version number.
For example, an unstable protocol called foo-bar with major version 2 containing the two interfaces wp_foo and wp_bar both minor version 1 will be placed in the directory unstable/foo-bar/ consisting of one file called README and one called foo-bar-unstable-v2.xml. The XML file will consist of two interfaces called zwp_foo_v2 and zwp_bar_v2 with the version attribute set to 1.
During the development of a new protocol it is possible that backward incompatible changes are needed. Such a change needs to be represented in the major and minor versions of the protocol.
Assuming a backward incompatible change is needed, the procedure for how to do so is the following:
Backward compatible changes within a major unstable version can be done in the regular way as done in core Wayland or in stable protocols.
Once it is decided that a protocol should be declared stable, meaning no more backward incompatible changes will ever be allowed, one last breakage is needed.
The procedure of doing this is the following:
stable/ toplevel directory with the same name as the protocol directory in the unstable/ directory..xml suffix.unstable part and the major version number.z prefix and the major version number suffix from all of the interfaces in the protocol.README file in the unstable directory and create a new README file in the new directory.There are other requirements for declaring a protocol stable, see GOVERNANCE section 2.3.
Each release of wayland-protocols finalizes the version of the protocols to their state they had at that time.