Module: UI

概述

UI模块包含许多从SketchUp Ruby脚本创建简单UI元素的方法。

版本：

• SketchUp 6.0

在命名空间下定义

类： Command,HtmlDialog,Notification,Toolbar,WebDialog

类方法摘要

• .add_context_menu_handler {|menu| ... } ⇒ Integer

  add_context_menu_handler方法用于向SketchUp注册代码块，当要显示上下文菜单时将调用该代码块。

• .beep ⇒ nil

  beep方法播放系统哔哔声。

• .create_cursor(filename, hot_x, hot_y) ⇒ Integer

  create_cursor方法用于从指定位置的图像文件创建光标。

• .inputbox(*args) ⇒ Array<String>, false

  创建用于输入用户信息的对话框。

• .inspector_names ⇒ Array<String>

  inspector_names方法用于返回所有检查器的名称。

• .menu(menu_name = "Plugins") ⇒ Sketchup::Menu

  这个UI.menu方法检索具有给定名称的SketchUp的菜单对象。

• .messagebox(message, type = MB_OK) ⇒ Integer

  创建一个包含静态文本的对话框，其中包含一系列按钮供用户选择。

• .model_info_pages ⇒ Array<String>

  model_info_pages方法用于返回所有可用的model info页面的名称。

• .openpanel(title, directory, filename) ⇒ String

  openpanel方法用于显示“打开”对话框。

• .openURL(url) ⇒ Boolean

  这个UI.openURL方法用于打开URL的默认浏览器。

• .play_sound(filename) ⇒ nil

  播放声音方法用于播放声音文件。

• .preferences_pages ⇒ Array<String>

  preferences_pages方法用于返回所有首选项页面的名称。

• .refresh_inspectors ⇒ nil

  告诉SketchUp刷新所有检查器，如组件浏览器和大纲视图。

• .refresh_toolbars ⇒ nil

  告诉SketchUp刷新所有浮动工具栏。

• .savepanel(title, directory, filename) ⇒ String

  savepanel方法用于显示“保存”对话框。

• .scale_factor ⇒ Float

  返回SketchUp在高DPI监视器上使用的比例因子。

• .select_directory(options = {}) ⇒ String, ...

  这个UI.select_directory方法用于显示操作系统对话框，用于从文件系统中选择一个或多个目录。

• .set_cursor(cursor_id) ⇒ Boolean

  在#UI.set_cursor方法将游标更改为具有给定游标id的新游标。

• .set_toolbar_visible(name, visible) ⇒ Boolean

  set_toolbar_visible方法用于设置给定工具栏是否可见。

• .show_extension_manager ⇒ nil

  这个show_extension_manager方法用于显示“扩展管理器”对话框。

• .show_inspector(name) ⇒ Boolean

  show_inspector方法用于显示具有给定名称的检查器。

• .show_model_info(page_name) ⇒ Boolean

  这个UI.show_model_info方法用于显示特定页的“模型信息”对话框。

• .show_preferences(page_name) ⇒ Boolean

  show_preferences方法用于显示“草图首选项”对话框。

• .start_timer(seconds, repeat = false) {|procedure| ... } ⇒ Integer

  start_timer方法用于启动计时器。

• .stop_timer(id) ⇒ nil

  stop_timer方法用于根据计时器的id停止计时器。

• .toolbar(name) ⇒ UI::Toolbar

  toolbar方法用于按名称获取Ruby工具栏。

• .toolbar_names ⇒ Array<String>

  toolbar_names方法用于返回所有可用的本机工具栏的名称（这与PC和Mac不同）。

• .toolbar_visible?(name) ⇒ Boolean

  toolbar_visible?方法用于确定给定工具栏是否可见。

类方法详细信息

.add_context_menu_handler {|menu| ... } ⇒ Integer

add_context_menu_handler方法用于向SketchUp注册代码块，当要显示上下文菜单时将调用该代码块。然后，上下文菜单处理程序可以显示包含您添加的项的上下文菜单。

请注意在上下文菜单处理程序中执行的操作。如果执行的操作需要很长时间，例如遍历模型或大模型中的选择，则会延迟菜单。

contextmenu.rb在Plugins/examples目录中编写示例脚本。

示例：

# Right click on anything to see a Hello World item.
UI.add_context_menu_handler do |context_menu|
  context_menu.add_item("Hello World") {
    UI.messagebox("Hello world")
  }
end

产量：

• (menu)—

  以菜单作为唯一参数的代码块。

返回值：

• (整数)—

  已注册的上下文处理程序数

版本：

• SketchUp 6.0

