Command Button

From Apache OpenOffice Wiki
Jump to: navigation, search



The command button com.sun.star.awt.UnoControlButton allows the user to perform an action by clicking on it. Usually a command button displays a label that is set by the Label property of the control model that supports the service com.sun.star.awt.UnoControlButtonModel.

A command button supports the display of images as explained in Image Control.

Properties of com.sun.star.awt.UnoControlButtonModel
DefaultButton boolean. The DefaultButton property specifies that the command button is the default button on the dialog. Pressing the ENTER key chooses the button even if another control has the focus.
ImagePosition short. The position of an image may be set. This is useful because the ImagePosition property is defined as relative to the Label of the control. It accepts one of the values defined in the constants group ImagePosition
ImageURL string. The ImageURL property contains the path to a graphics file. The image can be shown on the command button.
Graphic com.sun.star.
ImageAlign short. All standard graphics formats are supported, such as .gif, .jpg, .tif, .wmf and .bmp. The ImageAlign property defines the alignment and accepts one of the values defined in com.sun.star.awt.ImageAlign. The image is not automatically scaled, and can be cut off.
PushButtonType short. The default action of the command button is defined by the PushButtonType property. It accepts the values defined in the enumeration com.sun.star.awt.PushButtonType. An OK button returns 1 on execute(). The default action of a Cancel button is to close the dialog, and execute() will return 0.
Toggle boolean. If this property is set to true, a single operation of the command button control (pressing space while it is focused, or clicking onto it) toggles it between a pressed and a not-pressed state.

The default for this property is false, which means the button behaves like a usual push button.

Repeat boolean. If this property is set to true, a single operation on the command button control (pressing and holding space while it is focused, or pressing and holding the mouse button) sends repeated events (When Initiating). Mouse events are sent at intervals of RepeatDelay milliseconds. This is similar to the functionality of the arrows on a scroll bar.
RepeatDelay long. Delay in milliseconds between repeated mouse events (see Repeat, above). Keyboard repeat timing is controlled elsewhere. Only significant if Repeat is set.


  public XButton insertButton(XActionListener _xActionListener, int _nPosX, int _nPosY, int _nWidth, String _sLabel, short _nPushButtonType){
  XButton xButton = null;
  try{
      // create a unique name by means of an own implementation...
      String sName = createUniqueName(m_xDlgModelNameContainer, "CommandButton");
 
      // create a controlmodel at the multiservicefactory of the dialog model... 
      Object oButtonModel = m_xMSFDialogModel.createInstance("com.sun.star.awt.UnoControlButtonModel");
      XMultiPropertySet xButtonMPSet = (XMultiPropertySet) UnoRuntime.queryInterface(XMultiPropertySet.class, oButtonModel);
      // Set the properties at the model - keep in mind to pass the property names in alphabetical order!
      xButtonMPSet.setPropertyValues(
      new String[] {"Height", "Label", "Name", "PositionX", "PositionY", "PushButtonType", "Width" } ,
      new Object[] {new Integer(14), _sLabel, sName, new Integer(_nPosX), new Integer(_nPosY), new Short(_nPushButtonType), new Integer(_nWidth)});
 
      // add the model to the NameContainer of the dialog model
      m_xDlgModelNameContainer.insertByName(sName, oButtonModel);
      XControl xButtonControl = m_xDlgContainer.getControl(sName);
      xButton = (XButton) UnoRuntime.queryInterface(XButton.class, xButtonControl);
      // An ActionListener will be notified on the activation of the button...
      xButton.addActionListener(_xActionListener);
      }catch (com.sun.star.uno.Exception ex){
      /* perform individual exception handling here.
       * Possible exception types are:
       * com.sun.star.lang.IllegalArgumentException,
       * com.sun.star.lang.WrappedTargetException,
       * com.sun.star.container.ElementExistException,
       * com.sun.star.beans.PropertyVetoException,
       * com.sun.star.beans.UnknownPropertyException,
       * com.sun.star.uno.Exception
       */
      ex.printStackTrace(System.out);
  }
      return xButton;
  }

In the example, an action listener is attached to the command button. An action listener implements the interface com.sun.star.awt.XActionListener and its method actionPerformed() is invoked when the user clicks on the button. (see also Events).

The following code snippet shows an example of how to use the action listener.

  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);
  }}}

Graphics

When an image source is used several times it may be better to keep the image in its own object variable. The following code snippet shows how you can create such a variable:

  // creates a UNO graphic object that can be used to be assigned 
  // to the property "Graphic" of a controlmodel
  public XGraphic getGraphic(String _sImageUrl){
  XGraphic xGraphic = null;
  try{
      // create a GraphicProvider at the global service manager...
      Object oGraphicProvider = m_xMCF.createInstanceWithContext("com.sun.star.graphic.GraphicProvider", m_xContext);
      XGraphicProvider xGraphicProvider = (XGraphicProvider) UnoRuntime.queryInterface(XGraphicProvider.class, oGraphicProvider);
      // create the graphic object
      PropertyValue[] aPropertyValues = new PropertyValue[1];
      PropertyValue aPropertyValue = new PropertyValue();
      aPropertyValue.Name = "URL";
      aPropertyValue.Value = _sImageUrl;
      aPropertyValues[0] = aPropertyValue;
      xGraphic = xGraphicProvider.queryGraphic(aPropertyValues);
      return xGraphic;
  }catch (com.sun.star.uno.Exception ex){
      throw new java.lang.RuntimeException("cannot happen...");
  }}

This object variable may be assigned to the property Graphic that is also supported by image controls Image Control, check boxes Check Box, radio buttons Radio Button and command buttons. Note: Issue https://www.openoffice.org/issues/show_bug.cgi?id=76718 has not yet been resolved. The graphic may only be assigned to the control after the peer of the dialog has been created (see Displaying Dialogs).

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages