Difference between revisions of "ZH/Documentation/BASIC Guide/More Than Text"

Latest revision as of 14:40, 6 July 2018

Apache OpenOffice BASIC 编程指南

{{{parttitle}}}

[[{{{PrevPart}}}|< Previous Section]]

[[{{{NextPart}}}|Next Section >]]

• Apache OpenOffice BASIC 语言

• Apache OpenOffice Basic 程序概述
• 使用变量
• 字符串变量
• 数字变量
• 布尔变量
• 日期和时间变量
• 数组
• 变量的作用域和生命周期
• 常量
• 运算符
• 分支
• 循环
• 过程和函数
• 错误处理
• 其他指令

• Apache OpenOffice Basic 的运行时库

• 转换函数（Apache OpenOffice 运行时库）
• 字符串（Apache OpenOffice BASIC 运行时库）
• 日期和时间（Apache OpenOffice 运行时库）
• 文件和目录（Apache OpenOffice 运行时库）
• 消息和输入框（Apache OpenOffice 运行时库）
• 其他函数（Apache OpenOffice 运行时库）

• Apache OpenOffice API 简介

• 通用网络对象 (Universal Network Objects, UNO)
• 属性和方法 (API)
• 模块、服务和接口
• 使用 UNO 时所需的工具
• 几个主要接口的概述

• 使用 Apache OpenOffice 文档

• StarDesktop
• 模板

• 文本文档

• 文本文档结构
• 编辑文本文档
• 文本文档：文本以外的内容

• 电子表格

• 电子表格文档结构
  • 行和列
  • 单元格和区域
  • 设置电子表格文档格式
• 编辑电子表格文档

• 绘图和演示文稿

• 绘图结构
• 编辑绘图对象
• 演示文稿

• 图表

• 在电子表格中使用图表
• 图表结构
• 图表类型

• 数据库

• SQL: 查询语言
• 数据库访问类型
• 数据源
• 数据库访问

• 对话框

• 使用对话框
• 属性
• 事件
• 对话框控制元素详述

• 表单

• 使用表单
• 控制元素表单详述
• 数据库表单

< 上一页

下一页 >

到目前为止，本章仅介绍了文本段落及其各个组成部分。但文本文档可能还包含其他对象。这些对象包括表格、绘图、文本字段和目录。可以将所有这些对象锁定到文本中的任意位置。

由于有了这些常用功能，Apache OpenOffice 中的所有这些对象均支持一个称为 com.sun.star.text.TextContent 的常用基本服务。该服务提供了以下属性：

AnchorType (Enum)

确定 TextContent 对象的锁定类型（与 com.sun.star.text.TextContentAnchorType 枚举一致的默认值）。

AnchorTypes (sequence of Enum)

枚举所有支持特殊 TextContent 对象的 AnchorTypes。

TextWrap (Enum)

确定 TextContent 对象周围文本的环绕类型（与 com.sun.star.text.WrapTextMode 枚举一致的默认值）。

TextContent 对象还共享一些方法，尤其是用于创建、插入和删除对象的方法。

• 可以使用文档对象的 createInstance 方法创建新的 TextContent 对象。
• 可以使用文本对象的 insertTextContent 方法插入对象。
• 可以使用 removeTextContent 方法删除 TextContent 对象。

以下几节介绍了一些使用这些方法的示例。

表格

以下示例将借助上文中介绍的 createInstance 方法来创建一个表格。

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)
 
Doc.Text.insertTextContent(Cursor, Table, False)

Python 样例：

def inset_img(): 
   # abstract the objects in varialbes, doc, text and img, note we used the XSCRIPTCONTEXT
   doc = XSCRIPTCONTEXT.getDocument() 
   text = doc.getText() 
   cursor = text.createTextCursor()  # not sure
   Table = doc.createInstance(u'com.sun.star.text.TextTable') 
 
   # Verify code
   Table.initialize(5, 4)
 
   #inser the image in the text area location    
   text.insertTextContent(text.getEnd(), Table, False)

在创建表格后，使用 initialize 调用将其设置为所需的行数和列数，并使用 insertTextContent 将其插入到文本文档中。

正如示例所示，insertTextContent 方法不仅要求插入 Content 对象，而且还要求使用其他两个参数：

• Cursor 对象，用于确定插入位置
• 布尔变量，用于指定 Content 对象是替换光标当前选择的内容（True 值），还是在文本中当前选择的内容前面插入该对象 (False)

