sketchup-api-stubs 0.1.2 → 0.2.0

data/SketchUp/Layout/TableRow.rb

@@ -0,0 +1,135 @@
+# Copyright:: Copyright 2017 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# A {Layout::TableColumn} is a single row from a table.
+#
+# @example
+#   bounds = Geom::Bounds2d.new(1, 1, 4, 4)
+#   rows = 4
+#   columns = 4
+#   table = Layout::Table.new(bounds, rows, columns)
+#   rows.times { |index|
+#     row = table.row(index)
+#   }
+#
+# @version LayOut 2018
+class Layout::TableRow
+
+  # Instance Methods
+
+  # The {#bottom_edge_style} method returns the {Layout::Style} of a
+  # {Layout::TableRow}'s bottom edge.
+  #
+  # @example
+  #   bounds = Geom::Bounds2d.new(1, 1, 4, 4)
+  #   rows = 4
+  #   columns = 4
+  #   table = Layout::Table.new(bounds, rows, columns)
+  #   style = table.get_row(1).bottom_edge_style
+  #
+  # @return [Layout::Style]
+  #
+  # @version LayOut 2018
+  def bottom_edge_style
+  end
+
+  # The {#bottom_edge_style=} method sets the {Layout::Style} of a
+  # {Layout::TableRow}'s bottom edge.
+  #
+  # @example
+  #   bounds = Geom::Bounds2d.new(1, 1, 4, 4)
+  #   rows = 4
+  #   columns = 4
+  #   table = Layout::Table.new(bounds, rows, columns)
+  #   style = Layout::Style.new
+  #   style.stroke_width = 2.0
+  #   table.get_row(1).bottom_edge_style = style
+  #
+  # @param [Layout::Style] style
+  #
+  # @raise [LockedEntityError] if the {Layout::Table} is locked
+  #
+  # @raise [LockedLayerError] if the {Layout::Table} is on a locked
+  #   {Layout::Layer}
+  #
+  # @version LayOut 2018
+  def bottom_edge_style=(style)
+  end
+
+  # The {#height} method returns the height of the {Layout::TableRow}.
+  #
+  # @example
+  #   bounds = Geom::Bounds2d.new(1, 1, 4, 4)
+  #   rows = 4
+  #   columns = 4
+  #   table = Layout::Table.new(bounds, rows, columns)
+  #   height = table.get_row(1).height
+  #
+  # @return [Float]
+  #
+  # @version LayOut 2018
+  def height
+  end
+
+  # The {#height=} method sets the height of the {Layout::TableRow}.
+  #
+  # @example
+  #   bounds = Geom::Bounds2d.new(1, 1, 4, 4)
+  #   rows = 4
+  #   columns = 4
+  #   table = Layout::Table.new(bounds, rows, columns)
+  #   table.get_row(1).height = 3.0
+  #
+  # @param [Float] height
+  #
+  # @raise [ArgumentError] if height is not a valid height
+  #
+  # @raise [LockedEntityError] if the {Layout::Table} is locked
+  #
+  # @raise [LockedLayerError] if the {Layout::Table} is on a locked
+  #   {Layout::Layer}
+  #
+  # @version LayOut 2018
+  def height=(height)
+  end
+
+  # The {#top_edge_style} method returns the {Layout::Style} of a
+  # {Layout::TableRow}'s top edge.
+  #
+  # @example
+  #   bounds = Geom::Bounds2d.new(1, 1, 4, 4)
+  #   rows = 4
+  #   columns = 4
+  #   table = Layout::Table.new(bounds, rows, columns)
+  #   style = table.get_row(1).top_edge_style
+  #
+  # @return [Layout::Style]
+  #
+  # @version LayOut 2018
+  def top_edge_style
+  end
+
+  # The {#top_edge_style=} method sets the {Layout::Style} of a
+  # {Layout::TableRow}'s top edge.
+  #
+  # @example
+  #   bounds = Geom::Bounds2d.new(1, 1, 4, 4)
+  #   rows = 4
+  #   columns = 4
+  #   table = Layout::Table.new(bounds, rows, columns)
+  #   style = Layout::Style.new
+  #   style.stroke_width = 2.0
+  #   table.get_row(1).top_edge_style = style
+  #
+  # @param [Layout::Style] style
+  #
+  # @raise [LockedEntityError] if the {Layout::Table} is locked
+  #
+  # @raise [LockedLayerError] if the {Layout::Table} is on a locked
+  #   {Layout::Layer}
+  #
+  # @version LayOut 2018
+  def top_edge_style=(style)
+  end
+
+end

