sketchup-api-stubs 0.7.0 → 0.7.5

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

@@ -1,9 +1,11 @@
 # Copyright:: Copyright 2020 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

@@ -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

@@ -14,6 +14,9 @@
 # "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.
+#
 # @version SketchUp 2017
 class UI::HtmlDialog
 
@@ -141,7 +144,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 +164,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
@@ -301,7 +332,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 +374,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

@@ -2,9 +2,25 @@
 # 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.
+# 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
@@ -77,6 +93,9 @@ class UI::Notification
   #
   # In order to insert line breaks into the message you need to use +\\r\\n+.
   #
+  # @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.
+  #
   # @example
   #   notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon", "icon Tooltip")
   #   notification.show
@@ -113,8 +132,8 @@ 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 & brief messages.
+  # Remember that they disappear automatically.
   #
   # @example
   #   notification = UI::Notification.new(sketchup_extension)
@@ -133,6 +152,9 @@ 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|
@@ -171,8 +193,13 @@ 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")
@@ -212,9 +239,8 @@ 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.
   #
   # @example
   #   notification = UI::Notification.new(sketchup_extension, "Hello world")

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

@@ -5,7 +5,7 @@
 # boxes from Ruby.
 #
 # If your goal is to simply display a website to your users, consider using
-# UI.getURL, which will show them a web page in their default browser rather
+# {UI.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:
@@ -428,7 +428,7 @@ class UI::WebDialog
   def set_background_color(color)
   end
 
-  # The #{set_file} method is used to identify a local HTML file to display in
+  # The {#set_file} method is used to identify a local HTML file to display in
   # the webdialog.
   #
   # @example

data/lib/sketchup-api-stubs/stubs/_top_level.rb

@@ -147,6 +147,8 @@
   PAGE_USE_ALL = nil # Stub value.
   PAGE_USE_CAMERA = nil # Stub value.
   PAGE_USE_HIDDEN = nil # Stub value.
+  PAGE_USE_HIDDEN_GEOMETRY = nil # Stub value.
+  PAGE_USE_HIDDEN_OBJECTS = nil # Stub value.
   PAGE_USE_LAYER_VISIBILITY = nil # Stub value.
   PAGE_USE_RENDERING_OPTIONS = nil # Stub value.
   PAGE_USE_SECTION_PLANES = nil # Stub value.

data/lib/sketchup-api-stubs/stubs/geom.rb

@@ -167,6 +167,9 @@ module Geom
   # The {.linear_combination} method is used to compute the linear combination of
   # points or vectors.
   #
+  # A linear combination is a standard term for vector math. It is defined as
+  # vector = weight1 * vector1 + weight2 * vector2.
+  #
   # @example
   #   point1 = Geom::Point3d.new(1, 1, 1)
   #   point2 = Geom::Point3d.new(10, 10, 10)

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

@@ -306,7 +306,7 @@ module Sketchup
   def self.format_angle(number)
   end
 
-  # The #{format_area} method formats a number as an area using the current units
+  # The {.format_area} method formats a number as an area using the current units
   # settings.
   #
   # The +number+ must be in square inches.
@@ -363,7 +363,7 @@ module Sketchup
   def self.format_length(*args)
   end
 
-  # The #{format_volume} method formats a number as a volume using the current
+  # The {.format_volume} method formats a number as a volume using the current
   # units settings.
   #
   # The +number+ must be in cubic inches.
@@ -427,10 +427,9 @@ module Sketchup
   # The os_language method returns the language code for the language SketchUp
   # is running in. This is an alias for the get_locale method.
   #
-  # Valid return values are: en-US, fr, it, de, es, ja, ko, zh-CN, zh-TW,
-  # pt-BR, nl, ru.
-  # If the OS language does not have corresponding folder and files in the
-  # SketchUp Resources folder, the returned language is, by default, en-US.
+  # Examples of return values are: en-US, fr, it, de, es, ja, ko, zh-CN, zh-TW,
+  # pt-BR, nl, ru and sv. For an up to date list os supported languages, see
+  # the SketchUp download page.
   #
   # @example
   #   language = Sketchup.os_language
@@ -461,7 +460,7 @@ module Sketchup
   # The get_shortcuts method retrieves an array of all keyboard shortcuts
   # currently registered with SketchUp. Each shortcut is returned as a
   # string with the shortcut and the command separated by a tab, similar
-  # to "Ctrl+A\tEdit/Select All"
+  # to "Ctrl+A\\tEdit/Select All"
   #
   # @example
   #   shortcuts = Sketchup.get_shortcuts
@@ -502,9 +501,15 @@ module Sketchup
   #     UI.messagebox("Error during unzip: " + error)
   #   end
   #
-  # @param [String] filename
+  # @param [String] filepath
   #   The path to the RBZ or ZIP file to install.
   #
+  # @param [Boolean] show_warning
+  #   Whether to warn the user not to install untrusted extensions.
+  #   In certain cases the warning can be confusing and redundant, e.g. when
+  #   automatically updating a trusted extension. When the user has selected
+  #   the archive themselves, it is best to warn about the possible risks.
+  #
   # @raise [Exception] If the archive cannot be installed.
   #
   # @raise [Interrupt] If the user cancel the installation.
@@ -514,7 +519,7 @@ module Sketchup
   # @return [Boolean]
   #
   # @version SketchUp 8.0 M2
-  def self.install_from_archive(filename)
+  def self.install_from_archive(filepath, show_warning = true)
   end
 
   # This methods indicates whether the host SketchUp application is 64bit.