在文本文档中创建和插入表格时，Apache OpenOffice Basic 使用的对象与 VBA 中的对象类似：文档对象和 Apache OpenOffice Basic 中的 TextCursor 对象，或者正如 VBA 中所使用的 Range 对象。在 VBA 中，Document.Tables.Add 方法负责完成创建和设置表格的任务；而在 Apache OpenOffice Basic 中，将使用 createInstance 创建表格，对表格进行初始化并通过 insertTextContent 将其插入到文档中（如上一示例所示）。

可以使用简单循环来确定在文本文档中插入的表格。可以使用文本文档对象的 getTextTables() 方法来实现此目的：

Dim Doc As Object
Dim TextTables As Object
Dim Table As Object
Dim I As Integer
Doc = StarDesktop.CurrentComponent
TextTables = Doc.getTextTables()
For I = 0 to TextTables.count - 1
 
   Table = TextTables(I)
   ' Editing table
 
Next I

在 Apache OpenOffice 中，文本表格是通过文档对象的 TextTables 列表提供的。上一示例说明了如何创建文本表格。下一节介绍了用于访问文本表格的选项。

编辑表格

表格由各个行组成。这些行又包含不同的单元格。严格地说，Apache OpenOffice 中并没有表格列。这些列是通过将行依次上下排列而隐式生成的。不过，为了简化对表格的访问，Apache OpenOffice 提供了一些可使用列进行操作的方法。如果在表格中未合并单元格，这些方法是非常有用的。

让我们先看一下表格本身的属性。这些属性是在 com.sun.star.text.TextTable 服务中定义的。下面列出了表格对象最重要的属性：

BackColor (Long)

表格的背景颜色。

BottomMargin (Long)

下边距，以百分之一毫米为单位。

LeftMargin (Long)

左边距，以百分之一毫米为单位。

RightMargin (Long)

右边距，以百分之一毫米为单位。

TopMargin (Long)

上边距，以百分之一毫米为单位

RepeatHeadline (Boolean)

在每个页面上重复表格标题。

Width (Long)

表格的绝对宽度，以百分之一毫米为单位。

行

表格由一个包含行的列表组成。以下示例说明了如何检索表格的行并设置其格式。

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
Dim Rows As Object
Dim Row As Object
Dim I As Integer
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)
 
Doc.Text.insertTextContent(Cursor, Table, False)
Rows = Table.getRows
For I = 0 To Rows.getCount() - 1
   Row = Rows.getByIndex(I)
   Row.BackColor = &HFF00FF
Next

本示例首先使用 Table.getRows 调用创建了一个包含所有行的列表。可通过 getCount 和 getByIndex 方法进一步处理该列表，这些方法属于 com.sun.star.table.XtableRows 接口。getByIndex 方法返回一个行对象，该对象支持 com.sun.star.text.TextTableRow 服务。

以下是 com.sun.star.table.XtableRows 接口的主要方法：

getByIndex(Integer)

返回指定索引的行对象。

getCount()

返回行对象的数目。

insertByIndex(Index, Count)

从表格中的 Index 位置开始插入 Count 个行。

removeByIndex(Index, Count)

从表格中的 Index 位置开始删除 Count 个行。

getByIndex 和 getCount 方法可用于所有表格，而 insertByIndex 和 removeByIndex 方法只能用于不包含合并单元格的表格。

com.sun.star.text.TextTableRow 服务提供了以下属性：

BackColor (Long)

行的背景颜色。

Height (Long)

行高度，以百分之一毫米为单位。

IsAutoHeight (Boolean)

根据内容动态调整表格高度。

VertOrient (const)

文本框的垂直方向，即有关表格中的文本垂直方向的详细信息（与 com.sun.star.text.VertOrientation 一致的值）

列

访问列的方式与访问行的方式相同，即对 Column 对象使用 getByIndex、getCount、insertByIndex 和 removeByIndex 方法，可通过 getColumns 访问该对象。不过，只能在不包含合并表格单元格的表格中使用这些方法。在 Apache OpenOffice Basic 中，不能按列设置单元格格式。为执行此操作，必须使用为单个表格单元格设置格式的方法。

单元格

Apache OpenOffice 文档的每个单元格都具有唯一的名称。如果 Apache OpenOffice 光标位于单元格中，则可以在状态栏中看到该单元格的名称。左上角的单元格通常称为 A1，右下角的单元格通常称为 Xn，其中 X 表示最高一列的字母，n 表示最后一行的编号。单元格对象是通过表格对象的 getCellByName() 方法提供的。以下示例说明了一个循环，它遍历表格的所有单元格，并在单元格中输入相应的行号和列号。

