sketchup-api-stubs 0.1.2 → 0.2.0

data/SketchUp/Sketchup/Entity.rb

@@ -41,10 +41,10 @@ class Sketchup::Entity
   #     status = entity.add_observer observer
   #   end
   #
-  # @param observer
+  # @param [Object] observer
   #   An observer.
   #
-  # @return true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 6.0
   def add_observer(observer)
@@ -73,7 +73,7 @@ class Sketchup::Entity
   #   status = entity1.set_attribute "testdictionary", "test", 115
   #   attrdicts = entity1.attribute_dictionaries
   #
-  # @return attributedictionaries - the AttributeDictionaries
+  # @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
@@ -107,15 +107,15 @@ class Sketchup::Entity
   #   status = entity1.set_attribute "testdictionary", "test", 115
   #   attrdict = entity1.attribute_dictionary "testdictionary"
   #
-  # @param name
+  # @param [String] name
   #   The name of the attribute dictionary.
   #
-  # @param [optional] create
+  # @param [Boolean] create
   #   boolean, if set to true then the attribute
   #   dictionary will be created if it does not exist.
   #
-  # @return attributedictionary - an AttributeDictionary object if
-  #   successful, or nil if there is no attribute dictionary
+  # @return [Sketchup::AttributeDictionary, nil] - an AttributeDictionary object
+  #   if successful, or nil if there is no attribute dictionary
   #
   # @version SketchUp 6.0
   def attribute_dictionary(name, create)
@@ -127,6 +127,11 @@ class Sketchup::Entity
   # AttributeDictionary. Otherwise, delete_attribute deletes the attribute with
   # the given key from the given dictionary.
   #
+  # In SketchUp 2018, special attribute dictionaries have been added. The name
+  # of these dictionaries are "SU_InstanceSet" and "SU_DefinitionSet". The
+  # dictionaries cannot be deleted via ruby and an ArgumentError will be raised.
+  # The key/value pairs in the dictionary can be deleted safely.
+  #
   # @example
   #   depth = 100
   #   width = 100
@@ -148,14 +153,14 @@ class Sketchup::Entity
   #
   # @overload delete_attribute(dictionary_name)
   #
-  #   @param dictionary_name The name of an attribute dictionary.
-  #   @return              nil
+  #   @param dictionary_name [String] The name of an attribute dictionary.
+  #   @return                [nil]
   #
   # @overload delete_attribute(dictionary_name, key)
   #
-  #   @param dictionary_name The name of an attribute dictionary.
-  #   @param key           An attribute key.
-  #   @return              nil
+  #   @param dictionary_name [String] The name of an attribute dictionary.
+  #   @param key             [String] An attribute key.
+  #   @return                [nil]
   #
   # @version SketchUp 6.0
   def delete_attribute(*args)
@@ -180,7 +185,7 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   status = entity1.deleted?
   #
-  # @return status - true if deleted, false if not deleted
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -208,52 +213,41 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   id = entity1.entityID
   #
-  # @return id - the id for the Entity object
+  # @return [Integer] the id for the Entity object
   #
   # @version SketchUp 6.0
   def entityID
   end
 
-  # The get_attribute method is used to retrieve the value of an attribute in
+  # The {#get_attribute} method is used to retrieve the value of an attribute in
   # the entity's attribute dictionary.
   #
-  # If the third parameter, default_value, is not passed and there is no
-  # attribute that matches the given name, it returns nil.
+  # If the third parameter, +default_value+, is not passed and there is no
+  # attribute that matches the given name, it returns +nil+.
   #
-  # If default_value is provided and there is no matching attribute it returns
+  # If +default_value+ is provided and there is no matching attribute it returns
   # the given value. It does not create an attribute with that name though.
   #
   # @example
-  #   depth = 100
-  #   width = 100
+  #   # Add an entity to the model:
   #   model = Sketchup.active_model
   #   entities = model.active_entities
-  #   pts = []
-  #   pts[0] = [0, 0, 0]
-  #   pts[1] = [width, 0, 0]
-  #   pts[2] = [width, depth, 0]
-  #   pts[3] = [0, depth, 0]
-  #
-  #   # Add the face to the entities in the model
-  #   face = entities.add_face pts
+  #   edge = entities.add_line([0, 0, 0], [9, 9, 9])
   #