data/SketchUp/Sketchup/Animation.rb

@@ -121,12 +121,15 @@ class Sketchup::Animation
   # an example of this.
   #
   # @example
-  #   def stop
-  #     # Insert your handler code for cleaning up after your animation.
+  #   class MyAnimation
+  #     def stop
+  #       # Insert your handler code for cleaning up after your animation.
+  #     end
   #   end
   #
-  # @note Do not call +view.animation = nil+ within this method! This will cause
-  #   a recursive loop and crash SketchUp.
+  # @note Do not call {#Sketchup::View#animation=} from this method. This will
+  #   cause a recursive loop and crash SketchUp 2017 and earlier versions.
+  #   As of SketchUp 2018 this will raise a +RunTimeError+.
   #
   # @return [nil]
   #

data/SketchUp/Sketchup/ArcCurve.rb

@@ -53,24 +53,24 @@ class Sketchup::ArcCurve < Sketchup::Curve
   def center
   end
 
-  # The end_angle method is used to retrieve the angle of the end of the arc
+  # The {#end_angle} method is used to retrieve the angle of the end of the arc
   # measured from the X axis in radians.
   #
   # @example
   #   # Create a 1/2 circle, normal to the Z axis
-  #   center = Geom::Point3d.new
-  #   normal = Geom::Vector3d.new 0,0,1
-  #   xaxis = Geom::Vector3d.new 1,0,0
   #   start_a = 0.0
-  #   end_a = Math::PI
+  #   end_a = 180.degrees
   #   model = Sketchup.active_model
   #   entities = model.entities
-  #   edgearray = entities.add_arc center, xaxis, normal, 5, start_a, end_a
-  #   edge = edgearray[0]
-  #   arccurve = edge.curve
-  #   end_angle = arccurve.end_angle
+  #   edges = entities.add_arc(ORIGIN, X_AXIS, Z_AXIS, 5, start_a, end_a)
+  #   arc_curve = edges.first.curve
+  #   end_angle = arc_curve.end_angle
+  #
+  # @note A bug in SketchUp 2017 and older will report the end-angle for some
+  #   circles as more than 360 degrees. In such case, subtract +2 * PI+ from
+  #   the end angle value.
   #
-  # @return angle - the angle of the end of the arc if successful
+  # @return [Float]
   #
   # @version SketchUp 6.0
   def end_angle

data/SketchUp/Sketchup/AttributeDictionaries.rb

@@ -42,10 +42,10 @@ class Sketchup::AttributeDictionaries < Sketchup::Entity
   #     UI.messagebox("No dictionary found.")
   #   end
   #
-  # @param key
+  # @param [String] key
   #   The name of the attribute dictionary.
   #
-  # @return dictionary - the dictionary
+  # @return [Sketchup::AttributeDictionary] the dictionary
   #
   # @version SketchUp 6.0
   def [](key)
@@ -71,17 +71,26 @@ class Sketchup::AttributeDictionaries < Sketchup::Entity
   # AttributeDictionary can be passed directly or identified by its
   # string name.
   #
+  # 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.
+  #
+  # object
+  #
   # @example
   #   model = Sketchup.active_model
   #   attrdicts = model.attribute_dictionaries
   #   # Deletes a dictionary called 'my_dictionary'
   #   attrdicts.delete 'my_dictionary'
   #
-  # @param key_or_dict
+  # @param [String, Sketchup::AttributeDictionary] key_or_dict
   #   The name of the attribute dictionary to delete, or
   #   the dictionary object itself.
   #