Dim Doc As Object
Dim Table As Object
Dim Cursor As Object
Dim Rows As Object
Dim RowIndex As Integer
Dim Cols As Object
Dim ColIndex As Integer
Dim CellName As String
Dim Cell As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
Table = Doc.createInstance("com.sun.star.text.TextTable")
Table.initialize(5, 4)
 
Doc.Text.insertTextContent(Cursor, Table, False)
 
Rows = Table.getRows
Cols = Table.getColumns
 
For RowIndex = 1 To Rows.getCount()
   For ColIndex = 1 To Cols.getCount()
      CellName = Chr(64 + ColIndex) & RowIndex
      Cell = Table.getCellByName(CellName)
      Cell.String = "row: " & CStr(RowIndex) + ", column: " & CStr(ColIndex)
   Next
Next

表格单元格与标准文本类似。它支持用于创建关联的 TextCursor 对象的 createTextCursor 接口。

CellCursor = Cell.createTextCursor()

因此，自动提供了为单个字符和段落设置格式的所有选项。

以下示例将搜索文本文档中的所有表格，并通过相应的段落属性对所有包含数值的单元格应用右对齐格式。

Dim Doc As Object
Dim TextTables As Object
Dim Table As Object
Dim CellNames
Dim Cell As Object
Dim CellCursor As Object
Dim I As Integer
Dim J As Integer
 
Doc = StarDesktop.CurrentComponent
TextTables = Doc.getTextTables()
 
For I = 0 to TextTables.count - 1
   Table = TextTables(I)
   CellNames = Table.getCellNames()
 
   For J = 0 to UBound(CellNames)
      Cell = Table.getCellByName(CellNames(J))
      If IsNumeric(Cell.String) Then
         CellCursor = Cell.createTextCursor()
         CellCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.RIGHT
      End If
   Next
Next

本示例创建了一个 TextTables 列表，其中包含通过循环在文本中遍历的所有表格。然后，Apache OpenOffice 创建了一个列表，其中包含每个表格的关联单元格名称。之后，又通过循环遍历这些单元格。如果单元格中包含数值，本示例将相应地更改其格式。为此，本示例首先创建了一个 TextCursor 对象，该对象引用表格单元格的内容，然后调整表格单元格的段落属性。

文本框

与表格和图形一样，文本框也被视为 TextContent 对象。文本框基本上由标准文本组成，但可以将其放在页面上的任意位置，而不是包含在文本流中。

与所有 TextContent 对象一样，在文档中实际创建和插入文本框时执行的操作是不同的。

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
Doc.Text.insertTextContent(Cursor, Frame, False)

文本框是使用文档对象的 createInstance 方法创建的。然后，可以使用 Text 对象的 insertTextContent 方法在文档中插入以这种方式创建的文本框。在执行此操作时，应指定正确的 com.sun.star.text.TextFrame 服务名称。

文本框的插入位置是由 Cursor 对象决定的，在执行插入操作时也会执行该对象。

Apache OpenOffice 的文本框对应于 Word 中使用的位置框。VBA 使用 Document.Frames.Add 方法来实现此目的；而上述过程使用文档对象的 TextCursor 和 createInstance 方法来完成 VBA 中的创建操作。

文本框对象提供了一系列属性，这些属性会影响文本框的位置和行为。其中的大多数属性是在 com.sun.star.text.BaseFrameProperties 服务中定义的，每个 TextFrame 服务也支持该服务。主要属性包括：

BackColor (Long)

文本框的背景颜色。

BottomMargin (Long)

下边距，以百分之一毫米为单位。

LeftMargin (Long)

左边距，以百分之一毫米为单位。

RightMargin (Long)

右边距，以百分之一毫米为单位。

TopMargin (Long)

上边距，以百分之一毫米为单位

Height (Long)

文本框高度，以百分之一毫米为单位。

Width (Long)

文本框宽度，以百分之一毫米为单位。

HoriOrient (const)

文本框的水平方向（与 com.sun.star.text.HoriOrientation 一致）。

VertOrient (const)

文本框的垂直方向（与 com.sun.star.text.VertOrientation 一致）。

以下示例将使用上述属性创建一个文本框：

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Cursor.gotoNextWord(False)
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
 
Frame.Width = 3000
Frame.Height = 1000
Frame.AnchorType = com.sun.star.text.TextContentAnchorType.AS_CHARACTER
Frame.TopMargin = 0
Frame.BottomMargin = 0
Frame.LeftMargin = 0
Frame.RightMargin = 0
Frame.BorderDistance = 0
Frame.HoriOrient = com.sun.star.text.HoriOrientation.NONE
Frame.VertOrient = com.sun.star.text.VertOrientation.LINE_TOP
 