.beep ⇒ nil

beep方法播放系统哔哔声。

beep方法不接受任何参数，也不返回任何值。

示例：

UI.beep

返回值：

• (无)

版本：

• SketchUp 6.0

.create_cursor(filename, hot_x, hot_y) ⇒ Integer

create_cursor方法用于从指定位置的图像文件创建光标。必须从自定义工具中调用。有关完整的示例，请参见工具类。

自SketchUp 2016年起，就可以为光标提供矢量图像。用于Windows的SVG格式和用于OS X的PDF格式。

示例：

cursor_id = nil
cursor_path = Sketchup.find_support_file("Pointer.png", "Plugins/")
if cursor_path
  cursor_id = UI.create_cursor(cursor_path, 0, 0)
end

def onSetCursor
  UI.set_cursor(cursor_id)
end

参数：

• 文件名 (String)—

  图像的文件名。

• hot_x (整数)—

  从光标图像的左边缘计算的光标的“热点”的x坐标。

• hot_y (整数)—

  从光标图像的上边缘计算的光标的“热点”的y坐标。例如，值（hot_x，hot_y）=（5,10）将标识光标在距光标图像左边缘5个像素处和光标图像上边缘10个像素处的热点。

返回值：

• (整数)—

  与光标关联的ID

版本：

• SketchUp 6.0

.inputbox(prompts, defaults, title) ⇒ Array<String>, false .inputbox(prompts, defaults, list, title) ⇒ Array<String>, false

创建用于输入用户信息的对话框。该对话框包含具有静态文本提示、可选默认值、可选下拉选择和可选标题的输入字段。

也可以使用此方法通过传递可选参数来显示选项的下拉列表。

示例：

# With three params, it shows all text boxes:
prompts = ["What is your Name?", "What is your Age?", "Gender"]
defaults = ["Enter name", "", "Male"]
input = UI.inputbox(prompts, defaults, "Tell me about yourself.")

# With four params, it shows a drop down box for prompts that have
# pipe-delimited lists of options. In this case, the Gender prompt
# is a drop down instead of a text box.
prompts = ["What is your Name?", "What is your Age?", "Gender"]
defaults = ["Enter name", "", "Male"]
list = ["", "", "Male|Female"]
input = UI.inputbox(prompts, defaults, list, "Tell me about yourself.")

过载：

• .inputbox（prompts, defaults, title）⇒Array<String>,false

  参数：

  • prompts (Array<String>)—

    显示在输入框中与输入字段相邻的提示名称数组。

  • defaults (Array<String>)—

    输入字段的默认值数组。

  • title (String)—

    输入框的标题。

• .inputbox（rompts, defaults, list, title）⇒Array<String>,false

  参数：

  • prompts (Array<String>)—

    显示在输入框中与输入字段相邻的提示名称数组。

  • defaults (Array<String>)—

    输入字段的默认值数组。

  • list (String,Array<String>)—

    包含由管道分隔的选项字符串的数组。

  • title (String)—

    输入框的标题。

返回值：

• (Array<String>,false)—

  如果用户没有取消对话框，则返回值的数组。如果用户取消了对话框，则返回false。数组中返回值的顺序与输入字段的顺序相同。

版本：

• SketchUp 6.0

.inspector_names ⇒ Array<String>

inspector_names方法用于返回所有检查器的名称。Inspectors是各种浮动对话框窗口的另一个名称，您可以使用SketchUp激活这些窗口，例如“材质”窗口。

示例：

inspectors = UI.inspector_names

返回值：

• (Array<String>)—

  包含检查员姓名的字符串数组。

版本：

• SketchUp 6.0

.menu(menu_name = "Plugins") ⇒ Sketchup::Menu

注：

“扩展”菜单在SketchUp 2015之前被命名为“插件”。为了向后兼容，“插件”仍然有效。

注：

如果你在2018年之前的草图版本中通过了一个空字符串。

这个menu方法检索具有给定名称的SketchUp的菜单对象。向上添加自定义菜单项。

有效的菜单名为：“File”、“Edit”、“View”、“Camera”、“Draw”、“Tools”、“Window”、“Extensions”和“Help”。

示例：

tool_menu = UI.menu("Tools")
tool_menu.add_item("Cheese Tool") {
  UI.messagebox("Cheese activated.")
}

参数：

• menu_name （默认为："Plugins")—

  现有顶级菜单的名称。

返回值：

• (Sketchup::Menu)

版本：

• SketchUp 6.0

.messagebox(message, type = MB_OK) ⇒ Integer

创建一个包含静态文本的对话框，其中包含一系列按钮供用户选择。

