OpenOffice开发者指南笔记

一、
1. Text Document modal
   是document模型，其下有一个controller,controller不是用来改变document的，而是用来负责显示效果，比如自动换行，光标，放大缩小。
   其包括5部分：
text
service manager (document internal) 用于控制text内容
draw page 画document
text content suppliers 非text内容提供，bookMark,textField
objects for styling and numbering 显示效果

2. spreadsheet document
   是所有table的模型，
   包括：
Spreadsheets Container
Service Manager (document internal)
DrawPages
Content Properties
Objects for Styling

3. Drawing Documents and Presentation Documents
   图象的模型

4. With OpenOffice.org 2.0, UNO is also programmable with .NET languages using the new Common Language Infrastructure binding

5. UNO provides bridges to send method calls and receive return values between processes and between objects written in different implementation languages. The remote bridges use a special UNO remote protocol (URP) for this purpose which is supported for sockets and pipes.
Uno提供桥接来实现不同语言对其函数的调用，桥接用指定的URP协议来实现，其支持socket和pipe两种方式。

二、first step
1. simple type
1>如果用c++写uno, uno有自己定义的type，对应在guide 44页，基本上所有的基本c++的类型前面都需要加sal_,String对应的是::rtl::OUString,外部传入的char, 需要用 ::rtl::OUString.createFromAscii() 来得到OUString.

2>而如果用java的话，则不需要用其它类型，用java自己的primitive type即可。
  

2. 设置property:
1> Java
xCellProps.setPropertyValue("VertJustify", com.sun.star.table.CellVertJustify.TOP);
2> Basic
oCellProps.VertJustify = com.sun.star.table.CellVertJustify.TOP
3> C++
rCellProps->setPropertyValue(OUString::createFromAscii( "VertJustify" ),
   ::com::sun::star::table::CellVertJustify.TOP);

2. Struct
   Uno中的struct相当于C的struct或java中的类中的public成员。可以用new来直接创建一个struct.如：
   com.sun.star.beans.PropertyValue aProperty = new com.sun.star.beans.PropertyValue();

3. Any
   any 用在uno内部用于广泛表示各种类型。比如: get & set property, name, getByIndex, Iterator遍历时等。
   1> 在java中，any被封装成java.lang.Object类
   2> 对于一个any类，可以有三种方式来对它进行操作
      1》如果它是一个接口，
         在java中，用queryInterface, 如：
   XSpreadsheets xSpreadsheets = xSpreadsheetDocument.getSheets();
   Object sheet = xSpreadsheets.getByName("MySheet");
   XSpreadsheet xSpreadsheet = (XSpreadsheet)UnoRuntime.queryInterface(XSpreadsheet.class, sheet);
Maybe,在C++中：
   Reference<XTextContent> xTextContent(para,UNO_QUERY);

      2》如果它是一个struct，则直接用 cast 转换它。如：
          Java：
   com.sun.star.table.TableBorder bord = (TableBorder)xTableProps.getPropertyValue("TableBorder");
   C++：
   Any any = PropertySet_uno::getProperty("ParaLineSpacing",para);

      3》如果它是一个简单类型，
          在java中，则用com.sun.star.uno.AnyConverter
   long cellColor = AnyConverter.toLong(xCellProps.getPropertyValue("CharColor"));
   在c++中， 有一个特别的操作符可用于any类型 >>
   //C++ has >>= and <<= for Any (the pointed brackets are always left)
   sal_Int32 cellColor;
   Any any;
   any = rCellProps->getPropertyValue(OUString::createFromAscii( "CharColor" ));  
   any >>= cellColor;

3. Interface
   All interface names start with the letter X to distinguish them from other types.
   所有的Interface都是用X开头的。

4. Sequence是不需要用函数来访问的一个元素集。通常在具体语言下用array来实现。
   1>需要说明sequence的类型：
   2> sequence example:
//C++
Sequence < ::com::sun::star::beans::PropertyValue > loadProperties; // empty sequence

//C++
Sequence< ::com::sun::star::beans::PropertyValue > loadProps( 1 );
// the structs are default constructed
loadProps[0].Name = OUString::createFromAscii( "AsTemplate" );
loadProps[0].Handle <<= true;
Reference < XComponent > rComponent = rComponentLoader->loadComponentFromURL(
   OUString::createFromAscii("private:factory/swriter"),
   OUString::createFromAscii("_blank"),
   0,
   loadProps);

