Class: UI::WebDialog Deprecated

Inherits:
Object
  • Object
show all

Overview

Deprecated.

Please use HtmlDialog that was introduced in SketchUp 2017.

The Ruby WebDialog class allows you to create and interact with DHTML dialog boxes from Ruby.

If your goal is to simply 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.

See this blog post for a detailed, step-by-step example: sketchupapi.blogspot.com/2008/02/sharing-data-between-sketchup-ruby-and.html

Under Windows the IE render mode is different in webdialogs than from what you see in the normal browser. It will by default pick an older render mode and different versions of SketchUp will use different modes. In order to reliably control the render mode of your webdialogs under Windows you need to insert a special META compatibility tag:

// To always force the latest version available:
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>

// To lock to a specific IE version:
<meta http-equiv="X-UA-Compatible" content="IE=8"/>

Starting with SketchUp 2013, you can embed a special HTML link in your dialog that will launch Extension Warehouse and show a specified extension's page. This can be useful if your extension has a dependency on another one and you would like to direct the user to install that extension.

For example, to launch an extension's page whose URL is: extensions.sketchup.com/en/content/advanced-camera-tools The link would be:

Examples:

<a href="skp:launchEW@advanced-camera-tools">Get Advanced Camera Tools</a>

Version:

  • SketchUp 6.0

Instance Method Summary # collapse

Constructor Details

↑ #initialize(dialog_title = "", scrollable = true, pref_key = nil, width = 250, height = 250, left = 0, top = 0, resizable = true) ⇒ UI::WebDialog #initialize(properties) ⇒ UI::WebDialog

Note:

Since SU2017 the position and size of the dialog is DPI aware - it will scale to the DPI of the monitor automatically. Specify units as they would be on a traditional low-DPI monitor.

Note:

The browser which is embedded inside the dialog depends on the user's OS. On Mac, Safari is embedded, while on the PC whatever version of Internet Explorer is installed will be embedded.

The new method is used to create a new webdialog.

Examples:

dlg = UI::WebDialog.new("Show sketchup.com", true,
  "ShowSketchupDotCom", 739, 641, 150, 150, true);
dlg.set_url "http://www.sketchup.com"
dlg.show

Overloads:

  • #initialize(dialog_title = "", scrollable = true, pref_key = nil, width = 250, height = 250, left = 0, top = 0, resizable = true) ⇒ UI::WebDialog

    Parameters:

    • dialog_title (String) (defaults to: "") —

      The title to be displayed in the webdialog.

    • scrollable (Boolean) (defaults to: true) —

      true if you want to allow scrollbars, false if you do not want to allow scrollbars.

    • pref_key (String, nil) (defaults to: nil) —

      The registry entry where the location and size of the dialog will be saved. If preferences_key is not included, the location and size will not be stored.

    • width (Integer) (defaults to: 250) —

      The width of the webdialog.

    • height (Integer) (defaults to: 250) —

      The height of the webdialog.

    • left (Integer) (defaults to: 0) —

      The number of pixels from the left.

    • top (Integer) (defaults to: 0) —

      The number of pixels from the top.

    • resizable (Integer) (defaults to: true) —

      true if you want the webdialog to be resizable, false if not.

  • #initialize(properties) ⇒ UI::WebDialog

    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
    • :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
    • :full_security (Integer) — default: false
    • :mac_only_use_nswindow (Integer) — default: false

    Version:

    • SketchUp 7.0

Version:

  • SketchUp 6.0

Instance Method Details

↑ #add_action_callback(callback_name) {|dialog, params| ... } ⇒ Object

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

Use the skp:callback_method_name to invoke the callback method from your webdialog. Your JavaScript in the webdialog will invoke the callback method with a string representing arguments to the callback method.

Note that you're sending data down to Ruby as a single string that's passed via the window.location bar. In Internet Explorer on PC, there is a length limit of 2038 characters for this bar, so if you're needing to pass large data down you might consider using get_element_value to pull in a longer string from a hidden input field in the HTML.

Examples:

# In Ruby code...
dlg.add_action_callback("ruby_messagebox") {|dialog, params|
  UI.messagebox("You called ruby_messagebox with: " + params.to_s)
}

# JavaScript inside the page loaded into the WebDialog:
# window.location = 'skp:ruby_messagebox@Hello World';

Returns nil.

Parameters:

  • callback_name —

    The name of the callback method to be invoked from the webdialog.

Yields:

  • (dialog, params)

Yield Parameters:

  • dialog —

    The dialog.

  • params —

    Any parameters passed to the dialog from HTML. This is passed as a single string.

Returns:

  • nil

Version:

  • SketchUp 6.0

↑ #allow_actions_from_host(hostname) ⇒ Boolean

By default, actions are only allowed on the host where the webdialog is displayed. The allow_actions_from_host method is used to selectively allow actions to take place on a host remote from the host where the webdialog exists. If the webdialog is local, no remote host is allowed unless you use this method.

