Difference between revisions of "ZH/Documentation/BASIC Guide/StarDesktop"

From Apache OpenOffice Wiki
Jump to: navigation, search
 
Line 21: Line 21:
 
<tt>StarDesktop</tt> 对象替代了以前作为根对象应用的 StarOffice 5 的 <tt>Application</tt> 对象。但与旧 <tt>Application</tt> 对象不同,它主要负责打开新文档。不再使用旧 <tt>Application</tt> 对象中用于控制 {{OOo}} 屏幕描述的函数(例如,<tt>FullScreen</tt>、<tt>FunctionBarVisible</tt>、<tt>Height</tt>、<tt>Width</tt>、<tt>Top</tt> 和 <tt>Visible</tt>)。
 
<tt>StarDesktop</tt> 对象替代了以前作为根对象应用的 StarOffice 5 的 <tt>Application</tt> 对象。但与旧 <tt>Application</tt> 对象不同,它主要负责打开新文档。不再使用旧 <tt>Application</tt> 对象中用于控制 {{OOo}} 屏幕描述的函数(例如,<tt>FullScreen</tt>、<tt>FunctionBarVisible</tt>、<tt>Height</tt>、<tt>Width</tt>、<tt>Top</tt> 和 <tt>Visible</tt>)。
  
{{Documentation/Note|在 Word 和 Excel 中,分别通过 <tt>Application.ActiveDocument</tt> 和 <tt>Application.ActiveWorkbook</tt> 来访问活动文档;而在 {{OOo}} 中,此任务是由 <tt>StarDesktop</tt> 负责完成的。在 {{OOo}} 中,活动文档对象是通过 <tt>StarDesktop.CurrentComponent</tt> 属性或 <tt>ThisComponent</tt> 进行访问的。}}
+
{{Note|在 Word 和 Excel 中,分别通过 <tt>Application.ActiveDocument</tt> 和 <tt>Application.ActiveWorkbook</tt> 来访问活动文档;而在 {{OOo}} 中,此任务是由 <tt>StarDesktop</tt> 负责完成的。在 {{OOo}} 中,活动文档对象是通过 <tt>StarDesktop.CurrentComponent</tt> 属性或 <tt>ThisComponent</tt> 进行访问的。}}
  
 
== ThisComponent ==
 
== ThisComponent ==
Line 85: Line 85:
 
在 {{OOo}} Basic 中,可以通过这种方式打开任意数目的文档,然后使用返回的文档对象对其进行编辑。
 
在 {{OOo}} Basic 中,可以通过这种方式打开任意数目的文档,然后使用返回的文档对象对其进行编辑。
  
{{Documentation/Note|<tt>StarDesktop.loadComponentFromURL</tt> 取代了旧 {{OOo}} API 中的 <tt>Documents.Add</tt> 和 <tt>Documents.Open</tt> 方法。}}
+
{{Note|<tt>StarDesktop.loadComponentFromURL</tt> 取代了旧 {{OOo}} API 中的 <tt>Documents.Add</tt> 和 <tt>Documents.Open</tt> 方法。}}
  
 
=== 替换文档窗口的内容 ===
 
=== 替换文档窗口的内容 ===

Latest revision as of 14:38, 6 July 2018

doc OOo
Book.png

在使用文档时,以下两项服务最为常用:

  • com.sun.star.frame.Desktop 服务,与 Apache OpenOffice 的核心服务类似。它为 Apache OpenOffice 框架对象提供了一些功能,可根据这些功能对所有文档窗口进行分类。还可以使用该服务创建、打开和导入文档。
  • 单个文档对象的基本功能是由 com.sun.star.document.OfficeDocument 服务提供的。该服务提供了用于保存、导出和打印文档的方法。

com.sun.star.frame.Desktop 服务是在启动 Apache OpenOffice 时自动创建的。在 Apache OpenOffice Basic 中,可以使用全局名称 StarDesktop 对该服务进行寻址。

com.sun.star.frame.XComponentLoader 是最重要的 StarDesktop 接口。它主要包含 loadComponentFromURL 方法,此方法负责创建、导入和打开文档。

StarDesktop 对象的名称可追溯到 StarOffice 5,其中将所有文档窗口都嵌入到一个名为 StarDesktop 的常用应用程序中。在当前的 Apache OpenOffice 版本中,不再使用可视化 StarDesktop。不过,Apache OpenOffice 的框架对象保留了名称 StarDesktop,因为该名称清楚地表明它是整个应用程序的基本对象。

