sketchup-api-stubs 0.1.0

data/SketchUp/geom.rb

@@ -0,0 +1,231 @@
+# Copyright:: Copyright 2017 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# The Geom module defines a number of Module methods that let you perform
+# different geometric operations.
+#
+# The methods in this module take lines
+# and planes as arguments. There is no special class for representing lines or
+# planes. Arrays are used for both.
+#
+# A line can be represented as either an Array of a point and a
+# vector, or as an Array of two points.
+#   line1 = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)]
+#   line2 = [Geom::Point3d.new(0, 0, 0), Geom::Point3d.new(0, 0, 100)]
+#
+# A plane can be represented as either an Array
+# of a point and a vector, or as an Array of 4 numbers that give the
+# coefficients of a plane equation.
+#   plane1 = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)]
+#   plane2 = [0, 0, 1, 0]
+#
+# There are several good books on 3D math if you are new to
+# the concepts of a line, plane, and vector.
+#
+# @note Lines and Planes are infinite.
+#
+# @version SketchUp 6.0
+module Geom
+
+  # Class Methods
+
+  # The {.closest_points} method is used to compute the closest points on two
+  # lines.
+  #
+  # @example
+  #   line1 = [Geom::Point3d.new(0, 2, 0), Geom::Vector3d.new(1, 0, 0)]
+  #   line2 = [Geom::Point3d.new(3, 0, 0), Geom::Vector3d.new(0, 1, 0)]
+  #   # This will return a point Point3d(3, 2, 0).
+  #   points = Geom.closest_points(line1, line2)
+  #
+  # @param [Array(Geom::Point3d, Geom::Vector3d)] line1
+  #   The first line to
+  #   intersect
+  #
+  # @param [Array(Geom::Point3d, Geom::Vector3d)] line2
+  #   The second line to
+  #   intersect
+  #
+  # @return [Array(Geom::Point3d, Geom::Point3d)] An array of two points. The
+  #   first point is on the first line and the second point is on the second line.
+  #
+  # @version SketchUp 6.0
+  def self.closest_points(line1, line2)
+  end
+
+  # The {.fit_plane_to_points} method is used to compute a plane that is a best
+  # fit to an array of points. If more than three points are given some of the
+  # points may not be on the plane.
+  #
+  # The plane is returned as an {Array} of 4 numbers which are the
+  # coefficients of the plane equation <code>Ax + By + Cz + D = 0</code>.
+  #
+  # @example
+  #   point1 = Geom::Point3d.new(0, 0, 0)
+  #   point2 = Geom::Point3d.new(10, 10, 10)
+  #   point3 = Geom::Point3d.new(25, 25, 25)
+  #   plane = Geom.fit_plane_to_points(point1, point2, point3)
+  #
+  # @overload fit_plane_to_points(point1, point2, point3, ...)
+  #
+  #   @param [Geom::Point3d] point1
+  #   @param [Geom::Point3d] point2
+  #   @param [Geom::Point3d] point3
+  #   @return [Array(Geom::Point3d, Geom::Vector3d)] A plane
+  #
+  # @overload fit_plane_to_points(points)
+  #
+  #   @param [Array<Geom::Point3d>] points
+  #   @return [Array(Geom::Point3d, Geom::Vector3d)] A plane
+  #
+  # @version SketchUp 6.0
+  def self.fit_plane_to_points(*args)
+  end
+
+  # The {.intersect_line_line} computes the intersection of two lines.
+  #
+  # @example
+  #   # Defines a line parallel to the Y axis, offset 20 units.
+  #   line1 = [Geom::Point3d.new(20, 0, 0), Geom::Vector3d.new(0, 1, 0)]
+  #   # Defines a line parallel to the X axis, offset 10 units.
+  #   line2 = [Geom::Point3d.new(0, 10, 0), Geom::Point3d.new(20, 10, 0)]
+  #   # This will return a point Point3d(20, 10, 0).
+  #   point = Geom.intersect_line_line(line1, line2)
+  #
+  # @param [Array(Geom::Point3d, Geom::Vector3d)] line1
+  #   The first line to
+  #   intersect.
+  #
+  # @param [Array(Geom::Point3d, Geom::Vector3d)] line2
+  #   The second line to
+  #   intersect.
+  #
+  # @return [Geom::Point3d, nil] The intersection point. Returns +nil+ if they
+  #   do not intersect.
+  #
+  # @see Geom
+  #   The Geom module for alternative versions of defining a line.
+  #
+  # @version SketchUp 6.0
+  def self.intersect_line_line(line1, line2)
+  end
+
+  # The {.intersect_line_plane} method is used to compute the intersection of a
+  # line and a plane.
+  #
+  # @example
+  #   # Defines a line parallel to the X axis, offset 20 units.
+  #   line = [Geom::Point3d.new(-10, 20, 0), Geom::Vector3d.new(1, 0, 0)]
+  #   # Defines a plane with it's normal parallel to the x axis.
+  #   plane = [Geom::Point3d.new(10, 0 ,0), Geom::Vector3d.new(1, 0, 0)]
+  #   # This will return a point Point3d(10, 20, 0).
+  #   point = Geom.intersect_line_plane(line, plane)
+  #
+  # @param [Array(Geom::Point3d, Geom::Vector3d)] line
+  #
+  # @param [Array(Geom::Point3d, Geom::Point3d)] plane
+  #
+  # @return [Geom::Point3d, nil] A Point3d object. Returns +nil+ if they do not
+  #   intersect.
+  #
+  # @see Geom
+  #   The Geom module for alternative versions of defining lines and
+  #   planes.
+  #
+  # @version SketchUp 6.0
+  def self.intersect_line_plane(line, plane)
+  end
+
+  # The {.intersect_plane_plane} method is used to compute the intersection of two
+  # planes.
+  #
+  # @example
+  #   # Defines a plane with it's normal parallel to the x axis.
+  #   plane1 = [Geom::Point3d.new(10, 0 ,0), Geom::Vector3d.new(1, 0, 0)]
+  #   # Defines a plane with it's normal parallel to the y axis.
+  #   plane2 = [Geom::Point3d.new(0, 20 ,0), Geom::Vector3d.new(0, 1, 0)]
+  #   # This will return a line [Point3d(10, 20, 0), Vector3d(0, 0, 1)].
+  #   line = Geom.intersect_plane_plane(plane1, plane2)
+  #
+  # @param [Array(Geom::Point3d, Geom::Point3d)] plane1
+  #   The first plane to
+  #   intersect
+  #
+  # @param [Array(Geom::Point3d, Geom::Point3d)] plane2
+  #   The second plane to
+  #   intersect
+  #
+  # @return [Array(Geom::Point3d, Geom::Vector3d)] A line where the planes
+  #   intersect if successful. Returns +nil+ if the planes do not intersect.
+  #
+  # @version SketchUp 6.0
+  def self.intersect_plane_plane(plane1, plane2)
+  end
+
+  # The {.linear_combination} method is used to compute the linear combination of
+  # points or vectors.
+  #
+  # @example
+  #   point1 = Geom::Point3d.new(1, 1, 1)
+  #   point2 = Geom::Point3d.new(10, 10, 10)
+  #   # Gets the point on the line segment connecting point1 and point2 that is
+  #   # 3/4 the way from point1 to point2: Point3d(7.75, 7.75, 7.75).
+  #   point = Geom.linear_combination(0.25, point1, 0.75, point2)
+  #
+  # @overload linear_combination(weight1, point1, weight2, point2)
+  #
+  #   @param [Float] weight1 A weight or percentage.
+  #   @param [Geom::Point3d] point1
+  #   @param [Float] weight2 A weight or percentage.
+  #   @param [Geom::Point3d] point2
+  #   @return [Geom::Point3d]
+  #
+  # @overload linear_combination(weight1, vector1, weight2, vector2)
+  #
+  #   @param [Float] weight1 A weight or percentage.
+  #   @param [Geom::Vector3d] vector1
+  #   @param [Float] weight2 A weight or percentage.
+  #   @param [Geom::Vector3d] vector2
+  #   @return [Geom::Vector3d]
+  #
+  # @version SketchUp 6.0
+  def self.linear_combination(weight1, pt_or_vect1, weight2, pt_or_vect2)
+  end
+
+  # The {.point_in_polygon_2D} method is used to determine whether a point is
+  # inside a polygon. The z component of both the point you're checking and
+  # the points in the polygon are ignored, effectively making it a 2-d check.
+  #
+  # @example
+  #   # Create a point that we want to check. (Note that the 3rd coordinate,
+  #   # the z, is ignored for purposes of the check.)
+  #   point = Geom::Point3d.new(5, 0, 10)
+  #
+  #   # Create a series of points of a triangle we want to check against.
+  #   triangle = []
+  #   triangle << Geom::Point3d.new(0, 0, 0)
+  #   triangle << Geom::Point3d.new(10, 0, 0)
+  #   triangle << Geom::Point3d.new(0, 10, 0)
+  #
+  #   # Test to see if our point is inside the triangle, counting hits on
+  #   # the border as an intersection in this case.
+  #   hits_on_border_count = true
+  #   status = Geom.point_in_polygon_2D(point, triangle, hits_on_border_count)
+  #
+  # @param [Geom::Point3d] point
+  #
+  # @param [Array<Geom::Point3d>] polygon
+  #   An array of points that represent the
+  #   corners of the polygon you are checking against.
+  #
+  # @param [Boolean] check_border
+  #   Pass true if a point on the border should be
+  #   counted as inside the polygon.
+  #
+  # @return [Boolean] +true+ if the point is inside the polygon.
+  #
+  # @version SketchUp 6.0
+  def self.point_in_polygon_2D(point, *polygon, check_border)
+  end
+
+end