Examples:

dialog.allow_actions_from_host("sketchup.com")

Parameters:

  • hostname (String) —

    The name (domain) of the host that your webdialog can access safely.

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0

↑ #bring_to_front ⇒ UI::WebDialog

The bring_to_front method is used to bring the webdialog to the front of all the windows on the desktop. See show_modal for how to ensure that your WedDialogs are on top.

Examples:

dialog.bring_to_front

Returns:

Version:

  • SketchUp 6.0

↑ #close ⇒ nil

The close method is used to close the webdialog.

Examples:

dialog.close

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #execute_script(script) ⇒ Boolean

The execute_script method is used to execute a JavaScript string on the web dialog.

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

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0

↑ #get_default_dialog_color ⇒ String

The get_default_dialog_color method is used to get the default dialog color for the web dialog.

Examples:

dialog.get_default_dialog_color
#ece9d8

Returns:

  • (String) —

    a six digit hexidecimal number representing the color

Version:

  • SketchUp 6.0

↑ #get_element_value(element_id) ⇒ String

The get_element_value method is used to get a value, with a given element_id, from the web dialog's DOM.

Examples:

# In Ruby code:
dialog.get_element_value("myTextInput")

# In webdialog's HTML:
<input type="text" id="myTextInput" value="hello">

Parameters:

  • element_id (String) —

    The name of the element in your HTML code.

Returns:

  • (String) —

    a string containing the retrieved value.

Version:

  • SketchUp 6.0

↑ #max_height ⇒ Integer

The max_height method is used to get the maximum height that the user is allowed to resize the dialog to.

Examples:

max = dialog.max_height

Returns:

  • (Integer) —

    the maximum height in pixels

Version:

  • SketchUp 7.0

↑ #max_height=(height) ⇒ Integer

Note:

As of SU2017 this will automatically scale the height by the same factor as UI.scale_factor.

The max_height= method is used to set the maximum height that the user is allowed to resize the dialog to.

Examples:

dialog.max_height = 400

Parameters:

  • height (Integer) —

    The maximum height in pixels

Returns:

  • (Integer)

Version:

  • SketchUp 7.0

↑ #max_width ⇒ Integer

The max_width method is used to get the maximum width that the user is allowed to resize the dialog to.

Examples:

max = dialog.max_width

Returns:

  • (Integer) —

    the maximum width in pixels

Version:

  • SketchUp 7.0

↑ #max_width=(width) ⇒ Integer

Note:

As of SU2017 this will automatically scale the width by the same factor as UI.scale_factor.

The max_width= method is used to set the maximum width that the user is allowed to resize the dialog to.

Examples:

dialog.max_width = 500

Parameters:

  • width (Integer) —

    The maximum width in pixels

Returns:

  • (Integer)

Version:

  • SketchUp 7.0

↑ #min_height ⇒ Integer

The min_width method is used to get the minimum height that the user is allowed to resize the dialog to.

Examples:

min = dialog.min_height

Returns:

  • (Integer) —

    the minimum height in pixels

Version:

  • SketchUp 7.0

↑ #min_height=(height) ⇒ Integer

Note:

As of SU2017 this will automatically scale the height by the same factor as UI.scale_factor.

The min_height= method is used to set the minimum height that the user is allowed to resize the dialog to.

Examples:

dialog.min_height = 100

Parameters:

  • height (Integer) —

    The minimum height in pixels

Returns:

  • (Integer)

Version:

  • SketchUp 7.0

↑ #min_width ⇒ Integer

The min_width method is used to get the minimum width that the user is allowed to resize the dialog to.

Examples:

min = dialog.min_width

Returns:

  • (Integer) —

    the minimum width in pixels

Version:

  • SketchUp 7.0

↑ #min_width=(width) ⇒ Integer

Note:

As of SU2017 this will automatically scale the width by the same factor as UI.scale_factor.

The min_width= method is used to set the minimum width that the user is allowed to resize the dialog to.

Examples:

dialog.min_width = 200

Parameters:

  • width (Integer) —

    The minimum width in pixels

Returns:

  • (Integer)

Version:

  • SketchUp 7.0

↑ #navigation_buttons_enabled=(nav_buttons) ⇒ Boolean

The navigation_buttons_enabled= method is used to set whether the home, next, and back buttons are visible at the top of the WebDialog on the mac. This method has no use on the PC, as these buttons are never displayed.

Examples:

dialog.navigation_buttons_enabled = false

Returns:

  • (Boolean)

Version:

  • SketchUp 7.0

↑ #navigation_buttons_enabled? ⇒ Boolean

The navigation_buttons_enabled? method is used to get whether the home, next, and back buttons are visible at the top of the WebDialog on the mac. This method has no use on the PC, as these buttons are never displayed.

On the mac, this defaults to true for new WebDialogs.

Examples:

nav_buttons = dialog.navigation_buttons_enabled?

Returns:

  • (Boolean)

Version:

  • SketchUp 7.0

