sketchup-api-stubs 0.7.0 → 0.7.5

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

@@ -3,6 +3,14 @@
 
 # An Image object represents a raster image placed in the Model.
 #
+# @example Create material from image (SU 2018 and later)
+#   model = Sketchup.active_model
+#   entities = model.active_entities
+#   image = entities.grep(Sketchup::Image).first
+#   img_rep = image.image_rep
+#   material = model.materials.add("New Name")
+#   material.texture = img_rep
+#
 # @version SketchUp 6.0
 class Sketchup::Image < Sketchup::Drawingelement
 

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

@@ -3,6 +3,12 @@
 
 # References an image representation object.
 #
+# @example
+#   # Get the color of the center of the first material texture found in model.
+#   texture = Sketchup.active_model.materials.map(&:texture).compact.first
+#   image_rep = texture.image_rep
+#   color = image_rep.color_at_uv(0.5, 0.5)
+#
 # @version SketchUp 2018
 class Sketchup::ImageRep
 
@@ -23,7 +29,8 @@ class Sketchup::ImageRep
   end
 
   # The {#color_at_uv} method returns a color corresponding to the UV texture
-  # coordinates
+  # coordinates. +0.0, 0.0+ maps to the bottom left and +1.0, 1.0+ to the top
+  # right of the image.
   #
   # @example
   #   image_rep = Sketchup::ImageRep.new
@@ -69,6 +76,8 @@ class Sketchup::ImageRep
   #   byte_string = image_rep.data
   #   byte_string.each_byte { |byte| puts byte, ' ' }
   #
+  # @note The byte order of the pixels are RGB(A) on macOS and BGR(A) on Windows.
+  #
   # @return [String, nil]
   #
   # @version SketchUp 2018
@@ -93,6 +102,7 @@ class Sketchup::ImageRep
   #
   # @example Default constructor
   #   image_rep = Sketchup::ImageRep.new
+  #   # Use #set_data or #load_file to add image data.
   #
   # @example Construct from file
   #   image_rep = Sketchup::ImageRep.new("/path/to/image.jpg")
@@ -155,15 +165,45 @@ class Sketchup::ImageRep
   def save_file(filepath)
   end
 
-  # The {#set_data} method sets the pixel data of the {Sketchup::ImageRep}.
+  # The {#set_data} method discards any existing data and sets new pixel data for
+  # the {Sketchup::ImageRep}.
   #
   # @example Setting new data
   #   image_rep = Sketchup::ImageRep.new
-  #   image_rep.load_file("/path/to/image.jpg")
-  #   new_image_rep = image_rep.set_data(800, 600, 24, 0, pixel_data)
+  #   width = 800
+  #   height = 600
+  #   bpp = 24
+  #   pixel = [127, 127, 127].pack("C*")
+  #   pixels = pixel * width * height
+  #   image_rep.set_data(width, height, bpp, 0, pixels)
+  #   image_rep.save_file(UI.savepanel)
+  #
+  # @example Handling system color differences
+  #   # Generates red image on Mac and blue on Windows.
+  #   image_rep = Sketchup::ImageRep.new
+  #   color = Sketchup::Color.new("Red")
+  #   rgba = color.to_a # Red, green , blue, alpha
+  #   color_data = rgba.pack("C*")
+  #   image_rep.set_data(1, 1, 32, 0, color_data)
+  #   image_rep.save_file(UI.savepanel)
+  #
+  #   # Generates red image on both systems.
+  #   image_rep = Sketchup::ImageRep.new
+  #   color = Sketchup::Color.new("Red")
+  #   color_code = color.to_a # Red, green, blue, alpha
+  #   if Sketchup.platform == :platform_win
+  #     # Change order to Blue, green, red, alpha on Windows.
+  #     color_code = color_code.values_at(2, 1, 0, 3)
+  #   end
+  #   color_data = color_code.pack("C*")
+  #   image_rep.set_data(1, 1, 32, 0, color_data)
+  #   image_rep.save_file(UI.savepanel)
+  #
+  # @note The byte order of the pixels are RGB(A) on macOS and BGR(A) on Windows.
   #
   # @note The encoding of the pixel_data {String} parameter should be ASCII-8BIT.
-  #   Any other encoding could corrupt the binary data.
+  #   Any other encoding could corrupt the binary data. Using
+  #   `Array#pack("C*")` gives correct encoding.
   #
   # @param [Integer] width
   #   The width of the pixel data. Must be greater than 0.
@@ -179,7 +219,7 @@ class Sketchup::ImageRep
   # @param [Integer] row_padding
   #   The row padding for the pixel data which is
   #   sized in bytes. Row padding is used to pad each row with zeros so that each