-  # @return dictionaries - the modified AttributeDictionaries object
+  # @raise ArgumentError if an advanced attribute dictionary is being deleted.
+  #
+  # @return [Sketchup::AttributeDictionaries] the modified AttributeDictionaries
   #
   # @version SketchUp 6.0
   def delete(key_or_dict)

data/SketchUp/Sketchup/AttributeDictionary.rb

@@ -31,10 +31,10 @@ class Sketchup::AttributeDictionary < Sketchup::Entity
   #   # value will contain 115
   #   value = attrdict["test"]
   #
-  # @param key
+  # @param [String] key
   #   The name of the attribute.
   #
-  # @return attribute - the attribute stored under your key, or
+  # @return [Object, nil] the attribute stored under your key, or
   #   nil if not found
   #
   # @version SketchUp 6.0
@@ -56,13 +56,13 @@ class Sketchup::AttributeDictionary < Sketchup::Entity
   #     UI.messagebox value
   #   end
   #
-  # @param key
+  # @param [String] key
   #   The valid key.
   #
-  # @param value
+  # @param [Boolean, Fixnum, Float, Length, nil, String, Time, Array, Geom::Point3d, Geom::Vector3d] value
   #   The value to be set.
   #
-  # @return value - the value that was set if successful, or false
+  # @return [Object, nil] the value that was set if successful, or false
   #   if unsuccessful.
   #
   # @version SketchUp 6.0
@@ -88,18 +88,18 @@ class Sketchup::AttributeDictionary < Sketchup::Entity
   # @example
   #   create_if_nil = true
   #   model = Sketchup.active_model
-  #   attrdict = model.attribute_dictionary "test_dict", create_if_nil
+  #   attrdict = model.attribute_dictionary("test_dict", create_if_nil)
   #   attrdict["attr_one"] = "one"
   #   attrdict["attr_two"] = "two"
   #
-  #   # Gets an array of values
+  #   # Delete a key/value pair and get the deleted value.
   #   attrdict = model.attribute_dictionaries['test_dict']
   #   value = attrdict.delete_key("attr_one")
   #
-  # @param key
+  # @param [String] key
   #   The key to be deleted.
   #
-  # @return value - the value of the key
+  # @return [Object, nil] the value of the key
   #
   # @version SketchUp 6.0
   def delete_key(key)
@@ -198,7 +198,7 @@ class Sketchup::AttributeDictionary < Sketchup::Entity
   #   attrdict = model.attribute_dictionaries['test_dict']
   #   keys = attrdict.keys
   #
-  # @return keys - an array of keys within the attribute dictionary
+  # @return [Array<String>] an array of keys within the attribute dictionary
   #   if successful
   #
   # @version SketchUp 6.0
@@ -234,7 +234,7 @@ class Sketchup::AttributeDictionary < Sketchup::Entity
   #   # Show the name.
   #   UI.messagebox attrdict.name
   #
-  # @return name - the name of the attribute dictionary if
+  # @return [String] the name of the attribute dictionary if
   #   successful
   #
   # @version SketchUp 6.0
@@ -271,7 +271,7 @@ class Sketchup::AttributeDictionary < Sketchup::Entity
   #   attrdict = model.attribute_dictionaries['test_dict']
   #   values = attrdict.values
   #
-  # @return keys - an array of keys within the attribute dictionary
+  # @return [Array<Object>] an array of values within the attribute dictionary
   #   if successful
   #
   # @version SketchUp 6.0

data/SketchUp/Sketchup/Color.rb

@@ -2,7 +2,7 @@
 # License:: The MIT License (MIT)
 
 # The Color class is used to create and manipulate colors within SketchUp
-# models.
+# Models. The class can also be used the same way with LayOut documents.
 #
 # For methods that accept a Color object, such as the
 # face.material method, you can pass in an actual Color object, or an object
@@ -10,7 +10,6 @@
 #
 # SketchUp ships with several built in colors in the Materials Browser.
 # These colors are listed in the following table.
-#
 # {include:file:assets/colors.html}
 #
 # @example
@@ -27,8 +26,8 @@ class Sketchup::Color
 
   # Class Methods
 
