Class: UI::HtmlDialog

Relationships
Inherits:	Object

Overview

Note:

The window size is not guaranteed to be pixel perfect in all SketchUp versions and operating systems. Prefer responsive designs that can take up some fluctuations in size.

The Ruby HtmlDialog class allows you to create and interact with HTML dialog boxes from Ruby. This is the best way to generate complex, embedded UIs inside SketchUp, but it does generally require HTML and JavaScript expertise.

If your goal is to simple display a website to your users, consider using UI#openURL, which will show them a web page in their default browser rather than inside a dialog in SketchUp.

The left, top, width, height etc. dimensions of the dialog are in logical units. This means you provide the units as if they where on a monitor with “normal” DPI. The units given will be multiplied by the same factor as returned by scale_factor.

For usage examples, including how to migrate from the old WebDialog class, see github.com/SketchUp/htmldialog-examples. You may use the Trimble Modus framework for a look and feel of your dialog that matches that of SketchUp’s dialogs.

HtmlDialog uses the following versions of CEF (Chromium Embedded Framework):

SketchUp 2024.0: CEF 112
SketchUp 2021.1: CEF 88
SketchUp 2019.0: CEF 64
SketchUp 2018.0: CEF 56
SketchUp 2017.0: CEF 52

Version:

SketchUp 2017

Constant Summary

CEF_VERSION =

Constants

# File 'lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb', line 44
```
nil
```
CHROME_VERSION =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb', line 46
```
nil
```
STYLE_DIALOG =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb', line 48
```
nil
```
STYLE_UTILITY =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb', line 49
```
nil
```
STYLE_WINDOW =

Stub value.

# File 'lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb', line 50
```
nil
```

Class Method Summary

.new(properties) ⇒ UI::HtmlDialog constructor

The new method is used to create a new HtmlDialog.

Instance Attribute Summary

#visible? ⇒ Boolean readonly

The #visible? method is useful to tell if the dialog is shown and still alive, if the dialog is minimized or not visible on the screen this will still return true.

Instance Method Summary

#add_action_callback(callback_name) {|action_context, *args| ... } ⇒ Boolean

The #add_action_callback method establishes a Ruby callback method that your html dialog can call to perform some function.
#bring_to_front ⇒ nil

The #bring_to_front method is used to bring the window to the front, putting it on top of other windows even if its minimized.
#center ⇒ true

The #center method is used to center the HtmlDialog relative to the active model window.
#close ⇒ nil

The #close method is used to close a dialog box.
#execute_script(script) ⇒ nil

The #execute_script method is used to execute a JavaScript string on the html dialog asynchronously.
#get_content_size ⇒ Array(Integer, Integer)^?

The #get_content_size method is used to get the content size of the HtmlDialog, in logical pixels.
#get_position ⇒ Array(Integer, Integer)^?

The #get_position method is used to get the position of the HtmlDialog relative to the screen, in logical pixels.
#get_size ⇒ Array(Integer, Integer)^?

The #get_size method is used to get the outer frame size of the HtmlDialog, in logical pixels.
#set_can_close ⇒ Boolean

The #set_can_close method is used to attach a block that is executed just before closing, this block has to return a boolean, if the block returns false the close will be canceled.
#set_content_size(width, height) ⇒ nil

The #set_content_size method is used to set the content size of the HtmlDialog, in logical pixels.
#set_file(filename) ⇒ nil

The #set_file method is used to identify a local HTML file to display in the HtmlDialog.
#set_html(html_string) ⇒ nil

The #set_html method is used to load a HtmlDialog with a string of provided HTML.
#set_on_closed ⇒ Boolean

The #set_on_closed method is used to attach a block that will be executed when a dialog is already in the process of closing, do any last minute operations within this block such as saving the current state.
#set_position(left, top) ⇒ true

The #set_position method is used to set the position of the HtmlDialog relative to the screen, in pixels.
#set_size(width, height) ⇒ true

The #set_size method is used to set the outer frame size of the HtmlDialog, in pixels.
#set_url(url) ⇒ nil

