sketchup-api-stubs 0.7.2 → 0.7.7

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

@@ -1,10 +1,11 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# This observer interface is implemented to react to pages 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.
+# This observer interface is implemented to react to pages events.
+#
+# @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 the pages for new ones.

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

@@ -1,15 +1,26 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# The PickHelper class is used to pick entities that reside under the current
-# cursor location. PickHelper and InputPoint are similar, but InputPoint also
-# uses inferencing. You can retrieve a PickHelper object using the pick_helper
-# method on a View object.
+# The {Sketchup::PickHelper} class is used to pick entities that reside under
+# the current cursor location, similar to native Select tool. Unlike
+# {Sketchup::InputPoint}, {Sketchup::PickHelper} uses no inference.
+#
+# 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 entity you just clicked, you would use {#do_pick} from within your
+# {Sketchup::Tool#onLButtonDown} method.
+#
+# You can retrieve a PickHelper object using the {Sketchup::View#pick_helper}
+# method.
 #
 # Entities that are picked (found under the
 # cursor when a mouse or keyboard event occurs), are called Pick Records and
 # are placed in an indexed list.
 #
+# @note The same {Sketchup::Pickhelper} instance is being reused by SketchUp.
+#   Don't extend, add methods or redefine methods on this object as it can
+#   clash with other extensions.
+#
 # @version SketchUp 6.0
 class Sketchup::PickHelper
 
@@ -110,8 +121,8 @@ class Sketchup::PickHelper
   # entities in the list of pick records.
   #
   # @example
-  #   ph = view.pick_helper
-  #   ph.do_pick(x, y)
+  #   pickhelper = view.pick_helper
+  #   pickhelper.do_pick(x, y)
   #   # Iterate all pick-routes:
   #   pickhelper.count.times { |pick_path_index|
   #     puts pickhelper.depth_at(pick_path_index)
@@ -156,8 +167,8 @@ class Sketchup::PickHelper
   # Use count() to get the number of possible pick paths.
   #
   # @example
-  #   ph = view.pick_helper
-  #   ph.do_pick(x, y)
+  #   pickhelper = view.pick_helper
+  #   pickhelper.do_pick(x, y)
   #   # Iterate all pick-routes:
   #   pickhelper.count.times { |pick_path_index|
   #     puts pickhelper.element_at(pick_path_index)
@@ -212,8 +223,8 @@ class Sketchup::PickHelper
   # Use count() to get the number of possible pick paths.
   #
   # @example
-  #   ph = view.pick_helper
-  #   ph.do_pick(x, y)
+  #   pickhelper = view.pick_helper
+  #   pickhelper.do_pick(x, y)
   #   # Iterate all pick-routes:
   #   pickhelper.count.times { |pick_path_index|
   #     p pickhelper.leaf_at(pick_path_index)
@@ -239,8 +250,8 @@ class Sketchup::PickHelper
   # item will be a drawing element that is not a group, component or image.
   #
   # @example
-  #   ph = view.pick_helper
-  #   ph.do_pick(x, y)
+  #   pickhelper = view.pick_helper
+  #   pickhelper.do_pick(x, y)
   #   # Iterate all pick-routes:
   #   pickhelper.count.times { |pick_path_index|
   #     p pickhelper.path_at(pick_path_index)
@@ -399,13 +410,24 @@ class Sketchup::PickHelper
   # coordinates of the leaf entity into the coordinates of the active entities.
   #
   # @example
-  #   ph = view.pick_helper
-  #   ph.do_pick(x, y)
+  #   pickhelper = view.pick_helper
+  #   pickhelper.do_pick(x, y)
   #   # Iterate all pick-routes:
   #   pickhelper.count.times { |pick_path_index|
   #     puts pickhelper.transformation_at(pick_path_index)
   #   }
   #