@@ -551,15 +556,15 @@ module Sketchup
   end
 
   # Returns a boolean flag indicating whether the application is SketchUp Pro.
-  # Note that after the free trial period, SketchUp Pro will revert to regular
-  # SketchUp and this method will return false until the user registers
-  # the product.
   #
   # @example
   #   if Sketchup.is_pro?
   #     UI.messagebox("You are running SU Pro.")
   #   end
   #
+  # @note In SketchUp Make this method will return +true+ during the Pro trial
+  #   period and revert to +false+ when the trial period is over.
+  #
   # @return [Boolean]
   #
   # @version SketchUp 7.0
@@ -603,28 +608,44 @@ module Sketchup
   def self.load(path)
   end
 
-  # The open_file method is used to open a file.
+  # The {.open_file} method is used to open a SketchUp model.
   #
   # @example
   #   result = Sketchup.open_file("C:\\model.skp")
   #
-  # @param [String] filename
-  #   The path and filename to open.
+  # @overload open_file(filename)
   #
-  # @return [Boolean] true if opening the file succeeded,
-  #   false otherwise.
+  #   @deprecated Prefer +with_status+ overload instead of this variant.
+  #   @param [String] filename  The model file to open.
+  #   @return [Boolean] +true+ if opening the file succeeded,
+  #     +false+ otherwise.
+  #
+  # @overload open_file(filename, with_status: true)
+  #
+  #   Starting with SketchUp 2021.0 SketchUp attempts to load newer SketchUp
+  #   models. If a newer model is loaded some information might have been skipped
+  #   and extensions should be careful to not save over the file they loaded from
+  #   as information might be lost.
+  #
+  #   Success status codes:
+  #   * {Sketchup::Model::LOAD_STATUS_SUCCESS}
+  #   * {Sketchup::Model::LOAD_STATUS_SUCCESS_MORE_RECENT}
+  #
+  #   @version SketchUp 2021.0
+  #   @param [String] filename  The model file to open.
+  #   @return [Integer, false]  status code if opening the file succeeded,
+  #     +false+ otherwise.
   #
   # @version SketchUp 6.0
-  def self.open_file(filename)
+  def self.open_file(*args)
   end
 
   # The os_language method returns the language code for the language SketchUp
   # is running in. This is an alias for the get_locale method.
   #
-  # Valid return values are: en-US, fr, it, de, es, ja, ko, zh-CN, zh-TW,
-  # pt-BR, nl, ru.
-  # If the OS language does not have corresponding folder and files in the
-  # SketchUp Resources folder, the returned language is, by default, en-US.
+  # Examples of return values are: en-US, fr, it, de, es, ja, ko, zh-CN, zh-TW,
+  # pt-BR, nl, ru and sv. For an up to date list os supported languages, see
+  # the SketchUp download page.
   #
   # @example
   #   language = Sketchup.os_language
@@ -751,6 +772,17 @@ module Sketchup
   def self.read_default(section, variable, default = nil)
   end
 
+  # The redo method is used redo the last transaction on the redo stack.
+  #
+  # @example
+  #   Sketchup.redo
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def self.redo
+  end
+
   # The register_extension method is used to register an extension with
   # SketchUp's extension manager (in SketchUp preferences).
   #

data/lib/sketchup-api-stubs/stubs/ui.rb

@@ -70,8 +70,8 @@ module UI
   #     UI.set_cursor(cursor_id)
   #   end
   #
-  # @param [String] filename
-  #   Filename for an image.
+  # @param [String] path
+  #   File path to an image.
   #
   # @param [Integer] hot_x
   #   An x coordinate that is the "hotpoint" for the cursor
@@ -88,7 +88,7 @@ module UI
   # @return [Integer] ID associated with the cursor
   #
   # @version SketchUp 6.0
-  def self.create_cursor(filename, hot_x, hot_y)
+  def self.create_cursor(path, hot_x, hot_y)
   end
 
   # Creates a dialog box for inputting user information. The dialog box contains
@@ -325,7 +325,9 @@ module UI
   end
 
   # The preferences_pages method is used to returns the names of all the
-  # preferences pages. These include windows like Extensions.
+  # preferences pages. These include windows like Templates.
+  #
+  # [SketchUp 2017] <code>"Extensions"</code> page was removed.
   #
   # @example
   #   prefs = UI.preferences_pages
@@ -469,7 +471,7 @@ module UI
   def self.select_directory(options = {})
   end
 
-  # The #{set_cursor} method is used to change the cursor to a new cursor with a
+  # The {.set_cursor} method is used to change the cursor to a new cursor with a
   # given cursor id. See UI.create_cursor and the Tool class for details
   # on creating your own tools with arbitrary cursors.
   #
@@ -543,7 +545,6 @@ module UI
   # {UI.model_info_pages}.
   #
   # [SketchUp 2014] <code>"Classifications"</code> page was added.
-  # [SketchUp 2017] <code>"Extensions"</code> page was removed.
   #
   # @example
   #   UI.show_model_info('Credits')
@@ -558,9 +559,9 @@ module UI
   end
 
   # The show_preferences method is used to display a SketchUp preferences dialog.
-  # You can get the list of valid dialogs with UI.preferences_pages.
+  # You can get the list of valid dialogs with {UI.preferences_pages}.
   #
-  # Note that under OSX this method doesn't currently work.
+  # @bug Under OSX this method doesn't currently work.
   #
   # @example
   #   status = UI.show_preferences('GraphicsCard')