Doc.Text.insertTextContent(Cursor, Frame, False)

本示例创建了一个 TextCursor 以作为文本框的插入标记。它位于文本的第一个词和第二个词之间。文本框是使用 Doc.createInstance 创建的。文本框对象的属性被设置为所需的起始值。

此处，应注意 AnchorType 属性（来自 TextContent 服务）和 VertOrient 属性（来自 BaseFrameProperties 服务）之间的交互。AnchorType 接受 AS_CHARACTER 值。因此，文本框将直接插入到文本流中，其行为与字符类似。例如，如果遇到换行符，文本框将移到下一行。VertOrient 属性的 LINE_TOP 值可确保文本框上边缘的高度与字符上边缘的高度相同。

在完成初始化后，将使用 insertTextContent 调用将文本框最终插入到文本文档中。

要编辑文本框的内容，用户可以使用 TextCursor；我们已多次提到该对象，它也可用于文本框。

Dim Doc As Object
Dim TextTables As Object
Dim Cursor As Object
Dim Frame As Object
Dim FrameCursor As Object
 
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
Frame = Doc.createInstance("com.sun.star.text.TextFrame")
 
Frame.Width = 3000
Frame.Height = 1000
 
Doc.Text.insertTextContent(Cursor, Frame, False)
 
FrameCursor = Frame.createTextCursor()
FrameCursor.charWeight = com.sun.star.awt.FontWeight.BOLD
FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER
FrameCursor.String = "This is a small Test!"

本示例创建了一个文本框，将其插入到当前文档中，然后为该文本框打开了 TextCursor。此光标用于将文本框中的字体设置为粗体，并将段落方向设置为居中。最后，为该文本框指定了字符串 "This is a small test!"。

文本字段

文本字段是 TextContent 对象，因为除了提供纯文本以外，它们还提供其他逻辑。可以在文本文档中插入文本字段，使用的方法与其他 TextContent 对象所使用的方法相同：

Dim Doc As Object
Dim DateTimeField As Object
Dim Cursor As Object
Doc = StarDesktop.CurrentComponent
Cursor = Doc.Text.createTextCursor()
 
DateTimeField = Doc.createInstance("com.sun.star.text.TextField.DateTime")
DateTimeField.IsFixed = False
DateTimeField.IsDate = True
Doc.Text.insertTextContent(Cursor, DateTimeField, False)

本示例在当前文本文档开头插入包含当前日期的文本字段。IsDate 属性的 True 值导致仅显示日期，而不显示时间。IsFixed 的 False 值确保在打开文档时自动更新日期。

在 VBA 中，字段类型是由 Document.Fields.Add 方法的参数指定的；而在 Apache OpenOffice Basic 中，则是由处理相关字段类型的服务名称定义的。

过去，文本字段是使用 Apache OpenOffice 在旧的 Selection 对象中提供的各种方法（例如 InsertField、DeleteUserField、SetCurField)）进行访问的。

在 Apache OpenOffice 2.x 中，字段是使用面向对象的概念进行管理的。要创建文本字段，应该先创建所需类型的文本字段，然后使用所需的属性对其进行初始化。接下来，使用 insertTextContent 方法在文档中插入文本字段。可以在上一示例中看到相应的源文本。以下几节介绍了最重要的字段类型及其属性。

除了插入文本字段以外，在文档中搜索字段也是一项非常重要的任务。以下示例说明了如何通过循环遍历文本文档的所有文本字段，并检查其相关类型。

Dim Doc As Object
Dim TextFieldEnum As Object
Dim TextField As Object
Dim I As Integer
 
Doc = StarDesktop.CurrentComponent
 
TextFieldEnum = Doc.getTextFields.createEnumeration
 
While TextFieldEnum.hasMoreElements()
 
   TextField = TextFieldEnum.nextElement()
 
   If TextField.supportsService("com.sun.star.text.TextField.DateTime") Then
      MsgBox "Date/time"
   ElseIf TextField.supportsService("com.sun.star.text.TextField.Annotation") Then
      MsgBox "Annotation"
   Else
      MsgBox "unknown"
   End If
 
Wend

确定现有文本字段的起点是文档对象的 TextFields 列表。本示例根据此列表创建了一个 Enumeration 对象，可以使用该对象通过循环查询所有文本字段。接下来，使用 supportsService 方法检查找到的文本字段，以确定所支持的服务。如果字段证明是日期/时间字段或注释，则在信息框中显示相应的字段类型。另一方面，如果本示例遇到其他字段，则显示信息 "unknown"。