+  # @example Get transformation for specific picked element
+  #   pickhelper = view.pick_helper
+  #   pickhelper.do_pick(x, y)
+  #   face = pickhelper.picked_face # Face may be inside a group or component.
+  #
+  #   index = pickhelper.count.times.find { |i| pickhelper.leaf_at(i) == face }
+  #   transformation = index ? pickhelper.transformation_at(index) : IDENTITY
+  #
+  #   # Face#area is one method that may need a transformation.
+  #   area = face.area(transformation)
+  #
   # @param index
   #   The index where the transformation should be retrieved.
   #

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The {Sketchup::RegionalSettings} module contains methods getting information about the

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The RenderingOptions class contains method to extract the rendering

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

@@ -1,10 +1,11 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to rendering options events.
-# To implement this observer, create a Ruby class of this type, implement the
-# desired methods, and add an instance of the observer to the objects of
-# interests.
+#
+# @abstract To implement this observer, create a Ruby class of this type, implement 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 the rendering options

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The SectionPlane class represents a section plane in a SketchUp model. Note

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # A set of the currently selected entities. Use the Model.selection method
@@ -38,7 +38,7 @@ class Sketchup::Selection
   # @param [Integer] index
   #   The index of the Entity object to retrieve.
   #
-  # @return [Sketchup::Entitiy, nil]
+  # @return [Sketchup::Entity, nil]
   #
   # @see #at
   #
@@ -108,7 +108,7 @@ class Sketchup::Selection
   # @param [Integer] index
   #   The index of the Entity object to retrieve.
   #
-  # @return [Sketchup::Entitiy, nil]
+  # @return [Sketchup::Entity, nil]
   #
   # @see #[]
   #
@@ -172,7 +172,12 @@ class Sketchup::Selection
   # efficient than using [].
   #
   # @example
-  #   selection.each { |entity| UI.messagebox(entity) }
+  #   selection.each { |entity| puts entity }
+  #
+  # @note Don't remove content from this collection while iterating over it with
+  #   {#each}. This would change the size of the collection and cause elemnts to
+  #   be skipped as the indices change. Instead copy the current collection to an
+  #   array using +to_a+ and then use +each+ on the array, when removing content.
   #
   # @return [nil]
   #
@@ -232,7 +237,7 @@ class Sketchup::Selection
   def include?(entity)
   end
 
-  # The #{invert} method is used to invert the selection.
+  # The {#invert} method is used to invert the selection.
   #
   # @example
   #   model = Sketchup.active_model

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

@@ -1,10 +1,11 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# This observer interface is implemented to react to selection 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.
+# This observer interface is implemented to react to selection events.
+#
+# @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 the selection for
@@ -30,7 +31,7 @@ class Sketchup::SelectionObserver
   #   end
   #
   # @note This event might not trigger even if a single element is selected. For
-  #   instance the Selection tool will trigger #onSelectionBulkChange regardless.
+  #   instance the Selection tool will trigger {#onSelectionBulkChange} regardless.
   #
   # @param [Sketchup::Selection] selection
   #
@@ -53,7 +54,7 @@ class Sketchup::SelectionObserver
   #
   # @example
   #   def onSelectionBulkChange(selection)
-  #     puts "onSelectionRemoved: #{selection}"
+  #     puts "onSelectionBulkChange: #{selection}"
   #   end
   #
   # @param [Sketchup::Selection] selection
@@ -80,27 +81,26 @@ class Sketchup::SelectionObserver
   def onSelectionCleared(selection)
   end
 
+  #
+  # @bug Due to a bug in SketchUp this event doesn't trigger. Instead
+  #   +onSelectedRemoved+ is called.
   #
   # @example
   #   class MySelectionObserver < Sketchup::SelectionObserver
