sketchup-api-stubs 0.7.2 → 0.7.7

data/lib/sketchup-api-stubs/stubs/Sketchup/ViewObserver.rb

@@ -1,9 +1,11 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# This observer interface is implemented to react to view events. To implement
-# this observer, create a Ruby class of this type, override the desired
-# methods, and add an instance of the observer to the view object.
+# This observer interface is implemented to react to view events.
+#
+# @abstract To implement this observer, create a Ruby class of this type,
+#   override the desired methods, and add an instance of the observer to the
+#   view object.
 #
 # @example
 #   # This is an example of an observer that watches tool interactions.

data/lib/sketchup-api-stubs/stubs/UI/Command.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Command class is the preferred class for adding tools to the menus and
@@ -87,10 +87,10 @@ class UI::Command
   end
 
   # The large_icon= method is used to identify the icon file for the command's
-  # large icon. large icons should be 24x24 pixel images for best display
+  # large icon. large icons should be 32x32 pixel images for best display
   # quality.
   #
-  # Since SketchUp 2016 it is possible to provide vector images for the cursors.
+  # Since SketchUp 2016 it is possible to provide vector images for the command.
   # SVG format for Windows and PDF format for OS X. Since the vector images scale
   # for both small and large icon sizes, you may choose to use only one vector
   # image for both variants.
@@ -150,8 +150,11 @@ class UI::Command
   end
 
   # The {#set_validation_proc} method allows you to change whether the command
-  # is enabled, checked, etc. based on the user state. For example, you might
-  # want your command to be disabled unless the user has a current selection.
+  # is enabled, checked, etc. For instance, the command toggling a dialog window
+  # may be displayed as checked while the dialog is open.
+  #
+  # @bug On Mac the validation proc isn't called as often as it should. For
+  #   instance a selection change doesn't trigger it.
   #
   # @example
   #   # Create a command object.
@@ -168,6 +171,10 @@ class UI::Command
   #   }
   #   UI.menu("Draw").add_item(cmd)
   #
+  # @note Avoid disabling an command as it often isn't obvious to the user why
+  #   it is disabled. Prefer keeping the command enabled but show an error
+  #   message if pressed when it cannot be used.
+  #
   # @return [UI::Command]
   #
   # @version SketchUp 6.0
@@ -199,7 +206,7 @@ class UI::Command
   end
 
   # The small_icon= method is used to identify the icon file for the command's
-  # small icon. Small icons should be 16x16 pixel images for best display
+  # small icon. Small icons should be 24x24 pixel images for best display
   # quality.
   #
   # Since SketchUp 2016 it is possible to provide vector images for the cursors.

data/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Ruby HtmlDialog class allows you to create and interact with HTML dialog
@@ -14,11 +14,29 @@
 # "normal" DPI. The units given will be multiplied by the same factor as
 # returned by {UI.scale_factor}.
 #
+# For usage examples, including how to migrate from the old WebDialog class,
+# see https://github.com/SketchUp/htmldialog-examples.
+#
+# HtmlDialog uses the following versions of CEF (Chromium Embedded Framework):
+#
+# [SketchUp 2021.1]
+#   CEF 88
+# [SketchUp 2019.0]
+#   CEF 64
+# [SketchUp 2018.0]
+#   CEF 56
+# [SketchUp 2017.0]
+#   CEF 52
+#
 # @version SketchUp 2017
 class UI::HtmlDialog
 
   # Constants
 
+  CEF_VERSION = nil # Stub value.
+
+  CHROME_VERSION = nil # Stub value.
+
   STYLE_DIALOG = nil # Stub value.
   STYLE_UTILITY = nil # Stub value.
   STYLE_WINDOW = nil # Stub value.
@@ -78,11 +96,16 @@ class UI::HtmlDialog
   # 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.
   #
+  # @bug Prior to SketchUp 2021.1, on Mac, the focus the was not being set
+  #   on the {UI::HtmlDialog}.
+  #
   # @example
   #   dialog.bring_to_front
   #
   # @return [nil]
   #
+  # @see Sketchup.focus
+  #
   # @version SketchUp 2017
   def bring_to_front
   end
@@ -94,7 +117,7 @@ class UI::HtmlDialog
   # @example
   #   dialog.center
   #
-  # @return [true]
+  # @return [true] This always return true, never false.
   #
   # @version SketchUp 2017
   def center