↑ #post_url(url, data) ⇒ nil

The post_url method is used to send the data to a url using the HTTP POST method.

Examples:

data = dialog.post_url("http://www.mydomain.com/formchecker.cgi",data)

Parameters:

  • url (String) —

    The url to send the data.

  • data (String) —

    The data to be sent.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #screen_scale_factor ⇒ Float

The screen_scale_factor method returns the ratio of screen pixels to logical window units (called 'points' on Mac) for the screen this WebDialog is currently in. On a retina screen Mac, this ratio will be greater than 1.0. On Windows this always return 1.0.

Examples:

factor = dialog.screen_scale_factor

Returns:

  • (Float) —

    screen scale factor

Version:

  • SketchUp 2014

↑ #set_background_color(color) ⇒ nil

The set_background_color method is used to set the background color for the webdialog.

Examples:

dlg.set_background_color("f3f0f0")

Parameters:

  • color (String) —

    A six digit hexidecimal color.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #set_file(filename, path = nil) ⇒ nil

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

Examples:

file = File.join(__dir__, 'mypage.html')
dialog.set_file(file)

Parameters:

  • filename (String) —

    The filename for the webdialog file (HTML file).

  • path (String) (defaults to: nil) —

    A path that filename is relative to.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #set_full_security ⇒ UI::WebDialog

The set_full_security method is used to place the WebDialog into a higher security mode where remote URLs and plugins (such as Flash) are not allowed inside the browser. This defaults to false when a new WebDialog is created.

Examples:

dialog.set_full_security

Returns:

Version:

  • SketchUp 7.0

↑ #set_html(html_string) ⇒ nil

The set_html method is used to load a webdialog 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 webdialog.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #set_on_close { ... } ⇒ nil

The set_on_close method is used to establish one or more activities to perform when the dialog closes (such as saving values stored in the dialog).

Examples:

dialog.set_on_close{ UI.messagebox("Closing the webDialog") }

Yields:

  • Ruby block to perform when the dialog closes.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #set_position(left, top) ⇒ nil

Note:

As of SU2017 this will automatically scale the x and y by the same factor as UI.scale_factor.

The set_position method is used to set the position of the webdialog 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:

  • (nil)

Version:

  • SketchUp 6.0

↑ #set_size(w, h) ⇒ nil

Note:

As of SU2017 this will automatically scale the width and height by the same factor as UI.scale_factor.

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

Examples:

dialog.set_size(320,240)

Parameters:

  • w (Integer) —

    Width of the webdialog.

  • h (Integer) —

    Height of the webdialog.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #set_url(url) ⇒ nil

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

Examples:

dialog.set_url "http://www.sketchup.com"

Parameters:

  • url (String) —

    The URL for a specific web site.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #show {|dialog| ... } ⇒ nil

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

Examples:

dialog.show {
  dialog.execute_script("alert(10)");
}

Yields:

  • (dialog) —

    (optional) Ruby code to perform when the dialog is first displayed.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #show_modal {|dialog| ... } ⇒ nil

The show_modal method is used to display a modal dialog box. In SketchUp 6 and 7, this behaves differently on Mac vs. PC. On the PC, it shows a truly modal dialog, meaning so long as the WebDialog is visible, no input can be performed elsewhere inside SketchUp. On the Mac, “modal” WebDialogs do not behave this way, but instead are “always on top” of other windows.

Examples:

dialog.show_modal {
  dialog.execute_script("alert(10)");
}

Yields:

  • (dialog) —

    (optional) Ruby code to perform when the dialog is first displayed.

Returns:

  • (nil)

Version:

  • SketchUp 6.0

↑ #visible? ⇒ Boolean

The visible? method is used to tell if the webdialog is currently shown.

Examples:

vis = dialog.visible?

Returns:

  • (Boolean)

Version:

  • SketchUp 6.0

↑ #write_image(image_path, option, top_left_x, top_left_y, bottom_right_x, bottom_right_y) ⇒ Object

The write_image method is used to grab a portion of the web dialog screen and save the image to the given file path.

Examples:

dialog.write_image('c:/grab.jpg', 70, 0, 0, 100, 100)
dialog.write_image('c:/grab.png', 4, 0, 0, 100, 100)

Parameters:

  • image_path (String) —

    The destination path of the saved image.

  • option (Integer) —

    Specifies what method to use when saving the image. For JPG/JPEG images, this specifies the image quality and can range from 1 to 100. For PNG images this specifies the compression algorithm: <4 (best speed), 4-8 (default), or >=9 (best compression).

  • top_left_x (Integer) —

    The x coordinate of the upper left corner of the region to grab.

  • top_left_y (Integer) —

    The x coordinate of the upper left corner of the region to grab.

  • bottom_right_x (Integer) —

    The x coordinate of the lower right corner of the region to grab.

  • bottom_right_y (Integer) —

    The x coordinate of the lower right corner of the region to grab.

Version:

  • SketchUp 7.1