sketchup-api-stubs 0.7.2 → 0.7.7

data/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.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 {Sketchup::Entities}
-# collection 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 objects of interests.
+# collection 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 objects of interests.
 #
 # @example
 #   # This is an example of an observer that watches the entities collection

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This is the base class for all SketchUp entities. Entities are basically
@@ -73,12 +73,11 @@ class Sketchup::Entity
   #   status = entity1.set_attribute "testdictionary", "test", 115
   #   attrdicts = entity1.attribute_dictionaries
   #
-  # @return [Sketchup::AttributeDictionaries, nil] the AttributeDictionaries
-  #   object associated with the entity, or nil if there are
-  #   no attribute_dictionary objects associated with the
-  #   model. Care must be taken if nil is returned, for
-  #   example: invoking attribute_dictionaries.length will
-  #   throw a NoMethodError exception, not return 0.
+  # @note The return value may be either +nil+ or an empty
+  #   {Sketchup::AttributeDictionaries} collection if this entity has no
+  #   {Sketchup::AttributeDictionary}s.
+  #
+  # @return [Sketchup::AttributeDictionaries, nil]
   #
   # @version SketchUp 6.0
   def attribute_dictionaries
@@ -155,14 +154,14 @@ class Sketchup::Entity
   #
   # @overload delete_attribute(dictionary_name)
   #
-  #   @param dictionary_name [String] The name of an attribute dictionary.
-  #   @return                [Boolean]
+  #   @param [String] dictionary_name The name of an attribute dictionary.
+  #   @return [Boolean]
   #
   # @overload delete_attribute(dictionary_name, key)
   #
-  #   @param dictionary_name [String] The name of an attribute dictionary.
-  #   @param key             [String] An attribute key.
-  #   @return                [Boolean]
+  #   @param [String] dictionary_name The name of an attribute dictionary.
+  #   @param [String] key An attribute key.
+  #   @return [Boolean]
   #
   # @version SketchUp 6.0
   def delete_attribute(*args)
@@ -344,6 +343,10 @@ class Sketchup::Entity
   #
   # The persistent id persistent between sessions.
   #
+  # [SketchUp 2020.1]
+  #   - {Sketchup::ComponentDefinition}
+  #   - {Sketchup::Material}
+  #   - {Sketchup::Style}
   # [SketchUp 2020.0]
   #   - {Sketchup::Layer}
   #   - {Sketchup::LineStyle}
@@ -504,16 +507,18 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   type = entity1.typename
   #
+  # @note Prefer +is_a?+ over +typename+ when possible as it is faster.
+  #
   # @return [String] the type of the entity
   #
   # @version SketchUp 6.0
   def typename
   end
 
-  # The valid? method is used to determine if your entity is still valid (not
-  # deleted by another script, for example.)
+  # The {#valid?} method is used to determine if your entity is still valid (not
+  # deleted by another script, for example).
   #
-  # This method is functionally identical to the deleted? method.
+  # This method is functionally the inverse to the {#deleted?} method.
   #
   # @example
   #   depth = 100

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

@@ -1,10 +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 entity 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 entity of
-# interests.
+# This observer interface is implemented to react to entity 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 entity of
+#   interests.
 #
 # @example
 #   class MyEntityObserver < Sketchup::EntityObserver

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The ExtensionsManager class provides a way of accessing the
@@ -21,11 +21,11 @@ class Sketchup::ExtensionsManager
   #
   # @example
   #   manager = Sketchup.extensions
-  #   extension = manager[0]
+  #   extension = manager[1]
   #   if (extension)
-  #     UI.messagebox extension.name
+  #     puts extension.name
   #   else
-  #     UI.messagebox "Failure"
+  #     puts "No Extensions installed"
   #   end
   #
   #   # You can also get extensions by name.
@@ -34,11 +34,12 @@ class Sketchup::ExtensionsManager
   #   # You can also get extensions by ID.
   #   my_extension = manager['2475A758-6503-46D5-AC5E-16AEA0A3162A']
   #
-  # @param index_or_name
+  # @note Index starts at 1.
+  #
+  # @param [Integer, String] index_or_name
   #   The index, name or ID of the SketchupExtension object.
   #
-  # @return extension - an SketchupExtension object if
-  #   successful, otherwise nil.
+  # @return [SketchupExtension, nil]
   #
   # @version SketchUp 8.0 M2
   def [](index_or_name)
@@ -66,7 +67,7 @@ class Sketchup::ExtensionsManager
   # @example
   #   manager = Sketchup.extensions
   #   # Retrieves each extension
-  #   manager.each { |extension| UI.messagebox extension.name }
+  #   manager.each { |extension| puts extension.name }
   #
   # @return nil
   #

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # Faces in SketchUp are flat, 2-sided polygons with 3 or more sides.
@@ -41,7 +41,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   def all_connected
   end
 