5. element访问
   主要有三种方式：
   com.sun.star.container.XNameContainer, [com.sun.star.container.XIndexContainer] and   com.sun.star.container.XEnumeration.
   这三个类都继承自：XElementAccess，而XElementAccess有两个方法：
type getElementType()
boolean hasElements()
   两个Container（com.sun.star.container.XNameContainer, com.sun.star.container.XIndexContainer）也实现了XIndexReplace/XNameReplace 方法，可以替换对应的element

   Container -> impliments Replacer -> impliments Access -> impliments XEnumeration

6. Text, table and drawing 是oo的三个公共部件（Common Mechanism），在document/spreadsheet/presentation中都用到了。
   1. 用com.sun.star.text.XText来管理Text
      XText ->impliments XSimpleText -> impliments XTextRange
      SimpleText有 createTextCursor()方法，可以获得光标来控制选择文本。

   2. Table
      com.sun.star.table.XCellRange 和XCell可以用来选择table 中的cell或range
   XCell xCell = xCellRange.getCellByPosition(0,0);
   XText xCellText = (XText)UnoRuntime.queryInterface(XText.class, xCell);
   xCellText.setString("Quotation");
   xCell = xCellRange.getCellByPosition(1,0);
   xCellText = (XText)UnoRuntime.queryInterface(XText.class, xCell);
   xCellText.setString("Year");
   // cell value
   xCell = xCellRange.getCellByPosition(1,1);
   xCell.setValue(1940);

   3. Drawing:
com.sun.star.drawing.XShape 用来管理drawing的位置和形状。
相关例子，P61 on developper guide

三、professional uno
   1. 在Uno IDL 文件中：
[oneway] flag indicates that an operation will be executed asynchronously. For instance, the
method acquire() in the interface com.sun.star.uno.XInterface is defined to be oneway.
定义成oneway的函数表示是异步执行的。

   2. Service
service由一系列interface组成，其定义与具体语言无关（其实就相当于java的interface）
其只定义了函数，没有包含具体的实现。

   3. 有些interface的实现是optional 的，需要在queryInterface之后检查是否为null.

   4. 这样做的好处，当增加新的feature时，只需要增加新的interface给Service，而无需改service的定义。
      这样就可以保证原有的应用能够正常工作。使Uno具有向下兼容性。

   5. struct封装了一些Uno IDL type，因为没有get/set，所以比用Uno bridge来调用更高效。
      它的存在就是为了避免过度调用uno bridge.

   6. 预定义的变量有两类：
1》常量
2》枚举变量

   7. Module
Modules are namespaces, similar to namespaces in C++.

   8. Exception
      Uno有base exception,是所有的exception的基类：com.sun.star.uno.Exception
      其中继承出来的Runtime exception是任何地方都可能抛出的。

   9. Singleton
      标注为singleton的类只会存在一个。比如ServiceManager
singleton theServiceManager {
   service com::sun::star::lang::ServiceManager
};

   10. 需要特别处理的service:
   you cannot ask the service manager to create an instance of a com.sun.star.text.TextDocument.
   You must load it using the method loadComponentFromUrl() at the desktop's
   com.sun.star.frame.XComponentLoader interface.

11. 删去（legal 问题）

    12. 所有的Bridge调用都是线程安全的，标示成[oneway]的方法是异步执行的方法。

    13. 可以通过改参数，让所有的调用都是同步的。如下：
soffice -accept=socket,host=0,port=2002;urp,Negotiate=0,forceSynchronous=1;
连接的时候：
"uno:socket,host=localhost,port=2002;urp,Negotiate=0,forceSynchronous=1;StarOffice.ServiceManager"
        这样就不会有死锁的问题。
Do not activate this mode unless you experience such problems.
        这句话说明此方式会带来低效率。
   
    14. 关闭连接：
        调用XConponent.dispose()方法

例子：
   用AWT打开文档,连接openoffice
   ProfUNO/InterprocessConn /ConnectionAwareClient.java

    15. Service Manager:
        1》old:
    用com.sun.star.lang.XMultiServiceFactory，它有三个方法：
   createInstance(), createInstanceWithArguments() and getAvailableServiceNames().
2》new:
    用conponent context, （老的方式会带来问题，最好不要再用了 P88 on guide)
   interface XComponentContext : XInterface
   {
    any getValueByName( [in] string Name );
    com::sun::star::lang::XMultiComponentFactory getServiceManager();
   };
    the ComponentContext has a reference to the service manager, but not conversely.
    用 ComponentContex 可以获取 Service Manager.

    16. 关于queryInterface:
