sketchup-api-stubs 0.3.1 → 0.4.0

data/SketchUp/Sketchup/UVHelper.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The UV Helper class contains methods allowing you to determine the location

data/SketchUp/Sketchup/Vertex.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # A Vertex. A Vertex represents the end of an Edge or a point inside a Face.

data/SketchUp/Sketchup/View.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This class contains methods to manipulate the current point of view of the
@@ -80,15 +80,14 @@ class Sketchup::View
   def camera
   end
 
-  # The camera= method is used to set the camera for the view. If a transition
+  # The {#camera=} method is used to set the camera for the view. If a transition
   # time is given, then it will animate the transition from the current camera
   # to the new one.
   #
   # @example
-  #   camera2 = Sketchup.Camera.new
-  #   model = Sketchup.active_model
-  #   view = model.active_view
-  #   status = view.camera=camera2
+  #   camera = Sketchup::Camera.new([5, 5, 9], [5, 10, 0], Z_AXIS)
+  #   view = Sketchup.active_model.active_view
+  #   view.camera = camera
   #
   # @overload camera=(camera)
   #
@@ -333,16 +332,16 @@ class Sketchup::View
   # @param [Array<Geom::Point3d>] pts
   #   An array of Point3d objects.
   #
-  # @param [Integer] pointstyle
-  #   Style of the point. 1 = open square,
-  #   2 = filled square, 3 = "+", 4 = "X", 5 = "*",
-  #   6 = open triangle, 7 = filled triangle.
+  # @param [Integer] pointsize
+  #   Size of the point in pixels.
   #
   # @param [Sketchup::Color] pointcolor
   #   Color of the point.
   #
-  # @param [Integer] pointsize
-  #   Size of the point in pixels.
+  # @param [Integer] pointstyle
+  #   Style of the point. 1 = open square,
+  #   2 = filled square, 3 = "+", 4 = "X", 5 = "*",
+  #   6 = open triangle, 7 = filled triangle.
   #
   # @return [Sketchup::View] a View object
   #
@@ -404,31 +403,34 @@ class Sketchup::View
   # @note Under Windows the font name must be less than 32 characters - due to
   #   system limitations.
   #
-  # @option options [Sketchup::Color] :color The color to draw the text with.
+  # @note As of SU2017 this will automatically scale the font-size by the same
+  #   factor as {UI.scale_factor}.
   #
-  # @option options [Integer] :align The text alignment, one of the following
-  #   constants +TextAlignLeft+, +TextAlignCenter+ or +TextAlignRight+.
+  # @option options [String] :font The name of the font to use. If it does not
+  #   exist on the system, a default font will be used instead.
   #
-  # @option options [Boolean] :italic Controls the Italic property of the font.
+  # @option options [Integer] :size The size of the font in points
   #
   # @option options [Boolean] :bold Controls the Bold property of the font.
   #
-  # @option options [Integer] :size The size of the font in points
-  #
-  # @option options [String] :font The name of the font to use. If it does not
-  #   exist on the system, a default font will be used instead.
+  # @option options [Boolean] :italic Controls the Italic property of the font.
   #
-  # @param [Hash] options
-  #   The text can be customized by providing a hash or
-  #   named arguments of options. Available from SketchUp 2016.
+  # @option options [Sketchup::Color] :color The color to draw the text with.
   #
-  # @param [String] text
-  #   The text string to draw.
+  # @option options [Integer] :align The text alignment, one of the following
+  #   constants +TextAlignLeft+, +TextAlignCenter+ or +TextAlignRight+.
   #
   # @param [Geom::Point3d] point
   #   A Point3d object representing a 2D coordinate
   #   in view space.
   #
+  # @param [String] text
+  #   The text string to draw.
+  #
+  # @param [Hash] options
+  #   The text can be customized by providing a hash or
+  #   named arguments of options. Available from SketchUp 2016.
+  #
   # @return [Sketchup::View]
   #
   # @version SketchUp 6.0
@@ -545,12 +547,12 @@ class Sketchup::View
   # @param [Numeric] x
   #   A x value.
   #
-  # @param [Sketchup::InputPoint] inputpoint1
-  #   An InputPoint object.
-  #
   # @param [Numeric] y
   #   A y value.
   #
+  # @param [Sketchup::InputPoint] inputpoint1
+  #   An InputPoint object.
+  #
   # @return [Sketchup::InputPoint]
   #
   # @version SketchUp 6.0