-  #   # I just happen to know that the second and third entities in the
-  #   # entities objects are edges.
-  #   entity1 = entities[1]
-  #   status = entity1.set_attribute "testdictionary", "test", 115
-  #   value = entity1.get_attribute "testdictoinary", "test"
+  #   # Read an attribute value from the edge. In this case this will return the
+  #   # default value provided; 42.
+  #   value = edge.get_attribute("MyExtension", "MyProperty", 42)
   #
-  # @param dict_name
+  # @param [String] dict_name
   #   The name of an attribute dictionary.
   #
-  # @param key
-  #   An attribute key.
+  # @param [Object] default_value
+  #   A default value to return if no attribute is found.
   #
-  # @param [optional] default_value
-  #   A default value to return if no attribute
-  #   is found.
+  # @param [String] key
+  #   An attribute key.
   #
-  # @return value - the retrieved value
+  # @return [Object] the retrieved value
   #
   # @version SketchUp 6.0
   def get_attribute(dict_name, key, default_value = nil)
@@ -280,7 +274,7 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   st = entity1.to_s
   #
-  # @return string - the string representation of the entity if
+  # @return [String] the string representation of the entity if
   #   successful
   #
   # @version SketchUp 6.0
@@ -308,7 +302,7 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   m = entity1.model
   #
-  # @return model - the model that contains the Entity object
+  # @return [Sketchup::Model] the model that contains the Entity object
   #
   # @version SketchUp 6.0
   def model
@@ -338,8 +332,8 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   parent = entity1.parent
   #
-  # @return entity - a Entity object representing the parent of
-  #   this entity
+  # @return [Sketchup::ComponentDefinition, Sketchup::Model] a Entity object
+  #   representing the parent of this entity
   #
   # @version SketchUp 6.0
   def parent
@@ -350,6 +344,28 @@ class Sketchup::Entity
   #
   # The persistent id persistent between sessions.
   #
+  # Note that only a subset of entity types support PIDs. Refer to the table
+  # below for which and when support was added.
+  #
+  # [SketchUp 2018]
+  #   - {Sketchup::Page}
+  # [SketchUp 2017]
+  #   - {Sketchup::Axes}
+  #   - {Sketchup::ComponentDefinition}
+  #   - {Sketchup::ComponentInstance}
+  #   - {Sketchup::ConstructionLine}
+  #   - {Sketchup::ConstructionPoint}
+  #   - {Sketchup::Curve}
+  #   - {Sketchup::Dimension}
+  #   - {Sketchup::Edge}
+  #   - {Sketchup::Face}
+  #   - {Sketchup::SectionPlane}
+  #   - {Sketchup::Text}
+  #   - {Sketchup::Vertex}
+  #   - Polyline3d entities exposed only as {Sketchup::Drawingelement} Use
+  #     {#typename} to determine if a {Sketchup::Drawingelement} is
+  #     a <tt>"Polyline3d"</tt>.
+  #
   # @example
   #   model = Sketchup.active_model
   #   entities = model.active_entities
@@ -382,10 +398,10 @@ class Sketchup::Entity
   #     status = entity.remove_observer observer
   #   end
   #
-  # @param observer
+  # @param [Object] observer
   #   An observer.
   #
-  # @return true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 6.0
   def remove_observer(observer)
@@ -419,16 +435,16 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   status = entity1.set_attribute "testdictionary", "test", 115
   #
-  # @param dict_name
+  # @param [String] dict_name
   #   The name of an attribute dictionary.
   #
-  # @param key
-  #   An attribute key.
-  #
-  # @param value
+  # @param [Object] value
   #   The value for the attribute.
   #
-  # @return value - the newly set value if successful
+  # @param [String] key
+  #   An attribute key.
+  #
+  # @return [Object] the newly set value if successful
   #
   # @version SketchUp 6.0
   def set_attribute(dict_name, key, value)
@@ -455,7 +471,7 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   st = entity1.to_s
   #
-  # @return string - the string representation of the entity if
+  # @return [String] the string representation of the entity if
   #   successful
   #
   # @version SketchUp 6.0