-  # The area method is used to retrieve the area of a face in current units.
+  # The area method is used to retrieve the area of a face.
   #
   # You can pass in an optional Transformation (or an array that can represent a
   # transformation), to correct for a parent group's transformation. For example,
@@ -66,13 +66,14 @@ class Sketchup::Face < Sketchup::Drawingelement
   #
   # @overload area
   #
-  #   @return [Float] the area of the face in current units (if successful)
+  #   @return [Float] the area of the face in square inches.
   #
   # @overload area(transform)
   #
-  #   @param transform [Geom::Transformation] A Transformation object or array
-  #                      that can be interpreted as a Transformation object.
-  #   @return [Float] the area of the face in current units (if successful)
+  #   @param [Geom::Transformation] transform
+  #    A Transformation object or array that can be interpreted as a
+  #    Transformation object.
+  #   @return [Float] the area of the face in square inches.
   #
   # @version SketchUp 6.0
   def area(*args)
@@ -199,6 +200,21 @@ class Sketchup::Face < Sketchup::Drawingelement
   def classify_point(point)
   end
 
+  # The {#clear_texture_projection} method is used to clear the texture
+  # projection. This is similar to toggling off Projection from the Position
+  # Texture tool in the UI.
+  #
+  # @param [Boolean] frontside
+  #   +true+ for front side, +false+ for back side.
+  #
+  # @see #position_material
+  #
+  # @see #get_texture_projection
+  #
+  # @version SketchUp 2021.1
+  def clear_texture_projection(frontside)
+  end
+
   # The edges method is used to get an array of edges that bound the face.
   #
   # @example
@@ -330,7 +346,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   def get_glued_instances
   end
 
-  # The get_texture_projection method will return a vector representing the
+  # The {#get_texture_projection} method will return a vector representing the
   # projection for either the front or back side of the face.
   #
   # @example
@@ -364,9 +380,14 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   vector = face.get_texture_projection(true)
   #
   # @param [Boolean] frontside
-  #   true for front side, false for back side.
+  #   +true+ for front side, +false+ for back side.
+  #
+  # @return [Geom::Vector3d, nil] a vector on success, +nil+ if face is not
+  #   textured with a projected texture mapping.
+  #
+  # @see #position_material
   #
-  # @return [Geom::Vector3d] a vector on success, nil on failure.
+  # @see #texture_projected?
   #
   # @version SketchUp 2014
   def get_texture_projection(frontside)
@@ -567,25 +588,26 @@ class Sketchup::Face < Sketchup::Drawingelement
   def plane
   end
 
-  # The position_material method is used to position a material on a face.
+  # The {#position_material} method is used to position a material on a face.
   #
-  # The pt_array must contain 2, 4, 6 or 8 points. The points are used in pairs
-  # to tell where a point in the texture image is positioned on the Face. The
-  # first point in each pair is a 3D point in the model. It should be a point on
-  # the Face. The second point in each pair of points is a 2D point that gives
-  # the (u,v) coordinates of a point in the image to match up with the 3D point.
+  # The +points+ argument must contain 2, 4, 6 or 8 points. The points are used
+  # in pairs to describe where a point in the texture image is positioned on the
+  # Face. The first point in each pair is a 3D point in the model. The second
+  # point in each pair of points is a 2D point that gives the (u,v) coordinates
+  # of a point in the image to match up with the 3D point.
   #
   # @example
   #   model = Sketchup.active_model
   #   entities = model.active_entities
   #
   #   # Create a face and add it to the model entities
-  #   pts = []
-  #   pts[0] = [0, 0, 1]
-  #   pts[1] = [9, 0, 1]
-  #   pts[2] = [9, 9, 1]
-  #   pts[3] = [0, 9, 1]
-  #   face = entities.add_face(pts)
+  #   points = [
+  #     Geom::Point3d.new(0, 0, 1),
+  #     Geom::Point3d.new(9, 0, 1),
+  #     Geom::Point3d.new(9, 9, 1),
+  #     Geom::Point3d.new(0, 9, 1),
+  #   ]
+  #   face = entities.add_face(points)
   #
   #   # Export an image to use as a texture
   #   path = Sketchup.temp_dir
@@ -599,26 +621,64 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   # Assign the new material to our face we created
   #   face.material = material
   #
-  #   pt_array = []
-  #   pt_array[0] = Geom::Point3d.new(3,0,0)
-  #   pt_array[1] = Geom::Point3d.new(0,0,0)
+  #   mapping = [
+  #     Geom::Point3d.new(3,0,0), # Model coordinate
+  #     Geom::Point3d.new(0,0,0), # UV coordinate
+  #   ]
   #   on_front = true
