sketchup-api-stubs 0.7.8 → 0.7.10

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2022 Trimble Inc.
+# Copyright:: Copyright 2024 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This is the interface to a SketchUp model. The model is the 3D drawing that
@@ -394,7 +394,7 @@ class Sketchup::Model
   def classifications
   end
 
-  # The close method is used to close this model. On Mac OS, only the active
+  # The {#close} method is used to close this model. On Mac OS, only the active
   # model can be closed. On Windows, since there can be only one document open,
   # this method will perform a File/New operation.
   #
@@ -403,10 +403,14 @@ class Sketchup::Model
   #   model = Sketchup.active_model
   #   model.close
   #
+  # @note As of SketchUp 2024.0 this method will ensure the next model window
+  #   gets focus if there is one. Before that `Sketchup.active_model` might
+  #   return `nil` after calling this method even though more models where open.
+  #
   # @param [Boolean] ignore_changes
-  #   If true, model changes will be
+  #   If `true`, model changes will be
   #   ignored and save prompts will be suppressed.
-  #   If false, changes will not be ignored and save
+  #   If `false`, changes will not be ignored and save
   #   prompts will be displayed normally.
   #
   # @return [nil]
@@ -943,7 +947,8 @@ class Sketchup::Model
   def latlong_to_point(lnglat_array)
   end
 
-  # The {#layers method retrieves a collection of all Layers objects in the model.
+  # The {#layers} method retrieves a collection of all {Sketchup::Layers} objects
+  # in the model.
   #
   # @example
   #   model = Sketchup.active_model
@@ -1096,6 +1101,20 @@ class Sketchup::Model
   def options
   end
 
+  #
+  # @api Overlays
+  #
+  # @example
+  #   Sketchup.active_model.overlays.each { |overlay|
+  #     puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
+  #   }
+  #
+  # @return [Sketchup::OverlaysManager]
+  #
+  # @version SketchUp 2023.0
+  def overlays
+  end
+
   # The {#pages} method retrieves a {Sketchup::Pages} object containing all of
   # the pages in the model.
   #
@@ -1279,6 +1298,9 @@ class Sketchup::Model
   # @note A bug in SketchUp 2016 and older caused the +.skb+ backup file
   #   written during save to be empty. The +.skp+ file was however valid.
   #
+  # @note Starting with SketchUp 2021, SketchUp is using a the same file format across versions.
+  #   For instance, SketchUp 2021 can open a file made in SketchUp 2022.
+  #
   # @overload save
   #
   #   Save model to the path it is already associated with.
@@ -1335,24 +1357,7 @@ class Sketchup::Model
   #   The path of the file to save the model copy to.
   #
   # @param [Integer] version
-  #   Optional SketchUp file format to use.
-  #   If not provided, latest file format will be used.
-  #   Possible values are:
-  #   - Sketchup::Model::VERSION_3,
-  #   - Sketchup::Model::VERSION_4,
-  #   - Sketchup::Model::VERSION_5,
-  #   - Sketchup::Model::VERSION_6,
-  #   - Sketchup::Model::VERSION_7,
-  #   - Sketchup::Model::VERSION_8,
-  #   - Sketchup::Model::VERSION_2013,
-  #   - Sketchup::Model::VERSION_2014,
-  #   - Sketchup::Model::VERSION_2015,
-  #   - Sketchup::Model::VERSION_2016,
-  #   - Sketchup::Model::VERSION_2017,
-  #   - Sketchup::Model::VERSION_2018,
-  #   - Sketchup::Model::VERSION_2019,
-  #   - Sketchup::Model::VERSION_2020,
-  #   - Sketchup::Model::VERSION_2021
+  #   See {Sketchup::Model#save} for supported values.
   #
   # @return [Boolean] true if successful, false if unsuccessful
   #

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2022 Trimble Inc.
+# Copyright:: Copyright 2024 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to model events.

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2022 Trimble Inc.
+# Copyright:: Copyright 2024 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The OptionsManager class manages various kinds of OptionsProviders on a
@@ -65,19 +65,18 @@ class Sketchup::OptionsManager
   def count
   end
 
-  # The each method is used to iterate through options providers.
+  # The {#each} method is used to iterate through options providers.
   #
   # @example
   #   model = Sketchup.active_model
   #   manager = model.options
   #   manager.each { |provider| puts provider.name }
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 6.0
   #
-  # @yield [opsprovider] A variable that will hold each OptionsProvider object
-  #   as they are found.
+  # @yieldparam [Sketchup::OptionsProvider] provider
   def each
   end
 

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2022 Trimble Inc.
+# Copyright:: Copyright 2024 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # An +OptionsProvider+ class provides various kinds of options on a
@@ -111,8 +111,6 @@ class Sketchup::OptionsProvider
   #
   # @version SketchUp 6.0
   #