有效的消息框类型包括：

• MB_OK-包含“确定”按钮。

• MB_OKCANCEL-包含“确定”和“取消”按钮。

• MB_ABORTRETRYIGNORE-包含“中止”、“重试”和“忽略”按钮。

• MB_YESNOCANCEL-包含“是”、“否”和“取消”按钮。

• MB_YESNO-包含“是”和“否”按钮。

• MB_RETRYCANCEL-包含“重试”和“取消”按钮。

• MB_MULTILINE-包含“确定”按钮。

返回值可以是以下任意值：

• IDOK

• IDCANCEL

• IDABORT

• IDRETRY

• IDIGNORE

• IDYES

• IDNO

在一个MB_MULTILINE消息框中，消息显示为带有滚动条的多行消息（根据需要）。MB_MULTILNE还允许第三个字符串参数用作messagebox的标题。

示例：

result = UI.messagebox('Do you like cheese?', MB_YESNO)
if result == IDYES
  UI.messagebox('SketchUp likes cheese too!')
end

参数：

• message (String)—

  要显示的消息。

• type (整数) （默认为：MB_OK)—

  消息框类型，它将是方法注释中列表中的常量。

返回值：

• (整数)—

  与用户所选内容相对应的数字。

版本：

• SketchUp 6.0

.model_info_pages ⇒ Array<String>

model_info_pages方法用于返回所有可用的model info页面的名称。这些包括UI窗口，如组件、学分和单位。

示例：

mypages = UI.model_info_pages

返回值：

• (Array<String>)—

  包含模型信息页名称的字符串数组。

版本：

• SketchUp 6.0

.openpanel(title, directory, filename) ⇒ String

openpanel方法用于显示“打开”对话框。返回的路径可以在代码中使用，以打开文本或图像文件。有关从磁盘读写的示例，请参阅标准的Ruby类文件。

SketchUp2014中修复的错误：从SU7到SU2013，通配符无法正常工作。通配符筛选器没有填充文件类型下拉列表。过滤器字符串将显示在文件名字段中，并将'；*'；个字符转换为'；个字符。注意，通配符筛选器字符串的格式已更改。

See the description of the filename parameter below for details.

示例：

chosen_image = UI.openpanel("Open SKP File", "c:/", "model.skp")
chosen_image = UI.openpanel("Open Image File", "c:/", "Image Files|*.jpg;*.png;||")
chosen_image = UI.openpanel("Open CAD File", "c:/", "DXF|*.dxf|DWG|*.dwg||")

参数：

• title (String)—

  要应用于“打开”对话框的标题。

• directory (String)—

  打开面板的默认目录。

• filename (String)—

  打开面板的默认文件名。在Windows上，也可以使用以下格式传递通配符筛选器：UIname |通配符| |。通过添加额外的过滤器名称和过滤器对，可以添加其他过滤器下拉列表项：UIname1 | wildcard1 | UIname2 | wildcard2 | |。另外，多个通配符过滤器也可以在filter字段中使用分号分隔的列表组合成一行：ui|name | wildcard1；wildcard2 | |。

返回值：

• (String)—

  所选文件的完整路径和名称，如果对话框被取消，则为零。

版本：

• SketchUp 6.0

.openURL(url) ⇒ Boolean

这个openURL方法用于打开URL的默认浏览器。

示例：

status = UI.openURL("http://www.sketchup.com")

参数：

• url (String)

返回值：

• (布尔型)

版本：

• SketchUp 6.0

已知错误：

• 在SketchUp2019.3之前，mac版本会对给定的URL进行URL编码。这可能会无意中损坏一些URL，如果它们有URL片段（#字符）。Windows版本不会。从SketchUp 2019.3起，这两个平台都不执行URL编码，API用户应提供有效的URL。

.play_sound(filename) ⇒ nil

播放声音方法用于播放声音文件。有效的声音文件包括Mac上的.wav和.mp3文件以及PC上的.wav文件。

示例：

UI.play_sound "Plugins/mediadiscussion.wav"

参数：

• filename (String)—

  SketchUp安装目录中文件名的相对路径，或文件的绝对路径。（参见Sketchup.find_支持_文件搜索特定文件的方法。）

返回值：

• (无)

版本：

• SketchUp 6.0

.preferences_pages ⇒ Array<String>

preferences_pages方法用于返回所有首选项页面的名称。其中包括类似windows的扩展。

示例：

prefs = UI.preferences_pages

返回值：

• (Array<String>)—

  包含首选项页名称的字符串数组。

版本：

• SketchUp 6.0