下面列出了最重要的文本字段及其关联的属性。API 参考的 com.sun.star.text.TextField 模块中提供了所有文本字段的完整列表。（在列出文本字段的服务名称时，应在 Apache OpenOffice Basic 中使用大写和小写字符，如上一示例中所示。）

页数、字数和字符数

文本字段

• com.sun.star.text.TextField.PageCount
• com.sun.star.text.TextField.WordCount
• com.sun.star.text.TextField.CharacterCount

返回文本的页数、字数或字符数。它们支持以下属性：

NumberingType (const)

编号格式（与 com.sun.star.style.NumberingType 中的常量一致的准则）。

当前页面

可以使用 com.sun.star.text.TextField.PageNumber 文本字段在文档中插入当前页码。可以指定以下属性：

NumberingType (const)

编号格式（与 com.sun.star.style.NumberingType 中的常量一致的准则）。

Offset (short)

添加到页码的偏移（也可以指定负数）。

以下示例说明了如何在文档页脚中插入页码。

Dim Doc As Object
Dim DateTimeField As Object
Dim PageStyles As Object
Dim StdPage As Object
Dim FooterCursor As Object
Dim PageNumber As Object
 
Doc = StarDesktop.CurrentComponent
 
PageNumber = Doc.createInstance("com.sun.star.text.TextField.PageNumber")
PageNumber.NumberingType = com.sun.star.style.NumberingType.ARABIC
 
PageStyles = Doc.StyleFamilies.getByName("PageStyles")
 
StdPage = PageStyles("Default")
StdPage.FooterIsOn = True
 
FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor()
StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)

本示例首先创建了一个支持 com.sun.star.text.TextField.PageNumber 服务的文本字段。由于页眉和页脚行被定义为 Apache OpenOffice 页面模板的一部分，因此，最初使用所有 PageStyles 的列表来创建它们。

要确保显示页脚行，应将 FooterIsOn 属性设置为 True。然后，使用左侧页脚行的关联文本对象在文档中插入该文本字段。

注释

可以通过文本中的小黄色符号来查看注释字段 (com.sun.star.text.TextField.Annotation)。单击此符号即可打开一个文本字段，可以在其中记录有关文本当前位置的注释。注释字段具有以下属性。

Author (String)

作者姓名。

Content (String)

注释文本。

Date (Date)

编写注释的日期。

日期/时间

日期/时间字段 (com.sun.star.text.TextField.DateTime) 表示当前日期或当前时间。它支持以下属性：

IsFixed (Boolean)

如果为 True，则插入时间详细信息保持不变；如果为 False，则每次打开文档时都会更新这些信息。

IsDate (Boolean)

如果为 True，该字段将显示当前日期，否则显示当前时间。

DateTimeValue (struct)

字段的当前内容（com.sun.star.util.DateTime 结构）

NumberFormat (const)

描述时间或日期所用的格式。

章节名称/编号

可通过 com.sun.star.text.TextField.Chapter 类型的文本字段提供当前章节的名称。可以使用以下两个属性定义该格式。

ChapterFormat (const)

确定是否描述章节名称或章节编号（与 com.sun.star.text.ChapterFormat 一致）

Level (Integer)

确定要显示章节名称和/或章节编号的章节级别。值 0 表示可用的最高级别。

书签

书签（com.sun.star.text.Bookmark 服务）是 TextContent 对象。书签是使用前面介绍的概念创建和插入的：

Dim Doc As Object
Dim Bookmark As Object
Dim Cursor As Object
 
Doc = StarDesktop.CurrentComponent
 
Cursor = Doc.Text.createTextCursor()
 
Bookmark = Doc.createInstance("com.sun.star.text.Bookmark")
Bookmark.Name = "My bookmarks"
Doc.Text.insertTextContent(Cursor, Bookmark, True)

本示例创建了一个 Cursor，它标记了书签的插入位置，然后又标记了实际的书签对象 (Bookmark)。接下来，为书签指定了名称，并通过 insertTextContent 将其插入到文档中的光标位置。

文本的书签是通过称为 Bookmarks 的列表进行访问的。可以按编号或名称来访问书签。

以下示例说明了如何在文本中查找书签，以及如何在书签位置插入文本。

Dim Doc As Object
Dim Bookmark As Object
Dim Cursor As Object
 
Doc = StarDesktop.CurrentComponent
 
Bookmark = Doc.Bookmarks.getByName("My bookmarks")
 
Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor)
Cursor.String = "Here is the bookmark"

本示例使用 getByName 方法按名称查找所需的书签。然后，createTextCursorByRange 调用创建了一个 Cursor，它位于书签的锁定位置中。接下来，光标将所需的文本插入到该位置。