sketchup-api-stubs 0.1.2 → 0.2.0

data/SketchUp/Sketchup/InstancePath.rb

@@ -18,7 +18,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   if path.size > 1
   #     # do something
   #   end
@@ -36,7 +36,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   path[0] == group # returns true
   #   path[1] == edge # returns true
   #
@@ -60,7 +60,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   path.each { |entity|
   #     # do something
   #   }
@@ -80,7 +80,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   if path.empty?
   #     # do something...
   #   end
@@ -99,7 +99,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   if path.include?(edge)
   #     # do something...
   #   end
@@ -144,7 +144,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   path.leaf == edge # returns true
   #
   # @raise [TypeError] if the instance path refer to deleted entities.
@@ -161,7 +161,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   if path.length > 1
   #     # do something
   #   end
@@ -183,7 +183,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   pid_path = path.persistent_id_path # something like "342.345"
   #
   # @raise [TypeError] if the instance path refer to deleted entities.
@@ -204,7 +204,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   path.root == group # returns true
   #
   # @raise [TypeError] if the instance path refer to deleted entities.
@@ -220,7 +220,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   if path.size > 1
   #     # do something
   #   end
@@ -240,7 +240,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   pid_string = path.to_a.join('.')
   #
   # @raise [TypeError] if the instance path refer to deleted entities.
@@ -259,7 +259,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   tr = path.transformation
   #
   # @param [Integer] index
@@ -286,7 +286,7 @@ class Sketchup::InstancePath
   #   model = Sketchup.active_model
   #   group = model.entities.add_group
   #   edge = group.entities.add_line([10, 10, 10], [20, 20, 20])
-  #   path = Sketchup::InstancePath.new(group, edge])
+  #   path = Sketchup::InstancePath.new([group, edge])
   #   if path.valid?
   #     # do something...
   #   end

data/SketchUp/Sketchup/Layer.rb

@@ -171,22 +171,18 @@ class Sketchup::Layer < Sketchup::Entity
   def page_behavior
   end
 
-  # The page_behavior= method is used to control the layer's visibility behavior
-  # on existing and new pages.
-  #
-  # The behavior is composed of a combination of these flags:
-  #   - LAYER_VISIBLE_BY_DEFAULT: 0x0000
-  #   - LAYER_HIDDEN_BY_DEFAULT: 0x0001
-  #   - LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES: 0x0000
-  #   - LAYER_IS_VISIBLE_ON_NEW_PAGES: 0x0010
-  #   - LAYER_IS_HIDDEN_ON_NEW_PAGES: 0x0020
+  # The {#page_behavior=} method is used to control the layer's visibility
+  # behavior on existing and new pages.
   #
   # When you Update a page (as opposed to creating a new page) the current
   # visibility of the layer is used.
   #
-  # NOTE: Prior to SketchUp 2014 the <code>LAYER_HIDDEN_BY_DEFAULT</code> flag
-  # would trigger the validation check in SketchUp that would reset the
-  # <code>page_behavior</code> of the layer.
+  # The behavior is composed of a combination of these flags:
+  # [+LAYER_VISIBLE_BY_DEFAULT: 0x0000+]
+  # [+LAYER_HIDDEN_BY_DEFAULT: 0x0001+]
+  # [+LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES: 0x0000+]
+  # [+LAYER_IS_VISIBLE_ON_NEW_PAGES: 0x0010+]
+  # [+LAYER_IS_HIDDEN_ON_NEW_PAGES: 0x0020+]
   #
   # @example
   #   layers = Sketchup.active_model.layers
@@ -194,14 +190,16 @@ class Sketchup::Layer < Sketchup::Entity
   #   behavior = LAYER_HIDDEN_BY_DEFAULT | LAYER_IS_HIDDEN_ON_NEW_PAGES
   #   layer.page_behavior = behavior
   #
-  # @param pagebehavior
-  #   Pagebehavior value.
+  # @note Prior to SketchUp 2014 the +LAYER_HIDDEN_BY_DEFAULT+ flag
+  #   would trigger the validation check in SketchUp that would reset the
+  #   {#page_behavior} of the layer.
+  #
+  # @param [Integer] page_behavior
   #
-  # @return pagebehavior - an integer representing the default
-  #   visibility of the layer.
+  # @return [Integer]
   #
   # @version SketchUp 6.0
-  def page_behavior=(pagebehavior)
+  def page_behavior=(page_behavior)
   end
 
   # The visible= method is used to set if the layer is visible.

data/SketchUp/Sketchup/Material.rb

@@ -43,10 +43,10 @@ class Sketchup::Material < Sketchup::Entity
   #   m2 = materials.add('Fred')
   #   p m1 <=> m2
   #
-  # @param material2
+  # @param [Sketchup::Material] material2
   #   A Material object.
   #
-  # @return status - 0 if they are equal, positive number if
+  # @return [Integer] 0 if they are equal, positive number if
   #   material1 > material2, negative if material1 < material2
   #
   # @version SketchUp 6.0
@@ -66,10 +66,10 @@ class Sketchup::Material < Sketchup::Entity
   #     UI.messagebox('The Materials are not equal.')
   #   end
   #
-  # @param material2
+  # @param [Sketchup::Material] material2
   #   A Material object.
   #
-  # @return status - true if the materials are the same, false if
+  # @return [Boolean] true if the materials are the same, false if
   #   they are different
   #
   # @version SketchUp 6.0
@@ -85,7 +85,7 @@ class Sketchup::Material < Sketchup::Entity
   # @example
   #   alpha_value = Sketchup.active_model.materials[0].alpha
   #
-  # @return alpha - a number between 0 and 1
+  # @return [Float] a number between 0 and 1
   #
   # @version SketchUp 6.0
   def alpha
@@ -103,10 +103,10 @@ class Sketchup::Material < Sketchup::Entity
   #   material = materials.add('Joe')
   #   material.alpha = 0.5
   #
-  # @param alpha
+  # @param [Float] alpha
   #   An opacity value.
   #
-  # @return status - the newly set opacity value
+  # @return [Float] the newly set opacity value
   #
   # @version SketchUp 6.0
   def alpha=(alpha)
@@ -123,7 +123,7 @@ class Sketchup::Material < Sketchup::Entity
   #   material.color = 'red'
   #   color = material.color
   #
-  # @return color - a Color object
+  # @return [Sketchup::Color] a Color object
   #
   # @version SketchUp 6.0
   def color
@@ -143,10 +143,10 @@ class Sketchup::Material < Sketchup::Entity
   #   material = materials.add('Joe')
   #   material.color = 'red'
   #
-  # @param color
+  # @param [Sketchup::Color, String, nil] color
   #   A Color object.
   #
-  # @return color - the newly set Color object's name
+  # @return [Sketchup::Color, String, nil] the newly set Color object
   #
   # @version SketchUp 6.0
   def color=(color)
@@ -158,7 +158,7 @@ class Sketchup::Material < Sketchup::Entity
   #   material = Sketchup.active_model.materials[0]
   #   h, l, s = material.colorize_deltas
   #
-  # @return Array - An array of floats representing the HLS delta.
+  # @return [Array(Float, Float, Float)] An array of floats representing the HLS delta.
   #
   # @version SketchUp 2015
   def colorize_deltas
@@ -176,7 +176,7 @@ class Sketchup::Material < Sketchup::Entity
   #   material = Sketchup.active_model.materials[0]
   #   type = material.colorize_type
   #
-  # @return type - the colorize type for the Material object.
+  # @return [Integer] the colorize type for the Material object.
   #
   # @version SketchUp 2015
   def colorize_type
@@ -194,10 +194,10 @@ class Sketchup::Material < Sketchup::Entity
   #   material = Sketchup.active_model.materials[0]
   #   material.colorize_type = Sketchup::Material::COLORIZE_TINT
   #
-  # @param type
-  #   - the new colorize type for the Material object.
+  # @param [Integer] type
+  #   the new colorize type for the Material object.
   #
-  # @return type - the colorize type for the Material object.
+  # @return [Integer] the colorize type for the Material object.
   #
   # @version SketchUp 2015
   def colorize_type=(type)
@@ -219,7 +219,7 @@ class Sketchup::Material < Sketchup::Entity
   #   # to the UI like SketchUp does.
   #   puts material.display_name # Outputs "Joe"
   #
-  # @return name - the display name for the material
+  # @return [String] the display name for the material
   #
   # @version SketchUp 6.0
   def display_name
@@ -237,7 +237,7 @@ class Sketchup::Material < Sketchup::Entity
   #   material = Sketchup.active_model.materials[0]
   #   type = material.materialType
   #
-  # @return type - the material type for the Material object. See
+  # @return [Integer] the material type for the Material object. See
   #   summary for details.
   #
   # @version SketchUp 6.0
@@ -260,7 +260,7 @@ class Sketchup::Material < Sketchup::Entity
   #   # to the UI like SketchUp does.
   #   puts material.display_name # Outputs "Joe"
   #
-  # @return name - the name of the Material object
+  # @return [String] the name of the Material object
   #
   # @version SketchUp 6.0
   def name
@@ -273,7 +273,13 @@ class Sketchup::Material < Sketchup::Entity
   #   material = materials.add("Joe")
   #   material.name = 'Jeff'
   #
-  # @return name - the newly set material name.
+  # @param [String] str
+  #   the new material name
+  #
+  # @raise [ArgumentError] if the name is not unique to the model.
+  #   (Added in SU2018)
+  #
+  # @return [String] the newly set material name.
   #
   # @version SketchUp 8.0 M1
   def name=(str)
@@ -309,7 +315,7 @@ class Sketchup::Material < Sketchup::Entity
   #   material.texture = "C:/Materials/Carpet.jpg"
   #   texture = material.texture
   #
-  # @return texture - the Texture object within the Material.
+  # @return [Sketchup::Texture, nil] the Texture object within the Material.
   #   Returns nil if the Material does not have a texture.
   #
   # @version SketchUp 6.0
@@ -328,15 +334,20 @@ class Sketchup::Material < Sketchup::Entity
   #
   # @overload texture=(filename)
   #
-  #   @param [String] filename The file path to the texture the material should
-  #     use.
+  #   @param filename [String] The file path to the texture the material should use.
+  #   @return [String]
+  #
+  # @overload texture=(image_rep)
+  #
+  #   @param [Sketchup::ImageRep] image_rep The pixel data representing the
+  #     texture. (Added in SketchUp 2018)
+  #   @return [Sketchup::ImageRep]
   #
   # @overload texture=(properties)
   #
-  #   @param [Array<String, Integer, Integer>] properties An array with the
+  #   @param properties [Array(String, Integer, Integer)] An array with the
   #     texture filename and optionally the width and height in model units.
-  #
-  # @return [Sketchup::Texture] the newly set Texture object
+  #   @return [Array(String, Integer, Integer)]
   #
   # @version SketchUp 6.0
   def texture=(arg)
@@ -351,8 +362,7 @@ class Sketchup::Material < Sketchup::Entity
   #   material = Sketchup.active_model.materials[0]
   #   is_alpha = material.use_alpha?
   #
-  # @return type - the material type for the Material object. See
-  #   summary for details.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -369,13 +379,13 @@ class Sketchup::Material < Sketchup::Entity
   #     material.write_thumbnail(thumbnail_file, 128)
   #   }
   #
-  # @param filename
+  # @param [String] filename
   #   The file name for the thumbnail.
   #
-  # @param resolution
+  # @param [Integer] resolution
   #   The resolution of the thumbnail.
   #
-  # @return status - true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 8.0 M1
   def write_thumbnail(filename, resolution)

data/SketchUp/Sketchup/Materials.rb

@@ -29,14 +29,14 @@ class Sketchup::Materials < Sketchup::Entity
   #
   # @overload [](index)
   #
-  #   @param index         A number representing the material's index in an array
+  #   @param index [Integer] A number representing the material's index in an array
   #                        of Material objects.
-  #   @return              material - a Material object on success, Nil on failure
+  #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @overload [](name)
   #
-  #   @param name          The name of the material.
-  #   @return              material - a Material object on success, Nil on failure
+  #   @param name [String] The name of the material.
+  #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @version SketchUp 6.0
   def [](arg)
@@ -53,10 +53,10 @@ class Sketchup::Materials < Sketchup::Entity
   #   materials = model.materials
   #   material = materials.add('Joe')
   #
-  # @param name
+  # @param [String] name
   #   The name of the new material.
   #
-  # @return material - a Material object
+  # @return [Sketchup::Material] a Material object
   #
   # @version SketchUp 6.0
   def add(name)
@@ -69,10 +69,10 @@ class Sketchup::Materials < Sketchup::Entity
   #   materials = Sketchup.active_model.materials
   #   status = materials.add_observer(observer)
   #
-  # @param observer
+  # @param [Object] observer
   #   An observer.
   #
-  # @return success - true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 6.0
   def add_observer(observer)
@@ -89,14 +89,14 @@ class Sketchup::Materials < Sketchup::Entity
   #
   # @overload [](index)
   #
-  #   @param index         A number representing the material's index in an array
+  #   @param index [Integer] A number representing the material's index in an array
   #                        of Material objects.
-  #   @return              material - a Material object on success, Nil on failure
+  #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @overload [](name)
   #
-  #   @param name          The name of the material.
-  #   @return              material - a Material object on success, Nil on failure
+  #   @param name [String] The name of the material.
+  #   @return [Sketchup::Material, nil] a Material object on success, Nil on failure
   #
   # @version SketchUp 6.0
   def at(arg)
@@ -125,7 +125,7 @@ class Sketchup::Materials < Sketchup::Entity
   # @example
   #   current = Sketchup.active_model.materials.current
   #
-  # @return material - a Material object.
+  # @return [Sketchup::Material] a Material object.
   #
   # @version SketchUp 6.0
   def current
@@ -138,10 +138,10 @@ class Sketchup::Materials < Sketchup::Entity
   #   materials = Sketchup.active_model.materials
   #   materials.current = materials[0]
   #
-  # @param material
+  # @param [Sketchup::Material] material
   #   A Material object.
   #
-  # @return true if successful, false if unsuccessful.
+  # @return [Sketchup::Material]
   #
   # @version SketchUp 6.0
   def current=(material)
@@ -155,11 +155,11 @@ class Sketchup::Materials < Sketchup::Entity
   #     puts material.display_name
   #   }
   #
-  # @return material - a Material object
+  # @return [nil]
   #
   # @version SketchUp 6.0
   #
-  # @yield [material] A variable that will hold each Material object as they
+  # @yield [Sketchup::Material] A variable that will hold each Material object as they
   #   are found.
   def each
   end
@@ -206,7 +206,7 @@ class Sketchup::Materials < Sketchup::Entity
   #   materials = Sketchup.active_model.materials
   #   materials.purge_unused
   #
-  # @return materials - The Materials object.
+  # @return [Sketchup::Materials] The Materials object.
   #
   # @version SketchUp 6.0
   def purge_unused
@@ -241,10 +241,10 @@ class Sketchup::Materials < Sketchup::Entity
   #   material = materials.add('Joe')
   #   materials.remove(material)
   #
-  # @param material
+  # @param [Sketchup::Material] material
   #   The material to remove.
   #
-  # @return status - true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 8.0 M1
   def remove(material)
@@ -257,10 +257,10 @@ class Sketchup::Materials < Sketchup::Entity
   #   materials = Sketchup.active_model.materials
   #   status = materials.remove_observer(observer)
   #
-  # @param observer
+  # @param [Object] observer
   #   An observer.
   #
-  # @return success - true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 6.0
   def remove_observer(observer)
@@ -282,4 +282,22 @@ class Sketchup::Materials < Sketchup::Entity
   def size
   end
 
+  # The {#unique_name} method is used to retrieve a unique name from the
+  # materials collection that is based on the provided one. If provided name is
+  # unique it will be returned, otherwise any trailing indices will be replaced
+  # by a new index.
+  #
+  # @example
+  #   materials = Sketchup.active_model.materials
+  #   unique_name = materials.unique_name("test_name")
+  #
+  # @param [String] name
+  #   the suggested name.
+  #
+  # @return [String] a unique name.
+  #
+  # @version SketchUp 2018
+  def unique_name(name)
+  end
+
 end