@@ -619,6 +621,9 @@ class Sketchup::View
   # @example
   #   view.line_width = width
   #
+  # @note As of SU2017 this will automatically scale the line width by the same
+  #   factor as {UI.scale_factor}.
+  #
   # @param [Integer] width
   #   The width in pixels.
   #
@@ -726,7 +731,10 @@ class Sketchup::View
   # desired size in pixels.
   #
   # @example
-  #   size = view.pixels_to_model pixels, point
+  #   size = view.pixels_to_model(pixels, point)
+  #
+  # @note As of SU2017 this will automatically scale the pixel-size by the same
+  #   factor as {UI.scale_factor}.
   #
   # @param [Numeric] pixels
   #   The pixel size.
@@ -880,32 +888,9 @@ class Sketchup::View
   #
   # If a hash is passed as the first parameter, then the contents of that hash
   # define how the image is exported.
-  # The keys are:
-  #  - filename        The filename for the saved image.
-  #  - width           (optional) Width in pixels (max 16000).
-  #  - height          (optional) Height in pixels (max 16000).
-  #  - antialias       (optional) true or false
-  #  - compression     (optional) Float compression factor for JPEG images,
-  #                    between 0.0 and 1.0
-  #  - transparent     true or false
-  #
-  # @example
-  #   depth = 100
-  #   width = 100
-  #   model = Sketchup.active_model
-  #   entities = model.active_entities
-  #   pts = []
-  #   pts[0] = [0, 0, 0]
-  #   pts[1] = [width, 0, 0]
-  #   pts[2] = [width, depth, 0]
-  #   pts[3] = [0, depth, 0]
-  #   # Add the face to the entities in the model
-  #   face = entities.add_face pts
-  #   UI.messagebox "Now Lets Write the Image"
-  #   view = model.active_view
-  #   # Puts in SketchUp install directory by default
-  #   status = view.write_image "test.jpg"
-  #   keys = {
+  #
+  # @example With options hash.
+  #   options = {
   #     :filename => "c:/tmp/write_image.png",
   #     :width => 640,
   #     :height => 480,
@@ -915,7 +900,15 @@ class Sketchup::View
   #   }
   #   model = Sketchup.active_model
   #   view = model.active_view
-  #   view.write_image keys
+  #   view.write_image(options)
+  #
+  # @example Legacy arguments variant.
+  #   filename => "c:/tmp/write_image.png"
+  #   antialias => false
+  #   compression => 0.9
+  #   model = Sketchup.active_model
+  #   view = model.active_view
+  #   view.write_image(filename, 640, 480, antialias, compression)
   #
   # @overload write_image(filename, width = view.vpwidth, height = view.vpheight, antialias = false, compression = 1.0)
   #
@@ -933,7 +926,15 @@ class Sketchup::View
   #
   # @overload write_image(options)
   #
+  #   @version SketchUp 7
   #   @param [Hash] options
+  #   @option options [String] filename  The filename for the saved image.
+  #   @option options [Integer] width (#vpwidth)  Width in pixels (max 16000).
+  #   @option options [Integer] height (#vpheight)  Height in pixels (max 16000).
+  #   @option options [Boolean] antialias (false)
+  #   @option options [Float] compression (1.0)  Compression factor for JPEG,
+  #     images between 0.0 and 1.0
+  #   @option options [Boolean] transparent (false) Added in SketchUp 8.
   #
   # @return [Boolean]
   #

data/SketchUp/Sketchup/ViewObserver.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to view events. To implement
@@ -26,7 +26,7 @@ class Sketchup::ViewObserver
   #
   # @example
   #   def onViewChanged(view)
-  #     pust "onViewChanged: #{view}"
+  #     puts "onViewChanged: #{view}"
   #   end
   #
   # @param [Sketchup::View] view

data/SketchUp/UI/Command.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Command class is the preferred class for adding tools to the menus and
@@ -49,6 +49,9 @@ class UI::Command
   #   cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") }
   #   testmenu.add_item cmd
   #
+  # @note Prior to SketchUp 2019 it was not possible to sub-class {UI::Command}
+  #   due to a bug in how SketchUp initialized the class.
+  #
   # @param [String] menutext
   #   The text that will appear for this command's menu item
   #   if it appears on a menu.

