Difference between revisions of "Documentation/DevGuide/GUI/Events"

Latest revision as of 18:48, 21 December 2020

Apache OpenOffice dialogs are based on an event-oriented programming model where you can assign event handlers to the control elements. An event handler runs a predefined procedure when a particular action occurs. Event handlers are always added directly to the control (not to the control models). All dialog controls implement the interface com.sun.star.awt.XControl which extends the interface com.sun.star.awt.XWindow. Listeners are added to a control with a specific add<ListenerName>Listener() method like addMouseListener( [in] XMouseListener xListener ). Listeners are removed with a specific remove<ListenerName>Listener() method like removeMouseListener( [in] XMouseListener xListener ).

The methods of all listener interfaces have a parameter of a type derived from com.sun.star.lang.EventObject, for example com.sun.star.awt.MouseEvent, com.sun.star.awt.FocusEvent etc. This event object always carries a property Source by which it is possible to query the control an event has been triggered at.

The following code example shows how to implement an XActionListener. You must remember to implement the disposing() method as dictated by com.sun.star.lang.XEventListener. disposing() is supposed to be triggered when a dispose() command at the control has been invoked.

  public void actionPerformed(ActionEvent rEvent){
  try{
      // get the control that has fired the event, 
      XControl xControl = (XControl) UnoRuntime.queryInterface(XControl.class, rEvent.Source);
      XControlModel xControlModel = xControl.getModel();
      XPropertySet xPSet = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, xControlModel);
      String sName = (String) xPSet.getPropertyValue("Name");
      // just in case the listener has been added to several controls,
      // we make sure we refer to the right one
      if (sName.equals("CommandButton1")){
          //...
      }
  }catch (com.sun.star.uno.Exception ex){
      /* perform individual exception handling here.
       * Possible exception types are:
       * com.sun.star.lang.WrappedTargetException,
       * com.sun.star.beans.UnknownPropertyException,
       * com.sun.star.uno.Exception
       */
      ex.printStackTrace(System.out);
  }}

Mouse Listeners

Events that correspond to mouse actions are triggered by a com.sun.star.awt.XMouseListener that react to mouse movements over a control. Popular use-cases for a mouse listener are changing the mouse pointer when the mouse moves over the window or querying the click count of the event mousePressed([in] com.sun.star.awt.MouseEvent e) when you want to differentiate between a single-click and a double click. For this purpose all methods carry a parameter MenuEvent, a structure that contains amongst other things, the member ClickCount. Other members (PositionX and PositionY) are to query the mouse position during the event invocation and Buttons that refers to the pressed mouse buttons.

A MouseMotionListener that implements com.sun.star.awt.XMouseMotionListener can be used when a movement of the mouse pointer must be observed. The following example code shows a part of an implementation of a mouse motion listener that is executed when the mouse is entering a control. For further information about WindowPeers, see Displaying Dialogs.

  public void mouseEntered(MouseEvent _mouseEvent) {
      try {
          // retrieve the control that the event has been invoked at...
          XControl xControl = (XControl) UnoRuntime.queryInterface(XControl.class, _mouseEvent.Source);
          Object tk = m_xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", m_xContext);
          XToolkit xToolkit = (XToolkit) UnoRuntime.queryInterface(XToolkit.class, tk);
          // create the peer of the control by passing the windowpeer of the parent 
          // in this case the windowpeer of the control
          xControl.createPeer(xToolkit, m_xWindowPeer);
          // create a pointer object "in the open countryside" and set the type accordingly...
          Object oPointer = this.m_xMCF.createInstanceWithContext("com.sun.star.awt.Pointer", this.m_xContext);
          XPointer xPointer = (XPointer) UnoRuntime.queryInterface(XPointer.class, oPointer);
          xPointer.setType(com.sun.star.awt.SystemPointer.REFHAND); 
          // finally set the created pointer at the windowpeer of the control
          xControl.getPeer().setPointer(xPointer);
      } catch (com.sun.star.uno.Exception ex) {
          throw new java.lang.RuntimeException("cannot happen...");
      }}

Keyboard Listener

Keyboard events can be captured by a KeyListener that implements com.sun.star.awt.XKeyListener. This allows you to verify each keyboard stroke. This listener is very useful for edit controls. The interface dictates the implementation of the two methods keyPressed() and keyReleased().

  public void keyReleased(KeyEvent keyEvent) {
      int i = keyEvent.KeyChar;
      int n = keyEvent.KeyCode;
      int m = keyEvent.KeyFunc;
  }

Focus Listener

A focus listener implementing com.sun.star.awt.XFocusListener is notified when the focus is entering (focusGained()) or leaving (focusLost()) a control.

The FocusListener is usually used to verify the user input when the control loses the focus.

This example demonstrates how to use the focusEvent:

  public void focusLost(FocusEvent _focusEvent) {
      short nFocusFlags = _focusEvent.FocusFlags;
      int nFocusChangeReason = nFocusFlags & FocusChangeReason.TAB;
      if (nFocusChangeReason == FocusChangeReason.TAB){
          // get the window of the Window that has gained the Focus...
          // Note that the xWindow is just a representation of the controlwindow
          // but not of the control itself
          XWindow xWindow = (XWindow) UnoRuntime.queryInterface(XWindow.class, _focusEvent.NextFocus);
      }
  }

Paint Listener

Paint Listeners implementing com.sun.star.awt.XPaintListener are used to repaint areas that have become invalid.

Control element-specific events

Control element-specific events are events that only occur in relation to certain control elements.

The When initiating event is implemented in some control-button models. It is particularly useful because it is sent by either a key-press or a mouse-down action. Thus, it provides a consistent interface for users who navigate by mouse or by keyboard. If the model implements the Repeat capability, When initiating is the event that is repeatedly sent.