offapi/com/sun/star/awt/XKeyHandler.idl | 30 ++++++++++++++++-------
offapi/com/sun/star/awt/XKeyListener.idl | 8 ++++--
offapi/com/sun/star/awt/XMouseClickHandler.idl | 9 ++++++
offapi/com/sun/star/awt/XMouseListener.idl | 5 +++
offapi/com/sun/star/awt/XMouseMotionHandler.idl | 3 ++
offapi/com/sun/star/awt/XMouseMotionListener.idl | 6 ++++
6 files changed, 50 insertions(+), 11 deletions(-)
New commits:
commit c8f72c2a3a7b347c54089d96b0794b4586022688
Author: Moritz Duge <moritz.d...@allotropia.de>
AuthorDate: Mon Jun 24 18:34:44 2024 +0200
Commit: Samuel Mehrbrodt <samuel.mehrbr...@allotropia.de>
CommitDate: Thu Jun 27 07:24:31 2024 +0200
Improve documentation on key and mouse handlers and listeners.
Change-Id: I443fd0c53f1fb11df3b4e13806771c2c649cae23
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/169473
Reviewed-by: Samuel Mehrbrodt <samuel.mehrbr...@allotropia.de>
Tested-by: Jenkins
diff --git a/offapi/com/sun/star/awt/XKeyHandler.idl
b/offapi/com/sun/star/awt/XKeyHandler.idl
index d6455914f640..38b57696e800 100644
--- a/offapi/com/sun/star/awt/XKeyHandler.idl
+++ b/offapi/com/sun/star/awt/XKeyHandler.idl
@@ -20,15 +20,27 @@
module com { module sun { module star { module awt {
-/** This key handler is similar to
- ::com::sun::star::awt::XKeyListener but allows the
- consumption of key events. If a key event is consumed by one
- handler both the following handlers, with respect to the list of key
- handlers of the broadcaster, and a following handling by the
- broadcaster will not take place.
-
- @since OOo 1.1.2
-*/
+/** makes it possible to receive keyboard events.
+ *
+ * This key handler is similar to com::sun::star::awt::XKeyListener.
+ * But this handler is easier to use and more flexible for many
+ * purposes.
+ *
+ * This handler is usually added via
+ * com::sun::star::awt::XUserInputInterception to the controller from
+ * com::sun::star::frame::XModel. While
+ * com::sun::star::awt::XKeyListener needs to be added to exactly the
+ * correct widget.
+ *
+ * Also this handler is more flexible then
+ * com::sun::star::awt::XKeyListener, because it optionally allows the
+ * consumption of key events. If a key event is consumed by one handler
+ * both the following handlers, with respect to the list of
+ * key handlers of the broadcaster, and a following handling by the
+ * broadcaster will not take place.
+ *
+ * @since OOo 1.1.2
+ */
published interface XKeyHandler : ::com::sun::star::lang::XEventListener
{
/** This function is called by the broadcaster, an
diff --git a/offapi/com/sun/star/awt/XKeyListener.idl
b/offapi/com/sun/star/awt/XKeyListener.idl
index bb9375b22fa5..373cc0c43bca 100644
--- a/offapi/com/sun/star/awt/XKeyListener.idl
+++ b/offapi/com/sun/star/awt/XKeyListener.idl
@@ -24,8 +24,12 @@
/** makes it possible to receive keyboard events.
*
- * @see com::sun::star::awt::XKeyHandler This interface allows you receive
(and consume) key events,
- * even on windows which are not at the top.
+ * @see com::sun::star::awt::XKeyHandler That interface is better suited for
many purposes. In
+ * opposite to this listener, the com::sun::star::awt::XKeyHandler doesn't
need to be added on
+ * exactly the correct widget. Optionally com::sun::star::awt::XKeyHandler can
also consume events.
+ *
+ * @see com::sun::star::awt::XVclContainer The function getWindows might be
helpful to find the
+ * correct widget to add the this listener to.
*/
published interface XKeyListener: com::sun::star::lang::XEventListener
{
diff --git a/offapi/com/sun/star/awt/XMouseClickHandler.idl
b/offapi/com/sun/star/awt/XMouseClickHandler.idl
index fc63485f91e6..1f070a58850a 100644
--- a/offapi/com/sun/star/awt/XMouseClickHandler.idl
+++ b/offapi/com/sun/star/awt/XMouseClickHandler.idl
@@ -24,6 +24,15 @@ module com { module sun { module star { module awt {
/** makes it possible to receive events from the mouse in a certain window.
+ This handler is usually added via
+ com::sun::star::awt::XUserInputInterception to the controller from
+ com::sun::star::frame::XModel. While
+ com::sun::star::awt::XMouseListener needs to be added to exactly the
+ correct widget.
+
+ Also this handler is more flexible, because it optionally allows the
+ consumption of key events.
+
@since OOo 1.1.2
*/
published interface XMouseClickHandler: ::com::sun::star::lang::XEventListener
diff --git a/offapi/com/sun/star/awt/XMouseListener.idl
b/offapi/com/sun/star/awt/XMouseListener.idl
index a3f003daa0cc..48dd94b16d3f 100644
--- a/offapi/com/sun/star/awt/XMouseListener.idl
+++ b/offapi/com/sun/star/awt/XMouseListener.idl
@@ -30,6 +30,11 @@
* <li>com::sun::star::awt::XMouseClickHandler</li>
* <li>com::sun::star::awt::XMouseMotionHandler</li>
* </ul>
+ * These interfaces are better suited for many purposes. In opposite to this
listener they don't
+ * need to be added on exactly the correct widget. Optionally they can also
consume events.
+ *
+ * @see com::sun::star::awt::XVclContainer The function getWindows might be
helpful to find the
+ * correct widget to add this listener to.
*/
published interface XMouseListener: com::sun::star::lang::XEventListener
{
diff --git a/offapi/com/sun/star/awt/XMouseMotionHandler.idl
b/offapi/com/sun/star/awt/XMouseMotionHandler.idl
index 48cb21178c90..cba0dd0e7d5a 100644
--- a/offapi/com/sun/star/awt/XMouseMotionHandler.idl
+++ b/offapi/com/sun/star/awt/XMouseMotionHandler.idl
@@ -23,6 +23,9 @@
/** makes it possible to receive mouse motion events on a window.
+ *
+ * @see ::com::sun::star::awt::XMouseMotionListener This handler is more
+ * flexible, because it optionally allows the consumption of key events.
*/
published interface XMouseMotionHandler: com::sun::star::lang::XEventListener
{
diff --git a/offapi/com/sun/star/awt/XMouseMotionListener.idl
b/offapi/com/sun/star/awt/XMouseMotionListener.idl
index b3073ba7a923..7f02f9c37f98 100644
--- a/offapi/com/sun/star/awt/XMouseMotionListener.idl
+++ b/offapi/com/sun/star/awt/XMouseMotionListener.idl
@@ -23,6 +23,12 @@
/** makes it possible to receive mouse motion events on a window.
+ *
+ * @see com::sun::star::awt::XMouseListener
+ * @see com::sun::star::awt::XMouseMotionHandler This can optionally consume
events.
+ *
+ * @see com::sun::star::awt::XVclContainer The function getWindows might be
helpful to find the
+ * correct widget to add this listener to.
*/
published interface XMouseMotionListener: com::sun::star::lang::XEventListener
{