@@ -127,8 +150,54 @@ class UI::HtmlDialog
   def execute_script(script)
   end
 
+  # The {#get_content_size} method is used to get the content size of the HtmlDialog, in logical pixels.
+  #
+  # @example
+  #   width, height = dialog.get_content_size
+  #
+  # @return [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
+  def get_content_size
+  end
+
+  # The {#get_position} method is used to get the position of the HtmlDialog
+  # relative to the screen, in logical pixels.
+  #
+  # @example
+  #   left, top = dialog.get_position
+  #
+  # @return [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
+  def get_position
+  end
+
+  # The {#get_size} method is used to get the outer frame size of the HtmlDialog, in logical pixels.
+  #
+  # @example
+  #   width, height = dialog.get_size
+  #
+  # @return [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
+  def get_size
+  end
+
   # The new method is used to create a new HtmlDialog.
   #
+  # When +use_content_size+ is 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:
   #
@@ -141,7 +210,7 @@ class UI::HtmlDialog
   # [+UI::HtmlDialog::STYLE_UTILITY+]  HtmlDialog is shown with small titlebar
   #                                    and stays on top of SketchUp.
   #
-  # @example
+  # @example With options Hash
   #   dialog = UI::HtmlDialog.new(
   #   {
   #     :dialog_title => "Dialog Example",
@@ -161,10 +230,38 @@ class UI::HtmlDialog
   #   dialog.set_url("http://www.sketchup.com")
   #   dialog.show
   #
+  # @example 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
+  #
   # @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.
   #
+  # @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.
+  #
   # @option properties [String] :dialog_title
   #
   # @option properties [String] :preferences_key
@@ -173,6 +270,8 @@ class UI::HtmlDialog
   #
   # @option properties [Boolean] :resizable (true)
   #
+  # @option properties [Boolean] :use_content_size (false)
+  #
   # @option properties [Integer] :width (250)
   #
   # @option properties [Integer] :height (250)
@@ -217,6 +316,23 @@ class UI::HtmlDialog
   def set_can_close
   end
 
+  # The {#set_content_size} method is used to set the content size of the HtmlDialog, in logical pixels.
+  #
+  # @example
+  #   dialog.set_content_size(600, 400)
+  #
+  # @param [Integer] width
+  #   Content width of the HtmlDialog.
+  #
+  # @param [Integer] height
+  #   Content height of the HtmlDialog.
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.1
+  def set_content_size(width, height)
+  end
+
   # The {#set_file} method is used to identify a local HTML file to display in the
   # HtmlDialog.
   #
@@ -265,6 +381,9 @@ class UI::HtmlDialog
   # The {#set_position} method is used to set the position of the HtmlDialog
   # relative to the screen, in pixels.
   #
+  # @bug Prior to SketchUp 2021.1, on Windows, calling this method incorrectly
+  #   set the focus on the {UI::HtmlDialog}.
+  #
   # @example
   #   dialog.set_position(100, 50)
   #
@@ -274,24 +393,27 @@ class UI::HtmlDialog
   # @param [Integer] top
   #   The number of pixels from the top of the screen.
   #
-  # @return [true]
+  # @return [true] This always return true, never false.
   #
   # @version SketchUp 2017
   def set_position(left, top)
   end
 
-  # The {#set_size} method is used to set the size of the HtmlDialog, in pixels.
+  # The {#set_size} method is used to set the outer frame size of the HtmlDialog, in pixels.
+  #
+  # @bug Prior to SketchUp 2021.1, on Windows, calling this method incorrectly
+  #   set the focus on the {UI::HtmlDialog}.
   #
   # @example
   #   dialog.set_size(320, 240)
   #
   # @param [Integer] width
-  #   Width of the HtmlDialog.
+  #   Outer frame width of the HtmlDialog.
   #
   # @param [Integer] height
-  #   Height of the HtmlDialog.
+  #   Outer frame height of the HtmlDialog.
   #
-  # @return [true]
+  # @return [true] This always return true, never false.
   #
   # @version SketchUp 2017
   def set_size(width, height)
@@ -301,7 +423,7 @@ class UI::HtmlDialog
   # specific URL. This method allows you to load web sites in a HtmlDialog.
   #
   # @example
-  #   dialog.set_url("http://www.sketchup.com")
+  #   dialog.set_url("https://www.sketchup.com")
   #
   # @param [String] url
   #   The URL for a specific web site.
