Merge branch 'main' of https://github.com/odilia-app/atspi into tree-…

…example

Synchronize with latest changes on 'main'.

atspi-common/src/events/object.rs

@@ -477,7 +477,7 @@ pub struct AnnouncementEvent {
 	/// Text of the announcement.
 	pub text: String,
 	/// Politeness level.
-	pub live: crate::Live,
+	pub live: crate::Politeness,
 }
 
 #[derive(Debug, PartialEq, Clone, serde::Serialize, serde::Deserialize, Eq, Hash, Default)]

atspi-common/src/lib.rs

@@ -48,6 +48,8 @@ pub type MatchArgs<'a> = (
 	bool,
 );
 
+pub type TextSelection = (ObjectRef, i32, ObjectRef, i32, bool);
+
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, Type)]
 #[repr(u32)]
 /// Enumeration used by interface `CollectionProxy` to specify the way [`ObjectRef`]
@@ -209,25 +211,25 @@ pub enum ScrollType {
 /// The argument in the `Announcement` event is named `politeness`.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize, Type)]
 #[repr(i32)]
-pub enum Live {
+pub enum Politeness {
 	/// No live region.
 	#[default]
-	None,
+	None = 0,
 	/// This live region should be considered polite.
-	Polite,
+	Polite = 1,
 	/// This live region should be considered assertive.
-	Assertive,
+	Assertive = 2,
 }
 
-impl TryFrom<i32> for Live {
+impl TryFrom<i32> for Politeness {
 	type Error = AtspiError;
 
 	fn try_from(value: i32) -> std::result::Result<Self, Self::Error> {
 		match value {
-			0 => Ok(Live::None),
-			1 => Ok(Live::Polite),
-			2 => Ok(Live::Assertive),
-			_ => Err(AtspiError::Conversion("Unknown Live variant")),
+			0 => Ok(Politeness::None),
+			1 => Ok(Politeness::Polite),
+			2 => Ok(Politeness::Assertive),
+			_ => Err(AtspiError::Conversion("Unknown Politeness variant")),
 		}
 	}
 }
@@ -241,18 +243,18 @@ mod tests {
 
 	#[test]
 	fn convert_i32_to_live() {
-		assert_eq!(Live::None, Live::try_from(0).unwrap());
-		assert_eq!(Live::Polite, Live::try_from(1).unwrap());
-		assert_eq!(Live::Assertive, Live::try_from(2).unwrap());
-		assert!(Live::try_from(3).is_err());
-		assert!(Live::try_from(-1).is_err());
+		assert_eq!(Politeness::None, Politeness::try_from(0).unwrap());
+		assert_eq!(Politeness::Polite, Politeness::try_from(1).unwrap());
+		assert_eq!(Politeness::Assertive, Politeness::try_from(2).unwrap());
+		assert!(Politeness::try_from(3).is_err());
+		assert!(Politeness::try_from(-1).is_err());
 	}
 
 	#[test]
 	fn validate_live_signature() {
 		let signature = signal_body_type_signature!("Announcement");
 		let politeness_signature = signature.slice(1..2);
-		assert_eq!(Live::signature(), politeness_signature);
+		assert_eq!(Politeness::signature(), politeness_signature);
 	}
 
 	#[test]

atspi-common/xml/Accessible.xml

@@ -77,6 +77,11 @@
     -->
     <property name="AccessibleId" type="s" access="read"/>
 
+    <!--
+        HelpText: help text for the current object.
+    -->
+    <property name="HelpText" type="s" access="read"/>
+
     <!--
         GetChildAtIndex:
         @index: 0-based index of the child to query.

atspi-common/xml/Document.xml

@@ -20,5 +20,14 @@
       <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiAttributeSet"/>
     </method>
 
+    <method name="GetTextSelections">
+      <arg direction="out" name="selections" type="a((so)i(so)ib)"/>
+    </method>
+
+    <method name="SetTextSelections">
+      <arg direction="in" name="selections" type="a((so)i(so)ib)"/>
+      <arg direction="out" type="b"/>
+    </method>
+
   </interface>
 </node>

atspi-common/xml/Event.xml

@@ -81,19 +81,22 @@
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>
     </signal>
     <signal name="Announcement">
-      <arg name="text" type="s"/>
+      <arg type="s"/>
       <!-- politeness should be 1 (ATSPI_LIVE_POLITE) or 2
            (ATSPI_LIVE_ASSERTIVE) -->
       <arg type="i" name="politeness"/>
       <arg type="i"/>
+      <!-- The variant should enclose a string with the text to be announced -->
       <arg type="v"/>
       <arg name="properties" type="a{sv}"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>
     </signal>
     <signal name="AttributesChanged">
-      <arg type="s"/>
+      <!-- name specifies the name of the attribute that has changed, when available -->
+      <arg name="name" type="s"/>
       <arg type="i"/>
       <arg type="i"/>
+      <!-- The variant should include a string with the attribute's new value, when available -->
       <arg type="v"/>
       <arg name="properties" type="a{sv}"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>
@@ -460,9 +463,11 @@
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>
     </signal>
     <signal name="AttributesChanged">
-      <arg type="s"/>
+      <!-- name specifies the name of the attribute that has changed, when available -->
+      <arg name="name" type="s"/>
       <arg type="i"/>
       <arg type="i"/>
+      <!-- The variant should include a string with the attribute's new value, when available -->
       <arg type="v"/>
       <arg name="properties" type="a{sv}"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>

atspi-common/xml/Socket.xml

@@ -32,6 +32,17 @@
       <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiObjectReference"/>
     </method>
 
+    <!--
+        Embedded:
+        @path: the object path of the socket.
+
+        This method is called by a socket to inform the plug that it is being
+        embedded. The plug should register the embedding socket as its parent.
+    -->
+    <method name="Embedded">
+      <arg direction="in" name="path" type="s"/>
+    </method>
+
     <!--
         Unembed:
         @plug: a string for the unique bus name of the application, and an object path

atspi-common/xml/Text.xml

@@ -33,6 +33,12 @@
       <arg direction="out" name="endOffset" type="i"/>
     </method>
 
+    <!--
+        GetTextAtOffset:
+
+        Returns the text at the given offset.
+        Deprecated: Use GetStringAtOffset.
+    -->
     <method name="GetTextAtOffset">
       <arg direction="in" name="offset" type="i"/>
       <arg direction="in" name="type" type="u"/>

atspi-proxies/src/accessible.rs

@@ -227,6 +227,10 @@ trait Accessible {
 	/// All other objects should have that one as their highest-level ancestor.
 	#[zbus(property)]
 	fn parent(&self) -> zbus::Result<ObjectRef>;
+
+	/// Help text for the current object.
+	#[zbus(property)]
+	fn help_text(&self) -> zbus::Result<String>;
 }
 
 impl TryFrom<AccessibleProxy<'_>> for ObjectRef {

atspi-proxies/src/document.rs

@@ -10,8 +10,16 @@
 //! section of the zbus documentation.
 //!
 
+use crate::common::TextSelection;
+
 #[zbus::proxy(interface = "org.a11y.atspi.Document", assume_defaults = true)]
 trait Document {
+	/// GetTextSelections method
+	fn get_text_selections(&self) -> zbus::Result<Vec<TextSelection>>;
+
+	/// SetTextSelections method
+	fn set_text_selections(&self, selections: Vec<TextSelection>) -> zbus::Result<bool>;
+
 	/// GetAttributeValue method
 	fn get_attribute_value(&self, attributename: &str) -> zbus::Result<String>;
 

atspi-proxies/src/socket.rs

@@ -18,9 +18,31 @@ use crate::common::ObjectRef;
 	default_service = "org.a11y.atspi.Registry"
 )]
 trait Socket {
-	/// Embed method
+	/// @plug: a string for the unique bus name of the application, and an object path
+	/// for the application's' root object.
+	///
+	/// This is the entry point for an application that wants to register itself against
+	/// the accessibility registry.  The application's root object, which it passes in
+	/// @plug, must support the org.a11y.atspi.Application interface.
+	///
+	/// When an application calls this method on the registry, the following handshake happens:
+	///
+	/// * Application calls this method on the registry to identify itself.
+	/// * The registry sets the "Id" property on the org.a11y.atspi.Application interface on the @plug object.
+	/// * The Embed method returns with the bus name and object path for the registry's root object.
+	/// Returns: the bus name and object path of the registry's root object.
 	fn embed(&self, plug: &(&str, zbus::zvariant::ObjectPath<'_>)) -> zbus::Result<ObjectRef>;
 
+	/// This method is called by a socket to inform the plug that it is being
+	/// embedded. The plug should register the embedding socket as its parent.
+	fn embedded(&self, path: zbus::zvariant::ObjectPath<'_>) -> zbus::Result<()>;
+
 	/// Unembed method
+	/// @plug: a string for the unique bus name of the application, and an object path
+	/// for the application's' root object.
+	///
+	/// Unregisters an application from the accesibility registry.  It is not necessary to
+	/// call this method; the accessibility registry detects when an application
+	/// disconnects from the bus.
 	fn unembed(&self, plug: &(&str, zbus::zvariant::ObjectPath<'_>)) -> zbus::Result<()>;
 }