sketchup-api-stubs 0.7.2 → 0.7.7

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # A DefinitionList object holds a list of all of the ComponentDefinition
@@ -6,7 +6,7 @@
 # definitions from the list.
 #
 # @version SketchUp 6.0
-class Sketchup::DefinitionList < Sketchup::Entity
+class Sketchup::DefinitionList < Entity
 
   # Includes
 
@@ -131,10 +131,8 @@ class Sketchup::DefinitionList < Sketchup::Entity
   def count
   end
 
-  # The each method is used to iterate through all of the component definitions
-  # in the definition list.
-  #
-  # Throws an exception if there are no component definitions.
+  # The {#each} method is used to iterate through all of the component
+  # definitions in the definition list.
   #
   # @example
   #   model = Sketchup.active_model
@@ -142,6 +140,11 @@ class Sketchup::DefinitionList < Sketchup::Entity
   #   definitions.add("BedTraditional")
   #   number = definitions.each { |definition| puts definition.name }
   #
+  # @note Don't remove content from this collection while iterating over it with
+  #   {#each}. This would change the size of the collection and cause elements to
+  #   be skipped as the indices change. Instead copy the current collection to an
+  #   array using +to_a+ and then use +each+ on the array, when removing content.
+  #
   # @return [nil]
   #
   # @version SketchUp 6.0
@@ -150,6 +153,33 @@ class Sketchup::DefinitionList < Sketchup::Entity
   def each
   end
 
+  # The {#import} method is used to import a (non-SketchUp) 3d model file as a definition.
+  #
+  # Importers using the C API +SketchUpModelImporterInterface+ interface are supported (those in the +Importers/+ directory).
+  #
+  # See the {file:pages/importer_options.md Importer Options} file for information
+  # on creating a valid hash for the various importers.
+  #
+  # For SketchUp models, instead use {#load}.
+  #
+  # @example
+  #   path = "C:/circle.dwg"
+  #   definition = Sketchup.active_model.definitions.import(path)
+  #
+  # @param [String] path
+  #
+  # @param [Hash] options
+  #
+  # @raise [IOError] if the file is missing.
+  #
+  # @raise [ArgumentError] if no suitable importer could be found.
+  #
+  # @return [Sketchup::ComponentDefinition]
+  #
+  # @version SketchUp 2021.1
+  def import(path, options = {})
+  end
+
   # The {#length} method is used to retrieve number of component definitions in
   # the list.
   #
@@ -166,46 +196,79 @@ class Sketchup::DefinitionList < Sketchup::Entity
   def length
   end
 
-  # The load method is used to load a component from a file.
+  # The {#load} method is used to load a component from a file.
+  #
+  # @bug In SketchUp versions prior to SketchUp 2019 the application would crash
+  #   if you tried to open a newer model instead of raising the expected
+  #   +RuntimeError+.
   #
   # @example
-  #   path=Sketchup.find_support_file "Bed.skp",
-  #     "Components/Components Sampler/"
+  #   path = Sketchup.find_support_file("Bed.skp",
+  #     "Components/Components Sampler/")
   #   model = Sketchup.active_model
   #   definitions = model.definitions
-  #   componentdefinition = definitions.load path
+  #   definition = definitions.load(path)
   #
-  # @param [String] path
-  #   The path where the component definition file is located.
+  # @overload load(path)
+  #
+  #   @param [String] path
+  #     The path where the component definition file is located.
+  #
+  # @overload load(path, allow_newer: true)
   #
-  # @raise RuntimeError If filename is an invalid SketchUp model. Added in
-  #   SketchUp 2019. Possible that prior versions of SketchUp will crash.
+  #   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.
+  #
+  #   @version SketchUp 2021.0
+  #   @param [String] path
+  #     The path where the component definition file is located.
+  #   @param [Boolean] allow_newer
+  #     Indicate that it is ok to load a model with of a newer version.
+  #
+  # @raise IOError If the file is not a valid SketchUp model.
+  #
+  # @raise RuntimeError If the file is the same as the model being loaded into.
+  #
+  # @raise IOError If the file is an empty component.
+  #
+  # @raise RuntimeError If the file contains only screen text.
+  #
+  # @raise RuntimeError If the file is of a newer file version that the executing
+  #   SketchUp version cannot open.
   #
   # @return [Sketchup::ComponentDefinition] the loaded ComponentDefinition
-  #   object if successful
   #
   # @version SketchUp 6.0
-  def load(path)
+  def load(*args)
   end
 
-  # The load_from_url method loads a component from a location specified by
-  # string url. This method throws an exception if an url string is not
-  # given, or an error occurs during retrieval from url and a
-  # load_handler was not given. Optional second parameter load_handler can be
-  # used to pass in a ruby object that responds to the following methods:
+  # The {#load_from_url} method loads a component from a location specified by
+  # string url.
   #