The #set_url method is used to load a HtmlDialog with the content at a specific URL.
#show ⇒ nil

The #show method is used to display a non-modal dialog box.
#show_modal ⇒ nil

The #show_modal method is used to display a modal dialog box.

Constructor Details

.new(properties) ⇒ `HtmlDialog`

Note:

Prefix preference_key with something unique to your extension.

Note:

If there is no reference kept to the HtmlDialog object, the window will close once the garbage collection runs. This behavior can be confusing in trivial test code but is usually not a concern in real life scenarios. Typically a persistent reference, e.g. an instance variable, should be kept to bring the dialog to front, rather than creating a duplicate, if the user should request it a second time.

The new method is used to create a new HtmlDialog.

In SketchUp 2021.1 use_content_size was added. When set to true, width, height, min_width, max width, min_height, max_height will represent the size of the content area of the window. This excludes the titlebar and the window frame. When use_content_size is set to false (the default value), the size dimensions will represent the outer frame size.

The properties hash accepts an optional key style where the value is one of:

UI::HtmlDialog::STYLE_DIALOG: HtmlDialog stays at the top of SketchUp.
UI::HtmlDialog::STYLE_WINDOW: HtmlDialog can go behind SketchUp and doesn’t disappear when SketchUp looses focus.
UI::HtmlDialog::STYLE_UTILITY: HtmlDialog is shown with small titlebar and stays on top of SketchUp.

Examples:

With options Hash

dialog = UI::HtmlDialog.new(
{
  :dialog_title => "Dialog Example",
  :preferences_key => "com.sample.plugin",
  :scrollable => true,
  :resizable => true,
  :width => 600,
  :height => 400,
  :left => 100,
  :top => 100,
  :min_width => 50,
  :min_height => 50,
  :max_width =>1000,
  :max_height => 1000,
  :style => UI::HtmlDialog::STYLE_DIALOG
})
dialog.set_url("http://www.sketchup.com")
dialog.show

With keyword style argument

dialog = UI::HtmlDialog.new(
  dialog_title: "Dialog Example",
  preferences_key: "my_name_my_extension_my_dialog",
  scrollable: true,
  resizable: true,
  width: 600,
  height: 400,
  left: 100,
  top: 100,
  min_width: 50,
  min_height: 50,
  max_width: 1000,
  max_height: 1000,
  style: UI::HtmlDialog::STYLE_DIALOG
)
dialog.set_url("https://www.sketchup.com")
dialog.show

Parameters:

properties (Hash) —

A hash containing the initial properties of the newly created dialog.

Options Hash (properties):

:dialog_title (String)
:preferences_key (String)
:scrollable (Boolean)
:resizable (Boolean) — default: true
:use_content_size (Boolean) — default: false
:width (Integer) — default: 250
:height (Integer) — default: 250
:left (Integer) — default: 0
:top (Integer) — default: 0
:min_width (Integer) — default: 0
:min_height (Integer) — default: 0
:max_width (Integer) — default: -1
:max_height (Integer) — default: -1
:style (Integer) — default: UI::HtmlDialog::STYLE_DIALOG

Version:

SketchUp 2017

Instance Attribute Details

#visible? ⇒ `Boolean` (readonly)

The #visible? method is useful to tell if the dialog is shown and still alive, if the dialog is minimized or not visible on the screen this will still return true.

Examples:

if dialog.visible?
  dialog.bring_to_front
else
  dialog = UI::HtmlDialog.new
  dialog.set_url("https://www.sketchup.com")
  dialog.show
end

Returns:

(Boolean) —

Returns true if the dialog is open.

Version:

SketchUp 2017

Instance Method Details

#add_action_callback(callback_name) {|action_context, *args| ... } ⇒ `Boolean`

Note:

When an HtmlDialog is closed, all callbacks to that instance are cleared. Re-attach them if you need to open the dialog again.

The #add_action_callback method establishes a Ruby callback method that your html dialog can call to perform some function.