-  #   scanline on the pixel data will end on the data-type boundry.
+  #   scanline on the pixel data will end on the data-type boundary.
   #
   # @param [String] pixel_data
   #   The binary string containing the pixel data

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

@@ -53,7 +53,8 @@
 #     # processing the file.
 #     def load_file(file_path, status)
 #       UI.messagebox(file_path)
-#       return 0 # 0 is the code for a successful import
+#
+#       return Sketchup::Importer::ImportSuccess
 #     end
 #   end
 #
@@ -68,7 +69,6 @@ class Sketchup::Importer
   ImportFail = nil # Stub value.
   ImportFileNotFound = nil # Stub value.
   ImportSuccess = nil # Stub value.
-  ImporterNotFound = nil # Stub value.
 
   # Instance Methods
 
@@ -144,20 +144,19 @@ class Sketchup::Importer
   # File object and processing it in whatever way you need.
   #
   # You must return an integer success code to SketchUp when you are done.
-  # These are the codes that SketchUp understands and what will happen when
-  # SketchUp receives each key.
+  # These are the codes that SketchUp understands:
   #
-  #   - 0 = Import Success (no additional dialog shown)
-  #   - 1 = Import Failed (no additional dialog shown)
-  #   - 2 = Import Cancelled by User (SketchUp will show a "cancelled" dialog)
-  #   - 4 = Import File not Found (SketchUp will show a "not found" dialog)
-  #   - 5 = SketchUp version not supported (no additional dialog shown)
+  #   - Sketchup::Importer::ImportSuccess
+  #   - Sketchup::Importer::ImportFail
+  #   - Sketchup::Importer::ImportCanceled - SketchUp will show a "cancelled" dialog
+  #   - Sketchup::Importer::ImportFileNotFound - SketchUp will show a "not found" dialog
   #
   # @example
   #   def load_file(file_path, status)
   #     # Here is where you would open the file and process it.
-  #     UI.messagebox(file_path)
-  #     return 0   # Success
+  #     puts file_path
+  #
+  #     return Sketchup::Importer::ImportSuccess
   #   end
   #
   # @param file_path

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

@@ -1,14 +1,23 @@
 # Copyright:: Copyright 2020 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# The InputPoint used to pick entities that reside under the current cursor
-# location. InputPoint and PickHelper are similar, but InputPoint also uses
-# inferencing.   Only tools react to cursor location. Therefore, most of the
-# methods in this class are only useful in the context of a tool you are
-# writing. For example, if you want to determine the entity that you just
-# clicked on with the mouse, you would use InputPoint.pick from within your
-# onLMouseButton method in a tool. See the example script linetool.rb for
-# examples of using the InputPoint class.
+# The {Sketchup::InputPoint} class is used to pick 3d points and/or entities
+# that reside under the current cursor location, similar to native Line tool
+# and other drawing tools. Unlike {Sketchup::PickHelper},
+# {Sketchup::InputPoint} uses inference, i.e. "snaps" to vertices and other
+# entities when the cursor is close to them.
+#
+# Only {Sketchup::Tool}s react to cursor location and most of these methods are
+# only useful in the context of a tool. For example, if you want to determine
+# the 3d point you just moved the cursor over, you would use
+# {#pick} from within your {Sketchup::Tool#onMouseMove} method.
+# {Sketchup::InputPoints} are best picked from mouse move, as you want them to
+# draw them to the view.
+#
+# For an example, see https://github.com/SketchUp/sketchup-ruby-api-tutorials/tree/master/examples/02_custom_tool.
+#
+# To lock inference similar to native SketchUp tools, see
+# {View#lock_inference}.
 #
 # @version SketchUp 6.0
 class Sketchup::InputPoint
@@ -188,10 +197,8 @@ class Sketchup::InputPoint
   def edge
   end
 
-  # The face method retrieves the face if the input point is getting its
-  # position from a face.
-  #
-  # Otherwise it returns nil.
+  # The face method retrieves the face at or behind the input point. This can be
+  # used to determine a plane, similar to what native Rotate tool does.
   #
   # @example
   #   view = Sketchup.active_model.active_view
@@ -200,8 +207,10 @@ class Sketchup::InputPoint
   #   ip1 = view.inputpoint x,y
   #   f = ip1.face
   #
-  # @return face - a Face object if successful, or nil if
-  #   unsuccessful
+  # @note The InputPoint doesn't necessarily lie on the face, but can be e.g. on
+  #   an edge in front of the face.
+  #
+  # @return [Sketchup::Face, nil]
   #
   # @version SketchUp 6.0
   def face