-  #   - cancelled?(a_boolean)
-  #   - onPercentChange(a_float)
-  #   - onSuccess()
-  #   - onFailure(message_string)
+  # This method throws an exception if an url string is not
+  # given, or an error occurs during retrieval from URL and a
+  # +load_handler+ was not given. Optional second parameter +load_handler+ can be
+  # used to pass in a Ruby object that responds to the following methods:
   #
-  # @example
-  #   class LoadHandler
+  # - +cancelled?+
+  # - +onPercentChange(percent)+
+  # - +onSuccess()+
+  # - +onFailure(message_string)+
+  #
+  # @bug Calling this method from an {UI::HtmlDialog}'s action callback on macOS will cause the
+  #   SketchUp application to become unresponsive. To work around this, defer the call from the
+  #   action callback with a non-repeating zero-delay timer;
+  #   +UI.start_timer(0, false) { method_calling_load_from_url }+
   #
-  #     attr :error
+  # @example Download a component using a LoadHandler
+  #   class LoadHandler
+  #     attr_accessor :error
   #
+  #     # @param [Float] percent
   #     def onPercentChange(percent)
-  #       Sketchup::set_status_text("LOADING: #{percent}%")
+  #       Sketchup::set_status_text("loading: #{percent.round}%")
   #     end
   #
   #     def cancelled?
@@ -219,34 +282,67 @@ class Sketchup::DefinitionList < Sketchup::Entity
   #       Sketchup::set_status_text('')
   #     end
   #
+  #     # @param [String] error_message
   #     def onFailure(error_message)
   #       self.error = error_message
   #       Sketchup::set_status_text('')
   #     end
-  #
   #   end
   #
   #   # Replace this with a real URL...
-  #   url = 'http://www.sketchup.com/model.skp'
+  #   url = 'https://www.sketchup.com/model.skp'
   #   model = Sketchup.active_model
+  #   load_handler = LoadHandler.new
   #   definition = model.definitions.load_from_url(url, load_handler)
   #
   #   if definition.nil?
   #     puts "Error: #{load_handler.error}"
   #   end
   #
-  # @param [String] url
-  #   URL to load a .skp file from.
+  # @example Workaround for macOS bug related to HtmlDialog action callbacks
+  #   module Example
   #
-  # @param [Object] load_handler
-  #   Ruby object that has methods defined
-  #   as described in the load_from_url details.
+  #     def self.open_dialog
+  #       @dialog = UI::HtmlDialog.new
+  #       @dialog.add_action_callback("say") { |action_context, url|
+  #         self.load_component_deferred(url)
+  #       }
+  #       @dialog.set_file("path/to/file.html")
+  #       @dialog.show
+  #     end
   #
-  # @return [Sketchup::ComponentDefinition] the loaded ComponentDefinition
-  #   object if successful
+  #     def load_component_deferred
+  #       # The timer delay is enough to avoid .load_from_url from deadlocking.
+  #       UI.start_timer(0, false) do
+  #         self.load_component(url)
+  #       end
+  #     end
+  #
+  #     def self.load_component(url)
+  #       model = Sketchup.active_model
+  #       definition = model.definitions.load_from_url(url)
+  #       # ...
+  #     end
+  #
+  #   end
+  #
+  # @overload load_from_url(url)
+  #
+  #   @param [String] url
+  #     URL to load a .skp file from.
+  #
+  # @overload load_from_url(url, load_handler)
+  #
+  #   @param [String] url
+  #     URL to load a .skp file from.
+  #   @param [Object] load_handler
+  #     Ruby object that has methods defined
+  #     as described in the +load_from_url+ details above.
+  #
+  # @return [Sketchup::ComponentDefinition]
   #
   # @version SketchUp 7.0
-  def load_from_url(url, load_handler = nil)
+  def load_from_url(*args)
   end
 
   # The purge_unused method is used to remove the unused component definitions.

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

@@ -1,10 +1,12 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to component definition
-# 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
-# definitions of interests.
+# 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
+#   definitions of interests.
 #
 # @example
 #   # This is an example of an observer that watches a specific definition

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

@@ -1,10 +1,12 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to events on a definitions
-# collection. To implement this observer, create a Ruby class of this type,
-# override the desired methods, and add an instance of the observer to the
-# collection of interest.
+# collection.
+#
+# @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
+#   collection of interest.
 #
 # @example
 #   class MyDefinitionsObserver < Sketchup::DefinitionsObserver

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Dimension class provides base functionality for classes DimensionLinear

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The DimensionLinear class represents linear dimensions.
@@ -168,17 +168,11 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
   #
   # @example
   #   dim.offset_vector = Geom::Vector3d.new(0, 0, 10)