-  #   face.position_material(material, pt_array, on_front)
+  #   face.position_material(material, mapping, on_front)
   #
-  # @param [Sketchup::Material] material
-  #   a Material object.
+  # @overload position_material(material, points, on_front)
+  #
+  #   This variant positions a material on the face's plane without projection.
+  #
+  #   @param [Sketchup::Material] material
+  #
+  #   @param [Array<Geom::Point3d>] points
+  #     An array of Point3d objects used to position the material.
+  #     The points should be on the plane of the face. If they are not they will
+  #     be projected to the face's plane.
+  #
+  #   @param [Boolean] on_front
+  #     +true+ to position the texture on the front of the Face or
+  #     +false+ to position it on the back of the Face.
   #
-  # @param [Array<Geom::Point3d>] pt_array
-  #   An array of Point3d objects used to position the material.
+  # @overload position_material(material, points, on_front, projection)
   #
-  # @param [Boolean] o_front
-  #   true to position the texture on the front of the Face or
-  #   false to position it on the back of the Face.
+  #   This variant positions a material on the face's plane with projection.
   #
-  # @return [Sketchup::Face, false] the face upon success, false upon failure.
+  #   @param [Sketchup::Material] material
+  #
+  #   @param [Array<Geom::Point3d>] points
+  #     An array of Point3d objects used to position the material.
+  #     The points should be on the same plane. The plane should be parallel to
+  #     the +projection+ vector. If they are not on a plane parallel to the
+  #     projection vector they will be projected to such a plane.
+  #
+  #   @param [Boolean] on_front
+  #     +true+ to position the texture on the front of the Face or
+  #     +false+ to position it on the back of the Face.
+  #
+  #   @param [Geom::Vector3d] projection_vector
+  #     The direction of the texture projection.
+  #
+  # @raise ArgumentError if the provided points are not in the size of 2, 4, 6 or 8.
+  #
+  # @raise ArgumentError if the provided points could not be computed to a valid UV mapping.
+  #
+  # @return [Sketchup::Face, false] the face upon success, +false+ if material or
+  #   texture if not valid.
+  #
+  # @see #texture_positioned?
+  #
+  # @see #texture_projected?
+  #
+  # @see #get_texture_projection
+  #
+  # @see #clear_texture_projection
   #
   # @version SketchUp 6.0
-  def position_material(material, pt_array, o_front)
+  def position_material(*args)
   end
 
   # The pushpull method is used to perform a push/pull on a face.
@@ -639,8 +699,8 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   status = face.pushpull(100, true)
   #
-  # @param [Numeric] distance
-  #   The distance, in current units, to push/pull the face.
+  # @param [Length] distance
+  #   The distance to push/pull the face.
   #
   # @param [Boolean] copy
   #   Create a new push/pull starting face if true (equivalent
@@ -677,50 +737,157 @@ class Sketchup::Face < Sketchup::Drawingelement
   def reverse!
   end
 
-  # The set_texture_projection method is used to set the texture projection
+  # The {#set_texture_projection} method is used to set the texture projection
   # direction.
   #
-  # @deprecated This function never worked right. It's not possible to control
-  #   the position and orientation of the texture.
+  # @deprecated This function never worked correctly. It's not capable of
+  #   controlling the position and orientation of the texture. In some cases it
+  #   produced an invalid model. After SketchUp 2021.1 the method will raise
+  #   +NotImplementedError+.
+  #
+  # @param [Geom::Vector3d] vector
+  #   representing the direction of the projection. Use +nil+ to remove the
+  #   projection.
+  #
+  # @param [Boolean] frontside
+  #   +true+ for front side, +false+ for back side.
+  #
+  # @return [Boolean]
+  #
+  # @see #position_material
+  #
+  # @see #clear_texture_projection
+  #
+  # @version SketchUp 2014
+  def set_texture_projection(vector, frontside)
+  end
+
+  # The {#texture_positioned?} method is used to check if the face has a
+  # texture that is positioned.
+  #
+  # A texture is positioned when it's not using the default texture coordinates.
+  #
+  # When a user uses the Paint Bucket Tool to apply a material sampled from the
+  # Material Browser it will use default texture coordinates and not be
+  # positioned. It will be positioned if the user uses the Position Texture Tool.
+  #
+  # When an API user uses {Sketchup::Drawinglement#material=} the texture is not
+  # positioned. It will be positioned when the API user uses
+  # {Sketchup::Face#position_material}. It it also positioned of the face was
+  # crafted via {Geom::PolygonMesh}.
   #
   # @example
   #   model = Sketchup.active_model
   #   entities = model.active_entities
-  #   materials = model.materials
+  #   faces = entities.grep(Sketchup::Face).select { |face|
+  #     face.texture_positioned?(true) || face.texture_positioned?(false)
+  #   }
   #
