summaryrefslogtreecommitdiff
path: root/offapi/com
diff options
context:
space:
mode:
authorMoritz Duge <moritz.duge@allotropia.de>2024-06-24 18:34:44 +0200
committerSamuel Mehrbrodt <samuel.mehrbrodt@allotropia.de>2024-06-27 07:24:31 +0200
commitc8f72c2a3a7b347c54089d96b0794b4586022688 (patch)
tree76f530297d11d8823e1b2f718d4cc27f220cfdb9 /offapi/com
parentc983881b821f10b081336129ce547435b45d1704 (diff)
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.mehrbrodt@allotropia.de> Tested-by: Jenkins
Diffstat (limited to 'offapi/com')
-rw-r--r--offapi/com/sun/star/awt/XKeyHandler.idl30
-rw-r--r--offapi/com/sun/star/awt/XKeyListener.idl8
-rw-r--r--offapi/com/sun/star/awt/XMouseClickHandler.idl9
-rw-r--r--offapi/com/sun/star/awt/XMouseListener.idl5
-rw-r--r--offapi/com/sun/star/awt/XMouseMotionHandler.idl3
-rw-r--r--offapi/com/sun/star/awt/XMouseMotionListener.idl6
6 files changed, 50 insertions, 11 deletions
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
{