-  #   # or
-  #   dim.offset_vector = [0, 0, 10]
   #
-  # @param vec
-  #   the offset vector to be set, either a Vector3d or in
-  #   array form.
-  #
-  # @return the offset vector that was set
+  # @param [Geom::Vector3d] offset_vector
   #
   # @version SketchUp 2014
-  def offset_vector=(vec)
+  def offset_vector=(offset_vector)
   end
 
   # The start method returns the point or entity the dimension is referencing at

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

@@ -1,8 +1,12 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to changes in dimension text.
 #
+# @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
+#   dimensions of interest.
+#
 # @example
 #   # This is an example of a DimensionObserver
 #   class MyDimensionObserver < Sketchup::DimensionObserver

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The DimensionRadial class represents radius and diameter dimensions on

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # Drawingelement is a base class for an item in the model that can be
@@ -11,8 +11,14 @@ class Sketchup::Drawingelement < Sketchup::Entity
 
   # Instance Methods
 
-  # The bounds method is used to retrieve the BoundingBox for an drawing
-  # element.
+  # The {#bounds} method is used to retrieve the {Geom::BoundingBox} bounding a
+  # {Sketchup::Drawingelement}.
+  #
+  # For a {Sketchup::Edge}, {Sketchup::ComponentInstance} and most other
+  # {Sketchup::Drawingelement}s, the boundingbox follows the coordinate system
+  # the drawing element is placed in.
+  # For {Sketchup::ComponentDefinition}, the box bounds the contents of the
+  # component and follows the component's own internal coordinate system.
   #
   # @example
   #   depth = 100
@@ -31,7 +37,7 @@ class Sketchup::Drawingelement < Sketchup::Entity
   #   # is a sub-class of Drawingelement.
   #   boundingbox = face.bounds
   #
-  # @return [Geom::BoundingBox] A BoundingBox object if successful
+  # @return [Geom::BoundingBox]
   #
   # @version SketchUp 6.0
   def bounds

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Edge class contains methods modifying and extracting information for
@@ -155,20 +155,13 @@ class Sketchup::Edge < Sketchup::Drawingelement
   def explode_curve
   end
 
-  # The faces method is used to retrieve all of the faces common to the edge.
+  # The {#faces} method is used to retrieve all of the faces common to the edge.
   #
   # @example
-  #   edge = Sketchup.active_model.entities.add_line([0,0,0],[100,100,0])
+  #   edge = Sketchup.active_model.entities.add_line([0, 0, 0], [100, 100, 0])
   #   faces = edge.faces
-  #   if (faces)
-  #     # Display the pointer to the first face returned in the array
-  #     UI.messagebox faces[0]
-  #   else
-  #     UI.messagebox "Failure: No Faces Found"
-  #   end
   #
-  # @return [Array<Sketchup::Face>] an array of Face objects if successful, false
-  #   if unsuccessful
+  # @return [Array<Sketchup::Face>]
   #
   # @version SketchUp 6.0
   def faces
@@ -229,8 +222,9 @@ class Sketchup::Edge < Sketchup::Drawingelement
   #
   # @overload length(transform)
   #
-  #   @param transform [Geom::Transformation] A Transformation object or array
-  #                       that can be interpreted as a Transformation object.
+  #   @param [Geom::Transformation] transform
+  #     A Transformation object or array that can be interpreted as a
+  #     Transformation object.
   #   @return [Length] the length of the edge
   #
   # @version SketchUp 6.0
@@ -416,7 +410,7 @@ class Sketchup::Edge < Sketchup::Drawingelement
   def soft?
   end
 
-  # The split method is used to  to split an edge into to or more distinct
+  # The split method is used to  to split an edge into two or more distinct
   # edges. If a Point3d is given, it must be a point that is on the Edge.
   #
   # If a Float is given, it is a number between 0 and 1 that gives the

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The EdgeUse class defines how an Edge is used in the definition of a Face.

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

@@ -1,8 +1,9 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# The Entities class is a container class for all entities in a model (it is a
-# collection of Entity objects).
+# The {Sketchup::Entities} class is a collection of Entity objects, either in a
+# {Sketchup::ComponentDefinition} or directly in the {Sketchup::Model}. A
+# {Sketchup::Entities} object corresponds to a drawing context in the GUI.
 #
 # @version SketchUp 6.0
 class Sketchup::Entities
@@ -540,8 +541,8 @@ class Sketchup::Entities
   #     UI.messagebox "Failure"
   #   end
   #
-  # @param [String] filename
-  #   A filename for the image file.
+  # @param [String] path
+  #   A path for the image file.
   #
   # @param [Geom::Point3d] point
   #   A Point3d object representing the insertion point of
