sketchup-api-stubs 0.7.2 → 0.7.7

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

@@ -1,4 +1,4 @@
-# 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 camera

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

@@ -1,15 +1,13 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # A Group class contains methods for manipulating groups of entities.
 #
-# Groups in SketchUp are very similar to Components, except that there is no
-# instancing of groups. That means that you always will have one and only one
-# of each of your groups. (In the actual implementation, SketchUp keeps track
-# of groups as a special kind of Component that combines properties of
-# definitions and instances, which is why you will see deprecated methods
-# like Group.make_unique, and the class of observer you attach to Groups are
-# ComponentInstance observers.)
+# Groups in SketchUp are very similar to components, but can from a user point
+# of view be thought of as unique objects. Groups can be instanced when copied
+# but are silently made unique when edited through the GUI. To honor this
+# behavior, make sure to call {#make_unique} before modifying a group through
+# the API.
 #
 # @version SketchUp 6.0
 class Sketchup::Group < Sketchup::Drawingelement
@@ -203,6 +201,57 @@ class Sketchup::Group < Sketchup::Drawingelement
   def explode
   end
 
+  # The {#glued_to} method is used to retrieve the entity that this group is
+  # glued to.
+  #
+  # @example
+  #   point = Geom::Point3d.new(10, 20, 30)
+  #   transform = Geom::Transformation.new(point)
+  #   model = Sketchup.active_model
+  #   entities = model.active_entities
+  #   group = entities.add_group
+  #   group.entities.add_face([[0, 0, 0], [10, 0, 0], [10, 10, 0], [0, 10, 0]])
+  #   status = group.glued_to
+  #
+  # @return [Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil]
+  #
+  # @version SketchUp 2021.1
+  def glued_to
+  end
+
+  # The {glued_to=} method glues this group to a drawing element.
+  # When moving this other drawing elment with the Move tool, the glued group moves with it.
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   entities = model.active_entities
+  #
+  #   # Create a face
+  #   face = entities.add_face([[0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]])
+  #
+  #   # Create a group
+  #   definitions = model.definitions
+  #   group = entities.add_group
+  #   group.entities.add_face([[0, 0, 0], [10, 0, 0], [10, 10, 0], [0, 10, 0]])
+  #
+  #   # Make group "gluable"
+  #   group.definition.behavior.is2d = true
+  #
+  #   # Glue the group to the face.
+  #   # If you now move the face, the group will follow.
+  #   group.glued_to = face
+  #
+  # @param [Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil] drawing_element
+  #
+  # @raise ArgumentError if the {Sketchup::Behavior} for this group doesn't allow gluing,
+  #   if the alignment is wrong, or if this would lead to cyclic gluing.
+  #
+  # @return [Sketchup::Face, Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil] the entity the group was glued to.
+  #
+  # @version SketchUp 2021.1
+  def glued_to=(drawing_element)
+  end
+
   # The guid method is used to get the base 64 encoded unique id
   # for this SketchUp object.
   #