data/SketchUp/UI/HtmlDialog.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Ruby HtmlDialog class allows you to create and interact with HTML dialog
@@ -9,6 +9,11 @@
 # {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 {UI.scale_factor}.
+#
 # @version SketchUp 2017
 class UI::HtmlDialog
 
@@ -33,6 +38,11 @@ class UI::HtmlDialog
   # Basic types such as booleans, numbers, strings, arrays and hashes are
   # automatically converted between Ruby and JavaScript.
   #
+  # @example Ruby Code
+  #   dialog.add_action_callback("say") { |action_context, param1, param2|
+  #     puts "JavaScript said #{param1} and #{param2}"
+  #   }
+  #
   # @example JavaScript
   #   sketchup.say('Hello World', 42);
   #
@@ -43,11 +53,6 @@ class UI::HtmlDialog
   #     }
   #   });
   #
-  # @example Ruby Code
-  #   dialog.add_action_callback("say") { |action_context, param1, param2|
-  #     puts "JavaScript said #{param1} and #{param2}"
-  #   }
-  #
   # @note When an HtmlDialog is closed, all callbacks to that instance are
   #   cleared. Re-attach them if you need to open the dialog again.
   #
@@ -62,11 +67,11 @@ class UI::HtmlDialog
   #
   # @yield [action_context, ...]
   #
-  # @yieldparam [Object] ...
-  #   The parameters sent from JavaScript.
-  #
   # @yieldparam [Object] action_context
   #   action_context  Currently unused.
+  #
+  # @yieldparam [Object] ...
+  #   The parameters sent from JavaScript.
   def add_action_callback(callback_name)
   end
 
@@ -156,9 +161,9 @@ class UI::HtmlDialog
   #   dialog.set_url("http://www.sketchup.com")
   #   dialog.show
   #
-  # @option properties [Integer] :width (250)
-  #
-  # @option properties [Integer] :max_height (-1)
+  # @note Prior to SketchUp 2019 the +:width+ and +:height+ provided is ignored
+  #   if a +:preference_key+ is also present. To work around this bug on older
+  #   versions use {#set_size} after you initialize the dialog.
   #
   # @option properties [String] :dialog_title
   #
@@ -168,9 +173,9 @@ class UI::HtmlDialog
   #
   # @option properties [Boolean] :resizable (true)
   #
-  # @option properties [Integer] :height (250)
+  # @option properties [Integer] :width (250)
   #
-  # @option properties [Integer] :max_width (-1)
+  # @option properties [Integer] :height (250)
   #
   # @option properties [Integer] :left (0)
   #
@@ -180,6 +185,10 @@ class UI::HtmlDialog
   #
   # @option properties [Integer] :min_height (0)
   #
+  # @option properties [Integer] :max_width (-1)
+  #
+  # @option properties [Integer] :max_height (-1)
+  #
   # @option properties [Integer] :style (UI::HtmlDialog::STYLE_DIALOG)
   #
   # @param [Hash] properties

data/SketchUp/UI/Notification.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # UI::Notification objects allows you to show native notifications in the
@@ -47,7 +47,7 @@ class UI::Notification
   #
   # @example
   #   notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon", "icon Tooltip")
-  #   puts "Tooltip: " notification.icon_tooltip
+  #   puts "Tooltip: #{notification.icon_tooltip}"
   #   notification.show
   #
   # @return [String]
@@ -81,18 +81,18 @@ class UI::Notification
   #   notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon", "icon Tooltip")
   #   notification.show
   #
-  # @param [String] icon_tooltip
-  #   Optionally set an image tooltip.
-  #
-  # @param [String] icon_name
-  #   Optionally set a path to an image.
+  # @param [SketchupExtension] sketchup_extension
+  #   Required sketchup_extension
+  #   to identify the sender.
   #
   # @param [String] message
   #   Optionally assign the message.
   #
-  # @param [SketchupExtension] sketchup_extension
-  #   Required sketchup_extension
-  #   to identify the sender.
+  # @param [String] icon_name
+  #   Optionally set a path to an image.
+  #
+  # @param [String] icon_tooltip
+  #   Optionally set an image tooltip.
   #
   # @return [UI::Notification]
   #

data/SketchUp/UI/Toolbar.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Toolbar class contains methods to create and manipulate SketchUp

