Difference between revisions of "Zh/Documentation/DevGuide/ProUNO/Properties"
Line 223: | Line 223: | ||
− | {{ | + | {{Tip|如果通过其他进程或远程使用一个组件,请设法遵守规则来使用 |
<idl>com.sun.star.beans.XPropertyAccess</idl> 和 <idl>com.sun.star.beans.XMultiPropertySet</idl>,而不对每个单个属性进行单独调用。}} | <idl>com.sun.star.beans.XPropertyAccess</idl> 和 <idl>com.sun.star.beans.XMultiPropertySet</idl>,而不对每个单个属性进行单独调用。}} | ||
Latest revision as of 20:10, 14 July 2018
属性是属于某项服务的名称/值对,用于确定服务实例中某个对象的属性。属性通常用于非结构属性,如对象的字体、大小或颜色,而 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
以下示例同时处理多个属性:
// 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 注册此类更改的侦听器。
如果通过其他进程或远程使用一个组件,请设法遵守规则来使用
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). |