Use the sketchup.callback_method_name to invoke the callback method from your html dialog. Your JavaScript in the html dialog will invoke the callback with the same number of arguments.

The call is asynchronous. JavaScript call might return before Ruby callback even called. Use onCompleted callback to get notified for completion.

Basic types such as booleans, numbers, strings, arrays and hashes are automatically converted between Ruby and JavaScript.

Examples:

Ruby Code

dialog.add_action_callback("say") { |action_context, param1, param2|
  puts "JavaScript said #{param1} and #{param2}"
}

JavaScript

sketchup.say('Hello World', 42);

JavaScript with callback

sketchup.say('Hello World', 42, {
  onCompleted: function() {
    console.log('Ruby side done.');
  }
});

Parameters:

callback_name (String) —

The name of the callback method to be invoked from the html dialog.

Yields:

(action_context, *args)

Yield Parameters:

action_context (Object) —

Currently unused.
args (Array<Object>) —

The parameters sent from JavaScript.

Returns:

(Boolean) —

true if action added successfully, false otherwise.

Version:

SketchUp 2017

#bring_to_front ⇒ `nil`

The #bring_to_front method is used to bring the window to the front, putting it on top of other windows even if its minimized.

Examples:

dialog.bring_to_front

#center ⇒ `true`

The #center method is used to center the HtmlDialog relative to the active model window. If there is no active model window, this function doesn’t do anything.

Examples:

dialog.center

Returns:

(true) —

This always return true, never false.

Version:

SketchUp 2017

#close ⇒ `nil`

The #close method is used to close a dialog box.

Examples:

dialog.close

Version:

SketchUp 2017

#execute_script(script) ⇒ `nil`

The #execute_script method is used to execute a JavaScript string on the html dialog asynchronously.

Examples:

js_command = "document.getElementById('id').innerHTML = '<b>Hi!</b>'"
dialog.execute_script(js_command)

Parameters:

script (String) —

The JavaScript script to execute on the HtmlDialog.

Version:

SketchUp 2017

#get_content_size ⇒ Array(`Integer`, `Integer`)^?

The #get_content_size method is used to get the content size of the HtmlDialog, in logical pixels.

Examples:

width, height = dialog.get_content_size

Returns:

(Array(Integer, Integer), nil) —

Content width and height of the HtmlDialog. A nil value is returned if the HtmlDialog is not visible.

Version:

SketchUp 2021.1

#get_position ⇒ Array(`Integer`, `Integer`)^?

The #get_position method is used to get the position of the HtmlDialog relative to the screen, in logical pixels.

Examples:

left, top = dialog.get_position

Returns:

(Array(Integer, Integer), nil) —

Left and top position of the dialog. A nil value is returned if the HtmlDialog is not visible.

Version:

SketchUp 2021.1

#get_size ⇒ Array(`Integer`, `Integer`)^?

The #get_size method is used to get the outer frame size of the HtmlDialog, in logical pixels.

Examples:

width, height = dialog.get_size

Returns:

(Array(Integer, Integer), nil) —

Outer frame width and height of the HtmlDialog. A nil value is returned if the HtmlDialog is not visible.

Version:

SketchUp 2021.1

#set_can_close ⇒ `Boolean`

The #set_can_close method is used to attach a block that is executed just before closing, this block has to return a boolean, if the block returns false the close will be canceled.

Examples:

dialog.set_can_close { false }

Yield Returns:

(Boolean) —

Return a boolean to indicate if the dialogs should close.

Version:

SketchUp 2017

#set_content_size(width, height) ⇒ `nil`

The #set_content_size method is used to set the content size of the HtmlDialog, in logical pixels.

Examples:

dialog.set_content_size(600, 400)

Parameters:

width (Integer) —

Content width of the HtmlDialog.
height (Integer) —

Content height of the HtmlDialog.

Version:

SketchUp 2021.1

#set_file(filename) ⇒ `nil`

The #set_file method is used to identify a local HTML file to display in the HtmlDialog.

Examples:

dialog.set_file("c:/mypage.html")

Parameters:

filename (String) —