data/SketchUp/UI/WebDialog.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2017 Trimble Inc.
+# Copyright:: Copyright 2019 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Ruby WebDialog class allows you to create and interact with DHTML dialog
@@ -75,12 +75,12 @@ class UI::WebDialog
   #
   # @yield [dialog, params]
   #
+  # @yieldparam dialog
+  #   The dialog.
+  #
   # @yieldparam params
   #   Any parameters passed to the dialog from HTML.
   #   This is passed as a single string.
-  #
-  # @yieldparam dialog
-  #   The dialog.
   def add_action_callback(callback_name)
   end
 
@@ -177,20 +177,20 @@ class UI::WebDialog
 
   # The +new+ method is used to create a new webdialog.
   #
-  # 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 that 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.
-  #
   # @example
   #   dlg = UI::WebDialog.new("Show sketchup.com", true,
   #     "ShowSketchupDotCom", 739, 641, 150, 150, true);
   #   dlg.set_url "http://www.sketchup.com"
   #   dlg.show
   #
+  # @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.
+  #
   # @overload initialize(dialog_title = "", scrollable = true, pref_key = nil, width = 250, height = 250, left = 0, top = 0, resizable = true)
   #
   #   @param [String] dialog_title   The title to be displayed in the webdialog.
@@ -251,6 +251,9 @@ class UI::WebDialog
   # @example
   #   dialog.max_height = 400
   #
+  # @note As of SU2017 this will automatically scale the height by the same
+  #   factor as {UI.scale_factor}.
+  #
   # @param [Integer] height
   #   The maximum height in pixels
   #
@@ -278,6 +281,9 @@ class UI::WebDialog
   # @example
   #   dialog.max_width = 500
   #
+  # @note As of SU2017 this will automatically scale the width by the same factor
+  #   as {UI.scale_factor}.
+  #
   # @param [Integer] width
   #   The maximum width in pixels
   #
@@ -305,6 +311,9 @@ class UI::WebDialog
   # @example
   #   dialog.min_height = 100
   #
+  # @note As of SU2017 this will automatically scale the height by the same
+  #   factor as {UI.scale_factor}.
+  #
   # @param [Integer] height
   #   The minimum height in pixels
   #
@@ -332,6 +341,9 @@ class UI::WebDialog
   # @example
   #   dialog.min_width = 200
   #
+  # @note As of SU2017 this will automatically scale the width by the same factor
+  #   as {UI.scale_factor}.
+  #
   # @param [Integer] width
   #   The minimum width in pixels
   #
@@ -486,6 +498,9 @@ class UI::WebDialog
   # @example
   #   dialog.set_position(100,50)
   #
+  # @note As of SU2017 this will automatically scale the x and y by the same
+  #   factor as {UI.scale_factor}.
+  #
   # @param [Integer] left
   #   The number of pixels from the left.
   #
@@ -503,6 +518,9 @@ class UI::WebDialog
   # @example
   #   dialog.set_size(320,240)
   #
+  # @note As of SU2017 this will automatically scale the width and height by the
+  #   same factor as {UI.scale_factor}.
+  #
   # @param [Integer] w
   #   Width of the webdialog.
   #
@@ -586,10 +604,6 @@ class UI::WebDialog
   #   dialog.write_image('c:/grab.jpg', 70, 0, 0, 100, 100)
   #   dialog.write_image('c:/grab.png', 4, 0, 0, 100, 100)
   #
-  # @param [Integer] top_left_x
-  #   The x coordinate of the upper left corner of the
-  #   region to grab.
-  #
   # @param [String] image_path
   #   The destination path of the saved image.
   #
@@ -600,16 +614,20 @@ class UI::WebDialog
   #   the compression algorithm: <4 (best speed), 4-8
   #   (default), or >=9 (best compression).
   #
-  # @param [Integer] bottom_right_y
-  #   The x coordinate of the lower right corner of the
+  # @param [Integer] top_left_x
+  #   The x coordinate of the upper left corner of the
+  #   region to grab.
+  #
+  # @param [Integer] top_left_y
+  #   The x coordinate of the upper left corner of the
   #   region to grab.
   #
   # @param [Integer] bottom_right_x
   #   The x coordinate of the lower right corner of the
   #   region to grab.
   #
-  # @param [Integer] top_left_y
-  #   The x coordinate of the upper left corner of the
+  # @param [Integer] bottom_right_y
+  #   The x coordinate of the lower right corner of the
   #   region to grab.
   #
   # @version SketchUp 7.1