@@ -343,7 +465,7 @@ class UI::HtmlDialog
   #     dialog.bring_to_front
   #   else
   #     dialog = UI::HtmlDialog.new
-  #     dialog.set_url("http://www.sketchup.com")
+  #     dialog.set_url("https://www.sketchup.com")
   #     dialog.show
   #   end
   #

data/lib/sketchup-api-stubs/stubs/UI/Notification.rb

@@ -1,10 +1,26 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# UI::Notification objects allows you to show native notifications in the
-# desktop, they are positioned in the top right of your screen, they can be
-# customized to have a message, icon and accept and/or dismiss buttons with
-# callback blocks.
+# {UI::Notification} objects allows you to show native notifications in the
+# desktop. Notifications can have a message, icon and accept and/or dismiss
+# buttons with callback blocks.
+#
+# @example
+#   # For consistency, the accept (yes) and the dismiss (no) buttons
+#   # are always displayed in the same order.
+#   message = "A new version of pizza is available. Install now?"
+#   @notification = UI::Notification.new(sketchup_extension, message)
+#   @notification.on_accept("Pizza!") { puts "Pizza" }
+#   @notification.on_dismiss("No thanks") { puts "No pizza" }
+#   @notification.show
+#
+#   # The two options are however not treated differently by SketchUp and can
+#   # also be used for questions with no strict yes/no answer.
+#   message = "Pizza clashes with health. Select which one to keep."
+#   @notification = UI::Notification.new(sketchup_extension, message)
+#   @notification.on_accept("Pizza") { puts "Pizza" }
+#   @notification.on_dismiss("Health") { puts "Salad" }
+#   @notification.show
 #
 # @version SketchUp 2017
 class UI::Notification
@@ -15,9 +31,10 @@ class UI::Notification
   # the file system path.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon", "icon Tooltip")
-  #   puts "Icon Name: #{notification.icon_name}"
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon",
+  #       "Icon Tooltip")
+  #   puts "Icon Name: #{@notification.icon_name}"
+  #   @notification.show
   #
   # @return [String]
   #
@@ -29,9 +46,9 @@ class UI::Notification
   # has to be a local filesystem path.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world")
-  #   notification.icon_name = "/path/to/icon"
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world")
+  #   @notification.icon_name = "/path/to/icon"
+  #   @notification.show
   #
   # @param [String] icon_name
   #   String providing the icon filesystem path.
@@ -46,9 +63,10 @@ class UI::Notification
   # the icon.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon", "icon Tooltip")
-  #   puts "Tooltip: #{notification.icon_tooltip}"
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon",
+  #       "Icon Tooltip")
+  #   puts "Tooltip: #{@notification.icon_tooltip}"
+  #   @notification.show
   #
   # @return [String]
   #
@@ -60,9 +78,9 @@ class UI::Notification
   # icon.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world")
-  #   notification.icon_tooltip = "icon Tooltip"
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world")
+  #   @notification.icon_tooltip = "icon Tooltip"
+  #   @notification.show
   #
   # @param [String] icon_tooltip
   #   String providing the new icon Tooltip.
@@ -73,39 +91,48 @@ class UI::Notification
   def icon_tooltip=(icon_tooltip)
   end
 
-  # The new method is used to create a new {UI::Notification}.
+  # Creates a new {UI::Notification} object.
+  #
+  # @bug Prior to SketchUp 2018 messages could only be 3 lines long on Windows
+  #   and 2 lines on Mac. Now the notification expands to fit its content.
   #
-  # In order to insert line breaks into the message you need to use +\\r\\n+.
+  # @bug Prior to SketchUp 2021.1 SketchUp could crash if the {UI::Notification} object is garbaged
+  #   collected while it has notifications displayed on the screen. This could happen if the
+  #   {UI::Notification} object was assigned to a local variable. The local variable would go out of
+  #   scope and the garbage collector might collect it before the callbacks are invoked.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon", "icon Tooltip")
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon",
+  #       "Icon Tooltip")
+  #   @notification.show
+  #
+  # @note In order to insert line breaks into the message you need to use +\\r\\n+.
   #
   # @param [SketchupExtension] sketchup_extension
-  #   Required sketchup_extension
-  #   to identify the sender.
+  #   {SketchupExtension} instance used to identify
+  #   the source of the notification.
   #
   # @param [String] message
-  #   Optionally assign the message.
+  #   Message to display.
   #
   # @param [String] icon_name