.refresh_inspectors ⇒ nil

告诉SketchUp刷新所有检查器，如组件浏览器和大纲视图。当您需要在通过Ruby对文档进行更改后手动强制刷新时，这很有用。一般来说，SketchUp会为您保持这些同步，但偶尔它不会，例如何时model.start_操作已禁用UI更新。

示例：

UI.refresh_inspectors

返回值：

• (无)

版本：

• SketchUp 7.0

.refresh_toolbars ⇒ nil

告诉SketchUp刷新所有浮动工具栏。当您需要在通过Ruby对文档进行更改后手动强制刷新时，这很有用。一般来说，SketchUp会为您保持这些同步，但偶尔它不会，例如何时Sketchup::Model#start_operation已禁用UI更新。这只影响macOS，在Windows上工具栏总是刷新的。

示例：

UI.refresh_toolbars

返回值：

• (无)

版本：

• SketchUp 2018

.savepanel(title, directory, filename) ⇒ String

savepanel方法用于显示“保存”对话框。返回的路径可以在代码中使用，以保存文本或图像文件。有关从磁盘读写的示例，请参阅标准的Ruby类文件。

SketchUp2014中修复的错误：从SU7到SU2013，通配符无法正常工作。分号分隔的通配符列表没有填充文件类型下拉列表。将&*；字段中显示的字符串&*39。

示例：

path_to_save_to = UI.savepanel("Save Image File", "c:\\", "Shapes.jpg")

参数：

• title (String)—

  要应用于“保存”对话框的标题。

• directory (String)—

  保存面板的默认目录。

• filename (String)—

  保存面板的默认文件名。在Windows上，您也可以传递一个掩码，如“*.txt”，以显示所有的.txt文件。如果要显示多个文件类型，可以为文件名提供多个掩码，并用分号分隔，如下所示：“.txt；.doc。

返回值：

• (String)—

  选定文件的完整路径和名称，如果对话框被取消，则为空。

版本：

• SketchUp 6.0

.scale_factor ⇒ Float

注：

SU2017M0将自动放大线宽和文本大小，但不会放大提供给Sketchup::View#draw2d.

返回SketchUp在高DPI监视器上使用的比例因子。对像Sketchup::View#draw2d.

示例：

# Scale a set of points representing 2d screen points to account for high
# DPI monitors.
points2d = [
  Geom::Point3d.new(0, 0, 0),
  Geom::Point3d.new(8, 0, 0),
  Geom::Point3d.new(8, 4, 0),
  Geom::Point3d.new(0, 4, 0)
]
tr = Geom::Transformation.scaling(UI.scale_factor)
points2d.each { |point| point.transform!(tr)

返回值：

• (浮点值)

版本：

• SketchUp 2017

.select_directory(options = {}) ⇒ String, ...

这个select_directory方法用于显示操作系统对话框，用于从文件系统中选择一个或多个目录。

示例：

# Default title and folder:
chosen_folder = UI.select_directory

# Custom dialog title:
chosen_folder = UI.select_directory(title: "Select Image Directory")

# Force a start folder:
chosen_folder = UI.select_directory(directory: "C:/images")

# Allow multiple items to the selected:
chosen_folder = UI.select_directory(select_multiple: true)

# Custom dialog title and force a start folder:
chosen_folder = UI.select_directory(
  title: "Select Image Directory",
  directory: "C:/images"
)

参数：

• options (哈希值) （默认为：{})—

  可以通过提供选项的哈希或命名参数来自定义对话框。

选项哈希(options):

• ：title (String) — 默认值：无 —

  对话框的标题。

• ：directory (String) — 默认值：无 —

  强制对话框的起始目录。如果未指定，将使用最后选择的目录。

• ：选择多个 (布尔型) — 默认值：false —

  设置为true以允许选择多个项目。

返回值：

• (String,Array<String>,无)—

  当：select_multiple选项设置为false时，具有所选目录完整路径的字符串，否则为字符串数组，如果用户取消，则为nil。

版本：

• SketchUp 2015

.set_cursor(cursor_id) ⇒ Boolean

在#set_cursor方法将游标更改为具有给定游标id的新游标。请参阅UI.create_光标以及工具类，以获取有关使用任意光标创建自己的工具的详细信息。

如果在标准SketchUp工具处于活动状态时调用此选项，则不会看到自定义光标，因为这些工具会不断设置自己的光标以指示SketchUp的状态。

示例：

def onSetCursor
  UI.set_cursor(cursor_id)
end

参数：

• cursor_id (整数)—

  要显示的光标的id。

返回值：

• (布尔型)

版本：