-  # The names method is used to retrieve an array of all color names recognized
-  # by SketchUp.
+  # The {#names} method is used to retrieve an array of all color names
+  # recognized by SketchUp.
   #
   # In general, whenever a method wants a color, you can pass in a String with
   # one of these names.
@@ -36,8 +35,7 @@ class Sketchup::Color
   # @example
   #   array = Sketchup::Color.names
   #
-  # @return names - an array of all SketchUp color names if
-  #   successful
+  # @return [Array]
   #
   # @version SketchUp 6.0
   def self.names
@@ -45,36 +43,51 @@ class Sketchup::Color
 
   # Instance Methods
 
-  # The alpha method is used to retrieve the opacity of the color. A value of 0
-  # is transparent, 255 is opaque.
+  # The {#==} method checks to see if the two {Sketchup::Color}s are equal. This
+  # checks whether the RGBA values are the same. In versions prior to SketchUp
+  # 2018 two color objects with the same values would be considered different.
+  #
+  # @example
+  #   SketchUp::Color.new(255, 255, 255) == Sketchup::Color.new(1.0, 1.0, 1.0)
+  #
+  # @param [Object] other
+  #
+  # @return [Boolean]
+  #
+  # @version SketchUp 2018
+  def ==(other)
+  end
+
+  # The {#alpha} method is used to retrieve the opacity of the color. A value of
+  # 0 is transparent, 255 is opaque.
   #
   # @example
   #   color = Sketchup::Color.new "OldLace"
   #   alpha = color.alpha
   #
-  # @return alpha - the opacity of the color if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def alpha
   end
 
-  # The alpha= method is used to set the opacity of the color. A value of 0 is
+  # The {#alpha=} method is used to set the opacity of the color. A value of 0 is
   # transparent, 255 is opaque.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
   #   alpha = color.alpha = 255
   #
-  # @param alpha
+  # @param [Integer] alpha
   #   The new opacity value.
   #
-  # @return alpha - the newly set opacity value if successful
+  # @return [Integer]
   #
   # @version SketchUp 8.0 M1
   def alpha=(alpha)
   end
 
-  # The blend method is used to blend two colors.
+  # The {#blend} method is used to blend two colors.
   #
   # The blended color will be the result of taking (1 - weight) * color1 +
   # weight * color2. If weight = 0, you will get color2. If weight = 1 you will
@@ -85,93 +98,76 @@ class Sketchup::Color
   #   color2 = Sketchup::Color.new "AliceBlue"
   #   color3 = color1.blend color2, 0.5
   #
-  # @param color2
-  #   The second color to be blended (with this color).
+  # @param [Sketchup::Color] color2
+  #   The second color to be blended
+  #   (with this color).
   #
-  # @param weight
+  # @param [Float] weight
   #   A Float between 0.0 and 1.0
   #
-  # @return color3 - the newly blended Color object if successful
+  # @return [Sketchup::Color]
   #
   # @version SketchUp 6.0
   def blend(color2, weight)
   end
 
-  # The blue method is used to retrieve the blue value of a color. Colors are
-  # comprised of red, green, and blue values.
+  # The {#blue} method is used to retrieve the blue value of a color.
   #
   # Value range is 0 to 255.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
-  #   setting = color.blue
+  #   blue = color.blue
   #
-  # @return blue - the blue value for the color if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def blue
   end
 
-  # The blue= method is used to set the blue value of a color. Colors are
-  # comprised of red, green, and blue values.
+  # The {#blue=} method is used to set the blue value of a color.
   #
   # Value range is 0 to 255.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
-  #   setting = color.blue = 200
-  #   if (setting)
-  #     UI.messagebox setting
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
-  #
-  # @param blue
+  #   blue = color.blue = 200
+  #
+  # @param [Integer] blue
   #   The blue value for the color.
   #
-  # @return blue - the new blue value for the color if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def blue=(blue)
   end
 
-  # The green method is used to retrieve the green value of a color. Colors are
-  # comprised of red, green, and blue values.
+  # The {#green} method is used to retrieve the green value of a color.
   #
   # Value range is 0 to 255.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