@@ -484,7 +500,7 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   type = entity1.typename
   #
-  # @return type - the type of the entity
+  # @return [String] the type of the entity
   #
   # @version SketchUp 6.0
   def typename
@@ -511,7 +527,7 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   status = entity1.valid?
   #
-  # @return status - true if deleted, false if not deleted
+  # @return [Boolean]
   #
   # @return [Boolean]
   #

data/SketchUp/Sketchup/Face.rb

@@ -35,7 +35,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   connected = face.all_connected
   #
-  # @return entities - the entities connected to the face
+  # @return [Array<Sketchup::Entity>] the entities connected to the face
   #
   # @version SketchUp 6.0
   def all_connected
@@ -66,15 +66,13 @@ class Sketchup::Face < Sketchup::Drawingelement
   #
   # @overload area
   #
-  #   @return              area - the area of the face in current units (if
-  #                        successful)
+  #   @return [Float] the area of the face in current units (if successful)
   #
   # @overload area(transform)
   #
-  #   @param transform     A Transformation object or array that can
-  #                        be interpreted as a Transformation object.
-  #   @return              area - the area of the face in current units (if
-  #                        successful)
+  #   @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)
   #
   # @version SketchUp 6.0
   def area(*args)
@@ -101,7 +99,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face.back_material = "red"
   #   material = face.back_material
   #
-  # @return material - a Material object representing the material
+  # @return [Sketchup::Material, nil] a Material object representing the material
   #   on the back of the face (if successful)
   #
   # @version SketchUp 6.0
@@ -125,10 +123,10 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   status = face.back_material = "red"
   #
-  # @param material
+  # @param [Sketchup::Material] material
   #   A Material object or the name of a valid material.
   #
-  # @return material - the name of the valid material or the new
+  # @return [Sketchup::Material] the name of the valid material or the new
   #   Material object (if successful)
   #
   # @version SketchUp 6.0
@@ -191,10 +189,10 @@ class Sketchup::Face < Sketchup::Drawingelement
   #     puts "#{pt.to_s} is not on the same plane as the face"
   #   end
   #
-  # @param point
+  # @param [Geom::Point3d] point
   #   A Point3d.
   #
-  # @return result - an integer describing where a Point3d is in
+  # @return [Integer] an integer describing where a Point3d is in
   #   relation to the referenced Face.
   #
   # @version SketchUp 6.0
@@ -217,7 +215,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   edges = face.edges
   #
-  # @return edges - an array of Edge objects (if successful)
+  # @return [Array<Sketchup::Edge>] an array of Edge objects (if successful)
   #
   # @version SketchUp 6.0
   def edges
@@ -279,18 +277,18 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   tw = Sketchup.create_texture_writer
   #   uvHelp = face.get_UVHelper(true, true, tw)
   #
-  # @param front
+  # @param [Boolean] front
   #   True if you want the texture coordinates for the front
   #   face, false if not. Defaults to true.
   #
-  # @param back
+  # @param [Sketchup::TextureWriter] texturewriter
+  #   An optional TextureWriter object.
+  #
+  # @param [Boolean] back
   #   True if you want the texture coordinates for the back
   #   face, false if not. Defaults to true.
   #
-  # @param texturewriter
-  #   A TextureWriter object.
-  #
-  # @return uvhelper - a UVHelper object
+  # @return [Sketchup::UVHelper] a UVHelper object
   #
   # @version SketchUp 6.0
   def get_UVHelper(front, back, texturewriter)
@@ -313,7 +311,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   glued_array = face.get_glued_instances
   #
-  # @return instances - An array of ComponentInstance objects that
+  # @return [Array<Sketchup::ComponentInstance, Sketchup::Group, Sketchup::Image>] An array of ComponentInstance objects that
   #   are currently glued to the face.
   #
   # @version SketchUp 7.0 M1
@@ -353,10 +351,10 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   # Get the projection of the applied material
   #   vector = face.get_texture_projection(true)
   #
-  # @param frontside
+  # @param [Boolean] frontside
   #   true for front side, false for back side.
   #
-  # @return vector - a vector on success, nil on failure.
+  # @return [Geom::Vector3d] a vector on success, nil on failure.
   #
   # @version SketchUp 2014
   def get_texture_projection(frontside)