1> If queryInterface() on a specific object returned a null reference for a given type, it must
always return a null reference for the same type.
2> If queryInterface() on reference A returns reference B, queryInterface() on B for Type A
must return interface reference A or calls made on the returned reference must be equivalent to
calls made on reference A.
3> If queryInterface() on a reference A returns reference B, queryInterface() on A and B for
XInterface must return the same interface reference (object identity).

    17. Property
        Property 是一系列 key / value 的键对。
通常property用来表示一些无结构的属性，如字体，颜色。而用get & set来获得有结构的属性，如父亲，子对象。
修改property的接口：
com.sun.star.beans.XPropertySet 用name来获得property
com.sun.star.beans.XPropertyAccess 一次性取得所有property
com.sun.star.beans.XMultiPropertySet 一次性取得指定的property set
com.sun.star.beans.XFastPropertySet 用ID来取得property
例如：
   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);
       更多的例子：P92
     
   18. Container and Collection
       Container 是一般是可以从外部调用insert 和 remove来管理的容器。
       Collection 是内部来管理的容器，不能直接修改其包含的element.
       可以用：com.sun.star.container.XIndexAccess 或com.sun.star.container.XNameAccess 或
       com.sun.star.container.XEnumerationAccess 来遍历容器中的元素。
  
   19. Event Model
       com.sun.star.lang.XEventListener 作为基类，当增加Listener时，需要对disposing()方法重载，将所有reference去掉。

   20. Exception
  
   21. XInterface 有 acquire()和 dispose()方法。但不需要手工调用。
The UNO Java binding encapsulates acquire() and release() in the
UnoRuntime.queryInterface() call. The same applies to the Reference<> template in C++. As long as
the interface references are obtained through these mechanisms, acquire() and release() do not have to
be called in your programs.
   22. Identity
Every UNO runtime environment defines how this check should be performed. In Java UNO,
there is a static areSame() function at the com.sun.star.uno.UnoRuntime class. In C++, the
check is performed with the Reference<>::operator == () function that queries both references
for XInterface and compares the resulting XInterface pointers.
试了一下，我们自己写的toolkit uno object不能这样比。

   23. Java language binding
       To control the office from a client program, the client needs a Java 1.3 installation, a free socket
       port, and the following jar files jurt.jar, jut.jar, javaunohelper.jar, ridl.jar, classes.jar and sandbox.jar.

   24. com.sun.star.comp.helper.Bootstrap class 可以获得XMultiComponentFactory, 然后可以再获得以下这些service manager:
   com.sun.star.lang.ServiceManager
   com.sun.star.lang.MultiServiceFactory
   com.sun.star.loader.Java
   com.sun.star.loader.Java2
   com.sun.star.bridge.UnoUrlResolver
   com.sun.star.bridge.BridgeFactory
   com.sun.star.connection.Connector
   com.sun.star.connection.Acceptor
       用com.sun.star.bridge.UnoUrlResolver 来获得对应的用resolve来连接soffice, 需要指定地址，以URP协议。P108
       resolver 解析程序

   25. Uno 与 Java语言的对应关系：
       Any 相当于java.lang.Object,
       Reference 对应于 java的接口，在做函数参数和返回时，全部用Any，然后拿到any之后再通过queryInterface来获得
       具体需要的参数。
       Sequence 对应于数组
       Module 对应于namespace 或 package
       Interface 对应于 java 的同名interface
       Enum 对应于 java 的 final class 中的同名变量

   26. Uno 与 C++ 语言的对应关系
       用 cpp 连接soffice P121
// construct a deskop object and acquire it
Reference< XInterface > rDesktop = xSMgr->createInstance(
   OUString::createFromAscii("com.sun.star.frame.Desktop"));

// query it for the XFrameLoader interface
Reference< XFrameLoader > rLoader( rDesktop , UNO_QUERY );

// check, if the frameloader interface is supported
if( rLoader.is() )
{
   // now do something with the frame loader
   ...
}      

The UNO_QUERY is a dummy parameter that tells the constructor to query the first constructor argument
for the XFrameLoader interface. If the queryInterface() returns successfully, it is assigned
to the rLoader reference. You can check if querying was successful by calling is() on the new
reference.
Methods on interfaces can be invoked using the operator ->

Sequence 对应于：
   template< class t >
   com::sun::star::uno::Sequence< t >

Page 127 here
后面都是讲VB的，跳过。