-  # @yield [key, value]
-  #
   # @yieldparam [String] key
   #
   # @yieldparam [Object] value
@@ -128,8 +126,6 @@ class Sketchup::OptionsProvider
   #
   # @version SketchUp 6.0
   #
-  # @yield [key]
-  #
   # @yieldparam [String] key
   def each_key
   end
@@ -147,27 +143,23 @@ class Sketchup::OptionsProvider
   #
   # @version SketchUp 6.0
   #
-  # @yield [key, value]
-  #
   # @yieldparam [String] key
   #
   # @yieldparam [Object] value
   def each_pair
   end
 
-  # The each_value method is used to iterate through all of the attribute
+  # The {#each_value} method is used to iterate through all of the attribute
   # values.
   #
-  # Throws an exception if there are no keys.
-  #
   # @example
   #   provider.each_value { |value| puts value }
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 6.0
   #
-  # @yield [value] A variable that will hold each value as they are found.
+  # @yieldparam [Object] value
   def each_value
   end
 
@@ -208,16 +200,11 @@ class Sketchup::OptionsProvider
   def key?(name)
   end
 
-  # The keys method is used to retrieve an array with all of the attribute keys.
+  # The {#keys} method is used to retrieve an array with all of the attribute keys.
   #
   # @example
   #   keys = provider.keys
   #   key = keys[0]
-  #   if (key)
-  #     UI.messagebox key
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
   #
   # @return keys - an array of keys within the options provider if
   #   successful

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2022 Trimble Inc.
+# Copyright:: Copyright 2024 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to operations provider

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