@@ -220,15 +229,18 @@ class Sketchup::InputPoint
   #   sub-class {Sketchup::InputPoint} due to a bug in how SketchUp initialized
   #   the class.
   #
-  # @param pt_or_vertex
-  #   An optional Point3d or Vertex where the new InputPoint
-  #   should be created.
+  # @overload initialize()
   #
-  # @return inputpoint - the newly created InputPoint object if
-  #   successful
+  #   @return [Sketchup::InputPoint]
+  #
+  # @overload initialize(pt_or_vertex)
+  #
+  #   @param pt_or_vertex  [Geom::Point3d, Sketchup::Vertex] An optional Point3d
+  #                        or Vertex where the new InputPoint should be created.
+  #   @return              [Sketchup::InputPoint]
   #
   # @version SketchUp 6.0
-  def initialize(pt_or_vertex)
+  def initialize(*args)
   end
 
   # The {#instance_path} method retrieves the instance path for the picked point.

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

@@ -2,13 +2,15 @@
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to component instance
-# events. To implement this observer, create a Ruby class of this type,
-# override the desired methods, and add an instance of the observer to the
-# objects of interests.
+# events.
 #
 # Note that you may also attach {Sketchup::InstanceObserver}s to
 # {Sketchup::Group}s.
 #
+# @abstract To implement this observer, create a Ruby class of this type,
+#   override the desired methods, and add an instance of the observer to the
+#   objects of interests.
+#
 # @example
 #   # This is an example of an observer that watches a specific instance
 #   # for open edit actions and shows a messagebox.

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

@@ -30,7 +30,7 @@ class Sketchup::InstancePath
   def ==(other)
   end
 
-  # The elements of an instance path can be accessed like an array.
+  # The elements of an instance path can be accessed similarly to an array.
   #
   # @example
   #   model = Sketchup.active_model
@@ -40,6 +40,9 @@ class Sketchup::InstancePath
   #   path[0] == group # returns true
   #   path[1] == edge # returns true
   #
+  # @note This method does not accept negative indices. For the exact behavior
+  #   of an array, use +{#to_a}+.
+  #
   # @param [Integer] index
   #
   # @raise [IndexError] if the given index is out of bounds

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

@@ -4,7 +4,8 @@
 # The Layer class contains methods modifying and extracting information for a
 # layer.
 #
-# By default, a SketchUp model has one layer, Layer 0 (zero), which is the base
+# By default, a SketchUp model has one layer, Layer 0 (Named "Untagged" in the
+# UI since SketchUp 2020), which is the base
 # layer. You can't delete or rename Layer 0. Unlike certain other CAD software
 # packages, entities associated with different layers in SketchUp still
 # intersect with each other. (If you want collections of entities to not
@@ -15,12 +16,14 @@
 # wall and roof entities different groups, associate layers with those groups,
 # and then hide those layers so as to display just the floor plan in the model.
 #
-# You can programatically create a new layer by calling the Layers.add method.
-#
 # @example
 #   model = Sketchup.active_model
 #   layers = model.layers
-#   new_layer = layers.add "test layer"
+#   new_layer = layers.add('Doors')
+#
+# @note As of SketchUp 2020 "Layers" were renamed to "Tags" in the UI.
+#   The API retains the use of "Layer" for compatibility and is synonymous with
+#   "Tag".
 #
 # @version SketchUp 6.0
 class Sketchup::Layer < Sketchup::Entity
@@ -31,8 +34,8 @@ class Sketchup::Layer < Sketchup::Entity
 
   # Instance Methods
 
-  # The <=> method is used to compare two layers based on their names. You could
-  # use this for sorting if you're building a list of layer names.
+  # The {#<=>} method is used to compare two layers based on their names. You
+  # could use this for sorting if you're building a list of layer names.
   #
   # @example
   #   model = Sketchup.active_model
@@ -42,37 +45,31 @@ class Sketchup::Layer < Sketchup::Entity
   #   layer2 = layers[1]
   #   status = layer1 <=> layer2
   #
-  # @param layer2
-  #   A Layer object.
+  # @param [Sketchup::Layer] layer2
   #
-  # @return status - -1 if layer1 is less than layer2. 1 if layer2
-  #   is less than layer1. 0 if layer1 and layer2 are
-  #   equal.
+  # @return [Integer] -1 if layer1 is less than layer2. 1 if layer2
+  #   is less than layer1. 0 if layer1 and layer2 are equal.
   #
   # @version SketchUp 6.0
   def <=>(layer2)
   end
 
