属性

From Apache OpenOffice Wiki
Jump to: navigation, search



属性是属于某项服务的名称/值对，用于确定服务实例中某个对象的属性。属性通常用于非结构属性，如对象的字体、大小或颜色，而 get 和 set 方法则用于像父对象或子对象这样的结构属性。


几乎在所有情况下，com.sun.star.beans.XPropertySet 都用于按名称访问的属性。其他接口，例如 com.sun.star.beans.XPropertyAccess 或 com.sun.star.beans.XMultiPropertySet，前者用于同时设置和获取所有属性，后者用于同时访问多个指定属性。这对远程连接非常有用。另外，还有用于按数字 ID 访问属性的接口，如 com.sun.star.beans.XFastPropertySet。


下面的示例说明如何使用一个给定文本文档光标的 XPropertySet 接口来查询和更改该光标的属性： 

  // get an XPropertySet, here the one of a text cursor
  XPropertySet xCursorProps = (XPropertySet) 
          UnoRuntime.queryInterface(XPropertySet.class, mxDocCursor);
 
  // get the character weight property 
  Object aCharWeight = xCursorProps.getPropertyValue("CharWeight");
  float fCharWeight = AnyConverter.toFloat(aCharWeight);
  System.out.println("before: CharWeight=" + fCharWeight);
 
  // set the character weight property to BOLD
  xCursorProps.setPropertyValue("CharWeight", new Float(com.sun.star.awt.FontWeight.BOLD));
 
  // get the character weight property again
  aCharWeight = xCursorProps.getPropertyValue("CharWeight");
  fCharWeight = AnyConverter.toFloat(aCharWeight);
  System.out.println("after: CharWeight=" + fCharWeight);


此代码的输出可能会是： 

 before: CharWeight=100.0
 after: CharWeight=150.0
Documentation caution.png 必须对属性名称序列进行排序。


以下示例同时处理多个属性： 

  // get an XMultiPropertySet, here the one of the first paragraph
  XEnumerationAccess xEnumAcc = (XEnumerationAccess) UnoRuntime.queryInterface(
      XEnumerationAccess.class, mxDocText);
  XEnumeration xEnum = xEnumAcc.createEnumeration();
  Object aPara = xEnum.nextElement();
  XMultiPropertySet xParaProps = (XMultiPropertySet) UnoRuntime.queryInterface(
      XMultiPropertySet.class, aPara);
 
  // get three property values with a single UNO call
  String[] aNames = new String[3];
  aNames[0] = "CharColor";
  aNames[1] = "CharFontName";
  aNames[2] = "CharWeight";
  Object[] aValues = xParaProps.getPropertyValues(aNames);
 
  // print the three values
  System.out.println("CharColor=" + AnyConverter.toLong(aValues[0]));
  System.out.println("CharFontName=" + AnyConverter.toString(aValues[1]));
  System.out.println("CharWeight=" + AnyConverter.toFloat(aValues[2]));


可以通过给属性指定标志来确定属性的特定行为，如 read-only、bound、constrained 或 void。com.sun.star.beans.PropertyAttribute 中指定了可能的标志。不能设定 read-only 属性。bound 属性将值的更改广播到注册的侦听器，而 constrained 属性则禁止对这些侦听器的更改。


属性可能使用一种状态来指定值的来源。请参阅 com.sun.star.beans.XPropertySet。该值确定值是来自对象、样式表，还是根本无法确定值的来源。例如，选择时存在一个具有多个值的多项选择。


以下示例说明如何获得属性值的状态信息： 

  // get an XPropertySet, here the one of a text cursor
  XPropertySet xCursorProps = (XPropertySet) UnoRuntime.queryInterface(
      XPropertySet.class, mxDocCursor);
 
  // insert "first" in NORMAL character weight
  mxDocText.insertString(mxDocCursor, "first ", true);
  xCursorProps.setPropertyValue("CharWeight", new Float(com.sun.star.awt.FontWeight.NORMAL));
 
  // append "second" in BODL characer weight
  mxDocCursor.collapseToEnd();
  mxDocText.insertString(mxDocCursor, "second", true);
  xCursorProps.setPropertyValue("CharWeight", new Float(com.sun.star.awt.FontWeight.BOLD));
 
  // try to get the character weight property of BOTH words
  mxDocCursor.gotoStart(true);
  try {
      Object aCharWeight = xCursorProps.getPropertyValue("CharWeight");
      float fCharWeight = AnyConverter.toFloat(aCharWeight );
      System.out.println("CharWeight=" + fCharWeight);
  } catch (NullPointerException e) { 
      System.out.println("CharWeight property is NULL");
  }
 
  // query the XPropertState interface of the cursor properties
  XPropertyState xCursorPropsState = (XPropertyState) UnoRuntime.queryInterface(
      XPropertyState.class, xCursorProps);
 
  // get the status of the character weight property
  PropertyState eCharWeightState = xCursorPropsState.getPropertyState("CharWeight");
  System.out.print("CharWeight property state has ");
  if (eCharWeightState == PropertyState.AMBIGUOUS_VALUE)
      System.out.println("an ambiguous value");
  else
      System.out.println("a clear value");