@@ -0,0 +1,490 @@
+# Copyright:: Copyright 2024 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# An Overlay provides contextual model information directly in the viewport.
+# This can be presented in 2D and 3D.
+#
+# Examples can be annotations or analytical model information such as geometry
+# analysis, energy analysis, etc.
+#
+# The overlay feature is not intended as a mechanism to provide custom entities
+# to SketchUp. Whatever overlays draw is not pickable nor exportable.
+#
+# It is also not allowed to perform model changes from overlay events. Doing
+# so will result in a +RuntimeError+ being thrown.
+#
+# @api Overlays
+#
+# @example
+#   class ExampleOverlay < Sketchup::Overlay
+#
+#     def initialize
+#       super('example_inc.my_overlay', 'Example Overlay')
+#     end
+#
+#     def draw(view)
+#       rectangle = [
+#         [100, 100, 0], [300, 100, 0], [300, 200, 0], [100, 200, 0]
+#       ]
+#       view.drawing_color = 'blue'
+#       view.draw2d(GL_QUADS, rectangle)
+#       point = Geom::Point3d.new(120, 120, 0)
+#       view.draw_text(point, "Hello Overlay", size: 20, bold: true, color: 'white')
+#     end
+#
+#   end
+#
+#   # Using an observer to create a new overlay per model.
+#   class ExampleAppObserver < Sketchup::AppObserver
+#
+#     def expectsStartupModelNotifications
+#       true
+#     end
+#
+#     def register_overlay(model)
+#       overlay = ExampleOverlay.new
+#       model.overlays.add(overlay)
+#     end
+#     alias_method :onNewModel, :register_overlay
+#     alias_method :onOpenModel, :register_overlay
+#
+#   end
+#
+#   observer = ExampleAppObserver.new
+#   Sketchup.add_observer(observer)
+#
+#   # The following line is needed if you copy+paste in the Ruby Console or
+#   # at the moment the extension is installed:
+#   observer.register_overlay(Sketchup.active_model)
+#
+# @version SketchUp 2023.0
+class Sketchup::Overlay
+
+  # Instance Methods
+
+  # This is a short user facing description of the overlay that will appear in the UI.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   Sketchup.active_model.overlays.each { |overlay|
+  #     puts "#{overlay.name}: #{overlay.description}"
+  #   }
+  #
+  # @return [String]
+  #
+  # @version SketchUp 2023.0
+  def description
+  end
+
+  # Sets a short user facing description of the overlay that will appear in the UI.
+  # Set this before adding to the {Sketchup::OverlaysManager}.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   Sketchup.active_model.overlays.each { |overlay|
+  #     puts "#{overlay.name}: #{overlay.description}"
+  #   }
+  #
+  # @return [String]
+  #
+  # @version SketchUp 2023.0
+  def description=(description)
+  end
+
+  #
+  # @abstract It is called whenever the view updates.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #
+  #     def draw(view)
+  #       # Draw a square.
+  #       points = [
+  #         Geom::Point3d.new(0, 0, 0),
+  #         Geom::Point3d.new(9, 0, 0),
+  #         Geom::Point3d.new(9, 9, 0),
+  #         Geom::Point3d.new(0, 9, 0)
+  #       ]
+  #       # Fill
+  #       view.drawing_color = Sketchup::Color.new(255, 128, 128)
+  #       view.draw(GL_QUADS, points)
+  #       # Outline
+  #       view.line_stipple = '' # Solid line
+  #       view.drawing_color = Sketchup::Color.new(64, 0, 0)
+  #       view.draw(GL_LINE_LOOP, points)
+  #     end
+  #
+  #   end
+  #
+  # @note This is called very often. Perform minimal amount of computation in
+  #   this event. Cache the data needed to draw what the overlay needs whenever
+  #   possible.
+  #
+  # @note If you draw outside the model bounds you need to implement
+  #   {Sketchup::Overlay#getExtents} which return a bounding box large enough to
+  #   include the points you draw. Otherwise your drawing will be clipped.
+  #
+  # @param [Sketchup::View] view
+  #   A View object where the method was invoked.
+  #
+  # @see getExtents
+  #
+  # @see Sketchup::View#draw
+  #
+  # @version SketchUp 2023.0
+  def draw(view)
+  end
+
+  #
+  # @api Overlays
+  #
+  # @note In most cases, extensions doesn't need to expose any new UI for
+  #   enabling them. This can be done from the Overlays panel. However, in some
+  #   cases the extension might have additional UI related to the overlays and
+  #   might want to offer a way to toggle its overlays along with the rest of
+  #   the UI.
+  #
+  # @param [Boolean] enabled
+  #
+  # @raise [RuntimeError] if the overlay is not added to a model.
+  #
+  # @version SketchUp 2023.0
+  def enabled=(enabled)
+  end
+
+  #
+  # @api Overlays
+  #
+  # @example
+  #   Sketchup.active_model.overlays.each { |overlay|
+  #     puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
+  #   }
+  #
+  # @return [Boolean]
+  #
+  # @version SketchUp 2023.0
+  def enabled?
+  end
+
+  # In order to accurately draw things, SketchUp needs to know the extents of
+  # what it is drawing. If the overlay is doing its own drawing, it may need to
+  # implement this method to tell SketchUp the extents of what it will be
+  # drawing. If you don't implement this method, you may find that part of what
+  # the overlay is drawing gets clipped to the extents of the rest of the
+  # model.
+  #
+  # This must return a {Geom::BoundingBox}. In a typical implementation, you
+  # will create a new {Geom::BoundingBox}, add points to set the extents of the
+  # drawing that the overlay will do and then return it.
+  #
+  # @abstract The method should be implementing sub-classes ensure what is drawn
+  #   in 3D space doesn't appear clipped. If the overlay only draws in 2D this
+  #   isn't needed.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #       @points = [ [0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0] ]
+  #     end
+  #
+  #     def getExtents
+  #       bb = Sketchup.active_model.bounds
+  #       bb.add(@points)
+  #       return bb
+  #     end
+  #
+  #     def draw(view)
+  #       view.draw(GL_QUADS, @points)
+  #     end
+  #
+  #   end
+  #
+  # @note This is called very often. Perform minimal amount of computation in
+  #   this event. Cache the data needed to compute the bounds of what the overlay
+  #   draws whenever possible.
+  #
+  # @return [Geom::BoundingBox]
+  #
+  # @version SketchUp 2023.0
+  def getExtents
+  end
+
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       description = "A short sentence describing the overlay."
+  #       super('example_inc.my_overlay', 'Example Overlay', description: description)
+  #     end
+  #
+  #   end
+  #
+  #   overlay = ExampleOverlay.new
+  #
+  # @param [String] id
+  #   The string should be unique per overlay subclass.
+  #   A good pattern would be something like: +"company_name.extension_name.overlay_name"+.
+  #
+  # @param [String] name
+  #   This is a user facing display name that will appear in the UI.
+  #   Make it short and representative for what the overlay does.
+  #
+  # @param [String] description
+  #   This is a user facing description that will appear in the UI.
+  #   Make it short and representative for what the overlay does.
+  #
+  # @raise [ArgumentError] if +id+ or +name+ is an empty string
+  #
+  # @version SketchUp 2023.0
+  def initialize(id, name, description: "")
+  end
+
+  # This is a user facing display name that will appear in the UI.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   Sketchup.active_model.overlays.each { |overlay|
+  #     puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
+  #   }
+  #
+  # @return [String]
+  #
+  # @version SketchUp 2023.0
+  def name
+  end
+
+  # The {#onMouseEnter} method is called by SketchUp when the mouse enters the
+  # viewport.
+  #
+  # @abstract It can be used by implementing sub-classes to react to
+  #   mouse movement in the viewport.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #
+  #     def onMouseEnter(flags, x, y, view)
+  #       puts "onMouseEnter: flags = #{flags}"
+  #       puts "                  x = #{x}"
+  #       puts "                  y = #{y}"
+  #       puts "               view = #{view}"
+  #     end
+  #
+  #   end
+  #
+  # @param [Integer] flags
+  #   A bit mask that tells the state of the modifier
+  #   keys and other mouse buttons at the time.
+  #
+  # @param [Integer] x
+  #   The X coordinate on the screen where the event occurred.
+  #
+  # @param [Integer] y
+  #   The Y coordinate on the screen where the event occurred.
+  #
+  # @param [Sketchup::View] view
+  #
+  # @version SketchUp 2023.0
+  def onMouseEnter(flags, x, y, view)
+  end
+
+  # The {#onMouseLeave} method is called by SketchUp when the mouse enters the
+  # viewport.
+  #
+  # @abstract It can be used by implementing sub-classes to react to
+  #   mouse movement in the viewport.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #
+  #     def onMouseLeave(view)
+  #       puts "onMouseLeave"
+  #     end
+  #
+  #   end
+  #
+  # @param [Sketchup::View] view
+  #
+  # @version SketchUp 2023.0
+  def onMouseLeave(view)
+  end
+
+  # Try to make this method as efficient as possible because this method is
+  # called often.
+  #
+  # @abstract It can be used by implementing sub-classes to react to
+  #   mouse movement in the viewport.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #
+  #     def onMouseMove(flags, x, y, view)
+  #       puts "onMouseMove: flags = #{flags}"
+  #       puts "                  x = #{x}"
+  #       puts "                  y = #{y}"
+  #       puts "               view = #{view}"
+  #     end
+  #
+  #   end
+  #
+  # @param [Integer] flags
+  #   A bit mask that tells the state of the modifier
+  #   keys and other mouse buttons at the time.
+  #
+  # @param [Integer] x
+  #   The X coordinate on the screen where the event occurred.
+  #
+  # @param [Integer] y
+  #   The Y coordinate on the screen where the event occurred.
+  #
+  # @param [Sketchup::View] view
+  #
+  # @version SketchUp 2023.0
+  def onMouseMove(flags, x, y, view)
+  end
+
+  #
+  # @api Overlays
+  #
+  # @example Implementing
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #
+  #   end
+  #
+  # @example Accessing
+  #   Sketchup.active_model.overlays.each { |overlay|
+  #     puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
+  #   }
+  #
+  # @return [String]
+  #
+  # @version SketchUp 2023.0
+  def overlay_id
+  end
+
+  # Describes the source associated with the overlay. This is automatically inferred
+  # when the overlay instance is initialized.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   Sketchup.active_model.overlays.each { |overlay|
+  #     puts "#{overlay.name} (Extension: #{overlay.source})"
+  #   }
+  #
+  # @return [String]
+  #
+  # @version SketchUp 2023.0
+  def source
+  end
+
+  #
+  # @abstract It can be used by implementing sub-classes to react when the overlay
+  #   becomes active, for instance when the user turns it on.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #
+  #     def start
+  #       puts "Overlay #{self} started"
+  #     end
+  #
+  #   end
+  #
+  # @version SketchUp 2023.0
+  def start
+  end
+
+  #
+  # @abstract It can be used by implementing sub-classes to react when the overlay
+  #   becomes inactive, for instance when the user turns it off.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #
+  #     def stop(view)
+  #       puts "Overlay #{self} stopped"
+  #     end
+  #
+  #   end
+  #
+  # @version SketchUp 2023.0
+  def stop
+  end
+
+  # Indicates whether the overlay is valid. An overlay becomes invalid after
+  # being removed from the model and cannot be reused.
+  #
+  # @api Overlays
+  #
+  # @example
+  #   class ExampleOverlay < Sketchup::Overlay
+  #     def initialize
+  #       super('example_inc.my_overlay', 'Example Overlay')
+  #     end
+  #   end
+  #
+  #   overlay = ExampleOverlay.new
+  #   p overlay.valid? # => true
+  #   Sketchup.active_model.overlays.add(overlay)
+  #   p overlay.valid? # => true
+  #
+  #   Sketchup.active_model.overlays.remove(overlay)
+  #   p overlay.valid? # => false
+  #
+  # @return [Boolean]
+  #
+  # @version SketchUp 2023.0
+  def valid?
+  end
+
+end