data/SketchUp/languagehandler.rb

@@ -0,0 +1,92 @@
+# Copyright:: Copyright 2017 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# The LanguageHandler class contains methods used to help make SketchUp
+# extensions easier to localize across different languages. It looks for
+# translated resources within the Resources folder in the extension's directory
+# structure. All translated resources should be located within the appropriate
+# language folder and encoded in UTF-8. The strings file should include
+# "key"="value" string pairs in the following format:
+#
+# @example Example code that uses LanguageHandler:
+#   # Create a global language handler object
+#   swiveldriver_langHandler = LanguageHandler.new('swiveldriver.strings')
+#
+#   # Get localized string
+#   localizedStr = swiveldriver_langHandler.GetString('String 1')
+#
+# @example
+#   "String 1"="Localized String 1";
+#   "String 2"="Localized String 2";
+#
+# @example Here's an example extension directory structure:
+#   gocorp_swiveldriver.rb <- creates the SketchupExtension instance
+#   gocorp_swiveldriver/
+#   gocorp_swiveldriver/Resources/
+#   gocorp_swiveldriver/Resources/en/swiveldriver.strings <- OPTIONAL localization files by language code
+#   gocorp_swiveldriver/Resources/fr/swiveldriver.strings
+#   gocorp_swiveldriver/Resources/es/swiveldriver.strings
+#
+# @version SketchUp 2014
+class LanguageHandler
+
+  # Instance Methods
+
+  # Looks up and returns the localized version of a given string, based on the
+  # language SketchUp is currently running in, and the available translations
+  # in the Resources folder.
+  #
+  # @example
+  #   swiveldriver_langHandler = LanguageHandler.new('swiveldriver.strings')
+  #   localized_string = swiveldriver_langHandler['String 1']
+  #
+  # @param key
+  #   The key for the string to be retrieved.
+  #
+  # @return the localized string.
+  #
+  # @version SketchUp 2014
+  def [](key)
+  end
+
+  # The new method is used to create a new LanguageHandler object.
+  #
+  # @example
+  #   swiveldriver_langHandler = LanguageHandler.new('swiveldriver.strings')
+  #
+  # @param filename
+  #   The name of the file that contains the localized strings
+  #   with their keys in UTF-8 encoding.
+  #
+  # @return the new LanguageHandler object
+  #
+  # @version SketchUp 2014
+  def initialize(filename)
+  end
+
+  # Returns a string containing the path to the given filename if it can be found
+  # in the Resources folder.
+  #
+  # @example
+  #   swiveldriver_langHandler = LanguageHandler.new('swiveldriver.strings')
+  #   image = swiveldriver_langHandler.resource_path('fancy_image.png')
+  #
+  # @return path - the location of the file in the Resources folder.
+  #
+  # @version SketchUp 2014
+  def resource_path
+  end
+
+  # Returns a Hash object containing the localization dictionary.
+  #
+  # @example
+  #   swiveldriver_langHandler = LanguageHandler.new('swiveldriver.strings')
+  #   hash = swiveldriver_langHandler.strings
+  #
+  # @return hash - the localization dictionary.
+  #
+  # @version SketchUp 2014
+  def strings
+  end
+
+end