-  # The == method is used to determine if two layers are the same.
+  # The {#==} method is used to determine if two layers are the same.
   #
   # @example
   #   model = Sketchup.active_model
   #   layers = model.layers
-  #   layer1 = layers.add "test layer 1"
-  #   layer2 = layers.add "test layer 2"
-  #   status = layer1 == layer2
-  #
-  # @param layer2
-  #   A Layer object.
+  #   layer1 = layers.add("Test layer 1")
+  #   layer2 = layers.add("Test layer 2")
+  #   equal = layer1 == layer2
   #
-  # @return status - true if layer1 and layer2 are equal. false if
-  #   layer1 and layer2 are not equal.
+  # @param [Object] other
   #
   # @version SketchUp 6.0
-  def ==(layer2)
+  def ==(other)
   end
 
-  # The color method is used to retrieve the color of the layer.
+  # The {#color} method is used to retrieve the color of the layer.
   #
   # @example
   #   model = Sketchup.active_model
@@ -80,13 +77,13 @@ class Sketchup::Layer < Sketchup::Entity
   #   new_layer = layers.add('Test layer')
   #   color = new_layer.color
   #
-  # @return color - the color of the Layer object
+  # @return [Sketchup::Color]
   #
   # @version SketchUp 2014
   def color
   end
 
-  # The color= method is used to set the name of a layer.
+  # The {#color=} method is used to set the name of a layer.
   #
   # @example
   #   model = Sketchup.active_model
@@ -94,10 +91,7 @@ class Sketchup::Layer < Sketchup::Entity
   #   new_layer = layers.add('Test layer')
   #   new_layer.color = Sketchup::Color.new(192, 0, 0)
   #
-  # @param color
-  #   The new color for the Layer object.
-  #
-  # @return color
+  # @param [Sketchup::Color] color
   #
   # @version SketchUp 2014
   def color=(color)
@@ -111,7 +105,7 @@ class Sketchup::Layer < Sketchup::Entity
   #   new_layer = layers.add ("test layer")
   #   name = new_layer.display_name
   #
-  # @return [String] the display name of the Layer object
+  # @return [String]
   #
   # @see #name
   #
@@ -119,8 +113,46 @@ class Sketchup::Layer < Sketchup::Entity
   def display_name
   end
 
-  # Layer Group methods
-  def layer_group
+  # The {#folder} method is used to return the parent layer folder of a layer.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder1 = layers.add('Folder1')
+  #   parent_folder = folder1.folder # Returns: nil
+  #
+  #   folder2 = folder1.add('Folder2')
+  #   parent_folder = folder2.folder # Returns: folder1
+  #
+  # @return [Sketchup::LayerFolder, nil] +nil+ if the folder is a direct child to
+  #   the layer manager.
+  #
+  # @version SketchUp 2021.0
+  def folder
+  end
+
+  # The {#folder=} method is used to set the parent layer folder of a layer.
+  #
+  # This will trigger +onParentFolderChanged+ in normal cases and
+  # +onLayerChanged+ during undo/redo.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder = layers.add_folder('Hello')
+  #   layer = layers.add_layer('World')
+  #   layer.folder = folder
+  #
+  # @param [Sketchup::LayerFolder, nil] parent
+  #   +nil+ will make the layer a
+  #   direct child to the layer manager.
+  #
+  # @version SketchUp 2021.0
+  def folder=(parent)
   end
 
   # The {#line_style} method retrieves the line style on this layer.
@@ -165,7 +197,7 @@ class Sketchup::Layer < Sketchup::Entity
   def name
   end
 
-  # The name= method is used to set the name of a layer.
+  # The {#name=} method is used to set the name of a layer.
   #
   # @example
   #   model = Sketchup.active_model
@@ -173,16 +205,13 @@ class Sketchup::Layer < Sketchup::Entity
   #   new_layer = layers.add "test layer"
   #   name = new_layer.name = "new test layer"
   #
-  # @param name
-  #   The new name for the Layer object.
-  #
-  # @return name - the newly set name
+  # @param [String] name
   #
   # @version SketchUp 6.0
   def name=(name)
   end
 
-  # The page_behavior method is used to retrieve the visibility behavior of the
+  # The {#page_behavior} method is used to retrieve the visibility behavior of the
   # layer for new pages and existing pages. For example, you may want your layer
   # to be visible or hidden by default in any new pages (aka Scenes) created by
   # the user.
@@ -192,15 +221,25 @@ class Sketchup::Layer < Sketchup::Entity
   # determined by one of these values:
   #
   # The behaviour 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