-  #   setting = color.green
-  #   if (setting)
-  #     UI.messagebox setting
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
+  #   green = color.green
   #
-  # @return green - the green value for the color if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def green
   end
 
-  # The green= method is used to set the green component of a RGB Color.
+  # The {#green=} method is used to set the green component of a RGB Color.
   #
   # Value range is 0 to 255.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
-  #   setting = color.green = 200
-  #   if (setting)
-  #     UI.messagebox setting
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
-  #
-  # @param green
+  #   green = color.green = 200
+  #
+  # @param [Integer] green
   #   The green value for the color.
   #
-  # @return green - the new green value for the color if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def green=(green)
@@ -183,6 +179,7 @@ class Sketchup::Color
   #   color_from_name = Sketchup::Color.new "OldLace"
   #   color_from_rgb = Sketchup::Color.new(0, 128, 255)
   #   color_from_rgba = Sketchup::Color.new(0, 128, 255, 128)
+  #   color_from_hex = Sketchup::Color.new(0xFF0000)
   #
   #   # You can then assign colors to the material of DrawingElements.
   #   # Note that this creates a new Material object, and the alpha value
@@ -191,11 +188,14 @@ class Sketchup::Color
   #   face.material = color_from_rgba
   #   face.material.alpha = 0.5
   #
-  # @overload initialize(red, green, blue)
+  # @note When assigning colors via a hexadecimal, R and B will be flipped.
+  #
+  # @overload initialize(red, green, blue, alpha = 255)
   #
   #   @param [Integer] red   A red value between 0 and 255.
   #   @param [Integer] green A green value between 0 and 255.
   #   @param [Integer] blue  A blue value between 0 and 255.
+  #   @param [Integer] alpha A alpha value between 0 and 255.
   #   @return [Sketchup::Color]
   #
   # @overload initialize(name)
@@ -209,80 +209,70 @@ class Sketchup::Color
   def initialize(*args)
   end
 
-  # The red method is used to retrieve the red component of a RGB Color.
+  # The {#red} method is used to retrieve the red component of a RGB Color.
   #
   # Value range is 0 to 255.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
-  #   setting = color.red
-  #   if (setting)
-  #     UI.messagebox setting
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
+  #   red = color.red
   #
-  # @return red - the red value for the color if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def red
   end
 
-  # The red= method is used to set the red component of a RGB Color.
+  # The {#red=} method is used to set the red component of a RGB Color.
   #
   # Value range is 0 to 255.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
-  #   setting = color.red=200
+  #   red = color.red=200
   #
-  # @param red
+  # @param [Integer] red
   #   The red value for the color.
   #
-  # @return red - the new red value for the color if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def red=(red)
   end
 
-  # The to_a method is used to convert a Color object to an Array object. The
+  # The {#to_a} method is used to convert a Color object to an Array object. The
   # returned array will contain 4 integer values (RGBA) between 0 and 255.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
   #   color_array = color.to_a
-  #   if (color_array)
-  #     UI.messagebox color_array.to_s
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
   #
-  # @return array - an Array object if successful
+  # @return [Array]
   #
   # @version SketchUp 6.0
   def to_a
   end
 
-  # The to_i method is used to convert a Color object to an 32 bit integer.
+  # The {#to_i} method is used to convert a Color object to an 32 bit integer.
   #
   # @example
   #   color = Sketchup::Color.new "AliceBlue"
   #   integer = color.to_i
   #
-  # @return integer - a 32 bit integer if successful
+  # @return [Integer]
   #
   # @version SketchUp 6.0
   def to_i
   end
 
-  # Returns a string representation of a Color object, in the form
-  # of "Color(255, 255, 255, 255)".
+  # The {#to_s} method returns a string representation of the {Sketchup::Color}
+  # object, in the form of "Color(255, 255, 255, 255)".
   #
   # @example
-  #   color = Sketchup::Color.new "OldLace"
-  #   color.to_s
+  #   color = Sketchup::Color.new(255, 255, 255, 255)
+  #   color_str = color.to_s
   #
-  # @return string - a String name for the Color.
+  # @return [String]
   #
   # @version SketchUp 6.0
   def to_s