-  #   # Create a face and add it to the model entities
-  #   pts = []
-  #   pts[0] = [0, 0, 1]
-  #   pts[1] = [10, 0, 1]
-  #   pts[2] = [10, 10, 1]
-  #   face = entities.add_face(pts)
+  # @param [Boolean] front
+  #   +true+ Checks the front side of the face, +face+
+  #   the back side.
   #
-  #   # Export an image to use as a texture
-  #   path = Sketchup.temp_dir
-  #   full_name = File.join(path, "temp_image.jpg")
-  #   model.active_view.write_image(full_name, 500, 500, false, 0.0)
+  # @return [Boolean]
   #
-  #   # Create a material and assign the testure to it.
-  #   material = materials.add("Test Material")
-  #   material.texture = full_name
+  # @see #position_material
   #
-  #   # Assign the new material to our face we created
-  #   face.material = material
+  # @see #material=
   #
-  #   # Returns nil if not successful, path if successful
-  #   result = face.set_texture_projection(face.normal, true)
+  # @see #back_material=
   #
-  # @param [Geom::Vector3d] vector
-  #   representing the direction of the projection. Use nil
-  #   to remove the projection.
+  # @version SketchUp 2021.1
+  def texture_positioned?(front)
+  end
+
+  # The {#texture_projected?} method is used to check if the face has a
+  # texture that is projected.
   #
-  # @param [Boolean] frontside
-  #   true for front side, false for back side.
+  # A texture is projected when the user enables this property via the
+  # Position Texture Tool.
   #
-  # @return [Boolean] true on success
+  # It is also projected when the API user passes a projection vector to
+  # {#position_material}.
   #
-  # @version SketchUp 2014
-  def set_texture_projection(vector, frontside)
+  # @param [Boolean] front
+  #   +true+ Checks the front side of the face, +face+
+  #   the back side.
+  #
+  # @return [Boolean]
+  #
+  # @see #get_texture_projection
+  #
+  # @see #clear_texture_projection
+  #
+  # @see #position_material
+  #
+  # @version SketchUp 2021.1
+  def texture_projected?(front)
+  end
+
+  # The {#uv_tile_at} method is used to get the corner positions (model and UV)
+  # of a UV tile.
+  #
+  # The UV tile bounds the given reference point on the plane of the face. If the
+  # reference isn't on the plane of the face it will be projected onto it.
+  #
+  # The world coordinates are on the plane of the face unless the texture is
+  # projected. When the texture is projected the the world points are on an
+  # arbitrary plane that is perpendicular to the projection direction.
+  #
+  # The returned coordinates are arranged to be compatible with {#position_material}.
+  #
+  # <b>Getting the bounds of the UV tile under the cursor:</b>
+  #
+  # <i>The red quadrilateral represents the model points returned.</i>
+  #
+  # rdoc-image:../images/face-uv-tile-at.png
+  #
+  # @example Copy material from front to back
+  #   model = Sketchup.active_model
+  #   model.active_entities.grep(Sketchup::Face) { |face|
+  #     material = face.material
+  #
+  #     if material&.texture.nil?
+  #       face.back_material = material
+  #     end
+  #
+  #     reference = face.vertices.first.position
+  #     mapping = face.uv_tile_at(reference, true)
+  #     if face.texture_projected?(true)
+  #       projection = face.get_texture_projection(true)
+  #       face.position_material(material, mapping, false, projection)
+  #     else
+  #       face.position_material(material, mapping, false)
+  #     end
+  #   }
+  #
+  # @example Iterate each set of world and UV coordinates
+  #   model = Sketchup.active_model
+  #   faces = model.active_entities.grep(Sketchup::Face)
+  #   face = faces.find { |face| face.material&.texture }
+  #   reference = face.vertices.first.position
+  #   mapping = face.uv_tile_at(reference, true)
+  #   mapping.each_slice(2) { |position, uv|
+  #     puts "World: #{position.inspect} - UV: #{uv.inspect}"
+  #   }
+  #
+  # @param [Geom::Point3d] position
+  #   Model position on the face's plane that will be
+  #   bounded by the UV tile.
+  #
+  # @param [Boolean] front
+  #   +true+ Checks the front side of the face, +face+
+  #   the back side.
+  #
+  # @return [Array<Geom::Point3d>, nil] A set of 8 points. Each stride of two is
+  #   first a model space point, the second a UV
+  #   coordinate. +nil+ if the face doesn't have
+  #   a texture on the given side.
+  #
+  # @see #position_material
+  #
+  # @version SketchUp 2021.1
+  def uv_tile_at(position, front)
   end
 
   # The vertices method is used to get an array of all of the vertices that