docs: Improve the wl_registry protocol docs

Reword a few things, and add some details.
This commit is contained in:
Matthias Clasen 2013-03-30 01:11:34 -04:00 committed by Kristian Høgsberg
parent a5cc5b32bb
commit 8aa7a690a5

View file

@ -98,36 +98,41 @@
The global registry object. The server has a number of global The global registry object. The server has a number of global
objects that are available to all clients. These objects objects that are available to all clients. These objects
typically represent an actual object in the server (for example, typically represent an actual object in the server (for example,
an input device) or they are singleton objects that provides an input device) or they are singleton objects that provide
extension functionality. extension functionality.
When a client creates a registry object, the registry object When a client creates a registry object, the registry object
will emit a global event for each global currently in the will emit a global event for each global currently in the
registry. Globals come and go as a result of device hotplugs, registry. Globals come and go as a result of device or
reconfiguration or other events, and the registry will send out monitor hotplugs, reconfiguration or other events, and the
@global and @global_remove events to keep the client up to date registry will send out global and global_remove events to
with the changes. To mark the end of the initial burst of keep the client up to date with the changes. To mark the end
events, the client can use the wl_display.sync request of the initial burst of events, the client can use the
immediately after calling wl_display.get_registry. wl_display.sync request immediately after calling
wl_display.get_registry.
A client can 'bind' to a global object by using the bind A client can bind to a global object by using the bind
request. This creates a client side handle that lets the object request. This creates a client-side handle that lets the object
emit events to the client and lets the client invoke requests on emit events to the client and lets the client invoke requests on
the object. the object.
</description> </description>
<request name="bind"> <request name="bind">
<description summary="bind an object to the display"> <description summary="bind an object to the display">
Binds a new, client-created object to the server using @name as Binds a new, client-created object to the server using the
the identifier. specified name as the identifier.
</description> </description>
<arg name="name" type="uint" summary="unique number id for object"/> <arg name="name" type="uint" summary="unique name for the object"/>
<arg name="id" type="new_id"/> <arg name="id" type="new_id"/>
</request> </request>
<event name="global"> <event name="global">
<description summary="announce global object"> <description summary="announce global object">
Notify the client of global objects. Notify the client of global objects.
The event notifies the client that a global object with
the given name is now available, and it implements the
given version of the given interface.
</description> </description>
<arg name="name" type="uint"/> <arg name="name" type="uint"/>
<arg name="interface" type="string"/> <arg name="interface" type="string"/>
@ -136,10 +141,13 @@
<event name="global_remove"> <event name="global_remove">
<description summary="announce removal of global object"> <description summary="announce removal of global object">
Notify the client of removed global objects. This event Notify the client of removed global objects.
notifies the client that the global identifies by @name is no
longer available. If the client bound to the global using the This event notifies the client that the global identified
'bind' request, the client should now destroy that object. by name is no longer available. If the client bound to
the global using the bind request, the client should now
destroy that object.
The object remains valid and requests to the object will be The object remains valid and requests to the object will be
ignored until the client destroys it, to avoid races between ignored until the client destroys it, to avoid races between
the global going away and a client sending a request to it. the global going away and a client sending a request to it.