• SketchUp 6.0

.set_toolbar_visible(name, visible) ⇒ Boolean

set_toolbar_visible方法用于设置给定工具栏是否可见。请注意，在Mac和PC上，工具栏及其名称是不同的，因此在跨平台脚本中使用此方法时要小心并确保进行测试。

示例：

status = UI.set_toolbar_visible("Camera", true)

参数：

• name (String)—

  Ruby工具栏的名称。

• visible (布尔型)—

  如果为True，则使工具栏可见，如果为false，则将其隐藏。

返回值：

• (布尔型)—

  成功为真，不成功为假。

版本：

• SketchUp 6.0

.show_extension_manager ⇒ nil

这个show_extension_manager方法用于显示“扩展管理器”对话框。

示例：

UI.show_extension_manager

返回值：

• (无)

版本：

• SketchUp 2017

.show_inspector(name) ⇒ Boolean

show_inspector方法用于显示具有给定名称的检查器。您可以使用UI.inspector_名称.

示例：

status = UI.show_inspector("Components")

参数：

• 名称 (String)—

  要显示的检查器的名称。

返回值：

• (布尔型)—

  true为成功，false为失败

版本：

• SketchUp 6.0

.show_model_info(page_name) ⇒ Boolean

这个show_model_info方法用于显示特定页的“模型信息”对话框。您可以使用获取有效对话框的列表model_info_pages.

SketchUp 2014

"Classifications"页面已添加。

SketchUp 2017

"Extensions"页面已被删除。

示例：

UI.show_model_info('Credits')

参数：

• page_name (String)—

  要显示的“模型信息”对话框的名称。

返回值：

• (布尔型)

版本：

• SketchUp 6.0

.show_preferences(page_name) ⇒ Boolean

show_preferences方法用于显示SketchUp首选项对话框。您可以使用获取有效对话框的列表UI.preferences\u页面.

请注意，在OSX下，此方法目前不起作用。

示例：

status = UI.show_preferences('GraphicsCard')

参数：

• page_name (String)—

  要显示的“首选项”对话框的名称。

返回值：

• (布尔型)—

  true

版本：

• SketchUp 6.0

.start_timer(seconds, repeat = false) {|procedure| ... } ⇒ Integer

start_timer方法用于启动计时器。这是为任意动画创建重复代码段的有效方法。

有关使用计时器的自定义动画的详细示例，请参见此博客文章：sketchupapi.blogspot.com/2008/10/animate-yo-cheese.html

请注意，有一个bug，如果在非重复计时器中打开模式窗口，则计时器将重复，直到窗口关闭。

示例：

# Beep once after 10 seconds.
id = UI.start_timer(10, false) { UI.beep }

参数：

• seconds (Numeric)—

  应该在代码之前调用秒。

• repeat (布尔型) （默认为：false)—

  如果希望计时器重复，则为true；如果不希望计时器重复，则为false（或省略）。

产量：

• (程序)—

  秒后要执行的过程已过期。

返回值：

• (整数)—

  计时器ID

版本：

• SketchUp 6.0

.stop_timer(id) ⇒ nil

stop_timer方法用于根据计时器的id停止计时器。

示例：

# Stop timer before it triggers.
id = UI.start_timer(10) { UI.beep }
UI.stop_timer(id)

参数：

• id (整数)—

  要停止的计时器的计时器id。

返回值：

• (无)

版本：

• SketchUp 6.0

.toolbar(name) ⇒ UI::Toolbar

toolbar方法用于按名称获取Ruby工具栏。如果工具栏不存在，将创建一个新的工具栏。

示例：

toolbar = UI.toolbar('Test')

参数：

• name (String)—

  Ruby工具栏的名称。

返回值：

• (UI::Toolbar)—

  工具栏对象

版本：

• SketchUp 6.0

.toolbar_names ⇒ Array<String>

toolbar_names方法用于返回所有可用的本机工具栏的名称（这与PC和Mac不同）。这些工具栏名称不包括Ruby工具栏。

示例：

names = UI.toolbar_names

返回值：

• (Array<String>)—

  表示工具栏名称的字符串数组。

版本：

• SketchUp 6.0

.toolbar_visible?(name) ⇒ Boolean

工具栏是否可见？方法用于确定给定工具栏是否可见。请注意，在Mac和PC上，工具栏及其名称是不同的，因此在跨平台脚本中使用此方法时要小心并确保进行测试。

示例：

status = UI.toolbar_visible?("Camera")

参数：

• name (String)—

  本机工具栏的名称。

返回值：

• (布尔型)

版本：

• SketchUp 6.0