StarDesktop 对象替代了以前作为根对象应用的 StarOffice 5 的 Application 对象。但与旧 Application 对象不同,它主要负责打开新文档。不再使用旧 Application 对象中用于控制 Apache OpenOffice 屏幕描述的函数(例如,FullScreenFunctionBarVisibleHeightWidthTopVisible)。

Documentation note.png 在 Word 和 Excel 中,分别通过 Application.ActiveDocumentApplication.ActiveWorkbook 来访问活动文档;而在 Apache OpenOffice 中,此任务是由 StarDesktop 负责完成的。在 Apache OpenOffice 中,活动文档对象是通过 StarDesktop.CurrentComponent 属性或 ThisComponent 进行访问的。

ThisComponent

ThisComponent 通常返回与 StarDesktop.CurrentComponent 相同的对象,但其具有一个重要的优势。如果从 Basic IDE 中运行程序(调试或浏览),则 StarDesktop 返回 Basic IDE 本身。这可能并不是您想要的结果。ThisComponent 返回之前最后一个活动文档。

有关 Apache OpenOffice 中的文档的基本信息

在使用 Apache OpenOffice 文档时,了解 Apache OpenOffice 文档管理方面的一些基本问题是非常有用的。这些问题包括 Apache OpenOffice 文档的文件名构成方式以及文件的保存格式。

用 URL 表示的文件名

由于 Apache OpenOffice 是一种与平台无关的应用程序,因此,它使用 Internet Standard RFC 1738 的文件名部分中定义的 URL 表示法(不依赖于任何操作系统)。使用此系统的标准文件名以前缀 file:/// 开头,后跟本地路径。如果文件名包含子目录,则使用单个正斜杠(而不是 Windows 中通常使用的反斜杠)分隔这些子目录。以下路径引用 C: 驱动器上的 doc 目录中的 test.odt 文件。

file:///C:/doc/test.odt

为了将本地文件名转换为 URL,Apache OpenOffice 提供了 ConvertToUrl 函数。为了将 URL 转换为本地文件名,Apache OpenOffice 提供了 ConvertFromUrl 函数:

MsgBox ConvertToUrl("C:\doc\test.odt") 
  ' supplies file:///C:/doc/test.odt
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")    
  '  supplies (under Windows) c:\doc\test.odt

本示例将本地文件名转换为 URL,并在消息框中显示该 URL。然后,它又将 URL 转换为本地文件名,并显示该名称。

本示例所依据的 Internet Standard RFC 1738 允许使用 0-9a-zA-Z 字符。所有其他字符将作为转义编码插入到 URL 中。为此,需要将这些字符转换为 ISO 8859-1 (ISO-Latin) 字符集中的相应十六进制值,并在前面加上百分号。例如,本地文件名中的空格因而变为 URL 中的 %20

XML 文件格式

Apache OpenOffice 使用基于 XML 的文件格式。通过使用 XML,您可以在其他程序中打开和编辑文件。

文件压缩

由于 XML 基于标准文本文件,因此,所生成的文件通常都很大。因此,Apache OpenOffice 将压缩这些文件,并将其保存为 ZIP 文件。通过使用 storeAsURL 方法选项,用户可以直接保存原来的 XML 文件。请参见 storeAsURL 方法选项

创建、打开和导入文档

文档是使用以下方法打开、导入和创建的:

StarDesktop.loadComponentFromURL(URL, Frame, SearchFlags, FileProperties)

loadComponentFromURL 的第一个参数指定了关联文件的 URL。

作为第二个参数,loadComponentFromURL 要求提供 Apache OpenOffice 为进行管理而在内部创建的窗口框架对象的名称。预定义的 _blank 名称通常是在此处指定的,这可确保 Apache OpenOffice 创建一个新窗口。此外,也可以指定 _hidden,这可确保加载但不显示相应的文档。

通过使用这些参数,用户可以打开 Apache OpenOffice 文档,因为可以将占位符(虚拟值)赋值给最后两个参数:

Dim Doc As Object
Dim Url As String
Dim Dummy() 'It is an (empty) array of PropertyValues
 
Url = "file:///C:/test.odt"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy)

以上调用会在新窗口中打开并显示 text.odt 文件。