在字符线条粗细的属性状态中查询下面列出的字符串： 

 first second

而且，输出为： 

 CharWeight property is NULL
 CharWeight property state has an ambiguous value


com.sun.star.beans.XPropertySetInfo 给出了某个具体对象的属性说明。多个对象可以共享其说明中的同一属性信息。这为脚本语言中使用自省缓存带来很大方便，因为在脚本语言中，可直接访问属性，而无需直接调用前面提到的接口中的方法。


此示例说明如何找出对象提供的哪个属性使用 com.sun.star.beans.XPropertySetInfo： 

  try {
      // get an XPropertySet, here the one of a text cursor
      XPropertySet xCursorProps = (XPropertySet)UnoRuntime.queryInterface(
          XPropertySet.class, mxDocCursor);
 
      // get the property info interface of this XPropertySet
      XPropertySetInfo xCursorPropsInfo = xCursorProps.getPropertySetInfo();
 
      // get all properties (NOT the values) from XPropertySetInfo
      Property[] aProps = xCursorPropsInfo.getProperties();
      int i;
      for (i = 0; i < aProps.length; ++i) {
          // number of property within this info object
          System.out.print("Property #" + i);
 
          // name of property
          System.out.print(": Name<" + aProps[i].Name);
 
          // handle of property (only for XFastPropertySet)
          System.out.print("> Handle<" + aProps[i].Handle);
 
          // type of property
          System.out.print("> " + aProps[i].Type.toString());
 
          // attributes (flags)
          System.out.print(" Attributes<");
          short nAttribs = aProps[i].Attributes;
          if ((nAttribs & PropertyAttribute.MAYBEVOID) != 0)
              System.out.print("MAYBEVOID|");
          if ((nAttribs & PropertyAttribute.BOUND) != 0)
              System.out.print("BOUND|");
          if ((nAttribs & PropertyAttribute.CONSTRAINED) != 0)
              System.out.print("CONSTRAINED|");
          if ((nAttribs & PropertyAttribute.READONLY) != 0)
              System.out.print("READONLY|");
          if ((nAttribs & PropertyAttribute.TRANSIENT) != 0)
              System.out.print("TRANSIENT|");
          if ((nAttribs & PropertyAttribute.MAYBEAMBIGUOUS ) != 0)
              System.out.print("MAYBEAMBIGUOUS|");
          if ((nAttribs & PropertyAttribute.MAYBEDEFAULT) != 0)
              System.out.print("MAYBEDEFAULT|");
          if ((nAttribs & PropertyAttribute.REMOVEABLE) != 0)
              System.out.print("REMOVEABLE|");
          System.out.println("0>");
      }
  } catch (Exception e) {
      // If anything goes wrong, give the user a stack trace
      e.printStackTrace(System.out);
  }

以下是前面代码的示例输出。此输出显示文字光标属性的名称以及属性的句柄、类型和属性。句柄不是唯一的，由于特定对象不实现 com.sun.star.beans.XFastPropertySet，因此，此处不需要相应的句柄。 

 Using default connect string: socket,host=localhost,port=8100
 Opening an empty Writer document
 Property #0: Name<BorderDistance> Handle<93> Type<long> Attributes<MAYBEVOID|0>
 Property #1: Name<BottomBorder> Handle<93> Type<com.sun.star.table.BorderLine> Attributes<MAYBEVOID|0>
 Property #2: Name<BottomBorderDistance> Handle<93> Type<long> Attributes<MAYBEVOID|0>
 Property #3: Name<BreakType> Handle<81> Type<com.sun.star.style.BreakType> Attributes<MAYBEVOID|0>
 
 ...
 
 Property #133: Name<TopBorderDistance> Handle<93> Type<long> Attributes<MAYBEVOID|0>
 Property #134: Name<UnvisitedCharStyleName> Handle<38> =Type<string> Attributes<MAYBEVOID|0>
 Property #135: Name<VisitedCharStyleName> Handle<38> Type<string> Attributes<MAYBEVOID|0>


