Difference between revisions of "Documentation/DevGuide/GUI/Command Button"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Initial author Sun Microsystems, Inc.)
 
m
 
(10 intermediate revisions by 5 users not shown)
Line 6: Line 6:
 
|NextPage=Documentation/DevGuide/GUI/Image Control
 
|NextPage=Documentation/DevGuide/GUI/Image Control
 
}}
 
}}
−
{{DISPLAYTITLE:Command Button}}
+
{{Documentation/DevGuideLanguages|Documentation/DevGuide/GUI/{{SUBPAGENAME}}}}
 +
{{DISPLAYTITLE:Command Button}}
 
The command button <idl>com.sun.star.awt.UnoControlButton</idl> allows the user to perform an action by clicking on it. Usually a command button displays a label that is set by the <code>Label</code> property of the control model that supports the service <idl>com.sun.star.awt.UnoControlButtonModel</idl>.
 
The command button <idl>com.sun.star.awt.UnoControlButton</idl> allows the user to perform an action by clicking on it. Usually a command button displays a label that is set by the <code>Label</code> property of the control model that supports the service <idl>com.sun.star.awt.UnoControlButtonModel</idl>.
  
Line 36: Line 37:
 
|<code>boolean</code>. If this property is set to <code>true</code>, 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.  
 
|<code>boolean</code>. If this property is set to <code>true</code>, 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 <code>false</code>, which means the button behaves like a usual push button.
+
The default for this property is <code>false</code>, which means the button behaves like a usual push button.
 +
|-
 +
|<idlm>com.sun.star.awt.UnoControlButtonModel:Repeat</idlm>
 +
|<code>boolean</code>. If this property is set to <code>true</code>, 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 ([[Documentation/DevGuide/GUI/Events#Control element-specific events|When Initiating]]). Mouse events are sent at intervals of <code>RepeatDelay</code> milliseconds. This is similar to the functionality of the arrows on a scroll bar.
 +
|-
 +
|<idlm>com.sun.star.awt.UnoControlButtonModel:RepeatDelay</idlm>
 +
|<code>long</code>. Delay in milliseconds between repeated mouse events (see <code>Repeat</code>, above). Keyboard repeat timing is controlled elsewhere. Only significant if <code>Repeat</code> is set.
 
|}
 
|}
  
  
 +
<syntaxhighlight lang="java">
 
   public XButton insertButton(XActionListener _xActionListener, int _nPosX, int _nPosY, int _nWidth, String _sLabel, short _nPushButtonType){
 
   public XButton insertButton(XActionListener _xActionListener, int _nPosX, int _nPosY, int _nWidth, String _sLabel, short _nPushButtonType){
 
   XButton xButton = null;
 
   XButton xButton = null;
Line 74: Line 82:
 
       return xButton;
 
       return xButton;
 
   }
 
   }
−
 
+
</syntaxhighlight>
 
In the example, an action listener is attached to the command button. An action listener implements the interface <idl>com.sun.star.awt.XActionListener</idl> and its method <code>actionPerformed()</code> is invoked when the user clicks on the button. (see also [[Documentation/DevGuide/GUI/Events|Events]]).
 
In the example, an action listener is attached to the command button. An action listener implements the interface <idl>com.sun.star.awt.XActionListener</idl> and its method <code>actionPerformed()</code> is invoked when the user clicks on the button. (see also [[Documentation/DevGuide/GUI/Events|Events]]).
  
 
The following code snippet shows an example of how to use the action listener.
 
The following code snippet shows an example of how to use the action listener.
−
 
+
<syntaxhighlight lang="java">
 
   public void actionPerformed(ActionEvent rEvent){
 
   public void actionPerformed(ActionEvent rEvent){
 
       try{
 
       try{
Line 100: Line 108:
 
       ex.printStackTrace(System.out);
 
       ex.printStackTrace(System.out);
 
   }}}
 
   }}}
−
 
+
</syntaxhighlight>
 
==== Graphics ====
 
==== 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:
 
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:
−
 
+
<syntaxhighlight lang="java">
 
   // creates a UNO graphic object that can be used to be assigned  
 
   // creates a UNO graphic object that can be used to be assigned  
 
   // to the property "Graphic" of a controlmodel
 
   // to the property "Graphic" of a controlmodel
Line 124: Line 132:
 
       throw new java.lang.RuntimeException("cannot happen...");
 
       throw new java.lang.RuntimeException("cannot happen...");
 
   }}
 
   }}
−
 
+
</syntaxhighlight>
−
This object variable may be assigned to the property Graphic that is also supported by image controls [[Documentation/DevGuide/GUI/Image Control|Image Control]], check boxes [[Documentation/DevGuide/GUI/Check Box|Check Box]], radio buttons [[Documentation/DevGuide/GUI/Radio Button|Radio Button]] and command buttons. Note: Issue http://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 [[Documentation/DevGuide/GUI/Displaying Dialogs|Displaying Dialogs]]).
+
This object variable may be assigned to the property Graphic that is also supported by image controls [[Documentation/DevGuide/GUI/Image Control|Image Control]], check boxes [[Documentation/DevGuide/GUI/Check Box|Check Box]], radio buttons [[Documentation/DevGuide/GUI/Radio Button|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 [[Documentation/DevGuide/GUI/Displaying Dialogs|Displaying Dialogs]]).
  
 
{{PDL1}}
 
{{PDL1}}
−
[[Category: Graphical User Interfaces]]
+
 
 +
[[Category:Documentation/Developer's Guide/Graphical User Interfaces]]

Latest revision as of 18:55, 21 December 2020



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).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/GUI/Command_Button&oldid=246526"
Personal tools
In other languages