data/SketchUp/length.rb

@@ -0,0 +1,210 @@
+# Copyright:: Copyright 2017 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# Because length units are used so often in SketchUp, a special class has been
+# added to make it easier to work with length values. You can use a Length
+# object any place that you would use a Float.
+#
+# Internally, all lengths in SketchUp are stored in inches. The Length class
+# stores values in inches as well. A number of methods have been added to the
+# Ruby Numeric class to do units conversions.
+#
+# Constants:
+# Length Format:
+# - Length::Decimal
+# - Length::Architectural
+# - Length::Engineering
+# - Length::Fractional
+# Length Unit:
+# - Length::Inches
+# - Length::Feet
+# - Length::Millimeter
+# - Length::Centimeter
+# - Length::Meter
+# The setting for the Length format and Length unit can be retrieved from the
+# model options by querying the "UnitsOptions" OptionsProvider for
+# "LengthFormat" and "LengthUnit" respectively.
+#
+# @note Prior to SketchUp 2015, Length used to be derived from Float. This is
+#   no longer the case.
+#
+# @version SketchUp 6.0
+class Length < Float
+
+  # Instance Methods
+
+  # The < method is used to see if one length is less than another length.
+  #
+  # For example, if l1 = 1.0.inch and l2 = 1.000001.inch then l1 == l2 so l1
+  # < l2 should return false.
+  #
+  # @example
+  #   length1 = 12.to_l
+  #   length2 = 11.to_l
+  #   if length1 < length2
+  #     puts "length1 is less than length2"
+  #   else
+  #     puts "length1 is not less than length2"
+  #   end
+  #
+  # @param length2
+  #   A length value.
+  #
+  # @return status - true if length1 is < length2; false if
+  #   length1 is not < length2
+  #
+  # @version SketchUp 6.0
+  def <(length2)
+  end
+
+  # The <= method is used to see if one length is less than or equal to
+  # another length.
+  #
+  # @example
+  #   length1 = 11.to_l
+  #   length2 = 12.to_l
+  #   if length1 <= length2
+  #     puts "length1 is less than or equal length2"
+  #   else
+  #     puts "length1 is greater than length2"
+  #   end
+  #
+  # @param length2
+  #   A length value.
+  #
+  # @return status - true if length1 is <= length2; false if
+  #   length1 is not <= length2
+  #
+  # @version SketchUp 6.0
+  def <=(length2)
+  end
+
+  # The <=> method is used to see if one length is less than equal or greater
+  # than another length. Because we change == for Length to do a test based on
+  # a tolerance, we also need to change <=> to also take tolerance into account.
+  #
+  # @example
+  #   length1 = 20.to_l
+  #   length2 = 30.to_l
+  #   result = length1 <=> length2
+  #
+  # @param length2
+  #   A length value.
+  #
+  # @return result - the result of the comparison
+  #
+  # @version SketchUp 6.0
+  def <=>(length2)
+  end
+
+  # The == method is used to see if one length is equal to another length.
+  #
+  # The equality comparison on Length values uses the default tolerance that
+  # SketchUp uses for comparing lengths.
+  #
+  # @example
+  #   length1 = 20.to_l
+  #   length2 = 30.to_l
+  #   is_equal = length1 == length2
+  #
+  # @param length2
+  #   A length value.
+  #
+  # @return status - true if length1 is == length2; false if
+  #   length1 is not == length2
+  #
+  # @version SketchUp 6.0
+  def ==(length2)
+  end
+
+  # The > method is used to see if one length is greater than another length.
+  #
+  # For example, if l1 = 1.0.inch and l2 = 1.000001.inch then l1 == l2 so l1 >
+  # l2 should return false.
+  #
+  # @example
+  #   length1 = 11.to_l
+  #   length2 = 12.to_l
+  #   if length1 > length2
+  #     puts "length1 is greater than length2"
+  #   else
+  #     puts "length1 is not greater than length2"
+  #   end
+  #
+  # @param length2
+  #   A length value.
+  #
+  # @return status - true if length1 is > length2; false if length1
+  #   is not > length2
+  #
+  # @version SketchUp 6.0
+  def >(length2)
+  end
+
+  # The >= method is used to see if one length is greater than or equal to
+  # another length.
+  #
+  # For example, if l1 = 1.0.inch and l2 = 1.000001.inch then l1 == l2 so l1 >=
+  # l2 should return true. Also L1 <= l2 would return true.
+  #
+  # @example
+  #   length1 = 11.to_l
+  #   length2 = 12.to_l
+  #   if length1 >= length2
+  #     puts "length1 is greater than or equal length2"
+  #   else
+  #     puts "length1 is less than length2"
+  #   end
+  #
+  # @param length2
+  #   A length value.
+  #
+  # @return status - true if length1 is >= length2; false if
+  #   length1 is not >= length2
+  #
+  # @version SketchUp 6.0
+  def >=(length2)
+  end
+
+  # The inspect method is used to retrieve an unformatted string for the length,
+  # which is the length in inches, regardless of the user's model unit settings.
+  # See Length.to_s for a way automatically format your Length to the user's
+  # model units.
+  #
+  # @example
+  #   length = 55.to_l
+  #   str = length.inspect
+  #
+  # @return length - an unformatted length string
+  #
+  # @version SketchUp 6.0
+  def inspect
+  end
+
+  # The to_f method is used to convert a length to a normal float.
+  #
+  # @example
+  #   length = 45.to_l
+  #   f = length.to_f
+  #
+  # @return value - the float length value
+  #
+  # @version SketchUp 6.0
+  def to_f
+  end
+
+  # Format a length as a String using the current units formatting settings
+  # for the model. (So if the user's model is set to feet, this method will
+  # return a nicely formatted length in feet.)
+  #
+  # @example
+  #   length = 55.to_l
+  #   str = length.to_s
+  #
+  # @return value - the float length value
+  #
+  # @version SketchUp 6.0
+  def to_s
+  end
+
+end