@@ -558,7 +559,7 @@ class Sketchup::Entities
   # @return [Sketchup::Image, nil] an Image object if successful.
   #
   # @version SketchUp 6.0
-  def add_image(filename, point, width, height = 0.0)
+  def add_image(path, point, width, height = 0.0)
   end
 
   # The add_instance method adds a component instance to the collection of
@@ -806,8 +807,8 @@ class Sketchup::Entities
   def count
   end
 
-  # The each method is used to iterate through the entities in the collection of
-  # entities.
+  # The {#each} method is used to iterate through the entities in the collection
+  # of entities.
   #
   # @example
   #   coordinates = [10, 10, 10]
@@ -815,7 +816,12 @@ class Sketchup::Entities
   #   entities = model.entities
   #   point = Geom::Point3d.new coordinates
   #   text = entities.add_text "This is a Test", point
-  #   entities.each { | entity| UI.messagebox entity }
+  #   entities.each { | entity| puts entity }
+  #
+  # @note Don't remove content from this collection while iterating over it with
+  #   {#each}. This would change the size of the collection and cause elements to
+  #   be skipped as the indices change. Instead copy the current collection to an
+  #   array using +to_a+ and then use +each+ on the array, when removing content.
   #
   # @return [nil]
   #
@@ -1045,8 +1051,15 @@ class Sketchup::Entities
   # sub-entities all at once.
   #
   # @example
-  #   # Need better Ruby example.
-  #   entities = entities.transform_by_vectors sub_entities, vector_array
+  #   # Raise vertices in selection by their distance to the origin.
+  #   model = Sketchup.active_model
+  #   entities = model.active_entities
+  #   with_vertices = entities.select { |entity| entity.respond_to?(:vertices) }
+  #   vertices = with_vertices.flat_map(&:vertices).uniq
+  #   lengths = vertices.map { |vertex| vertex.position.distance(ORIGIN) }
+  #   vectors = lengths.map { |length| Geom::Vector3d.new(0, 0, length) }
+  #
+  #   entities.transform_by_vectors(vertices, vectors)
   #
   # @param [Array<Sketchup::Entity>] sub_entities
   #   An array of entities to transform.
@@ -1063,24 +1076,18 @@ class Sketchup::Entities
   # The transform_entities method is used to apply a transform to several
   # sub-entities all at once.
   #
-  # Important note: If you apply a transformation to entities that are
-  # not in the current edit context (i.e. faces that are inside a group),
-  # SketchUp will apply the transformation incorrectly, since the geometry
-  # has one origin and the current edit context has another. You can correct
-  # for this by watching the Model.edit_transform and Model.active_path. See
-  # ModelObserver.onActivePathChanged for more information.
+  # If you are transforming entities in the active drawing context or any of its
+  # parent drawing contexts, the transformation will be interpreted as relative
+  # to the global coordinate system. Otherwise the transformation will be
+  # interpreted as being on the local coordinate system.
   #
   # @example
   #   entities = Sketchup.active_model.entities
-  #   entities.add_line([0,0,0],[100,100,100])
-  #   entities.add_line([0,0,0],[200,-10,-10])
-  #
-  #   entities_to_transform = []
-  #   entities_to_transform.push(entities[0])
-  #   entities_to_transform.push(entities[1])
+  #   entity1 = entities.add_line([0,0,0],[100,100,100])
+  #   entity2 = entities.add_line([0,0,0],[200,-10,-10])
   #
-  #   transform = Geom::Transformation.new([100,0,0])
-  #   entities.transform_entities(transform, ent1, ent2, ent3)
+  #   transformation = Geom::Transformation.new([100,0,0])
+  #   entities.transform_entities(transformation, [entity1, entity2])
   #
   # @param [Geom::Transformation] transform
   #   The Transformation to apply.
@@ -1088,10 +1095,32 @@ class Sketchup::Entities
   # @param [Array<Sketchup::Entity>] entities
   #   An array or series of entities to transform.
   #
-  # @return [Boolean] results of the transform.
+  # @return [Boolean] +false+ if the entities array was empty.
   #
   # @version SketchUp 6.0
   def transform_entities(transform, entities)
   end
 
+  # The {#weld} method takes a set of edges and find all possible chains of edges
+  # and connect them with a {Sketchup::Curve}.
+  #
+  # A curve will not cross another curve. They will split where multiple curves
+  # meet.
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   edges = model.selection.grep(Sketchup::Edge)
+  #   curves = model.active_entities.weld(edges)
+  #
+  # @param [Array<Sketchup::Edge>] edges
+  #
+  # @raise [ArgumentError] if the given entities are not part of the same
+  #   {Sketchup::Entities} collection.
+  #
+  # @return [Array<Sketchup::Curve>]
+  #
+  # @version SketchUp 2020.1
+  def weld(edges)
+  end
+
 end