-  #   Optionally set a path to an image.
+  #   Path to an icon to display along with the message.
   #
   # @param [String] icon_tooltip
-  #   Optionally set an image tooltip.
+  #   Tooltip for the icon.
   #
   # @return [UI::Notification]
   #
   # @version SketchUp 2017
-  def initialize(sketchup_extension, message, icon_name, icon_tooltip)
+  def initialize(sketchup_extension, message = nil, icon_name = nil, icon_tooltip = nil)
   end
 
   # Gets the message as string.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension)
-  #   puts "This is the current message: #{notification.message}"
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension)
+  #   puts "This is the current message: #{@notification.message}"
+  #   @notification.show
   #
   # @return [String]
   #
@@ -113,13 +140,16 @@ class UI::Notification
   def message
   end
 
-  # Sets a new message, notifications are meant for quick & brief messages,
-  # remember that they are dismissed automatically.
+  # Sets a new message. Notifications are meant for quick and brief messages.
+  # These message disappear automatically after a short while if they are not
+  # interacted with.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension)
-  #   notification.message = "Hello world"
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension)
+  #   @notification.message = "Hello world"
+  #   @notification.show
+  #
+  # @note In order to insert line breaks into the message you need to use +\\r\\n+.
   #
   # @param [String] message
   #   String providing the new message.
@@ -133,12 +163,15 @@ class UI::Notification
   # Shows a button in the notification with the given title and callback block,
   # both arguments are required.
   #
+  # @bug Prior to SketchUp 2019 both the accept and dismiss buttons were
+  #   displayed, even if only one had been implemented.
+  #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world")
-  #   notification.on_accept("Accept")  do |notification, title|
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world")
+  #   @notification.on_accept("Accept")  do |notification, title|
   #      puts "The user pressed [#{title}] with message #{notification.message}"
   #   end
-  #   notification.show
+  #   @notification.show
   #
   # @param [String] title
   #   Sets the title of the button.
@@ -159,11 +192,11 @@ class UI::Notification
   # Returns the accept's button title.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world")
-  #   notification.on_accept("Accept")  do |notification, title|
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world")
+  #   @notification.on_accept("Accept")  do |notification, title|
   #      puts "The user pressed #{notification.on_accept_title}"
   #   end
-  #   notification.show
+  #   @notification.show
   #
   # @return [String]
   #
@@ -171,15 +204,20 @@ class UI::Notification
   def on_accept_title
   end
 
-  # Shows a button in the notification with the given title and callback block,
-  # both arguments are required.
+  # Shows a button in the notification with the given title and callback block.
+  # Both arguments are required. This callback is only called if you press the
+  # Dismiss button, not when the time runs out and the notification automatically
+  # disappears.
+  #
+  # @bug Prior to SketchUp 2019 both the accept and dismiss buttons were
+  #   displayed, even if only one had been implemented.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world")
-  #   notification.on_dismiss("Close")  do |notification, title|
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world")
+  #   @notification.on_dismiss("Close")  do |notification, title|
   #      puts "The user pressed [#{title}] with message #{notification.message}"
   #   end
-  #   notification.show
+  #   @notification.show
   #
   # @param [String] title
   #   Sets the title of the button.
@@ -200,11 +238,11 @@ class UI::Notification
   # Returns the dismiss's button title.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world")
-  #   notification.on_dismiss("Close")  do |notification, title|
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world")
+  #   @notification.on_dismiss("Close")  do |notification, title|
   #      puts "The user pressed #{notification.on_dismiss_title}"
   #   end
-  #   notification.show
+  #   @notification.show
   #
   # @return [String]
   #
@@ -212,13 +250,15 @@ class UI::Notification
   def on_dismiss_title
   end
 
-  # Shows the notification in the top right of the screen, the notifications will
-  # be ordered from top to bottom if multiple notifications are shown, it will
-  # automatically be dismissed if no action is taken.
+  # Shows the notification. If not interacted with, the notification will
+  # disappear without calling any callbacks.
+  #
+  # @bug If assigned to a local variable SketchUp might crash prior to SketchUp 2021.1.
+  #   See {#initialize} for more details.
   #
   # @example
-  #   notification = UI::Notification.new(sketchup_extension, "Hello world")
-  #   notification.show
+  #   @notification = UI::Notification.new(sketchup_extension, "Hello world")
+  #   @notification.show
   #
   # @return [Boolean]
   #