@@ -228,6 +277,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.intersect(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to intersect this group with.
   #
@@ -239,11 +290,11 @@ class Sketchup::Group < Sketchup::Drawingelement
   def intersect(group)
   end
 
-  # The local_bounds method returns the BoundingBox object that defines the size
-  # of the group in an untransformed state. Useful for determining the original
-  # width, height, and depth of a group regardless of its current position or
-  # scale. For components, you can get a similar result by checking
-  # my_instance.definition.bounds.
+  # The {#local_bounds} method is used to retrieve the {Geom::BoundingBox}
+  # bounding the contents of a {Sketchup::Group}, in the group's own internal
+  # coordinate system.
+  #
+  # @deprecated In favor of `group.definition.bounds`.
   #
   # @example
   #   # Add a group to the model.
@@ -257,7 +308,7 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group.transform! transformation
   #   local_bounds_2 = group.local_bounds
   #
-  # @return [Geom::BoundingBox] a BoundingBox object
+  # @return [Geom::BoundingBox]
   #
   # @version SketchUp 7.0
   def local_bounds
@@ -303,14 +354,14 @@ class Sketchup::Group < Sketchup::Drawingelement
   def locked?
   end
 
-  # The make_unique method is used to force a group to have a unique definition.
+  # The {#make_unique} method is used to force a group to have a unique
+  # definition. If the group is already unique in the model, nothing happens.
   #
-  # Copying a group using the copy tool in SketchUp will create copies of the
-  # group that share a common definition until an instance is edited manually or
-  # this method is used. If multiple copies are made, all copies share a
-  # definition until all copies are edited manually, or all copies have this
-  # method used on them. This method ensures that the group uses a unique
-  # definition entry in the drawing database.
+  # Copying a group in SketchUp will create a group that shares the same
+  # definition. SketchUp implicitly makes group unique when edited from the GUI,
+  # and from a user point of view groups could be thought of as always being
+  # unique. To honor this behavior, call this method before editing a group
+  # through the API.
   #
   # @example
   #   # Assume we have 2 groups, one copied from the other and sharing definitions
@@ -341,15 +392,16 @@ class Sketchup::Group < Sketchup::Drawingelement
   def manifold?
   end
 
-  # The move! method is used to apply a transformation to the group.
+  # The {#move!} method is used to set the transformation of this group
+  # instance, similarly to {#transformation=} but without recording to the undo
+  # stack.
   #
-  # This method is the same as the transform! method except that it does not
-  # record the move in an undo operation. This method is useful for
-  # transparently moving things during an animation.
+  # This method is useful for moving entities inside of an animation or page
+  # transition.
   #
   # @example
   #   point = Geom::Point3d.new 500,500,500
-  #   t = Geom::Transformation.new point
+  #   transformation = Geom::Transformation.new point
   #   depth = 100
   #   width = 100
   #   model = Sketchup.active_model
@@ -369,21 +421,17 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   # Add a face to within the group
   #   face = entities2.add_face pts
   #   UI.messagebox "Group before Move"
-  #   group = group.move! t
-  #   if (group)
-  #     UI.messagebox "Group after move"
-  #     UI.messagebox group
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
+  #   group = group.move!(transformation)
   #
-  # @param [Geom::Transformation] transform
-  #   A Transformation object.
+  # @note Despite the name being similar to {#transform!}, this method closer
+  #   corresponds to {#transformation=}.
+  #
+  # @param [Geom::Transformation] transformation
   #
   # @return [Sketchup::Group] the transformed Group object if successful
   #
   # @version SketchUp 6.0
-  def move!(transform)
+  def move!(transformation)
   end
 
   # The name method is used to retrieve the name of the group.
@@ -503,6 +551,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.split(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to split this group with.
   #
@@ -528,6 +578,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.subtract(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to subtract this group from.
   #
@@ -613,24 +665,21 @@ class Sketchup::Group < Sketchup::Drawingelement
   def transformation
   end
 
-  # The transformation= method is used to set the transformation for the
-  # group.
+  # The {#transformation=} method is used to set the transformation of this
+  # group
   #
   # @example
   #   # Add a group to the model.
   #   group = Sketchup.active_model.entities.add_group
   #   group.entities.add_line([0,0,0],[100,100,100])
   #
-  #   new_transform = Geom::Transformation.new([100,0,0])
-  #   group.transformation = new_transform
-  #
-  # @param [Geom::Transformation] transform
-  #   The Transformation object to apply
+  #   new_transformation = Geom::Transformation.new([100,0,0])
+  #   group.transformation = new_transformation
   #
-  # @return [Geom::Transformation] the applied transformation
+  # @param [Geom::Transformation] transformation
   #
   # @version SketchUp 6.0
-  def transformation=(transform)
+  def transformation=(transformation)
   end
 
   # The trim method is used to compute the (non-destructive) boolean difference
@@ -644,6 +693,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.trim(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to trim this group against.
   #
@@ -665,6 +716,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.union(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to union this group with.
   #

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The {Sketchup::Http} module provides interfaces to create asynchronous HTTP

data/lib/sketchup-api-stubs/stubs/Sketchup/Http/Request.rb

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # Http::Request objects allows you to send HTTP request to HTTP servers.
@@ -11,9 +11,9 @@ class Sketchup::Http::Request
   # Gets the http body that is going to be used when sending the request.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
   #
-  #   request.start do |request, response|
+  #   @request.start do |request, response|
   #     puts "body: #{request.body}"
   #   end
   #
@@ -26,10 +26,10 @@ class Sketchup::Http::Request
   # Sets the http body that is going to be used when sending the request.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
-  #   request.body = "Hello World"
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request.body = "Hello World"
   #
-  #   request.start do |request, response|
+  #   @request.start do |request, response|
   #     puts "body: #{request.body}"
   #   end
   #
@@ -45,12 +45,12 @@ class Sketchup::Http::Request
   # Cancels the request.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
-  #   request.start do |request, response|
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request.start do |request, response|
   #     puts "body: #{response.body}"
   #   end
   #
-  #   request.cancel
+  #   @request.cancel
   #
   # @return [true]
   #
@@ -61,10 +61,10 @@ class Sketchup::Http::Request
   # Returns the http headers that are going to be used when sending the request.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
-  #   request.headers = { :key1 => "value1", :key2 => "value2" }
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request.headers = { :key1 => "value1", :key2 => "value2" }
   #
-  #   request.headers.each do |key, value|
+  #   @request.headers.each do |key, value|
   #     puts "#{key}: #{value}"
   #   end
   #
@@ -77,10 +77,10 @@ class Sketchup::Http::Request
   # Sets the http headers that are going to be used when sending the request.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
-  #   request.headers = { :key1 => "value1", :key2 => "value2" }
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request.headers = { :key1 => "value1", :key2 => "value2" }
   #
-  #   request.headers.each do |key, value|
+  #   @request.headers.each do |key, value|
   #     puts "#{key}: #{value}"
   #   end
   #
@@ -96,10 +96,7 @@ class Sketchup::Http::Request
   # The new method is used to create a new Sketchup::Http::Request.
   #
   # The default port is 80, to use a different port define it in the URL when
-  # creating a new Http::Request
-  #
-  # Keeping a reference to the request is necessary in order to ensure the use of
-  # the response.
+  # creating a new {Sketchup::Http::Request}.
   #
   # The +method+ parameter accepts any custom http method or one of the
   # following:
@@ -111,12 +108,16 @@ class Sketchup::Http::Request
   # * +Sketchup::Http::OPTIONS+
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080", Sketchup::Http::GET)
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080", Sketchup::Http::GET)
   #
-  #   request.start do |request, response|
+  #   @request.start do |request, response|
   #     puts "body: #{response.body}"
   #   end
   #
+  # @note If no reference is kept to the {Sketchup::Http::Request}, it can be garbage collected,
+  #   making the download silently fail. This is especially noticeable for larger downloads that
+  #   takes longer time.
+  #
   # @param [String] url
   #   The targetted URL.
   #
@@ -133,9 +134,9 @@ class Sketchup::Http::Request
   # Returns the http method that is going to be used when sending the request.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
   #
-  #   request.start do |request, response|
+  #   @request.start do |request, response|
   #     puts "request.method: #{request.method}"
   #   end
   #
@@ -155,10 +156,10 @@ class Sketchup::Http::Request
   # * +Sketchup::Http::OPTIONS+
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
-  #   request.method = Sketchup::Http::POST
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request.method = Sketchup::Http::POST
   #
-  #   request.start do |request, response|
+  #   @request.start do |request, response|
   #     puts "request.method: #{request.method}"
   #   end
   #
@@ -175,14 +176,20 @@ class Sketchup::Http::Request
   # have received data from the server until the download finishes.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
-  #
-  #   request.set_download_progress_callback do |current, total|
-  #     puts "download current: #{current}"
-  #     puts "download total: #{total}"
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
+  #
+  #   @request.set_download_progress_callback do |current, total|
+  #     if total == -1
+  #       puts "#{current}B"
+  #     else
+  #       percentage = (current.to_f / total * 100).round
+  #       puts "#{current}B / #{total}B (#{percentage}%)"
+  #     end
   #   end
   #
-  #   request.start
+  #   @request.start
+  #
+  # @note +total+ is -1 if the server doesn't specify a file size in the response header.
   #
   # @return [Boolean]
   #
@@ -202,9 +209,9 @@ class Sketchup::Http::Request
   # uploaded data to the server until the upload finishes.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
   #
-  #   request.set_upload_progress_callback do |current, total|
+  #   @request.set_upload_progress_callback do |current, total|
   #     puts "upload current: #{current}"
   #     puts "upload total: #{total}"
   #   end
@@ -228,9 +235,9 @@ class Sketchup::Http::Request
   # Starts the request and optionally add a callback block.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
   #
-  #   request.start do |request, response|
+  #   @request.start do |request, response|
   #     puts "body: #{response.body}"
   #   end
   #
@@ -257,9 +264,9 @@ class Sketchup::Http::Request
   # * +Sketchup::Http::STATUS_FAILED+
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
-  #   request.start
-  #   puts "response.status: #{request.status}"
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request.start
+  #   puts "response.status: #{@request.status}"
   #
   # @return [int]
   #
@@ -270,9 +277,9 @@ class Sketchup::Http::Request
   # Returns a copy of the Request's URL.
   #
   # @example
-  #   request = Sketchup::Http::Request.new("http://localhost:8080")
+  #   @request = Sketchup::Http::Request.new("http://localhost:8080")
   #
-  #   request.start do |request, response|
+  #   @request.start do |request, response|
   #     puts "url: #{request.url}"
   #   end
   #