Class: UI::HtmlDialog

Inherits:
Object
  • Object
show all
Defined in:
SketchUp/UI/HtmlDialog.rb

Overview

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 #openURL, which will show them a web page in their default browser rather than inside a dialog in SketchUp.

Version:

  • SketchUp 2017

Constant Summary collapse

STYLE_DIALOG =

Constants

nil
STYLE_UTILITY =

Stub value.

nil
STYLE_WINDOW =

Stub value.

nil

Instance Method Summary collapse

Constructor Details

#initialize(properties) ⇒ HtmlDialog

The new method is used to create a new HtmlDialog.

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:

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

Parameters:

  • properties (Hash) —

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

Options Hash (properties):

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

Version:

  • SketchUp 2017



192
193
 
# File 'SketchUp/UI/HtmlDialog.rb', line 192

def initialize(properties)
end

Instance Method Details

#add_action_callback(callback_name) {|action_context, ...| ... } ⇒ 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:

JavaScript

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

JavaScript with callback

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

Ruby Code

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

Parameters:

  • callback_name (String) —

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

Yields:

  • (action_context, ...)

Yield Parameters:

  • ... (Object) —

    The parameters sent from JavaScript.

  • action_context (Object) —

    action_context Currently unused.

Returns:

  • (Boolean) —

    true if action added successfully, false otherwise.

Version:

  • SketchUp 2017



70
71
 
# File 'SketchUp/UI/HtmlDialog.rb', line 70

def add_action_callback(callback_name)
end

#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

Returns:

  • (nil)

Version:

  • SketchUp 2017



82
83
 
# File 'SketchUp/UI/HtmlDialog.rb', line 82

def bring_to_front
end

#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)

Version:

  • SketchUp 2017



95
96
 
# File 'SketchUp/UI/HtmlDialog.rb', line 95

def center
end

#close ⇒ nil

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

Examples:

dialog.close

Returns:

  • (nil)

Version:

  • SketchUp 2017



106
107
 
# File 'SketchUp/UI/HtmlDialog.rb', line 106

def close
end

#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.

Returns:

  • (nil)

Version:

  • SketchUp 2017



122
123
 
# File 'SketchUp/UI/HtmlDialog.rb', line 122

def execute_script(script)
end

#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.

Returns:

  • (Boolean)

Version:

  • SketchUp 2017



208
209
 
# File 'SketchUp/UI/HtmlDialog.rb', line 208

def set_can_close
end

#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)

Returns:

  • (nil)

Version:

  • SketchUp 2017



223
224
 
# File 'SketchUp/UI/HtmlDialog.rb', line 223

def set_file(filename)
end

#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.

Returns:

  • (nil)

Version:

  • SketchUp 2017



240
241
 
# File 'SketchUp/UI/HtmlDialog.rb', line 240

def set_html(html_string)
end

#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 }

Returns:

  • (Boolean)

Version:

  • SketchUp 2017



253
254
 
# File 'SketchUp/UI/HtmlDialog.rb', line 253

def set_on_closed
end

#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)

Version:

  • SketchUp 2017



271
272
 
# File 'SketchUp/UI/HtmlDialog.rb', line 271

def set_position(left, top)
end

#set_size(width, height) ⇒ true

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

Examples:

dialog.set_size(320, 240)

Parameters:

  • width (Integer) —

    Width of the HtmlDialog.

  • height (Integer) —

    Height of the HtmlDialog.

Returns:

  • (true)

Version:

  • SketchUp 2017



288
289
 
# File 'SketchUp/UI/HtmlDialog.rb', line 288

def set_size(width, height)
end

#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("http://www.sketchup.com")

Parameters:

  • url (String) —

    The URL for a specific web site.

Returns:

  • (nil)

Version:

  • SketchUp 2017



303
304
 
# File 'SketchUp/UI/HtmlDialog.rb', line 303

def set_url(url)
end

#show ⇒ nil

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

Examples:

dialog.show

Returns:

  • (nil)

Version:

  • SketchUp 2017



314
315
 
# File 'SketchUp/UI/HtmlDialog.rb', line 314

def show
end

#show_modal ⇒ nil

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

Examples:

dialog.show_modal

Returns:

  • (nil)

Version:

  • SketchUp 2017



325
326
 
# File 'SketchUp/UI/HtmlDialog.rb', line 325

def show_modal
end

#visible? ⇒ Boolean

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("http://www.sketchup.com")
  dialog.show
end

Returns:

  • (Boolean) —

    Returns true if the dialog is open.

  • (Boolean)

Version:

  • SketchUp 2017



346
347
 
# File 'SketchUp/UI/HtmlDialog.rb', line 346

def visible?
end