-  #     # Note that there is a bug that prevent this from being called. Instead
-  #     # listen to onSelectedRemoved until the bug is fixed.
-  #     def onSelectionRemoved(selection, entity)
-  #       puts "onSelectionRemoved: #{entity}"
-  #     end
-  #     # To work around this you must catch this event instead until the bug is
-  #     # fixed:
-  #     def onSelectedRemoved(selection, entity)
-  #       # You can forward it to the correct event to be future compatible.
-  #       onSelectionRemoved(selection, entity)
-  #     end
+  #    def onSelectionRemoved(selection, entity)
+  #      puts "onSelectionRemoved: #{entity}"
+  #    end
+  #
+  #    # Due to a SketchUp bug, this method is called by the wrong name.
+  #    alias_method :onSelectedRemoved, :onSelectionRemoved
   #   end
   #
   #   # Attach the observer.
   #   Sketchup.active_model.selection.add_observer(MySelectionObserver.new)
   #
-  # @note Due to a bug in SketchUp this event doesn't trigger. Instead
-  #   +onSelectedRemoved+ is called.
+  # @note This event might not trigger even if a single element is deselected.
+  #   For instance the Selection tool will trigger {#onSelectionBulkChange}
+  #   regardless.
   #
   # @param [Sketchup::Selection] selection
   #

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The set class represents a collection of unique objects. This class is useful

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The ShadowInfo class contains method to extract the shadow information for a
@@ -20,7 +20,7 @@
 # - +Latitude+ (in Model Info > Geo-location > Set Manual Location...)
 # - +Light+ (in Window > Shadows)
 # - +Longitude+ (in Model Info > Geo-location > Set Manual Location...)
-# - +North+ Angle (in View > Toolbars > Solar North) Note that 'Toolbar' is called 'Tool Palettes' on Mac
+# - +NorthAngle+ (in View > Toolbars > Solar North) Note that 'Toolbar' is called 'Tool Palettes' on Mac
 # - +ShadowTime+ (in Window > Shadows)
 # - +ShadowTime_time_t+ (ShadowTime in Epoch time)
 # - +SunDirection+ (Generated based on ShadowTime)
@@ -50,7 +50,7 @@ class Sketchup::ShadowInfo < Sketchup::Entity
   # The each_key method iterates through all of the shadow information keys.
   #
   # @example
-  #   shadowinfo.each_key { |key| UI.messagebox(key) }
+  #   shadowinfo.each_key { |key| puts key }
   #
   # @return [nil]
   #
@@ -165,7 +165,7 @@ class Sketchup::ShadowInfo < Sketchup::Entity
   # The each_key method iterates through all of the shadow information keys.
   #
   # @example
-  #   shadowinfo.each_key { |key| UI.messagebox(key) }
+  #   shadowinfo.each_key { |key| puts key }
   #
   # @return [nil]
   #
@@ -175,7 +175,7 @@ class Sketchup::ShadowInfo < Sketchup::Entity
   def each_key
   end
 
-  # The #{each_pair} method is an alias for {#each}.
+  # The {#each_pair} method is an alias for {#each}.
   #
   # @example
   #   model = Sketchup.active_model

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

@@ -1,10 +1,12 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to changes to the shadow
-# settings. To implement this observer, create a Ruby class of this type,
-# override the desired methods, and add an instance of the observer to the
-# {Sketchup::ShadowInfo} object.
+# settings.
+#
+# @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
+#   {Sketchup::ShadowInfo} object.
 #
 # @example
 #   # This is an example of an observer that watches the selection for

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