某些情况下，属性用于指定 com.sun.star.beans.PropertyValue 序列中的选项。有关序列中的示例属性，请参阅 com.sun.star.view.PrintOptions 或 com.sun.star.document.MediaDescriptor。对这些属性的访问不是通过前面提到的方法，而是通过访问语言绑定中指定的序列。


下面的示例说明如何处理属性值序列： 

  // create a sequence of PropertyValue
  PropertyValue[] aArgs = new PropertyValue[2];
 
  // set name/value pairs (other fields are irrelevant here)
  aArgs[0] = new PropertyValue();
  aArgs[0].Name = "FilterName";
  aArgs[0].Value = "HTML (StarWriter)";
  aArgs[1] = new PropertyValue();
  aArgs[1].Name = "Overwrite";
  aArgs[1].Value = Boolean.TRUE;
 
  // use this sequence of PropertyValue as an argument
  // where a service with properties but witouth any interfaces is specified
  com.sun.star.frame.XStorable xStorable = (com.sun.star.frame.XStorable) UnoRuntime.queryInterface(
      com.sun.star.frame.XStorable.class, mxDoc);
  xStorable.storeAsURL("file:///tmp/devmanual-test.html", aArgs);

通常，对象支持的属性及其类型和标志在对象的生存期内是不变的。可能会有例外。如果可以从外部添加和删除属性，则必须使用接口 com.sun.star.beans.XPropertyContainer。在这种情况下，固定的 com.sun.star.beans.XPropertySetInfo 在该对象的生存期内更改其提供的信息。可以通过 com.sun.star.beans.XPropertyChangeListener 注册此类更改的侦听器。


Tip.png 如果通过其他进程或远程使用一个组件，请设法遵守规则来使用

com.sun.star.beans.XPropertyAccess 和 com.sun.star.beans.XMultiPropertySet，而不对每个单个属性进行单独调用。


下图显示的是与属性相关的接口之间的关系。

与属性有关接口之间的关系


从 OpenOffice.org 2.0 开始，在可表达性上，接口属性类似于上述属性：

  • [property] T P（类型为 T，名称为 P）对应 [attribute] T P。
  • A [property, readonly] T P corresponds to an [attribute, readonly] T P.
  • [property, readonly] T P 对应 [attribute, readonly] T P。
  • [property, bound] T P 对应 [attribute, bound] T P。
  • [property, maybeambiguous] T P 对应 [attribute] com.sun.star.beans.Ambiguous<T> P。
  • [property, maybedefault] T P 对应 [attribute] com.sun.star.beans.Defaulted<T> P。
  • [property, maybevoid] T P 对应 [attribute] com.sun.star.beans.Optional<T> P。
  • [property, optional] T P 对应 [attribute] T P { get raises (com.sun.star.beans.UnknownPropertyException); set raises (com.sun.star.beans.UnknownPropertyException); }。
  • [property, constrained] T P 对应 [attribute] T P { set raises (com.sun.star.beans.PropertyVetoException); }。


与属性相比，接口属性具有以下优点：

  • 对象支持的属性直接从该对象支持的接口类型的说明得出。
  • 访问接口属性为类型安全，而访问属性则使用一般的 any。此优点主要表现在静态键入的语言（如 Java 和 C++）中，与访问一般属性相比，访问接口属性通常仅需要编写更少的代码。


主要缺点是对象支持的接口属性设置是静态的，这样利用 XpropertySet 等动态属性的方案就不能很好地映射到接口属性。在一个对象支持所有的接口属性也可通过 XPropertySet 等访问的情况下，这可能非常有用。Java 和 C++ 语言绑定提供试验（但尚未发布）的支持来完成这些。有关详细信息，请访问 www.openoffice.org。


Content on this page is licensed under the Public Documentation License (PDL).
Retrieved from "https://wiki.openoffice.org/w/index.php?title=Zh/Documentation/DevGuide/ProUNO/Properties&oldid=242557"
Personal tools
In other languages