+  #
+  # [Default visibility]
+  #   These flags are used to set the value of {#page_behavior}. A page keeps
+  #   a list of layers that do not have their default behavior. If a layer
+  #   is not in that list, then it is set to its default visibility which
+  #   is determined by one of these flags.
+  #   - {LAYER_VISIBLE_BY_DEFAULT}: +0x0000+
+  #   - {LAYER_HIDDEN_BY_DEFAULT}: +0x0001+
+  #
+  # [Visibility on new pages]
+  #   You can also set this addition flag that controls the visibility of
+  #   a layer on newly created pages.
+  #   - {LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES}: +0x0000+
+  #   - {LAYER_IS_VISIBLE_ON_NEW_PAGES}: +0x0010+
+  #   - {LAYER_IS_HIDDEN_ON_NEW_PAGES}: +0x0020+
   #
   # The default visibility for a layer is set by either
-  # <code>LAYER_VISIBLE_BY_DEFAULT</code> or
-  # <code>LAYER_HIDDEN_BY_DEFAULT</code>. This is what will be used when a page
+  # {LAYER_VISIBLE_BY_DEFAULT} or
+  # {LAYER_HIDDEN_BY_DEFAULT}. This is what will be used when a page
   # does not contain the visibility state of a layer.
   #
   # The remaining flags control the visibility of the layer for new pages.
@@ -212,8 +251,7 @@ class Sketchup::Layer < Sketchup::Entity
   #   hidden_by_default = (layer.page_behavior & LAYER_HIDDEN_BY_DEFAULT) ==
   #                       LAYER_HIDDEN_BY_DEFAULT
   #
-  # @return pagebehavior - an integer representing the current
-  #   behavior of the layer.
+  # @return [Integer] an integer representing the current behavior of the layer.
   #
   # @version SketchUp 6.0
   def page_behavior
@@ -226,11 +264,25 @@ class Sketchup::Layer < Sketchup::Entity
   # visibility of the layer is used.
   #
   # 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+]
+  #
+  # [Default visibility]
+  #   These flags are used to set the value of {#page_behavior}. A page keeps
+  #   a list of layers that do not have their default behavior. If a layer
+  #   is not in that list, then it is set to its default visibility which
+  #   is determined by one of these flags.
+  #   - {LAYER_VISIBLE_BY_DEFAULT}: +0x0000+
+  #   - {LAYER_HIDDEN_BY_DEFAULT}: +0x0001+
+  #
+  # [Visibility on new pages]
+  #   You can also set this addition flag that controls the visibility of
+  #   a layer on newly created pages.
+  #   - {LAYER_USES_DEFAULT_VISIBILITY_ON_NEW_PAGES}: +0x0000+
+  #   - {LAYER_IS_VISIBLE_ON_NEW_PAGES}: +0x0010+
+  #   - {LAYER_IS_HIDDEN_ON_NEW_PAGES}: +0x0020+
+  #
+  # @bug 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.
   #
   # @example
   #   layers = Sketchup.active_model.layers
@@ -238,44 +290,35 @@ class Sketchup::Layer < Sketchup::Entity
   #   behavior = LAYER_HIDDEN_BY_DEFAULT | LAYER_IS_HIDDEN_ON_NEW_PAGES
   #   layer.page_behavior = behavior
   #
-  # @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 [Integer]
-  #
   # @version SketchUp 6.0
   def page_behavior=(page_behavior)
   end
 
-  # The visible= method is used to set if the layer is visible.
+  # The {#visible=} method is used to set if the layer is visible.
   #
   # @example
   #   model = Sketchup.active_model
   #   layers = model.layers
-  #   new_layer = layers.add "test layer"
+  #   layer = layers.add('Hello World')
+  #   layer.visible = false
   #
-  #   # Hide the layer.
-  #   new_layer.visible = false
-  #
-  # @param is_visible
-  #   The new visibility setting.
+  # @param [Boolean] visible
   #
   # @version SketchUp 6.0
-  def visible=(is_visible)
+  def visible=(visible)
   end
 
-  # The visible? method is used to determine if the layer is visible.
+  # The {#visible?} method is used to determine if the layer is visible.
   #
   # @example
   #   model = Sketchup.active_model
   #   layers = model.layers
-  #   new_layer = layers.add "test layer"
-  #   UI.messagebox(new_layer.visible?)
+  #   layer = layers.add('Hello World')
+  #   layer.visible? # Returns: true
   #
-  # @return [Boolean] true if the layer is visible
+  # @return [Boolean]
   #
   # @version SketchUp 6.0
   def visible?