@@ -0,0 +1,40 @@
+# Copyright:: Copyright 2021 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# The {Sketchup::Skp} module is used to read metadata from external SketchUp
+# files without loading the whole file.
+#
+# @version SketchUp 2021.0
+module Sketchup::Skp
+
+  # Class Methods
+
+  # The {.read_guid} method is used to read the GUID, globally unique identifier,
+  # for an external model.
+  #
+  # In SketchUp, GUIDs are used to test if {Sketchup::ComponentDefinition}s and
+  # {Sketchup::Model}s match (a component being an embedded model).
+  # When you insert a component to a model, its GUID is compared to existing
+  # component definitions in that model, and if there is a match the existing
+  # component definition is re-used rather than a duplicate being added.
+  # When a component definition is modified or a model is saved, their GUIDs are
+  # renewed.
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   definitions = model.definitions
+  #   definition = definitions.find { |definition| !definition.internal? }
+  #   # true if component matches its external file.
+  #   definition.guid == Sketchup::Skp.read_guid(definition.path)
+  #
+  # @param [String] filepath
+  #
+  # @raise [ArgumentError] if the file is missing or is not a SketchUp model.
+  #
+  # @return [String]
+  #
+  # @version SketchUp 2021.0
+  def self.read_guid(filepath)
+  end
+
+end

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Style class contains methods for modifying information about a specific

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Styles class contains methods for manipulating a collection of styles in
@@ -38,7 +38,12 @@ class Sketchup::Styles < Sketchup::Entity
   def [](arg)
   end
 
-  # The #{active_style} method is used to retrieve the active style.
+  # The {#active_style} method is used to retrieve the active style.
+  #
+  # While {#selected_style} is the style being selected in the Style Browser,
+  # the #{active_style} is a different object also including any unsaved style
+  # changes. These changes are silently dropped once a new style is selected.
+  # To save these changes to the selected style, call #{update_selected_style}.
   #
   # @example
   #   styles = Sketchup.active_model.styles
@@ -152,7 +157,8 @@ class Sketchup::Styles < Sketchup::Entity
   def purge_unused
   end
 
-  # The {#selected_style} method is used to retrieve the currently selected style.
+  # The {#selected_style} method is used to retrieve the style currently
+  # selected in the Styles Browser.
   #
   # @example
   #   styles = Sketchup.active_model.styles

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Text class contains method to manipulate a Text entity object.

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Texture class contains methods for obtaining information about textures
@@ -41,27 +41,19 @@ class Sketchup::Texture < Sketchup::Entity
   def average_color
   end
 
-  # The filename method retrieves the entire path, including the file, for a
+  # The {#filename} method retrieves the entire path, including the file, for a
   # texture object.
   #
   # @example
   #   model = Sketchup.active_model
-  #   materials=model.materials
-  #   # Adds a material as an in model material
-  #   m = materials.add "Test Color"
-  #   begin
-  #     # Returns nil if not successful, path if successful
-  #     m.texture = "c:\\Materials\\Carpet.jpg"
-  #   rescue
-  #     UI.messagebox $!.message
-  #   end
-  #   texture = m.texture
+  #   materials = model.materials
+  #   material = materials.add("Test Color")
+  #   material.texture = "c:\\Materials\\Carpet.jpg"
+  #   texture = material.texture
   #   filename = texture.filename
-  #   if (filename)
-  #     UI.messagebox filename
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
+  #
+  # @note Since SketchUp 2021.0 this method will append a file extension matching
+  #   the image format if the file extension is missing from stored filepath.
   #
   # @return [String] a string representation of the path and
   #   filename used for the texture.
@@ -206,11 +198,11 @@ class Sketchup::Texture < Sketchup::Entity
   # @example
   #   material = Sketchup.active_model.materials[0]
   #   basename = File.basename(material.texture.filename)
-  #   filename = File.join(Sketchup.temp_dir, basename)
-  #   material.texture.write(filename)
+  #   path = File.join(Sketchup.temp_dir, basename)
+  #   material.texture.write(path)
   #
-  # @param [String] filename
-  #   String - The filename to write the texture to.
+  # @param [String] path
+  #   The file path to write the texture to.
   #
   # @param [Boolean] colorize
   #   Boolean - Allows for the texture to
@@ -219,7 +211,7 @@ class Sketchup::Texture < Sketchup::Entity
   # @return [Boolean] true if the method succeeded
   #
   # @version SketchUp 2016
-  def write(filename, colorize = false)
+  def write(path, colorize = false)
   end
 
 end