The filename for the HtmlDialog file (HTML file)

Version:

SketchUp 2017

#set_html(html_string) ⇒ `nil`

The #set_html method is used to load a HtmlDialog with a string of provided HTML.

Examples:

html = '<b>Hello world!</b>'
dialog.set_html(html)

Parameters:

html_string (String) —

A string of valid html to display in your HtmlDialog.

Version:

SketchUp 2017

#set_on_closed ⇒ `Boolean`

The #set_on_closed method is used to attach a block that will be executed when a dialog is already in the process of closing, do any last minute operations within this block such as saving the current state.

Examples:

dialog.set_on_closed { save_selection }

Version:

SketchUp 2017

#set_position(left, top) ⇒ `true`

The #set_position method is used to set the position of the HtmlDialog relative to the screen, in pixels.

Examples:

dialog.set_position(100, 50)

Parameters:

left (Integer) —

The number of pixels from the left.
top (Integer) —

The number of pixels from the top of the screen.

Returns:

(true) —

This always return true, never false.

Version:

SketchUp 2017

#set_size(width, height) ⇒ `true`

The #set_size method is used to set the outer frame size of the HtmlDialog, in pixels.

Examples:

dialog.set_size(320, 240)

Parameters:

width (Integer) —

Outer frame width of the HtmlDialog.
height (Integer) —

Outer frame height of the HtmlDialog.

Returns:

(true) —

This always return true, never false.

Version:

SketchUp 2017

#set_url(url) ⇒ `nil`

The #set_url method is used to load a HtmlDialog with the content at a specific URL. This method allows you to load web sites in a HtmlDialog.

Examples:

dialog.set_url("https://www.sketchup.com")

Parameters:

url (String) —

The URL for a specific web site.

Version:

SketchUp 2017

#show ⇒ `nil`

The #show method is used to display a non-modal dialog box.

Examples:

dialog.show

Version:

SketchUp 2017

#show_modal ⇒ `nil`

The #show_modal method is used to display a modal dialog box.

Examples:

dialog.show_modal

Version:

SketchUp 2017

Class: UI::HtmlDialog

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(properties) ⇒ HtmlDialog

Instance Attribute Details

#visible? ⇒ Boolean (readonly)

Instance Method Details

#add_action_callback(callback_name) {|action_context, *args| ... } ⇒ Boolean

#bring_to_front ⇒ nil

#center ⇒ true

#close ⇒ nil

#execute_script(script) ⇒ nil

#get_content_size ⇒ Array(Integer, Integer)?

#get_position ⇒ Array(Integer, Integer)?

#get_size ⇒ Array(Integer, Integer)?

#set_can_close ⇒ Boolean

#set_content_size(width, height) ⇒ nil

#set_file(filename) ⇒ nil

#set_html(html_string) ⇒ nil

#set_on_closed ⇒ Boolean

#set_position(left, top) ⇒ true

#set_size(width, height) ⇒ true

#set_url(url) ⇒ nil

#show ⇒ nil

#show_modal ⇒ nil

.new(properties) ⇒ `HtmlDialog`

#visible? ⇒ `Boolean` (readonly)

#add_action_callback(callback_name) {|action_context, *args| ... } ⇒ `Boolean`

#bring_to_front ⇒ `nil`

#center ⇒ `true`

#close ⇒ `nil`

#execute_script(script) ⇒ `nil`

#get_content_size ⇒ Array(`Integer`, `Integer`)^?

#get_position ⇒ Array(`Integer`, `Integer`)^?

#get_size ⇒ Array(`Integer`, `Integer`)^?

#set_can_close ⇒ `Boolean`

#set_content_size(width, height) ⇒ `nil`

#set_file(filename) ⇒ `nil`

#set_html(html_string) ⇒ `nil`

#set_on_closed ⇒ `Boolean`

#set_position(left, top) ⇒ `true`

#set_size(width, height) ⇒ `true`

#set_url(url) ⇒ `nil`

#show ⇒ `nil`

#show_modal ⇒ `nil`