在 Apache OpenOffice Basic 中,可以通过这种方式打开任意数目的文档,然后使用返回的文档对象对其进行编辑。

Documentation note.png StarDesktop.loadComponentFromURL 取代了旧 Apache OpenOffice API 中的 Documents.AddDocuments.Open 方法。

替换文档窗口的内容

Frame 参数中名为 _blank_hidden 的值可确保 Apache OpenOffice 为来自 loadComponentFromURL 的每个调用创建一个新窗口。在某些情况下,替换现有窗口的内容非常有用。在这种情况下,窗口的框架对象应包含一个明确的名称。请注意,该名称不能以下划线开头。而且,还必须设置 SearchFlags 参数以创建相应的框架(如果此框架尚未存在)。SearchFlags 的相应常量为:

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL

以下示例说明了如何借助框架参数和 SearchFlags 替换打开的窗口的内容:

Dim Doc As Object
Dim Dummy() 
Dim Url As String
Dim SearchFlags As Long
 
SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL
Url = "file:///C:/test.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", SearchFlags, Dummy)
MsgBox "Press OK to display the second document."
 
Url = "file:///C:/test2.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

本示例首先在框架名称为 MyFrame 的新窗口中打开 test.odt 文件。在消息框中进行确认后,本示例使用 test2.odt 文件替换了窗口的内容。

loadComponentFromURL 方法选项

loadComponentFromURL 函数的第四个参数为 PropertyValue 数据字段,它为 Apache OpenOffice 提供了各种打开和创建文档的选项。此数据字段必须为每个选项提供一个 PropertyValue 结构,其中将选项名称保存为字符串和关联的值。

loadComponentFromURL 支持以下选项:

AsTemplate (Boolean)
如果为 true,则从给定 URL 中加载一个未命名的新文档。如果为 false,则加载模板文件以进行编辑。
CharacterSet (String)
定义文档所基于的字符集。
FilterName (String)
loadComponentFromURL 函数指定特殊过滤器。可用过滤器名称是在 \share\config\registry\instance\org\openoffice\office\TypeDetection.xml 文件中定义的。
FilterOptions (String)
为过滤器定义其他选项。
JumpMark (String)
在打开文档后,将跳转到 JumpMark 中定义的位置。
Password (String)
为受保护的文件传送密码。
ReadOnly (Boolean)
加载只读文档。

以下示例说明了如何使用 FilterName 选项打开 Apache OpenOffice Calc 中以逗点分隔的文本文件。

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
 
Url = "file:///C:/csv.doc"
FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="scalc: Text - txt - csv ({{OOo}} Calc)"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())

FileProperties 数据字段仅包含一个值,因为它只记录一个选项。Filtername 属性定义了 Apache OpenOffice 是否使用 Apache OpenOffice Calc 文本过滤器打开文件。

创建新文档

如果 URL 中指定的文档是一个模板,Apache OpenOffice 将自动创建一个新文档。

或者,如果只需要一个未经任何改编的空文档,则可以指定一个 private:factory URL:


Dim Dummy() 
Dim Url As String
Dim Doc As Object
 
Url = "private:factory/swriter"
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

该调用创建了一个空 Apache OpenOffice Writer 文档。

文档对象

上一节中介绍的 loadComponentFromURL 函数返回一个文档对象。它支持 com.sun.star.document.OfficeDocument 服务,而该服务又提供了两个主要接口:

保存和导出文档

Apache OpenOffice 文档是直接通过文档对象保存的。为此,com.sun.star.frame.XStorable 接口提供了 store 方法:

Doc.store()

只要已经为文档指定了内存空间,此调用就会生效。但新文档并非如此。对于新文档,需要使用 storeAsURL 方法。此方法也是在 com.sun.star.frame.XStorable 中定义的,它可用于定义文档的位置:

Dim URL As String
Dim Dummy()
 
Url = "file:///C:/test3.odt"
Doc.storeAsURL(URL, Dummy())

除了上述方法以外,com.sun.star.frame.XStorable 还提供了一些帮助方法,这些方法在保存文档时非常有用。这些方法是:

hasLocation()
指定是否已经为文档指定了 URL。
isReadonly()
指定文档是否具有只读保护。
isModified()
指定在上次保存后是否修改了文档。

可以通过这些选项扩展用于保存文档的代码,以便仅当确实修改了对象时才保存文档,并且仅当确实需要时才查询文件名:

If (Doc.isModified) Then
  If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
    Doc.store()
  Else
    Doc.storeAsURL(URL, Dummy())
  End If
End If

本示例首先检查在上次保存后是否修改了相关文档。只有进行了修改,它才会继续执行保存过程。如果已经为文档指定了 URL 并且文档不是只读文档,则在现有 URL 下保存该文档。如果文档没有 URL 或以只读状态打开文档,则在新 URL 下保存文档。

storeAsURL 方法选项

与使用 loadComponentFromURL 方法时一样,也可以使用 storeAsURL 方法以 PropertyValue 数据字段形式指定某些选项。它们可以确定 Apache OpenOffice 在保存文档时使用的过程。storeAsURL 提供了以下选项:

CharacterSet (String)
定义文档所基于的字符集。
FilterName (String)
loadComponentFromURL 函数指定特殊过滤器。可用过滤器名称是在 \share\config\registry\instance\org\openoffice\office\TypeDetection.xml 文件中定义的。
FilterOptions (String)
为过滤器定义其他选项。
Overwrite (Boolean)
无需查询即可覆盖已存在的文件。
Password (String)
为受保护的文件传送密码。
Unpacked (Boolean)
在子目录中保存文档(未压缩)。

以下示例说明了如何将 Overwrite 选项与 storeAsURL 一起使用:

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
' ... Initialize Doc 
 
Url = "file:///c:/test3.odt"
FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True
Doc.storeAsURL(sUrl, mFileProperties())

如果已存在同名文件,本示例将使用指定的文件名保存 Doc

打印文档

与文档保存类似,文档打印也是直接通过文档对象进行的。为此,com.sun.star.view.Xprintable 接口提供了 Print 方法。最简单的 print 调用形式为:

Dim Dummy()
 
Doc.print(Dummy())

与使用 loadComponentFromURL 方法时一样,Dummy 参数是一个 PropertyValue 数据字段,Apache OpenOffice 可通过此字段指定几个打印选项。

print 方法的选项

print 方法要求将 PropertyValue 数据字段作为参数,此字段反映了 Apache OpenOffice 打印对话框的设置:

CopyCount (Integer)
指定要打印的份数。
FileName (String)
打印指定文件中的文档。
Collate (Boolean)
建议打印机逐份打印。
Sort (Boolean)
打印多份文档时对页面进行排序 (CopyCount > 1)。
Pages (String)
包含要打印的页面列表(使用打印对话框中指定的语法)。

以下示例说明了如何使用 Pages 选项打印文档的几个页面:

Dim Doc As Object
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue
 
PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
Doc.print(PrintProperties())

打印机选择和设置

com.sun.star.view.XPrintable 接口提供了 Printer 属性,该属性可选择打印机。该属性接收包含以下设置的 PropertyValue 数据字段:

Name (String)
指定打印机的名称。
PaperOrientation (Enum)
指定纸张方向(com.sun.star.view.PaperOrientation.PORTRAIT 值表示纵向格式,com.sun.star.view.PaperOrientation.LANDSCAPE 值表示横向格式)。
PaperFormat (Enum)
指定纸张格式(例如,com.sun.star.view.PaperFormat.A4 表示 DIN A4,com.sun.star.view.PaperFormat.Letter 表示 US Letter)。
PaperSize (Size)
指定纸张大小,以百分之一毫米为单位。

以下示例说明了如何借助 Printer 属性更改打印机和设置纸张大小。

Dim Doc As Object
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue
Dim PaperSize As New com.sun.star.awt.Size
 
PaperSize.Width = 20000   ' corresponds to 20 cm
PaperSize.Height = 20000   ' corresponds to 20 cm
PrinterProperties (0).Name="Name"
PrinterProperties (0).Value="My HP Laserjet"
PrinterProperties (1).Name="PaperSize"
PrinterProperties (1).Value=PaperSize
Doc.Printer = PrinterProperties()

本示例定义了一个名为 PaperSize 的对象,其类型为 com.sun.star.awt.Size。在指定纸张大小时需要使用该对象。另外,本示例还为两个 PropertyValue 条目创建了一个名为 PrinterProperties 的数据字段。然后,使用要设置的值初始化该数据字段,并将其赋值给 Printer 属性。从 UNO 的角度看,Printer 并不是一个真实属性,而是一个模拟属性。

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