@@ -380,7 +378,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   loops = face.loops
   #
-  # @return loops - an array of Loop objects if successful
+  # @return [Array<Sketchup::Loop>] an array of Loop objects if successful
   #
   # @version SketchUp 6.0
   def loops
@@ -408,7 +406,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face.material = "red"
   #   material = face.material
   #
-  # @return material - a Material object representing the material
+  # @return [Sketchup::Material, nil] a Material object representing the material
   #   on the front of the face (if successful)
   #
   # @version SketchUp 6.0
@@ -433,10 +431,10 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   status = face.material = "red"
   #
-  # @param material
+  # @param [Sketchup::Material] material
   #   A Material object or the name of a valid material.
   #
-  # @return material - the name of the valid material or the new
+  # @return [Sketchup::Material] the name of the valid material or the new
   #   Material object (if successful)
   #
   # @version SketchUp 6.0
@@ -504,7 +502,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   normal = face.normal
   #
-  # @return vector - a Vector3d object if successful
+  # @return [Geom::Vector3d] a Vector3d object if successful
   #
   # @version SketchUp 6.0
   def normal
@@ -526,7 +524,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   loop = face.outer_loop
   #
-  # @return loop - a Loop object representing the outer loop (if
+  # @return [Sketchup::Loop] a Loop object representing the outer loop (if
   #   successful)
   #
   # @version SketchUp 6.0
@@ -551,7 +549,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   plane = face.plane
   #
-  # @return plane - a plane that contains the face (if successful)
+  # @return [Array(Float, Float, Float, Float)] a plane that contains the face (if successful)
   #
   # @version SketchUp 6.0
   def plane
@@ -595,17 +593,17 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   on_front = true
   #   face.position_material(material, pt_array, on_front)
   #
-  # @param material
+  # @param [Sketchup::Material] material
   #   a Material object.
   #
-  # @param pt_array
-  #   An array of Point3d objects used to position the material.
-  #
-  # @param o_front
+  # @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.
   #
-  # @return the face upon success, false upon failure.
+  # @param [Array<Geom::Point3d>] pt_array
+  #   An array of Point3d objects used to position the material.
+  #
+  # @return [Sketchup::Face, false] the face upon success, false upon failure.
   #
   # @version SketchUp 6.0
   def position_material(material, pt_array, o_front)
@@ -629,18 +627,18 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   status = face.pushpull(100, true)
   #
-  # @param distance
+  # @param [Numeric] distance
   #   The distance, in current units, to push/pull the face.
   #
-  # @param copy
+  # @param [Boolean] copy
   #   Create a new push/pull starting face if true (equivalent
   #   of pressing CTRL while in SketchUp), do not create a
   #   push/pull starting face if false.
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 6.0
-  def pushpull(distance, copy)
+  def pushpull(distance, copy = false)
   end
 
   # The reverse! method is used to reverse the face's orientation, meaning the
@@ -660,7 +658,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   status = face.reverse!
   #
-  # @return face - the reversed Face object if successful, false if
+  # @return [Sketchup::Face, false] the reversed Face object if successful, false if
   #   unsuccessful
   #
   # @version SketchUp 6.0
@@ -670,6 +668,9 @@ class Sketchup::Face < Sketchup::Drawingelement
   # 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.
+  #
   # @example
   #   model = Sketchup.active_model
   #   entities = model.active_entities
@@ -697,14 +698,14 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   # Returns nil if not successful, path if successful
   #   result = face.set_texture_projection(face.normal, true)
   #
-  # @param vector
+  # @param [Geom::Vector3d] vector
   #   representing the direction of the projection. Use nil
   #   to remove the projection.
   #
-  # @param frontside
+  # @param [Boolean] frontside
   #   true for front side, false for back side.
   #
-  # @return boolean - true on success
+  # @return [Boolean] true on success
   #
   # @version SketchUp 2014
   def set_texture_projection(vector, frontside)
@@ -728,7 +729,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   vertices = face.vertices
   #
-  # @return vertices - an array of Vertex objects if successful
+  # @return [Array<Sketchup::Vertex>] an array of Vertex objects if successful
   #
   # @version SketchUp 6.0
   def vertices