From c0c4d8cbebb3fbdc10849a09d5f8550007c48f56 Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Thu, 5 Feb 2026 13:14:09 +0100 Subject: [PATCH 1/6] SketchUp 2025.0 and SketchUp 2026.0. --- README.md | 6 +- lib/sketchup-api-stubs/sketchup.rb | 6 + lib/sketchup-api-stubs/stubs/Array.rb | 2 +- lib/sketchup-api-stubs/stubs/Geom.rb | 12 +- .../stubs/Geom/BoundingBox.rb | 4 +- lib/sketchup-api-stubs/stubs/Geom/Bounds2d.rb | 40 +- lib/sketchup-api-stubs/stubs/Geom/LatLong.rb | 49 +- .../stubs/Geom/OrientedBounds2d.rb | 2 +- lib/sketchup-api-stubs/stubs/Geom/Point2d.rb | 101 +- lib/sketchup-api-stubs/stubs/Geom/Point3d.rb | 240 +++-- .../stubs/Geom/PolygonMesh.rb | 86 +- .../stubs/Geom/Transformation.rb | 128 ++- .../stubs/Geom/Transformation2d.rb | 66 +- lib/sketchup-api-stubs/stubs/Geom/UTM.rb | 24 +- lib/sketchup-api-stubs/stubs/Geom/Vector2d.rb | 245 +++-- lib/sketchup-api-stubs/stubs/Geom/Vector3d.rb | 429 ++++---- .../stubs/LanguageHandler.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout.rb | 2 +- .../stubs/Layout/AngularDimension.rb | 2 +- .../stubs/Layout/AutoTextDefinition.rb | 18 +- .../stubs/Layout/AutoTextDefinitions.rb | 2 +- .../stubs/Layout/ConnectionPoint.rb | 2 +- .../stubs/Layout/Dictionary.rb | 234 +++++ .../stubs/Layout/Document.rb | 134 ++- .../stubs/Layout/Ellipse.rb | 2 +- .../stubs/Layout/Entities.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Entity.rb | 111 +- .../stubs/Layout/FormattedText.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Grid.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Group.rb | 8 +- lib/sketchup-api-stubs/stubs/Layout/Image.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Label.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Layer.rb | 2 +- .../stubs/Layout/LayerInstance.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Layers.rb | 2 +- .../stubs/Layout/LinearDimension.rb | 65 +- .../stubs/Layout/LockedEntityError.rb | 2 +- .../stubs/Layout/LockedLayerError.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Page.rb | 101 +- .../stubs/Layout/PageInfo.rb | 27 +- lib/sketchup-api-stubs/stubs/Layout/Pages.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Path.rb | 8 +- .../stubs/Layout/Rectangle.rb | 2 +- .../stubs/Layout/ReferenceEntity.rb | 2 +- .../stubs/Layout/SketchUpModel.rb | 2 +- lib/sketchup-api-stubs/stubs/Layout/Style.rb | 48 +- lib/sketchup-api-stubs/stubs/Layout/Table.rb | 2 +- .../stubs/Layout/TableCell.rb | 2 +- .../stubs/Layout/TableColumn.rb | 2 +- .../stubs/Layout/TableRow.rb | 2 +- lib/sketchup-api-stubs/stubs/Length.rb | 10 +- lib/sketchup-api-stubs/stubs/Numeric.rb | 2 +- lib/sketchup-api-stubs/stubs/Sketchup.rb | 107 +- .../stubs/Sketchup/Animation.rb | 78 +- .../stubs/Sketchup/AppObserver.rb | 2 +- .../stubs/Sketchup/ArcCurve.rb | 2 +- .../stubs/Sketchup/AttributeDictionaries.rb | 9 +- .../stubs/Sketchup/AttributeDictionary.rb | 19 +- lib/sketchup-api-stubs/stubs/Sketchup/Axes.rb | 26 +- .../stubs/Sketchup/Behavior.rb | 22 +- .../stubs/Sketchup/Camera.rb | 25 +- .../stubs/Sketchup/ClassificationSchema.rb | 2 +- .../stubs/Sketchup/Classifications.rb | 4 +- .../stubs/Sketchup/Color.rb | 2 +- .../stubs/Sketchup/ComponentDefinition.rb | 42 +- .../stubs/Sketchup/ComponentInstance.rb | 23 +- .../stubs/Sketchup/Console.rb | 2 +- .../stubs/Sketchup/ConstructionLine.rb | 19 +- .../stubs/Sketchup/ConstructionPoint.rb | 2 +- .../stubs/Sketchup/Curve.rb | 2 +- .../stubs/Sketchup/DefinitionList.rb | 14 +- .../stubs/Sketchup/DefinitionObserver.rb | 2 +- .../stubs/Sketchup/DefinitionsObserver.rb | 2 +- .../stubs/Sketchup/Dimension.rb | 32 +- .../stubs/Sketchup/DimensionLinear.rb | 34 +- .../stubs/Sketchup/DimensionObserver.rb | 2 +- .../stubs/Sketchup/DimensionRadial.rb | 6 +- .../stubs/Sketchup/Drawingelement.rb | 25 +- lib/sketchup-api-stubs/stubs/Sketchup/Edge.rb | 4 +- .../stubs/Sketchup/EdgeUse.rb | 20 +- .../stubs/Sketchup/Entities.rb | 78 +- .../stubs/Sketchup/EntitiesBuilder.rb | 2 +- .../stubs/Sketchup/EntitiesObserver.rb | 2 +- .../stubs/Sketchup/Entity.rb | 6 +- .../stubs/Sketchup/EntityObserver.rb | 2 +- .../stubs/Sketchup/Environment.rb | 406 ++++++++ .../stubs/Sketchup/Environments.rb | 185 ++++ .../stubs/Sketchup/EnvironmentsObserver.rb | 113 ++ .../stubs/Sketchup/ExtensionsManager.rb | 9 +- lib/sketchup-api-stubs/stubs/Sketchup/Face.rb | 119 ++- .../stubs/Sketchup/FrameChangeObserver.rb | 4 +- .../stubs/Sketchup/Group.rb | 42 +- lib/sketchup-api-stubs/stubs/Sketchup/Http.rb | 2 +- .../stubs/Sketchup/Http/Request.rb | 41 +- .../stubs/Sketchup/Http/Response.rb | 20 +- .../stubs/Sketchup/Image.rb | 71 +- .../stubs/Sketchup/ImageRep.rb | 4 +- .../stubs/Sketchup/Importer.rb | 4 +- .../stubs/Sketchup/InputPoint.rb | 42 +- .../stubs/Sketchup/InstanceObserver.rb | 2 +- .../stubs/Sketchup/InstancePath.rb | 7 +- .../stubs/Sketchup/Layer.rb | 22 +- .../stubs/Sketchup/LayerFolder.rb | 48 +- .../stubs/Sketchup/Layers.rb | 20 +- .../stubs/Sketchup/LayersObserver.rb | 10 +- .../stubs/Sketchup/Licensing.rb | 13 +- .../Sketchup/Licensing/ExtensionLicense.rb | 2 +- .../stubs/Sketchup/LineStyle.rb | 2 +- .../stubs/Sketchup/LineStyles.rb | 2 +- .../stubs/Sketchup/LoadHandler.rb | 70 ++ lib/sketchup-api-stubs/stubs/Sketchup/Loop.rb | 2 +- .../stubs/Sketchup/Material.rb | 961 +++++++++++++++--- .../stubs/Sketchup/Materials.rb | 57 +- .../stubs/Sketchup/MaterialsObserver.rb | 2 +- lib/sketchup-api-stubs/stubs/Sketchup/Menu.rb | 2 +- .../stubs/Sketchup/Model.rb | 230 +++-- .../stubs/Sketchup/ModelObserver.rb | 25 +- .../stubs/Sketchup/OptionsManager.rb | 25 +- .../stubs/Sketchup/OptionsProvider.rb | 2 +- .../stubs/Sketchup/OptionsProviderObserver.rb | 2 +- .../stubs/Sketchup/Overlay.rb | 61 +- .../stubs/Sketchup/OverlaysManager.rb | 14 +- lib/sketchup-api-stubs/stubs/Sketchup/Page.rb | 174 +++- .../stubs/Sketchup/Pages.rb | 69 +- .../stubs/Sketchup/PagesObserver.rb | 2 +- .../stubs/Sketchup/PickHelper.rb | 101 +- .../stubs/Sketchup/RegionalSettings.rb | 2 +- .../stubs/Sketchup/RenderingOptions.rb | 14 +- .../Sketchup/RenderingOptionsObserver.rb | 2 +- .../stubs/Sketchup/SectionPlane.rb | 2 +- .../stubs/Sketchup/Selection.rb | 175 ++-- .../stubs/Sketchup/SelectionObserver.rb | 2 +- lib/sketchup-api-stubs/stubs/Sketchup/Set.rb | 3 +- .../stubs/Sketchup/ShadowInfo.rb | 7 +- .../stubs/Sketchup/ShadowInfoObserver.rb | 2 +- lib/sketchup-api-stubs/stubs/Sketchup/Skp.rb | 2 +- lib/sketchup-api-stubs/stubs/Sketchup/Snap.rb | 125 +++ .../stubs/Sketchup/Style.rb | 21 +- .../stubs/Sketchup/Styles.rb | 72 +- lib/sketchup-api-stubs/stubs/Sketchup/Text.rb | 37 +- .../stubs/Sketchup/Texture.rb | 44 +- .../stubs/Sketchup/TextureWriter.rb | 18 +- lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb | 361 ++++--- .../stubs/Sketchup/Tools.rb | 2 +- .../stubs/Sketchup/ToolsObserver.rb | 2 +- .../stubs/Sketchup/UVHelper.rb | 2 +- .../stubs/Sketchup/Vertex.rb | 45 +- lib/sketchup-api-stubs/stubs/Sketchup/View.rb | 434 ++++++-- .../stubs/Sketchup/ViewObserver.rb | 42 +- .../stubs/SketchupExtension.rb | 22 +- lib/sketchup-api-stubs/stubs/String.rb | 2 +- lib/sketchup-api-stubs/stubs/UI.rb | 70 +- lib/sketchup-api-stubs/stubs/UI/Command.rb | 30 +- lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb | 45 +- .../stubs/UI/Notification.rb | 17 +- lib/sketchup-api-stubs/stubs/UI/Toolbar.rb | 23 +- lib/sketchup-api-stubs/stubs/UI/WebDialog.rb | 15 +- lib/sketchup-api-stubs/stubs/_top_level.rb | 14 +- pages/ReleaseNotes.md | 302 +++++- pages/TOS.md | 5 +- pages/exporter_options.md | 125 ++- pages/extension_requirements.md | 80 +- 162 files changed, 5825 insertions(+), 2203 deletions(-) create mode 100644 lib/sketchup-api-stubs/stubs/Layout/Dictionary.rb create mode 100644 lib/sketchup-api-stubs/stubs/Sketchup/Environment.rb create mode 100644 lib/sketchup-api-stubs/stubs/Sketchup/Environments.rb create mode 100644 lib/sketchup-api-stubs/stubs/Sketchup/EnvironmentsObserver.rb create mode 100644 lib/sketchup-api-stubs/stubs/Sketchup/LoadHandler.rb create mode 100644 lib/sketchup-api-stubs/stubs/Sketchup/Snap.rb diff --git a/README.md b/README.md index 3165001..57e3487 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ The SketchUp Ruby API allows you to interact with SketchUp models and the SketchUp application. It is available from within SketchUp, it cannot be used by itself. -

- Get started with the Ruby API Overview. -

+ All interactions with the SketchUp Ruby API must be performed from the main thread to avoid unexpected behavior and application instability. + +Get started with the [Ruby API Overview](_index.html). Visit our [SketchUp Developer Center](https://developer.sketchup.com) for more information and resources on SketchUp's APIs. diff --git a/lib/sketchup-api-stubs/sketchup.rb b/lib/sketchup-api-stubs/sketchup.rb index efd8bf3..4c1a7a3 100644 --- a/lib/sketchup-api-stubs/sketchup.rb +++ b/lib/sketchup-api-stubs/sketchup.rb @@ -21,6 +21,7 @@ require 'sketchup-api-stubs/stubs/Layout/AutoTextDefinition.rb' require 'sketchup-api-stubs/stubs/Layout/AutoTextDefinitions.rb' require 'sketchup-api-stubs/stubs/Layout/ConnectionPoint.rb' +require 'sketchup-api-stubs/stubs/Layout/Dictionary.rb' require 'sketchup-api-stubs/stubs/Layout/Document.rb' require 'sketchup-api-stubs/stubs/Layout/Ellipse.rb' require 'sketchup-api-stubs/stubs/Layout/Entities.rb' @@ -82,6 +83,9 @@ require 'sketchup-api-stubs/stubs/Sketchup/Entities.rb' require 'sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb' require 'sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.rb' +require 'sketchup-api-stubs/stubs/Sketchup/Environment.rb' +require 'sketchup-api-stubs/stubs/Sketchup/Environments.rb' +require 'sketchup-api-stubs/stubs/Sketchup/EnvironmentsObserver.rb' require 'sketchup-api-stubs/stubs/Sketchup/ExtensionsManager.rb' require 'sketchup-api-stubs/stubs/Sketchup/Face.rb' require 'sketchup-api-stubs/stubs/Sketchup/FrameChangeObserver.rb' @@ -103,6 +107,7 @@ require 'sketchup-api-stubs/stubs/Sketchup/Licensing/ExtensionLicense.rb' require 'sketchup-api-stubs/stubs/Sketchup/LineStyle.rb' require 'sketchup-api-stubs/stubs/Sketchup/LineStyles.rb' +require 'sketchup-api-stubs/stubs/Sketchup/LoadHandler.rb' require 'sketchup-api-stubs/stubs/Sketchup/Loop.rb' require 'sketchup-api-stubs/stubs/Sketchup/Material.rb' require 'sketchup-api-stubs/stubs/Sketchup/Materials.rb' @@ -129,6 +134,7 @@ require 'sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb' require 'sketchup-api-stubs/stubs/Sketchup/ShadowInfoObserver.rb' require 'sketchup-api-stubs/stubs/Sketchup/Skp.rb' +require 'sketchup-api-stubs/stubs/Sketchup/Snap.rb' require 'sketchup-api-stubs/stubs/Sketchup/Style.rb' require 'sketchup-api-stubs/stubs/Sketchup/Styles.rb' require 'sketchup-api-stubs/stubs/Sketchup/Text.rb' diff --git a/lib/sketchup-api-stubs/stubs/Array.rb b/lib/sketchup-api-stubs/stubs/Array.rb index f6a7736..4ee9f76 100644 --- a/lib/sketchup-api-stubs/stubs/Array.rb +++ b/lib/sketchup-api-stubs/stubs/Array.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The SketchUp Array class adds additional methods to the standard Ruby Array diff --git a/lib/sketchup-api-stubs/stubs/Geom.rb b/lib/sketchup-api-stubs/stubs/Geom.rb index 8db0774..1c7b10b 100644 --- a/lib/sketchup-api-stubs/stubs/Geom.rb +++ b/lib/sketchup-api-stubs/stubs/Geom.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Geom module defines a number of Module methods that let you perform @@ -73,12 +73,12 @@ def self.closest_points(line1, line2) # @param [Geom::Point3d] point1 # @param [Geom::Point3d] point2 # @param [Geom::Point3d] point3 - # @return [Array(Geom::Point3d, Geom::Vector3d)] A plane + # @return [Array(Float, Float, Float, Float)] A plane # # @overload fit_plane_to_points(points) # # @param [Array] points - # @return [Array(Geom::Point3d, Geom::Vector3d)] A plane + # @return [Array(Float, Float, Float, Float)] A plane # # @version SketchUp 6.0 def self.fit_plane_to_points(*args) @@ -125,7 +125,7 @@ def self.intersect_line_line(line1, line2) # # @param [Array(Geom::Point3d, Geom::Vector3d)] line # - # @param [Array(Geom::Point3d, Geom::Point3d)] plane + # @param [Array(Geom::Point3d, Geom::Vector3d)] plane # # @return [Geom::Point3d, nil] A Point3d object. Returns +nil+ if they do not # intersect. @@ -149,11 +149,11 @@ def self.intersect_line_plane(line, plane) # # 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 + # @param [Array(Geom::Point3d, Geom::Vector3d)] plane1 # The first plane to # intersect # - # @param [Array(Geom::Point3d, Geom::Point3d)] plane2 + # @param [Array(Geom::Point3d, Geom::Vector3d)] plane2 # The second plane to # intersect # diff --git a/lib/sketchup-api-stubs/stubs/Geom/BoundingBox.rb b/lib/sketchup-api-stubs/stubs/Geom/BoundingBox.rb index c68793b..03e4649 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/BoundingBox.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/BoundingBox.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Bounding boxes are three-dimensional boxes (eight corners), aligned with the @@ -141,7 +141,7 @@ def contains?(point_or_bb) # boundingbox.add([100, 200, -400], [200, 400, 100]) # # This will return Point3d(100, 200, -400). # boundingbox.corner(0) - # # This will return Point3d(100, 200, -400). + # # This will return Point3d(100, 400, 100). # boundingbox.corner(6) # # @param [Integer] corner_index diff --git a/lib/sketchup-api-stubs/stubs/Geom/Bounds2d.rb b/lib/sketchup-api-stubs/stubs/Geom/Bounds2d.rb index 1374516..153515d 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/Bounds2d.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/Bounds2d.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The bounds2d class represents an axis aligned bounding box represented by @@ -14,7 +14,10 @@ class Geom::Bounds2d # checks whether the point values are the same # # @example - # entity.bounds == entity.untransformed_bounds + # bounds1 = Geom::Bounds2d.new(0.0, 0.0, 5.0, 5.0) + # bounds2 = Geom::Bounds2d.new([0, 0], [5, 5]) + # # Return true + # bounds1 == bounds2 # # @param [Geom::Bounds2d] other # @@ -27,10 +30,10 @@ def ==(other) # The {#height} method returns the height of the {Geom::Bounds2d}. # # @example - # bounds = Geom::Bounds2d.new(0.0, 0.0, 1.0, 1.0) + # bounds = Geom::Bounds2d.new(5.0, 5.0, 1.0, 7.0) # height = bounds.height # - # @return [Geom::Point2d] + # @return [Float] # # @version LayOut 2018 def height @@ -39,7 +42,11 @@ def height # The {#initialize} method creates a new {Geom::Bounds2d}. # # @example - # bounds = Geom::Bounds2d.new(0.0, 0.0, 1.0, 1.0) + # bounds1 = Geom::Bounds2d.new(0.0, 0.0, 1.0, 1.0) + # + # upper_left = Geom::Point2d.new(1, 1) # is equivalent to upper_left = [1, 1] + # lower_right = Geom::Point2d.new(3, 3) # is equivalent to lower_right = [3, 3] + # bounds2 = Geom::Bounds2d.new(upper_left, lower_right) # # @overload initialize(other_bounds) # @@ -80,8 +87,9 @@ def initialize(*args) # corner of the {Geom::Bounds2d}. # # @example - # bounds = Geom::Bounds2d.new(0.0, 0.0, 1.0, 1.0) - # l_r = bounds.lower_right + # bounds = Geom::Bounds2d.new(2.0, 2.0, 1.0, 1.0) + # # The result is a Point2d(3, 3) + # lower_right = bounds.lower_right # # @return [Geom::Point2d] # @@ -89,8 +97,9 @@ def initialize(*args) def lower_right end - # The {#set!} method sets the {Geom::Bounds2d} to match another one. - # The argument is anything that can be converted into a {Geom::Bounds2d}. + # The {#set!} method is used to update the dimensions and position of a {Geom::Bounds2d} object so + # that it matches the specified bounds. The argument is anything that can be converted into a + # {Geom::Bounds2d}. # # @example # bounds = Geom::Bounds2d.new(3.0, 3.0, 5.0, 5.0) @@ -131,11 +140,11 @@ def lower_right def set!(*args) end - # The {#to_a} method returns an array which contains the {Geom::Point2d} that + # The {#to_a} method returns an array which contains the {Geom::Point2d}s that # define the {Geom::Bounds2d}. # # @example - # bounds = Geom::Bounds2d.new + # bounds = Geom::Bounds2d.new(2.0, 2.0, 5.0, 5.0) # bounds.to_a.each { |point| p point.to_s } # # @return [Array(Geom::Point2d, Geom::Point2d)] @@ -148,8 +157,9 @@ def to_a # of the {Geom::Bounds2d}. # # @example - # bounds = Geom::Bounds2d.new(0.0, 0.0, 1.0, 1.0) - # u_l = bounds.upper_left + # bounds = Geom::Bounds2d.new(2.0, 2.0, 1.0, 1.0) + # # The result is a Point2d(2, 2) + # upper_left = bounds.upper_left # # @return [Geom::Point2d] # @@ -160,10 +170,10 @@ def upper_left # The {#width} method returns the width of the {Geom::Bounds2d}. # # @example - # bounds = Geom::Bounds2d.new(0.0, 0.0, 1.0, 1.0) + # bounds = Geom::Bounds2d.new(5.0, 5.0, 7.0, 1.0) # width = bounds.width # - # @return [Geom::Point2d] + # @return [Float] # # @version LayOut 2018 def width diff --git a/lib/sketchup-api-stubs/stubs/Geom/LatLong.rb b/lib/sketchup-api-stubs/stubs/Geom/LatLong.rb index 6e21c13..e8fbc22 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/LatLong.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/LatLong.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The LatLong class contains various methods for creating and manipulating @@ -12,13 +12,13 @@ class Geom::LatLong # The new method creates a LatLong object. # # @example - # ll = [40.01700, 105.28300] - # latlong = Geom::LatLong.new(ll) - # if (latlong) - # UI.messagebox(latlong) - # else - # UI.messagebox("Failure") - # end + # # No arguments, creates a latlong with (0, 0) + # latlong1 = Geom::LatLong.new + # + # latlong2 = Geom::LatLong.new(40.01700, 105.28300) + # + # array = [40.01700, 105.28300] + # latlong3 = Geom::LatLong.new(array) # # @overload initialize # @@ -36,8 +36,8 @@ class Geom::LatLong # # @overload initialize(lat, long) # - # @param [Numeric] lat - # @param [Numeric] long + # @param [Numeric] latitude + # @param [Numeric] longitude # @return [Geom::LatLong] # # @version SketchUp 6.0 @@ -47,14 +47,9 @@ def initialize(*args) # The Latitude method retrieves the latitude coordinate from a LatLong object. # # @example - # ll = [40.01700, 105.28300] - # latlong = Geom::LatLong.new(ll) + # latlong = Geom::LatLong.new(40.01700, 105.28300) + # # The result is 40.01700 # latitude = latlong.latitude - # if (latitude) - # UI.messagebox(latitude) - # else - # UI.messagebox("Failure") - # end # # @return [Float] a latitude coordinate value # @@ -66,14 +61,9 @@ def latitude # object. # # @example - # ll = [40.01700, 105.28300] - # latlong = Geom::LatLong.new(ll) + # latlong = Geom::LatLong.new(40.01700, 105.28300) + # # The result is 105.28300 # longitude = latlong.longitude - # if (longitude) - # UI.messagebox(longitude) - # else - # UI.messagebox("Failure") - # end # # @return [Float] a latitude coordinate value # @@ -84,7 +74,7 @@ def longitude # The {#to_a} method converts a LatLong object to an array of two values. # # @example - # latlong = Geom::LatLong.new([40.01700, 105.28300]) + # latlong = Geom::LatLong.new(40.01700, 105.28300) # array = latlong.to_a # # @return [Array(Float, Float)] an array of latitude and longitude @@ -108,14 +98,9 @@ def to_s # The to_utm method converts a LatLong object to a UTM object. # # @example - # ll = [40.01700, 105.28300] - # latlong = Geom::LatLong.new(ll) + # latlong = Geom::LatLong.new(40.01700, 105.28300) + # # The result is UTM(48 T 524150.82056 4429682.40743) # utm = latlong.to_utm - # if (utm) - # UI.messagebox(utm) - # else - # UI.messagebox("Failure") - # end # # @return [Geom::UTM] # diff --git a/lib/sketchup-api-stubs/stubs/Geom/OrientedBounds2d.rb b/lib/sketchup-api-stubs/stubs/Geom/OrientedBounds2d.rb index 66ac2b8..b2c0161 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/OrientedBounds2d.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/OrientedBounds2d.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The OrientedBounds2d class is a bounding box represented by four diff --git a/lib/sketchup-api-stubs/stubs/Geom/Point2d.rb b/lib/sketchup-api-stubs/stubs/Geom/Point2d.rb index b8103c4..818d020 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/Point2d.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/Point2d.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Geom::Point2d} class allows you to work with a point in 2D space. @@ -10,14 +10,14 @@ # # @example # # No arguments, creates a point at the origin [0, 0] -# pt1 = Geom::Point2d.new +# point1 = Geom::Point2d.new # # # Creates a point at x of 1, y of 2. -# pt2 = Geom::Point2d.new(1, 2) +# point2 = Geom::Point2d.new(1, 2) # # # You can also create a point directly by simply assigning the x, and y # # values to a variable as an array: -# pt3 = [1, 2] +# point3 = [1, 2] # # @version LayOut 2018 class Geom::Point2d @@ -28,10 +28,16 @@ class Geom::Point2d # {Geom::Point2d}, or to set the values of the {Geom::Point2d} by adding a # {Geom::Vector2d} to the {Geom::Point2d}. # - # @example - # pt = [1, 1] - # # the result is a Point2d(2, 3) - # pt2 = pt + [1, 2] + # @example Translate Point2d with Vector2d + # point = Geom::Point2d.new(1, 1) + # vector = Geom::Vector2d.new(1, 2) + # # The result is a Point2d(2, 3) + # new_point = point + vector + # + # @example Translate Point2d with vector in Array form + # point = Geom::Point2d.new(1, 1) + # # The result is a Point2d(2, 3) + # new_point = point + [1, 2] # # @param [Geom::Vector2d, Array(Numeric, Numeric)] vector # @@ -44,23 +50,37 @@ def +(vector) # The {#-} operator is a simple way to subtract from the current x and y values # of the {Geom::Point2d}. # - # @example - # vec = Geom::Vector2d.new(1, 2) - # # result is a Point2d(3, 0) - # pt = [4, 2] - vec - # # result is a Vector2d(1, 2) - # vec2 = [4, 2] - pt + # @example Translate Point2d by vector in Array form + # point = Geom::Point2d.new(4, 2) + # # The result is a Vector2d(3, 0) + # vector = point - [1, 2] # - # @overload -(vector) + # @example Calculate the Vector2d between two Point2d + # point1 = Geom::Point2d.new(4, 2) + # point2 = Geom::Point2d.new(1, 2) + # # The result is a Vector2d(3, 0) + # vector = point1 - point2 # - # @param [Geom::Vector2d, Array(Numeric, Numeric)] vector - # @return [Geom::Point2d] + # @example Translate Point2d with Vector2d + # point = Geom::Point2d.new(4, 2) + # vector = Geom::Vector2d.new(3, 0) + # # The result is a Point2d(1, 2) + # new_point = point - vector + # + # @overload -(array2d) # - # @overload -(point) + # @param [Array(Numeric, Numeric)] array2d + # @return [Geom::Vector2d] + # + # @overload -(point2d) # # @param [Geom::Point2d] point2d - # @return [Geom::Vector2d] a vector indicating the difference between the two - # points + # @return [Geom::Vector2d] + # + # @overload -(vector2d) + # + # @param [Geom::Vector2d] vector2d + # @return [Geom::Point2d] # # @version LayOut 2018 def -(arg) @@ -72,6 +92,7 @@ def -(arg) # @example # point1 = Geom::Point2d.new(1, 1) # point2 = Geom::Point2d.new(0, 1) + # # Return false # status = point1 == point2 # # @param [Geom::Point2d, Array(Numeric, Numeric)] point @@ -88,7 +109,7 @@ def ==(point) # @example # point = Geom::Point2d.new(1, 2) # - # # returns the y value of 2 + # # Returns the y value of 2 # yvalue = point[1] # # @param [Integer] index @@ -126,7 +147,7 @@ def []=(index, value) # # @example # point = Geom::Point2d.new(1, 2) - # newpoint = point.clone + # new_point = point.clone # # @return [Geom::Point2d] the cloned {Geom::Point2d} object # @@ -140,7 +161,7 @@ def clone # @example # point1 = Geom::Point2d.new(1, 1) # point2 = Geom::Point2d.new(1, 4) - # # result is a value of 3 + # # The result is 3 # distance = point1.distance(point2) # # @param [Geom::Point2d, Array(Numeric, Numeric)] point @@ -155,14 +176,14 @@ def distance(point) # # @example # # No arguments, creates a point at the origin [0, 0] - # pt1 = Geom::Point2d.new + # point1 = Geom::Point2d.new # # # Creates a point at x of 1 and y of 2. - # pt2 = Geom::Point2d.new(1, 2) + # point2 = Geom::Point2d.new(1, 2) # # # You can also create a point directly by simply assigning the x and y # # values to a variable as an array: - # pt3 = [1, 2] + # point3 = [1, 2] # # @overload initialize # @@ -201,8 +222,8 @@ def inspect # @example # point = Geom::Point2d.new # vector = Geom::Vector2d.new(0, 2) - # # result is a Point2d(0, 1) - # point2 = point1.offset(vector, 1) + # # The result is a Point2d(0, 1) + # new_point = point.offset(vector, 1) # # @overload offset(vector) # @@ -226,8 +247,8 @@ def offset(*args) # @example # point = Geom::Point2d.new # vector = Geom::Vector2d.new(0, 2) - # # result is a Point2d(0, 1) - # point1.offset!(vector, 1) + # # The result is a Point2d(0, 1) + # point.offset!(vector, 1) # # @overload offset!(vector) # @@ -270,6 +291,8 @@ def set!(*args) # @example # point = Geom::Point2d.new(1, 2) # array = point.to_a + # # The result is [1, 2] + # p array # # @return [Array(Numeric, Numeric)] an array of two numbers representing x, y # of the {Geom::Point2d} @@ -282,7 +305,7 @@ def to_a # # @example # point = Geom::Point2d.new(1, 2) - # str = point.to_s + # string = point.to_s # # @return [String] # @@ -296,8 +319,8 @@ def to_s # @example # point = Geom::Point2d.new(4, 5) # transformation = Geom::Transformation2d.new([1, 0, 0, 1, 2, 3]) - # # pt will be (6, 8) - # pt = point.transform(transformation) + # # The result is a Point2d(6, 8) + # transformed_point = point.transform(transformation) # # @param [Geom::Transformation2d] transform # A Transformation object to apply to the point. @@ -314,7 +337,7 @@ def transform(transform) # @example # point = Geom::Point2d.new(4, 5) # transformation = Geom::Transformation2d.new([1, 0, 0, 1, 2, 3]) - # # point will be (6, 8) + # # The result is a Point2d(6, 8) # point.transform!(transformation) # # @param [Geom::Transformation2d] transform @@ -329,13 +352,13 @@ def transform!(transform) # The {#vector_to} method returns the vector between points. # # @example - # pt1 = Geom::Point2d.new(1, 1) - # pt2 = Geom::Point2d.new(3, 1) + # point1 = Geom::Point2d.new(1, 1) + # point2 = Geom::Point2d.new(3, 1) # - # # result is a Vector2d(2, 0) - # vec = pt1.vector_to(pt2) # is equivalent to (pt2 - pt1) + # # The result is a Vector2d(2, 0) + # vector = point1.vector_to(point2) # is equivalent to (point2 - point1) # - # @param [Geom::Point2d] point + # @param [Geom::Point2d, Array(Numeric, Numeric)] point # # @return [Geom::Vector2d] # diff --git a/lib/sketchup-api-stubs/stubs/Geom/Point3d.rb b/lib/sketchup-api-stubs/stubs/Geom/Point3d.rb index e9eb0d7..cc763b0 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/Point3d.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/Point3d.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Point3d class allows you to work with a point in 3D space. @@ -16,15 +16,15 @@ # See the Array class for details. # # @example -# # No arguments, creates a point at the origin [0,0,0] -# pt1 = Geom::Point3d.new +# # No arguments, creates a point at the origin [0, 0, 0] +# point1 = Geom::Point3d.new # # # Creates a point at x of 100, y of 200, z of 300. -# pt2 = Geom::Point3d.new(100,200,300) +# point2 = Geom::Point3d.new(100, 200, 300) # # # You can also create a point directly by simply assigning the x, y and z # # values to a variable as an array: -# pt3 = [100,200,300] +# point3 = [100, 200, 300] # # @version SketchUp 6.0 class Geom::Point3d @@ -41,8 +41,8 @@ class Geom::Point3d # point = weight1 * point1 + weight2 * point2. # # @example - # point1 = Geom::Point3d.new(1,1,1) - # point2 = Geom::Point3d.new(10,10,10) + # point1 = Geom::Point3d.new(1, 1, 1) + # point2 = Geom::Point3d.new(10, 10, 10) # # # Get the point that is half the way from point1 to point2. # points = Geom::Point3d.linear_combination(0.5, point1, 0.5, point2) @@ -73,23 +73,25 @@ def self.linear_combination(weight1, point1, weight2, point2) # The {#+} operator is a fast way to add to the current x, y and z values of # a vector. # - # @example Using vector - # point1 = Geom::Point3d.new(1, 2, 3) + # @example Translate Point3d with Vector3d + # point = Geom::Point3d.new(1, 2, 3) # vector = Geom::Vector3d.new(4, 5, 6) - # point2 = point1 + vector + # # The result is a Point3d(5, 7, 9) + # new_point = point + vector # - # @example Using array - # point1 = Geom::Point3d.new(1, 2, 3) - # point2 = point1 + [10,10,10] + # @example Translate Point3d with vector in Array form + # point = Geom::Point3d.new(1, 2, 3) + # # the result is a Point3d(11, 12, 13) + # new_point = point + [10, 10, 10] # - # @example Using point + # @example Translate Point3d with function in Array form # point1 = Geom::Point3d.new(1, 2, 3) # point2 = Geom::Point3d.new(4, 5, 6) - # # This works because SketchUp treats the array of triple numerics as - # # a vector in this case. - # point3 = point1 + point2.to_a + # # This works because SketchUp treats the array of triple numerics as a vector in this case. + # # The result is a Point3d(5, 7, 9) + # new_point = point1 + point2.to_a # - # @param [Geom::Vector3d] vector + # @param [Geom::Vector3d, Array(Numeric, Numeric, Numeric)] vector # # @return [Geom::Point3d] # @@ -100,31 +102,56 @@ def +(vector) # The '-' operator is a fast way to subtract from the current x, y and z values # of a point. # - # @example - # pt2 = pt - vec - # pt = pt - [10,10,10] + # @example Translate a point by a vector in array form + # point = Geom::Point3d.new(12, 11, 12) + # # The result is a Vector3d(2, 1, 2) + # new_point = point - [10, 10, 10] # - # @param [Geom::Point3d] point2 - # A Point3d object. + # @example Calculate the Vector3d between two Point2d + # point1 = Geom::Point2d.new(4, 2, 5) + # point2 = Geom::Point2d.new(1, 2, 4) + # # The result is a Vector3d(3, 0, 1) + # vector = point1 - point2 + # + # @example Translate Point3d with Vector3d + # point = Geom::Point2d.new(4, 2) + # vector = Geom::Vector2d.new(3, 0) + # # The result is a Point3d(1, 2) + # new_point = point - vector + # + # @overload -(array3d) + # + # @param [Array(Numeric, Numeric, Numeric)] array3d + # @return [Geom::Vector3d] + # + # @overload -(point3d) + # + # @param [Geom::Point3d] point3d A Point3d object. + # @return [Geom::Vector3d] + # + # @overload -(vector3d) # - # @return [Geom::Vector3d] + # @param [Geom::Vector3d] vector3d A Vector3d object. + # @return [Geom::Point3d] # # @version SketchUp 6.0 - def -(point2) + def -(arg) end - # The '<' operator is a fast way to determine if another point is closer to the - # origin. + # The {#<} compare method is used to compare two points to determine if + # the left-hand point is less than the right-hand point. # # @example - # pt1 = Geom::Point3d.new(10,10,10) - # pt2 = Geom::Point3d.new(20,20,20) - # result = pt1 < pt2 + # point1 = Geom::Point3d.new(10, 10, 10) + # point2 = Geom::Point3d.new(20, 20, 20) + # result = point1 < point2 # - # @param [Geom::Point3d] point2 + # @note The comparison is performed in the order x, y and z coordinates. + # + # @param [Geom::Point3d, Array(Numeric, Numeric, Numeric)] point2 # A Point3d object. # - # @return [Boolean] true if the point2 is closer to the origin. + # @return [Boolean] true if the point1 is smaller than point2 # # @version SketchUp 6.0 def <(point2) @@ -139,28 +166,30 @@ def <(point2) # x, y and z coordinates, as in the following examples: # # @example - # if( pt1 == pt2 ) - # UI.messagebox('equal') - # end + # point1 = Geom::Point3d.new(3, 4, 3) + # point2 = Geom::Point3d.new(3, 4, 3) + # # Return true + # point1 == point2 # # # ... or ... - # if( pt1 == [100,200,300] ) ... - # UI.messagebox('equal') - # end + # point3 = Geom::Point3d.new(100, 200, 301) + # # Return false + # point3 == [100, 200, 300] # # @example - # point1 = Geom::Point3d.new(1,1,1) - # point2 = Geom::Point3d.new(10,10,10) + # point1 = Geom::Point3d.new(1, 1, 1) + # point2 = Geom::Point3d.new(10, 10, 10) + # # Return false # status = point1 == point2 # - # @param [Geom::Point3d] point2 + # @param [Geom::Point3d, Array(Numeric, Numeric, Numeric)] point # A Point3d object. # # @return [Boolean] true if both points are equal; false if points are not # equal # # @version SketchUp 6.0 - def ==(point2) + def ==(point) end # The [] method is used to retrieve the value of the point at the specified @@ -169,7 +198,7 @@ def ==(point2) # @example # point = Geom::Point3d.new(1, 2, 3) # - # # retrieves the y value of 2 + # # Retrieves the y value of 2 # yvalue = point[1] # # @param [Integer] index @@ -186,7 +215,7 @@ def [](index) # specific index of the value. # # @example - # point = Geom::Point3d.new(1,2,3) + # point = Geom::Point3d.new(1, 2, 3) # yvalue = point[1] = 4 # # @param [Integer] index @@ -206,8 +235,8 @@ def []=(index, new_value) # being cloned. # # @example - # point = Geom::Point3d.new(1,2,3) - # newpoint = point.clone + # point = Geom::Point3d.new(1, 2, 3) + # new_point = point.clone # # @return [Geom::Point3d] the cloned Point3d object # @@ -219,8 +248,8 @@ def clone # point. # # @example - # point1 = Geom::Point3d.new(1,1,1) - # point2 = Geom::Point3d.new(10,10,10) + # point1 = Geom::Point3d.new(1, 1, 1) + # point2 = Geom::Point3d.new(10, 10, 10) # distance = point1.distance(point2) # # @param [Geom::Point3d] point2 @@ -238,9 +267,9 @@ def distance(point2) # See Geom module for how to specify a line. # # @example - # point1 = Geom::Point3d.new(1,1,1) - # line = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)] - # distance = point1.distance_to_line(line) + # point = Geom::Point3d.new(1, 1, 1) + # line = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] + # distance = point.distance_to_line(line) # # @note This function returns a `Float` value, not a `Length`. # @@ -260,6 +289,9 @@ def distance_to_line(line) # See module Geom for how to specify a plane. # # @example + # point = Geom::Point3d.new(10, 10, 10) + # plane = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] + # # The result is 10 # distance = point.distance_to_plane(plane) # # @note This function returns a `Float` value, not a `Length`. @@ -278,14 +310,14 @@ def distance_to_plane(plane) # # @example # # No arguments, creates a point at the origin [0,0,0] - # pt1 = Geom::Point3d.new + # point1 = Geom::Point3d.new # # # Creates a point at x of 100, y of 200, z of 300. - # pt2 = Geom::Point3d.new(100,200,300) + # point2 = Geom::Point3d.new(100, 200, 300) # # # You can also create a point directly by simply assigning the x, y and z # # values to a variable as an array: - # pt3 = [100,200,300] + # point3 = [100, 200, 300] # # @overload initialize # @@ -334,7 +366,7 @@ def initialize(*args) # which writes to the Ruby console. # # @example - # point = Geom::Point3d.new(10,10,10) + # point = Geom::Point3d.new(10, 10, 10) # string = point.inspect # # @return [String] a string point representation @@ -347,9 +379,9 @@ def inspect # point. The length of the vector must not be zero. # # @example - # point1 = Geom::Point3d.new(10,10,10) + # point = Geom::Point3d.new(10, 10, 10) # vector = Geom::Vector3d.new(0, 0, 1) - # point2 = point1.offset(vector) + # new_point = point.offset(vector) # # @param [Geom::Vector3d] vector # A Vector3d object to offset the point by. @@ -370,9 +402,9 @@ def offset(vector, length = vector.length) # Unlike offset, the point itself is modified. # # @example - # point1 = Geom::Point3d.new(10,10,10) - # vector = Geom::Vector3d.new(0,0,1) - # point2 = point1.offset!(vector) + # point = Geom::Point3d.new(10, 10, 10) + # vector = Geom::Vector3d.new(0, 0, 1) + # new_point = point.offset!(vector) # # @param [Geom::Vector3d] vector # A Vector3d object to offset the point by. @@ -392,8 +424,8 @@ def offset!(vector, length = vector.length) # See module Geom for the various ways to specify a line. # # @example - # line = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)] - # point = Geom::Point3d.new(10,10,10) + # line = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] + # point = Geom::Point3d.new(10, 10, 10) # status = point.on_line?(line) # # @param line @@ -410,8 +442,8 @@ def on_line?(line) # See module Geom for the various ways to specify a plane. # # @example - # plane = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)] - # point = Geom::Point3d.new(10,10,10) + # plane = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] + # point = Geom::Point3d.new(10, 10, 10) # status = point.on_plane?(plane) # # @param plane @@ -428,8 +460,8 @@ def on_plane?(plane) # The line may be defined by either a point and a vector or by two points. # # @example - # line = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)] - # point = Geom::Point3d.new(10,10,10) + # line = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] + # point = Geom::Point3d.new(10, 10, 10) # projected_point = point.project_to_line(line) # # @param line @@ -450,8 +482,8 @@ def project_to_line(line) # BY + CZ + D = 0. See Geom for details. # # @example - # plane = [Geom::Point3d.new(0,0,0), Geom::Vector3d.new(0,0,1)] - # point = Geom::Point3d.new(10,10,10) + # plane = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] + # point = Geom::Point3d.new(10, 10, 10) # projected_point = point.project_to_plane(plane) # # @param plane @@ -467,8 +499,8 @@ def project_to_plane(plane) # The {#set!} method is used to set the values of the Point3d. # # @example - # point = Geom::Point3d.new(10,10,10) - # point = point.set!(100,200,300) + # point = Geom::Point3d.new(10, 10, 10) + # point = point.set!(100, 200, 300) # # @overload set!(x, y, z) # @@ -494,14 +526,12 @@ def set!(*args) # The to_a method is used to convert the point to an array of 3 numbers # # @example - # point = Geom::Point3d.new(10,20,30) + # point = Geom::Point3d.new(10, 20, 30) # array = point.to_a + # # The result is [10, 20, 30] + # p array # - # pt = [100,200,300] - # # outputs [100.0,200.0,300.0] - # UI.messagebox(pt.to_a) - # - # @return [Array(Length, Length, Length)] an array of three numbers representing x,y,z of + # @return [Array(Length, Length, Length)] an array of three numbers representing x, y, z of # the Point3d # # @version SketchUp 6.0 @@ -511,8 +541,8 @@ def to_a # The to_s method is used to retrieve a string representation of a point. # # @example - # point = Geom::Point3d.new(10,10,10) - # str = point.to_s + # point = Geom::Point3d.new(10, 10, 10) + # string = point.to_s # # @return [String] the string representation of the Point3d # @@ -524,10 +554,11 @@ def to_s # vector is unchanged by this method. # # @example + # point1 = Geom::Point3d.new(10, 10, 10) + # point2 = Geom::Point3d.new(100, 200, 300) # transform = Geom::Transformation.new(point2) - # point2 = Geom::Point3d.new(100,200,300) - # point1 = Geom::Point3d.new(10,10,10) - # point3 = point1.transform(transform) + # # The result is a Point3d(110, 210, 310) + # transformed_point = point1.transform(transform) # # @param [Geom::Transformation] transform # A Transformation object. @@ -541,9 +572,10 @@ def transform(transform) # Apply a Transformation to a point. The point itself is modified. # # @example + # point1 = Geom::Point3d.new(10, 10, 10) + # point2 = Geom::Point3d.new(100, 200, 300) # transform = Geom::Transformation.new(point2) - # point2 = Geom::Point3d.new(100,200,300) - # point1 = Geom::Point3d.new(10,10,10) + # # The result is a Point3d(110, 210, 310) # point1.transform!(transform) # # @param [Geom::Transformation] transform @@ -558,29 +590,29 @@ def transform!(transform) # The vector_to team method retrieves the vector between points. # # @example - # point2 = Geom::Point3d.new(100,200,300) - # point1 = Geom::Point3d.new(10,10,10) + # point2 = Geom::Point3d.new(100, 200, 300) + # point1 = Geom::Point3d.new(10, 10, 10) # vector = point1.vector_to(point2) # # # Another example... - # pt1 = [1,1,0] - # pt2 = [3,1,0] - # pt1.vector_to(pt2) # returns the vector (2,0,0) - # pt1.vector_to(pt2) # is equivalent to (pt2 - pt1) + # point1 = [1, 1, 0] + # point2 = [3, 1, 0] + # # The result is a Vector3d(2, 0, 0) + # point1.vector_to(point2) # is equivalent to (point2 - point1) # - # @param [Geom::Point3d] point2 + # @param [Geom::Point3d, Array(Numeric, Numeric, Numeric)] point3d # A Point3d object. # # @return [Geom::Vector3d] a Vector object # # @version SketchUp 6.0 - def vector_to(point2) + def vector_to(point3d) end - # The x method retrieves the x value of the 3D point. + # The {#x} method retrieves the x value of the 3D point. # # @example - # point = Geom::Point3d.new(1,2,3) + # point = Geom::Point3d.new(1, 2, 3) # x = point.x # # @return [Length] the x value @@ -589,10 +621,10 @@ def vector_to(point2) def x end - # The x= method is used to set the x value of a 3D point. + # The {#x=} method is used to set the x value of a 3D point. # # @example - # point = Geom::Point3d.new(1,2,3) + # point = Geom::Point3d.new(1, 2, 3) # x = point.x = 2 # # @param [Numeric] value @@ -604,10 +636,10 @@ def x def x=(value) end - # The y method retrieves the y value of the 3D point. + # The {#y} method retrieves the y value of the 3D point. # # @example - # point = Geom::Point3d.new(1,2,3) + # point = Geom::Point3d.new(1, 2, 3) # y = point.y # # @return [Length] the y value @@ -616,10 +648,10 @@ def x=(value) def y end - # The y= method is used to set the y value of a 3D point. + # The {#y=} method is used to set the y value of a 3D point. # # @example - # point = Geom::Point3d.new(1,2,3) + # point = Geom::Point3d.new(1, 2, 3) # y = point.y = 2 # # @param [Numeric] value @@ -631,11 +663,11 @@ def y def y=(value) end - # The z method retrieves the z value of the 3D point. + # The {#z} method retrieves the z value of the 3D point. # # @example - # point = Geom::Point3d.new(1,2,3) - # z = point.x + # point = Geom::Point3d.new(1, 2, 3) + # z = point.z # # @return [Length] the z value # @@ -643,10 +675,10 @@ def y=(value) def z end - # The z= method is used to set the z value of a 3D point. + # The {#z=} method is used to set the z value of a 3D point. # # @example - # point = Geom::Point3d.new(1,2,3) + # point = Geom::Point3d.new(1, 2, 3) # z = point.z = 2 # # @param [Numeric] value diff --git a/lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb b/lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb index 5762a59..c91edd7 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {#Geom::PolygonMesh} class contains methods to create polygon mesh @@ -15,7 +15,7 @@ # # @example # entities = Sketchup.active_model.active_entities -# face = entities.grep(Sketchup::Face).first +# face = entities.add_face([1, 1, 1], [1, 2, 1], [2, 2, 1]) # # mesh = face.mesh # @@ -80,7 +80,6 @@ def add_point(point) # Adds a polygon from a list of the mesh's vertex indices. # @example # mesh = Geom::PolygonMesh.new - # # add points to mesh... # mesh.add_point(Geom::Point3d.new(0, 0, 0)) # mesh.add_point(Geom::Point3d.new(1, 0, 0)) # mesh.add_point(Geom::Point3d.new(1, 1, 0)) @@ -95,7 +94,6 @@ def add_point(point) # Adds a polygon from an Array of the mesh's vertex indices. # @example # mesh = Geom::PolygonMesh.new - # # add points to mesh... # mesh.add_point(Geom::Point3d.new(0, 0, 0)) # mesh.add_point(Geom::Point3d.new(1, 0, 0)) # mesh.add_point(Geom::Point3d.new(1, 1, 0)) @@ -143,7 +141,7 @@ def add_polygon(*args) # mesh = Geom::PolygonMesh.new # point = Geom::Point3d.new(0, 1, 2) # mesh.add_point(point) - # num = mesh.count_points + # number_points = mesh.count_points # # @return [Integer] the number of points in a mesh # @@ -159,7 +157,7 @@ def count_points # point2 = Geom::Point3d.new(1, 0, 2) # point3 = Geom::Point3d.new(2, 0, 1) # mesh.add_polygon(point1, point2, point3) - # nump = mesh.count_polygons + # number_polygons = mesh.count_polygons # # @return [Integer] the number of polygons in the mesh # @@ -188,15 +186,15 @@ def count_polygons # # @return [Geom::PolygonMesh] # - # @overload initialize(numpts) + # @overload initialize(number_points) # - # @param [Integer] numpts How many points will be in the mesh. + # @param [Integer] number_points How many points will be in the mesh. # @return [Geom::PolygonMesh] # - # @overload initialize(numpts, numpolys) + # @overload initialize(number_points, number_polygons) # - # @param [Integer] numpts How many points will be in the mesh. - # @param [Integer] numpolys How many polygons will be in the mesh. + # @param [Integer] number_points How many points will be in the mesh. + # @param [Integer] number_polygons How many polygons will be in the mesh. # @return [Geom::PolygonMesh] # # @raise [RangeError] If number of points or polygons are negative numbers. @@ -210,8 +208,13 @@ def initialize(*args) # {Sketchup::Face#mesh} with the +PolygonMeshNormals+ flag. # # @example + # model = Sketchup.active_model + # entity = model.active_entities + # face = entity.add_face([1, 1, 1], [2, 2, 1], [2, 1, 1]) + # # flags = 4 # PolygonMeshNormals # mesh = face.mesh(flags) + # # The result is a Vector3d(0, 0, -1) # normal = mesh.normal_at(1) # # @note Index starts at 1. @@ -310,7 +313,7 @@ def points # @param [Integer] index # The index of the desired polygon. # - # @return [Array, nil] + # @return [Array, nil] # # @version SketchUp 6.0 def polygon_at(index) @@ -346,7 +349,14 @@ def polygon_points_at(index) # indicates that the edge from +1+ to +2+ is hidden. # # @example - # polygons = polygonmesh.polygons + # mesh = Geom::PolygonMesh.new + # mesh.add_point([0, 0, 0]) + # mesh.add_point([1, 0, 0]) + # mesh.add_point([1, 1, 0]) + # + # mesh.add_polygon(1, 2, 3) + # mesh.add_polygon(-1, 3, 2) + # polygons = mesh.polygons # # @return [Array>] # @@ -395,26 +405,25 @@ def set_point(index, point) # # @example # mesh = Geom::PolygonMesh.new(4) - # # Create points for a triangle. # point1 = Geom::Point3d.new(0, 0, 0) # point2 = Geom::Point3d.new(9, 0, 0) # point3 = Geom::Point3d.new(9, 9, 0) # point4 = Geom::Point3d.new(0, 9, 0) - # # Create UV mapping to tile 2x cross triangle. - # uv1 = Geom::Point3d.new(0, 0, 0) - # uv2 = Geom::Point3d.new(2, 0, 0) - # uv3 = Geom::Point3d.new(2, 2, 0) - # uv4 = Geom::Point3d.new(0, 2, 0) - # # Add points and UV data to mesh. + # + # uv_point1 = Geom::Point3d.new(0, 0, 0) + # uv_point2 = Geom::Point3d.new(2, 0, 0) + # uv_point3 = Geom::Point3d.new(2, 2, 0) + # uv_point4 = Geom::Point3d.new(0, 2, 0) + # # index1 = mesh.add_point(point1) # index2 = mesh.add_point(point2) # index3 = mesh.add_point(point3) # index4 = mesh.add_point(point4) - # mesh.set_uv(index1, uv1, true) - # mesh.set_uv(index2, uv2, true) - # mesh.set_uv(index3, uv3, true) - # mesh.set_uv(index4, uv4, true) - # # Add polygons. + # mesh.set_uv(index1, uv_point1, true) + # mesh.set_uv(index2, uv_point2, true) + # mesh.set_uv(index3, uv_point3, true) + # mesh.set_uv(index4, uv_point4, true) + # # mesh.add_polygon(index1, index2, index3) # mesh.add_polygon(index1, index3, index4) # @@ -442,11 +451,12 @@ def set_uv(index, point, front) # # @example # point1 = Geom::Point3d.new(100, 200, 300) - # tr = Geom::Transformation.new(point1) + # transformation = Geom::Transformation.new(point1) # mesh = Geom::PolygonMesh.new # point2 = Geom::Point3d.new(0, 1, 2) # mesh.add_point(point2) - # mesh.transform!(tr) + # # The PolygonMesh contains a Point3d(100, 201, 302) + # mesh.transform!(transformation) # # @param [Geom::Transformation] transformation # @@ -471,7 +481,12 @@ def transform!(transformation) # referred to as UV mapping. # # @example - # point = mesh.uv_at(1, true) + # mesh = Geom::PolygonMesh.new + # index = mesh.add_point([2, 2, 2]) + # uv_point = Geom::Point3d.new(1, 1, 0) + # + # mesh.set_uv(index, uv_point, true) + # point = mesh.uv_at(index, true) # # @note Index starts at 1. # @@ -494,9 +509,20 @@ def uv_at(index, front) # mesh. # # @example - # # Get a mesh with front and back UVs. + # model = Sketchup.active_model + # entity = model.active_entities + # + # face = entity.add_face([1, 1, 1], [1, 3, 1], [3, 3, 1]) # mesh = face.mesh(1 | 2) - # uvs = mesh.uvs(true) + # + # uv_point1 = Geom::Point3d.new(0, 0, 0) + # uv_point2 = Geom::Point3d.new(1, 0, 0) + # uv_point3 = Geom::Point3d.new(1, 1, 0) + # mesh.set_uv(1, uv_point1, true) + # mesh.set_uv(2, uv_point2, true) + # mesh.set_uv(3, uv_point3, true) + # + # uv_points = mesh.uvs(true) # # @param [Boolean] front # diff --git a/lib/sketchup-api-stubs/stubs/Geom/Transformation.rb b/lib/sketchup-api-stubs/stubs/Geom/Transformation.rb index f7299ec..0e9ff77 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/Transformation.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/Transformation.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Transformations are a standard construct in the 3D world for representing @@ -24,7 +24,7 @@ class Geom::Transformation # # Creates a transformation that "flips" the axes from XYZ to XZY. Something # # one often need for importers/exporters when dealing with applications # # that threat Y as "up". - # tr = Geom::Transformation.axes(ORIGIN, X_AXIS, Z_AXIS, Y_AXIS.reverse) + # transformation = Geom::Transformation.axes(ORIGIN, X_AXIS, Z_AXIS, Y_AXIS.reverse) # # @overload axes(origin, xaxis, yaxis, zaxis) # @@ -52,31 +52,31 @@ def self.axes(*args) # The {.interpolate} method is used to create a new transformation that is the # result of interpolating between two other transformations. # - # Parameter is a weight (between `0.0` and `1.0`) that identifies whether to favor - # `transformation1` or `transformation2`. + # Parameter weight is a value (between 0.0 and 1.0) that represents the percentage given to + # `transformation1` and `transformation2`. # # @example # origin = Geom::Point3d.new(0, 0, 0) - # x = Geom::Vector3d.new(0, 1, 0) - # y = Geom::Vector3d.new(1, 0, 0) - # z = Geom::Vector3d.new(0, 0, 1) + # xaxis = Geom::Vector3d.new(0, 1, 0) + # yaxis = Geom::Vector3d.new(1, 0, 0) + # zaxis = Geom::Vector3d.new(0, 0, 1) # point = Geom::Point3d.new(10, 20, 30) - # t1 = Geom::Transformation.new(point) - # t2 = Geom::Transformation.axes(origin, x, y, z) - # # This produce a transformation that is a mix of 75% t1 and 25% t2. - # t3 = Geom::Transformation.interpolate(t1, t2, 0.25) + # transformation1 = Geom::Transformation.new(point) + # transformation2 = Geom::Transformation.axes(origin, xaxis, yaxis, zaxis) + # # This produce a transformation that is a mix of 75% transformation1 and 25% transformation2. + # new_transformation = Geom::Transformation.interpolate(transformation1, transformation2, 0.25) # - # @param [Geom::Transformation] transform1 + # @param [Geom::Transformation] transformation1 # - # @param [Geom::Transformation] transform2 + # @param [Geom::Transformation] transformation2 # # @param [Float] weight - # A value between 0.0 and 1.0 (see comments). + # A value between 0.0 and 1.0. # # @return [Geom::Transformation] # # @version SketchUp 6.0 - def self.interpolate(transform1, transform2, weight) + def self.interpolate(transformation1, transformation2, weight) end # The {.rotation} method is used to create a transformation that does rotation @@ -108,7 +108,7 @@ def self.rotation(point, vector, angle) # @example # point = Geom::Point3d.new(20, 30, 0) # scale = 10 - # tr = Geom::Transformation.scaling(point, scale) + # transformation = Geom::Transformation.scaling(point, scale) # # @overload scaling(scale) # @@ -154,7 +154,7 @@ def self.scaling(*args) # # @example # vector = Geom::Vector3d.new(0, 1, 0) - # tr = Geom::Transformation.translation(vector) + # transformation = Geom::Transformation.translation(vector) # # @overload translation(vector) # @@ -177,9 +177,9 @@ def self.translation(arg) # @example # point1 = Geom::Point3d.new(10, 20, 30) # point2 = Geom::Point3d.new(2, 2, 2) - # tr = Geom::Transformation.new(point1) - # # Returns Point3d(12, 22, 32) - # point3 = tr * point2 + # transformation = Geom::Transformation.new(point1) + # # The result is a Point3d(12, 22, 32) + # new_point = transformation * point2 # # @overload *(point) # @@ -219,8 +219,8 @@ def *(arg) # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr1 = Geom::Transformation.new(point) - # tr2 = tr1.clone + # transformation = Geom::Transformation.new(point) + # new_transformation = transformation.clone # # @return [Geom::Transformation] # @@ -233,22 +233,22 @@ def clone # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point) - # # Returns false. - # status = tr.identity? + # transformation = Geom::Transformation.new(point) + # # Returns false + # status = transformation.identity? # # @example - # tr = Geom::Transformation.new(ORIGIN) - # # Returns false. - # status = tr.identity? + # transformation = Geom::Transformation.new(ORIGIN) + # # Returns true + # status = transformation.identity? # # @example - # tr = Geom::Transformation.new - # # Returns true. - # status = tr.identity? + # transformation = Geom::Transformation.new + # # Returns true + # status = transformation.identity? # # @example - # # Returns true. + # # Returns true # status = IDENTITY.identity? # # @note As of SketchUp 2018, this now looks at the data to determine if the @@ -267,7 +267,18 @@ def identity? # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point) + # transformation = Geom::Transformation.new(point) + # + # @example + # origin = Geom::Point3d.new(10, 10, 10) + # zaxis = Geom::Vector3d.new(1, 2, 3) + # transformation = Geom::Transformation.new(origin, zaxis) + # + # @example + # origin = Geom::Point3d.new(1, 1, 1) + # axis = Geom::Vector3d.new(1, 0, 0) + # angle = 45.degrees # Return 45 degrees in radians. + # transformation = Geom::Transformation.new(origin, axis, angle) # # @overload initialize # @@ -306,8 +317,8 @@ def identity? # # @overload initialize(origin, zaxis) # - # Creates a Transformation where origin is the new origin, and zaxis is the - # z axis. The x and y axes are determined using an arbitrary axis rule. + # Creates a Transformation where origin is the new origin, and z axis is the + # new z axis. The x and y axes are determined using an arbitrary axis rule. # @param [Geom::Point3d] origin # @param [Geom::Vector3d] zaxis # @return [Geom::Transformation] @@ -345,8 +356,14 @@ def initialize(*args) # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr1 = Geom::Transformation.new(point) - # tr2 = tr1.inverse + # transformation = Geom::Transformation.new(point) + # new_transformation = transformation.inverse + # + # @note As of SketchUp 2026, this will raise an error if the + # {Geom::Transformation} is not invertible. Prior to 2026 this would silently attempt + # to invert the transformation possibly returning in an invalid transformation. + # + # @raise ArgumentError if the {Geom::Transformation} is not invertible (as of Sketchup 2026) # # @return [Geom::Transformation] # @@ -358,8 +375,14 @@ def inverse # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point) - # tr.invert! + # transformation = Geom::Transformation.new(point) + # new_transformation = transformation.invert! + # + # @note As of SketchUp 2026, this will raise an error if the + # {Geom::Transformation} is not invertible. Prior to 2026 this would silently attempt + # to invert the transformation possibly creating in an invalid transformation. + # + # @raise ArgumentError if the {Geom::Transformation} is not invertible (as of Sketchup 2026) # # @return [Geom::Transformation] # @@ -370,9 +393,9 @@ def invert! # The {#origin} method retrieves the origin of a rigid transformation. # # @example - # point1 = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point1) - # point2 = tr.origin + # point = Geom::Point3d.new(10, 20, 30) + # transformation = Geom::Transformation.new(point) + # new_point = transformation.origin # # @return [Geom::Point3d] the origin of the transformation. # @@ -386,9 +409,9 @@ def origin # # @example # point1 = Geom::Point3d.new(10, 20, 30) - # tr1 = Geom::Transformation.new(point) + # transformation = Geom::Transformation.new(point1) # point2 = Geom::Point3d.new(60, 40, 70) - # tr1.set!(point2) + # transformation.set!(point2) # # @overload set!(transformation) # @@ -424,9 +447,10 @@ def set!(arg) # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point) + # transformation = Geom::Transformation.new(point) # # This splits the 16 items into a string of 4x4 elements for easier reading. - # str4x4 = tr.to_a.each_slice(4).inject { |str, row| "#{str}\r\n#{row}" } + # matrix = transformation.to_a.each_slice(4).inject { |str, row|"#{str}\r\n#{row}"} + # puts matrix # # @return [Array] # @@ -438,8 +462,8 @@ def to_a # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point) - # x = tr.xaxis + # transformation = Geom::Transformation.new(point) + # x = transformation.xaxis # # @return [Geom::Vector3d] # @@ -451,8 +475,8 @@ def xaxis # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point) - # x = tr.yaxis + # transformation = Geom::Transformation.new(point) + # y = transformation.yaxis # # @return [Geom::Vector3d] # @@ -464,8 +488,8 @@ def yaxis # # @example # point = Geom::Point3d.new(10, 20, 30) - # tr = Geom::Transformation.new(point) - # x = tr.zaxis + # transformation = Geom::Transformation.new(point) + # z = transformation.zaxis # # @return [Geom::Vector3d] # diff --git a/lib/sketchup-api-stubs/stubs/Geom/Transformation2d.rb b/lib/sketchup-api-stubs/stubs/Geom/Transformation2d.rb index a60e094..be6d71e 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/Transformation2d.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/Transformation2d.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # @@ -29,9 +29,9 @@ def self.rotation(point, angle) # The {.scaling} method is used to create a transformation that does scaling. # # @example - # point = Geom::Point3d.new(20, 30, 0) + # point = Geom::Point2d.new(20, 30) # scale = 10 - # tr = Geom::Transformation2d.scaling(point, scale) + # transformation = Geom::Transformation2d.scaling(point, scale) # # @overload scaling(scale) # @@ -70,7 +70,7 @@ def self.scaling(*args) # # @example # vector = Geom::Vector2d.new(0, 1) - # tr = Geom::Transformation2d.translation(vector) + # transformation = Geom::Transformation2d.translation(vector) # # @overload translation(vector) # @@ -93,9 +93,9 @@ def self.translation(vector) # @example # point1 = Geom::Point2d.new(5, 10) # point2 = Geom::Point2d.new(2, 2) - # tr = Geom::Transformation2d.new(point1) - # # Returns Point2d(7, 12) - # point3 = tr * point2 + # transformation = Geom::Transformation2d.translation(point1) + # # The result is a Point2d(7, 12) + # new_point = transformation * point2 # # @overload *(point) # @@ -114,8 +114,8 @@ def self.translation(vector) # # @overload *(point) # - # @param [Array] point - # @return [Array] + # @param [Array(Float, Float)] point + # @return [Array(Float, Float)] # # @version LayOut 2019 def *(arg) @@ -125,8 +125,10 @@ def *(arg) # This checks whether the values of the transformations are the same. # # @example - # tr = Geom::Transformation2d.new({1.0, 0.0, 0.0, 1.0, 1.0, 1.0}) - # tr == tr.clone + # transformation1 = Geom::Transformation2d.new([1.0, 0.0, 0.0, 1.0, 1.0, 1.0]) + # transformation2 = Geom::Transformation2d.translation([1, 1]) + # # Returns true + # transformation1 == transformation2 # # @param [Geom::Transformation2d] other # @@ -139,8 +141,8 @@ def ==(other) # The {#clone} method creates a copy of the {Geom::Transformation2d}. # # @example - # tr1 = Geom::Transformation2d.new - # tr2 = tr1.clone + # transformation = Geom::Transformation2d.new + # new_transformation = transformation.clone # # @return [Geom::Transformation2d] # @@ -152,18 +154,18 @@ def clone # {IDENTITY_2D} transform. # # @example - # array = {1.0, 0.0, 0.0, 1.0, 1.0, 0.0} - # tr = Geom::Transformation2d.new(array) - # # Returns false. - # status = tr.identity? + # array = [1.0, 0.0, 0.0, 1.0, 1.0, 0.0] + # transformation = Geom::Transformation2d.new(array) + # # Returns false + # status = transformation.identity? # # @example - # tr = Geom::Transformation2d.new - # # Returns true. - # status = tr.identity? + # transformation = Geom::Transformation2d.new + # # Returns true + # status = transformation.identity? # # @example - # # Returns true. + # # Returns true # status = IDENTITY_2D.identity? # # @return [Boolean] +true+ if the transform is the identity @@ -177,7 +179,9 @@ def identity? # of {Geom::Transformation2d}. # # @example - # tr = Geom::Transformation2d.new({1.0, 0.0, 0.0, 1.0, 1.0, 1.0}) + # transformation1 = Geom::Transformation2d.new + # + # transformation2 = Geom::Transformation2d.new([1.0, 0.0, 0.0, 1.0, 1.0, 1.0]) # # @overload initialize # @@ -203,8 +207,8 @@ def initialize(*args) # # @example # point = Geom::Point2d.new(5, 10) - # tr1 = Geom::Transformation2d.new(point) - # tr2 = tr1.inverse + # transformation = Geom::Transformation2d.translation(point) + # new_transformation = transformation.inverse # # @return [Geom::Transformation2d] # @@ -216,8 +220,8 @@ def inverse # # @example # point = Geom::Point2d.new(5, 10) - # tr = Geom::Transformation2d.new(point) - # tr.invert! + # transformation = Geom::Transformation2d.translation(point) + # transformation.invert! # # @return [Geom::Transformation2d] # @@ -229,9 +233,9 @@ def invert! # The argument is anything that can be converted into a {Geom::Transformation2d}. # # @example - # tr1 = Geom::Transformation2d.new - # array = {2.0, 0.0, 0.0, 2.0, 0.0, 0.0} - # tr1.set!(array) + # transformation = Geom::Transformation2d.new + # matrix = [2.0, 0.0, 0.0, 2.0, 0.0, 0.0] + # transformation.set!(matrix) # # @overload set!(transformation) # @@ -251,8 +255,8 @@ def set!(arg) # define the Transformation2d. # # @example - # tr = Geom::Transformation2d.new - # tr.to_a.each_slice(2) {|a| p a} + # transformation = Geom::Transformation2d.new + # transformation.to_a.each_slice(2) {|a| p a} # # @return [Array] an array of 6 elements # diff --git a/lib/sketchup-api-stubs/stubs/Geom/UTM.rb b/lib/sketchup-api-stubs/stubs/Geom/UTM.rb index 2590b25..e1c3bbc 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/UTM.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/UTM.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The UTM class lets you work with UTM map coordinates. @@ -16,11 +16,10 @@ class Geom::UTM # instead of calling this method. # # @example - # # Create a copy of an existing UTM object. - # utm = Geom::UTM.new(utm2) + # utm1 = Geom::UTM.new # # # Create a new UTM object from scratch. - # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) + # utm2 = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) # # @overload initialize(zone_number, zone_letter, x, y) # @@ -35,7 +34,7 @@ class Geom::UTM # # @overload initialize(array) # - # @param [Array(Integer, String, Float, Float)] An array containing the zone + # @param [Array(Integer, String, Float, Float)] array contains the zone # number, zone letter, x and y positions. # # @return [Geom::UTM] @@ -49,9 +48,8 @@ def initialize(*args) # coordinate. # # @example - # # Create a new UTM object from scratch. # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) - # a = utm.to_a + # array = utm.to_a # # @return [Array(Integer, String, Float, Float)] # @@ -63,9 +61,8 @@ def to_a # and longitude. See the LatLong class for more information. # # @example - # # Create a new UTM object from scratch. # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) - # ll = utm.to_latlong + # latlong = utm.to_latlong # # @return [Geom::LatLong] # @@ -76,7 +73,6 @@ def to_latlong # The {#to_s} method is used to retrieve a string representation of a UTM. # # @example - # # Create a new UTM object from scratch. # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) # string = utm.to_s # @@ -89,7 +85,6 @@ def to_s # The {#x} method returns the UTM x coordinate. # # @example - # # Create a new UTM object from scratch. # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) # x = utm.x # @@ -102,7 +97,6 @@ def x # The {#y} method returns the UTM y coordinate. # # @example - # # Create a new UTM object from scratch. # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) # y = utm.y # @@ -115,9 +109,8 @@ def y # The {#zone_letter} method returns the UTM zone letter. # # @example - # # Create a new UTM object from scratch. # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) - # zl = utm.zone_letter + # zone_letter = utm.zone_letter # # @return [String] # @@ -128,9 +121,8 @@ def zone_letter # The {#zone_number} method returns the UTM zone number. # # @example - # # Create a new UTM object from scratch. # utm = Geom::UTM.new(13, "T", 475849.37521, 4429682.73749) - # zn = utm.zone_number + # zone_number = utm.zone_number # # @return [Integer] # diff --git a/lib/sketchup-api-stubs/stubs/Geom/Vector2d.rb b/lib/sketchup-api-stubs/stubs/Geom/Vector2d.rb index 1227e07..0cc04b0 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/Vector2d.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/Vector2d.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Geom::Vector2d} class represents vectors in a 2 dimensional space. @@ -10,19 +10,23 @@ class Geom::Vector2d # Instance Methods - # The {#%} method returns the dot product between two {Geom::Vector2d}. This is - # an alias of the dot method. + # The {#%} method is used to compute the dot product between two vectors. + # + # This is an alias of the {#dot} method. # # @example - # vector = Geom::Vector2d.new(0, 2) - # vector2 = Geom::Vector2d.new(1, 0) - # d2 = vector % vector2 + # vector1 = Geom::Vector2d.new(4, 5) + # vector2 = Geom::Vector2d.new(7, 1) + # # The result is 33 + # dot = vector1 % vector2 # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # - # @return The dot product of the vectors + # @return [Float] # - # @version LayOut 2018 + # @see #dot + # + # @version SketchUp 6.0 def %(vector) end @@ -30,13 +34,16 @@ def %(vector) # is an alias of the cross method. # # @example - # vector = Geom::Vector2d.new(1, 0) - # vector2 = Geom::Vector2d.new(0, 1) - # cross = vector * vector + # vector1 = Geom::Vector2d.new(2, 5) + # vector2 = Geom::Vector2d.new(5, 1) + # # The result is -23 + # cross = vector1 * vector2 # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # - # @return [Geom::Vector2d] + # @return [Float] + # + # @see #cross # # @version LayOut 2018 def *(vector) @@ -45,11 +52,11 @@ def *(vector) # The {#+} method adds a {Geom::Vector2d} to this one. # # @example - # vector = Geom::Vector2d.new(0, 2) + # vector1 = Geom::Vector2d.new(0, 2) # vector2 = Geom::Vector2d.new(1, 0) - # new_vector = vector + vector2 + # new_vector = vector1 + vector2 # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # # @return [Geom::Vector2d] # @@ -60,11 +67,11 @@ def +(vector) # The {#-} method subtracts a {Geom::Vector2d} from this one. # # @example - # vector = Geom::Vector2d.new(0, 2) + # vector1 = Geom::Vector2d.new(0, 2) # vector2 = Geom::Vector2d.new(1, 0) - # new_vector = vector - vector2 + # new_vector = vector1 - vector2 # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # # @return [Geom::Vector2d] # @@ -76,12 +83,12 @@ def -(vector) # tolerance. # # @example - # vector = Geom::Vector2d.new(1, 0) - # vector2 = Geom::Vector2d.new(0,1) + # vector1 = Geom::Vector2d.new(1, 0) + # vector2 = Geom::Vector2d.new(0, 1) # # Returns false - # status = vector == vector2 + # status = vector1 == vector2 # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # # @return [Boolean] # @@ -94,13 +101,13 @@ def ==(vector) # # @example # vector = Geom::Vector2d.new(1, 2) - # # retrieves the y value of 2 + # # Retrieves the y value of 2 # yvalue = vector[1] # # @param [Integer] index # The index into an array of two coordinates. # - # @return [Numeric] The value for the x or y coordinate. + # @return [Float] The value for the x or y coordinate. # # @version LayOut 2018 def [](index) @@ -110,17 +117,17 @@ def [](index) # specific index of the value. # # @example - # point = Geom::Vector2d.new(1,2) - # point[1] = 4 + # vector = Geom::Vector2d.new(1, 2) + # vector[1] = 4 # - # @param [Numeric] index + # @param [Integer] index # The index for a specific x or y value in the # {Geom::Vector2d} to set # - # @param [Numeric] value + # @param [Float] value # The value to set for x or y # - # @return [Numeric] The new x or y value if successful + # @return [Float] The new x or y value if successful # # @version LayOut 2018 def []=(index, value) @@ -130,14 +137,14 @@ def []=(index, value) # the {Geom::Vector2d} and another {Geom::Vector2d}. # # @example - # vector = Geom::Vector2d.new(1, 0) + # vector1 = Geom::Vector2d.new(1, 0) # vector2 = Geom::Vector2d.new(-1, 0) - # # returns PI - # angle = vector.angle_between(vector2) + # # Returns PI + # angle = vector1.angle_between(vector2) # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # - # @return [Numeric] The angle (in radians) + # @return [Float] The angle (in radians) # # @version LayOut 2018 def angle_between(vector) @@ -148,7 +155,7 @@ def angle_between(vector) # # @example # vector = Geom::Vector2d.new(1, 0) - # vector2 = vector.clone + # new_vector = vector.clone # # @return [Geom::Vector2d] # @@ -156,35 +163,43 @@ def angle_between(vector) def clone end - # The {#*} method returns the cross product between two {Geom::Vector2d}. This - # is an alias of the cross method. + # The {#cross} method returns the cross product between two {Geom::Vector2d}s. + # + # The cross product, also called the vector product, is an operation on two + # vectors. The cross product of two vectors produces a third vector which is + # perpendicular to the plane in which the first two lie. # # @example - # vector = Geom::Vector2d.new(1, 0) - # vector2 = Geom::Vector2d.new(0, 1) - # cross = vector * vector + # vector1 = Geom::Vector2d.new(3, 3) + # vector2 = Geom::Vector2d.new(2, 5) + # # The result is 9 + # cross = vector1.cross(vector2) # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # - # @return [Geom::Vector2d] + # @return [Float] + # + # @see #* # # @version LayOut 2018 def cross(vector) end - # The {#%} method returns the dot product between two {Geom::Vector2d}. This is - # an alias of the dot method. + # The {#dot} method is used to compute the dot product between two vectors. # # @example - # vector = Geom::Vector2d.new(0, 2) - # vector2 = Geom::Vector2d.new(1, 0) - # d2 = vector % vector2 + # vector1 = Geom::Vector2d.new(4, 1) + # # The result is 14 + # vector2 = Geom::Vector2d.new(3, 2) + # dot = vector1.dot(vector2) # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # - # @return The dot product of the vectors + # @return [Float] # - # @version LayOut 2018 + # @see #% + # + # @version SketchUp 6.0 def dot(vector) end @@ -192,7 +207,9 @@ def dot(vector) # # @example # # A vector that runs along the X axis. - # vector = Geom::Vector2d.new(1, 0) + # vector1 = Geom::Vector2d.new(1, 0) + # + # vector2 = Geom::Vector2d.new([5, 6]) # # @overload initialize # @@ -200,13 +217,13 @@ def dot(vector) # # @overload initialize(x, y) # - # @param [Numeric] x The length in the x direction - # @param [Numeric] y The length in the y direction + # @param [Float] x The length in the x direction + # @param [Float] y The length in the y direction # @return [Geom::Vector2d] # # @overload initialize(vector) # - # @param [Geom::Vector2d, Array(Numeric, Numeric)] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # @return [Geom::Vector2d] # # @version LayOut 2018 @@ -216,8 +233,8 @@ def initialize(*args) # The {#inspect} method formats the {Geom::Vector2d} as a string. # # @example - # point = Geom::Point2d.new(1, 2) - # string = point.inspect + # vector = Geom::Vector2d.new(1, 2) + # string = vector.inspect # # @return [String] the string representation of the {Geom::Vector2d} # @@ -229,8 +246,8 @@ def inspect # # @example # vector = Geom::Vector2d.new(0, 4) - # # returns 4 - # l = vector.length + # # The result is 4 + # length = vector.length # # @return [Length] The length of the {Geom::Vector2d} # @@ -243,13 +260,12 @@ def length # # @example # vector = Geom::Vector2d.new(0, 4) - # l = vector.length # vector.length = 2 # - # @param [Numeric] length + # @param [Float] length # The new length for the {Geom::Vector2d} # - # @return [Numeric] The new length + # @return [Length] The new length # # @version LayOut 2018 def length=(length) @@ -260,8 +276,8 @@ def length=(length) # # @example # vector = Geom::Vector2d.new(0, 4) - # # returns a new Vector2d(0, 1) - # vector2 = vector.normalize + # # The result is a Vector2d(0, 1) + # new_vector = vector.normalize # # @return [Geom::Vector2d] # @@ -270,27 +286,27 @@ def normalize end # The {#normalize!} method converts a {Geom::Vector2d} vector into a unit - # vector. Another way to do this is vector.length = 1 + # vector. Another way to do this is +vector.length = 1.0+ # # @example # vector = Geom::Vector2d.new(0, 4) - # # modifies vector to be the Vector2d(0, 1) + # # Modifies vector to be the Vector2d(0, 1) # vector.normalize! # # @version LayOut 2018 def normalize! end - # The {#parallel?} method determines if the {Geom::Vector2d} is parallel to - # another {Geom::Vector2d} to within tolerance. + # The {#parallel?} method determines if two {Geom::Vector2d}s are parallel within a + # tolerance. Two vectors are parallel if there exists a scalar multiple between them. # # @example - # vector = Geom::Vector2d.new(0, 1) - # vector2 = Geom::Vector2d.new(1, 2) - # # returns true - # status = vector.parallel?(vector2) + # vector1 = Geom::Vector2d.new(0, 1) + # vector2 = Geom::Vector2d.new(0, -9) + # # Returns true + # status = vector1.parallel?(vector2) # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # # @return [Boolean] # @@ -298,16 +314,17 @@ def normalize! def parallel?(vector) end - # The {#perpendicular?} method determines if the {Geom::Vector2d} is - # perpendicular to another {Geom::Vector2d} to within tolerance. + # The {#perpendicular?} method determines if two {Geom::Vector2d}s are + # perpendicular within a tolerance. Two vectors are considered + # perpendicular if their dot product is zero. # # @example - # vector = Geom::Vector2d.new(0, 1) - # vector2 = Geom::Vector2d.new(1, 2) - # # returns false - # status = vector.perpendicular?(vector2) + # vector1 = Geom::Vector2d.new(0, 5) + # vector2 = Geom::Vector2d.new(1, 0) + # # Returns true + # status = vector1.perpendicular?(vector2) # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # # @return [Boolean] # @@ -320,8 +337,8 @@ def perpendicular?(vector) # # @example # vector = Geom::Vector2d.new(1, 2) - # # returns the Vector2d(-1, -2) - # vector2 = vector.reverse + # # The result is a Vector2d(-1, -2) + # new_vector = vector.reverse # # @return [Geom::Vector2d] # @@ -333,7 +350,7 @@ def reverse # # @example # vector = Geom::Vector2d.new(1, 2) - # # modifies vector to be the Vector2d(-1, -2) + # # Modifies vector to be the Vector2d(-1, -2) # vector.reverse! # # @version LayOut 2018 @@ -344,12 +361,17 @@ def reverse! # to and in the same direction as another {Geom::Vector2d} within tolerance. # # @example - # vector = Geom::Vector2d.new(0, 1) + # vector1 = Geom::Vector2d.new(0, 1) # vector2 = Geom::Vector2d.new(1, 2) - # # returns true - # status = vector.sime_direction?(vector2) + # # Returns false + # status = vector1.same_direction?(vector2) + # + # @example + # vector = Geom::Vector2d.new(0, 2) + # # Returns true + # status = vector.same_direction?([0, 4]) # - # @param [Geom::Vector2d] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # # @return [Boolean] # @@ -365,13 +387,13 @@ def same_direction?(vector) # # @overload set!(vector) # - # @param [Geom::Vector2d, Array(Numeric, Numeric)] vector + # @param [Geom::Vector2d, Array(Float, Float)] vector # @return [Geom::Vector2d] # # @overload set!(x, y) # - # @param [Numeric] x - # @param [Numeric] y + # @param [Float] x + # @param [Float] y # @return [Geom::Vector2d] # # @version LayOut 2018 @@ -382,9 +404,10 @@ def set!(*args) # Array. # # @example - # a = vector.to_a + # vector = Geom::Vector2d.new(1, 2) + # array = vector.to_a # - # @return [Array(Numeric, Numeric)] + # @return [Array(Float, Float)] # # @version LayOut 2018 def to_a @@ -393,8 +416,8 @@ def to_a # The {#to_s} method returns a string representation of the {Geom::Vector2d}. # # @example - # point = Geom::Vector2d.new(1, 2) - # str = point.to_s + # vector = Geom::Vector2d.new(1, 2) + # string = vector.to_s # # @return [String] the string representation of the {Geom::Vector2d} # @@ -406,10 +429,11 @@ def to_s # vector. The original vector is unchanged by this method. # # @example - # vector = Geom::Vector2d.new(4, 5) - # transformation = Geom::Transformation2d.new([1, 0, 0, 1, 2, 3]) - # # vector2 will be (6, 8) - # vector2 = vector.transform(transformation) + # vector = Geom::Vector2d.new(3, 2) + # point = Geom::Point2d.new(0, 1) + # transformation = Geom::Transformation2d.scaling(point, 2) + # # The result is a Vector2d(6, 4) + # new_vector = vector.transform(transformation) # # @param [Geom::Transformation2d] transform # A transformation object to apply to the vector. @@ -425,8 +449,9 @@ def transform(transform) # # @example # vector = Geom::Vector2d.new(4, 5) - # transformation = Geom::Transformation2d.new([1, 0, 0, 1, 2, 3]) - # # vector will be (6, 8) + # point = Geom::Point2d.new(8, 9) + # transformation = Geom::Transformation2d.scaling(point, 3) + # # The result is a Vector2d(12, 15) # vector.transform!(transformation) # # @param [Geom::Transformation2d] transform @@ -443,8 +468,8 @@ def transform!(transform) # # @example # vector = Geom::Vector2d.new(1, 0) - # # returns true - # status = vector.unit_vector + # # Returns true + # status = vector.unit_vector? # # @return [Boolean] # @@ -457,7 +482,7 @@ def unit_vector? # # @example # vector = Geom::Vector2d.new(0, 4) - # status = vector.valid + # status = vector.valid? # # @return [Boolean] # @@ -471,7 +496,7 @@ def valid? # vector = Geom::Vector2d.new(1, 2) # x = vector.x # - # @return [Numeric] + # @return [Float] # # @version LayOut 2018 def x @@ -483,10 +508,10 @@ def x # vector = Geom::Vector2d.new(1, 2) # vector.x = 7 # - # @param [Numeric] x + # @param [Float] x # The desired x value of the {Geom::Vector2d} # - # @return [Numeric] The new x value of the {Geom::Vector2d} + # @return [Float] The new x value of the {Geom::Vector2d} # # @version LayOut 2018 def x=(x) @@ -498,7 +523,7 @@ def x=(x) # vector = Geom::Vector2d.new(1, 2) # y = vector.y # - # @return [Numeric] + # @return [Float] # # @version LayOut 2018 def y @@ -510,10 +535,10 @@ def y # vector = Geom::Vector2d.new(1, 2) # vector.y = 7 # - # @param [Numeric] y + # @param [Float] y # The desired y value of the {Geom::Vector2d} # - # @return [Numeric] The new y value of the {Geom::Vector2d} + # @return [Float] The new y value of the {Geom::Vector2d} # # @version LayOut 2018 def y=(y) diff --git a/lib/sketchup-api-stubs/stubs/Geom/Vector3d.rb b/lib/sketchup-api-stubs/stubs/Geom/Vector3d.rb index c2bb855..7925a0d 100644 --- a/lib/sketchup-api-stubs/stubs/Geom/Vector3d.rb +++ b/lib/sketchup-api-stubs/stubs/Geom/Vector3d.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Vector3d class is used to represent vectors in a 3 dimensional space. @@ -16,30 +16,29 @@ class Geom::Vector3d # at some percentage between two vectors. # # A linear combination is a standard term for vector math. It is defined as - # vector = weight1 * vector1 + weight2 * vector2. + # vector = weight1 * vector1 + weight2 * vector2 # # @example - # # Create a vector that is a 50%/50% linear combination of two others. - # vec1 = Geom::Vector3d.new 3,0,0 - # vec2 = Geom::Vector3d.new 0,3,0 - # new_vector = Geom::Vector3d.linear_combination(0.5, vec1, 0.5, vec2) - # # new_vector will now contain a Vector3d(1.5, 1.5, 0) + # vector1 = Geom::Vector3d.new(3, 0, 0) + # vector2 = Geom::Vector3d.new(0, 3, 0) + # # The result is a Vector3d(1.5, 1.5, 0) + # new_vector = Geom::Vector3d.linear_combination(0.5, vector1, 0.5, vector2) # # @overload linear_combination(weight1, vector1, weight2, vector2) # - # @param [Numeric] weight1 A weight or percentage. + # @param [Float] weight1 weights # @param [Geom::Vector3d] vector1 The first vector. - # @param [Numeric] weight2 A weight or percentage. + # @param [Float] weight2 weights # @param [Geom::Vector3d] vector2 The second vector. # @return [Geom::Vector3d] # # @overload linear_combination(x, xaxis, y, yaxis, z, zaxis) # - # @param [Numeric] x A weight or percentage for the x axis. + # @param [Float] x A weight or percentage for the x axis. # @param [Geom::Vector3d] xaxis The x axis vector. - # @param [Numeric] y A weight or percentage for the y axis. + # @param [Float] y A weight or percentage for the y axis. # @param [Geom::Vector3d] yaxis The y axis vector. - # @param [Numeric] z A weight or percentage for the z axis. + # @param [Float] z A weight or percentage for the z axis. # @param [Geom::Vector3d] zaxis The z axis vector. # @return [Geom::Vector3d] # @@ -54,18 +53,19 @@ def self.linear_combination(*args) # This is an alias of the {#dot} method. # # @example - # vector1 = Geom::Vector3d.new(0, 0, 1) - # vector2 = Geom::Vector3d.new(0, 1, 0) + # vector1 = Geom::Vector3d.new(2, 2, 1) + # vector2 = Geom::Vector3d.new(1, 3, 0) + # # The result is 8 # dot = vector1 % vector2 # - # @param [Geom::Vector3d] vector + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Float] # # @see #dot # # @version SketchUp 6.0 - def %(vector) + def %(vector3d) end # The {#*} method is used to compute the cross product between two vectors. @@ -77,156 +77,140 @@ def %(vector) # This is an alias of the {#cross} method. # # @example - # vector1 = Geom::Vector3d.new(1, 0, 0) - # vector2 = Geom::Vector3d.new(0, 1, 0) - # vector3 = vector1 * vector2 - # - # @example - # vector = Geom::Vector3d.new(1, 0, 0) - # vector2 = Geom::Vector3d.new(0, 1, 0) - # vector3 = vector.cross(vector2) + # vector1 = Geom::Vector3d.new(1, 0, 2) + # vector2 = Geom::Vector3d.new(3, 1, 1) + # # The result is a Vector3d(-2, 5, 1) + # cross = vector1 * vector2 # - # @param [Geom::Vector3d] vector + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # - # @return [Geom::Vector3d] the cross of vector1 and vector2 + # @return [Geom::Vector3d] # # @see #cross # # @version SketchUp 6.0 - def *(vector) + def *(vector3d) end - # The - method is used to add a vector to this one. + # The {#+} method is used to add a vector to this one. # # @example - # vector = Geom::Vector3d.new(0,0,2) - # vector2 = Geom::Vector3d.new(0,1,0) - # new_vector = vector + vector2 + # vector1 = Geom::Vector3d.new(0, 0, 2) + # vector2 = Geom::Vector3d.new(0, 1, 0) + # new_vector = vector1 + vector2 # - # @param vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Geom::Vector3d] the new vector. # # @version SketchUp 6.0 - def +(vector2) + def +(vector3d) end - # The - method is used to subtract a vector from this one. + # The {#-} method is used to subtract a vector from this one. # # @example - # vector = Geom::Vector3d.new(0,0,2) - # vector2 = Geom::Vector3d.new(0,1,0) - # new_vector = vector - vector2 + # vector1 = Geom::Vector3d.new(0, 0, 2) + # vector2 = Geom::Vector3d.new(0, 1, 0) + # new_vector = vector1 - vector2 # - # @param vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Geom::Vector3d] the new vector. # # @version SketchUp 6.0 - def -(vector2) + def -(vector3d) end - # The < method is used to determine if a vector's x, y or z value is less - # than another vector's x, y or z value. + # The {#<} compare method is used to compare two vectors to determine if the left-hand vector is + # less than the right-hand vector. # # @example - # vector = Geom::Vector3d.new(0,0,2) - # vector2 = Geom::Vector3d.new(0,1,0) - # lt = vector < vector2 + # vector1 = Geom::Vector3d.new(0, 1, 0) + # vector2 = Geom::Vector3d.new(0, 4, 2) + # # Returns true + # vector1 < vector2 # - # @param vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # - # @return [Boolean] true if the vector's x, y or z component is less + # @return [Boolean] true if the vector1 is closer to origin than vector2 # # @version SketchUp 6.0 - def <(vector2) + def <(vector3d) end - # The == method is used to determine if two vectors are equal to within + # The {#==} method is used to determine if two vectors are equal to within # tolerance. # # @example - # vector = Geom::Vector3d.new(1,0,0) - # vector2 = Geom::Vector3d.new(0,1,0) - # status = vector == vector2 + # vector1 = Geom::Vector3d.new(1, 0, 0) + # vector2 = Geom::Vector3d.new(0, 1, 0) # # Returns false - # UI.messagebox status + # status = vector1 == vector2 # - # @param vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Boolean] # # @version SketchUp 6.0 - def ==(vector2) + def ==(vector3d) end - # The [] method is used to access the coordinates of a vector as if it was an + # The {[]} method is used to access the coordinates of a vector as if it was an # Array. The index must be 0, 1 or 2. # # The following are equivalent: # # @example - # x = vector.x + # vector = Geom::Vector3d.new(1, 1, 0) # x = vector[0] # - # @example - # vector = Geom::Vector3d.new(1,0,0) - # value = vector[0] - # if (value) - # UI.messagebox value - # else - # UI.messagebox "Failure" - # end - # - # @param [Integer] i + # @param [Integer] index # An index into an array of three coordinates. # # @return [Length] the value for the x, y, or z coordinate. # # @version SketchUp 6.0 - def [](i) + def [](index) end - # The []= method is used to set the coordinates of a vector as if it was an + # The {[]=} method is used to set the coordinates of a vector as if it was an # Array. The value of i must be 0, 1 or 2. # # @example - # vector[i] = coordinate + # vector = Geom::Vector3d.new(4, 5, 0) + # + # vector[2] = 10 # # @param [Integer] index # The index for the x, y, or z coordinate. # - # @param [Numeric] value + # @param [Float] value # The value for the x, y, or z coordinate. # - # @return [Numeric] the newly set coordinate value + # @return [Float] the newly set coordinate value # # @version SketchUp 6.0 def []=(index, value) end - # The angle_between method is used to compute the angle (in radians) between + # The {#angle_between} method is used to compute the angle (in radians) between # this vector and another vector. # # @example - # vector1 = Geom::Vector3d.new(1,0,0) - # vector2 = Geom::Vector3d.new(0,1,0) - # angle = vector1.angle_between vector2 + # vector1 = Geom::Vector3d.new(1, 0, 0) + # vector2 = Geom::Vector3d.new(0, 1, 0) + # angle = vector1.angle_between(vector2) # - # @param [Geom::Vector3d] vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Float] an angle (in radians) # # @version SketchUp 6.0 - def angle_between(vector2) + def angle_between(vector3d) end - # The axes method is used to compute an arbitrary set of axes with the given + # The {#axes} method is used to compute an arbitrary set of axes with the given # vector as the z-axis direction. # # Returns an Array of three vectors [xaxis, yaxis, zaxis] @@ -234,8 +218,8 @@ def angle_between(vector2) # Vector3d objects # # @example - # vector = Geom::Vector3d.new(1,0,0) - # a = vector.axes + # vector = Geom::Vector3d.new(1, 0, 0) + # array = vector.axes # # @return [Array(Geom::Vector3d, Geom::Vector3d, Geom::Vector3d)] an Array object containing three # @@ -243,13 +227,11 @@ def angle_between(vector2) def axes end - # The clone method is used to make a copy of a vector. - # - # This method is equivalent to vec2 = Geom::Vector3d.new(vec) + # The {#clone} method is used to make a copy of a vector. # # @example - # vector = Geom::Vector3d.new(1,0,0) - # vector2 = vector.clone + # vector = Geom::Vector3d.new(1, 0, 0) + # new_vector = vector.clone # # @return [Geom::Vector3d] a Vector3d object which is the clone of # vector @@ -265,52 +247,46 @@ def clone # perpendicular to the plane in which the first two lie. # # @example - # vector1 = Geom::Vector3d.new(1, 0, 0) - # vector2 = Geom::Vector3d.new(0, 1, 0) - # vector3 = vector1 * vector2 - # - # @example - # vector = Geom::Vector3d.new(1, 0, 0) - # vector2 = Geom::Vector3d.new(0, 1, 0) - # vector3 = vector.cross(vector2) + # vector1 = Geom::Vector3d.new(1, 2, 0) + # vector2 = Geom::Vector3d.new(5, 1, 3) + # # The result is a Vector3d(6, -3, -9) + # cross = vector1.cross(vector2) # - # @param [Geom::Vector3d] vector + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # - # @return [Geom::Vector3d] the cross of vector1 and vector2 + # @return [Geom::Vector3d] # # @see #* # # @version SketchUp 6.0 - def cross(vector) + def cross(vector3d) end # The {#dot} method is used to compute the dot product between two vectors. # # @example - # vector1 = Geom::Vector3d.new(0, 0, 1) - # vector2 = Geom::Vector3d.new(0, 1, 0) + # vector1 = Geom::Vector3d.new(0, 5, 1) + # vector2 = Geom::Vector3d.new(0, 1, 2) + # # The result is 7 # dot = vector1.dot(vector2) # - # @param [Geom::Vector3d] vector + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Float] # # @see #% # # @version SketchUp 6.0 - def dot(vector) + def dot(vector3d) end # The new method is used to create a new vector. # # @example # # A vector that runs up the Z axis. - # vector = Geom::Vector3d.new(0,0,1) - # if (vector) - # UI.messagebox vector - # else - # UI.messagebox "Failure" - # end + # vector1 = Geom::Vector3d.new(0, 0, 1) + # + # vector2 = Geom::Vector3d.new([1, 1]) # # @overload initialize # @@ -318,19 +294,19 @@ def dot(vector) # # @overload initialize(x, y, z) # - # @param [Numeric] x - # @param [Numeric] y - # @param [Numeric] z + # @param [Float] x + # @param [Float] y + # @param [Float] z # @return [Geom::Vector3d] # # @overload initialize(array3d) # - # @param [Array(Numeric, Numeric, Numeric)] array3d + # @param [Array(Float, Float, Float)] array3d # @return [Geom::Vector3d] # # @overload initialize(array2d) # - # @param [Array(Numeric, Numeric)] array2d + # @param [Array(Float, Float)] array2d # @return [Geom::Vector3d] # # @overload initialize(vector) @@ -342,13 +318,12 @@ def dot(vector) def initialize(*args) end - # The inspect method is used to inspect the contents of a vector as a + # The {#inspect} method is used to inspect the contents of a vector as a # friendly string. # # @example - # vector = Geom::Vector3d.new(0,0,1) - # out_string = vector.inspect - # puts out_string + # vector = Geom::Vector3d.new(0, 0, 1) + # string = vector.inspect # # @return [Geom::Vector3d] the Vector3d object # @@ -356,11 +331,11 @@ def initialize(*args) def inspect end - # The length method is used to retrieve the length of the vector. + # The {#length} method is used to retrieve the length of the vector. # # @example - # vector = Geom::Vector3d.new(0,0,1) - # l = vector.length + # vector = Geom::Vector3d.new(0, 0, 1) + # length = vector.length # # @return [Length] the length of the vector # @@ -368,30 +343,28 @@ def inspect def length end - # The length= method is used to set the length of the vector. The length must + # The {#length=} method is used to set the length of the vector. The length must # be greater than 0. # # @example - # vector = Geom::Vector3d.new(0,0,1) - # l = vector.length - # UI.messagebox(l) - # newl = vector.length = 2 + # vector = Geom::Vector3d.new(0, 0, 1) + # vector.length = 2 # - # @param [Numeric] length + # @param [Float] length # A length for the vector. # - # @return [Numeric] a newly set length + # @return [Length] a newly set length # # @version SketchUp 6.0 def length=(length) end - # The normalize method is used to return a vector that is a unit vector + # The {#normalize} method is used to return a vector that is a unit vector # of another. # # @example - # vector = Geom::Vector3d.new(0,0,2) - # vector2 = vector.normalize + # vector = Geom::Vector3d.new(0, 0, 2) + # new_vector = vector.normalize # # @return [Geom::Vector3d] a new normalized Vector3d object # @@ -399,13 +372,13 @@ def length=(length) def normalize end - # The normalize! method is used to convert a vector into a unit vector, + # The {#normalize!} method is used to convert a vector into a unit vector, # in place. # - # Another way to do this is vec.length = 1 + # Another way to do this is +vector.length = 1.0+ # # @example - # vector = Geom::Vector3d.new(0,0,2) + # vector = Geom::Vector3d.new(0, 0, 2) # vector.normalize! # # @return [Geom::Vector3d] a normalized Vector3d object @@ -414,100 +387,97 @@ def normalize def normalize! end - # The parallel method is used to determine if this vector is parallel to - # another vector to within tolerance. + # The {#parallel?} method determines if two {Geom::Vector3d}s are parallel within a + # tolerance. Two vectors are parallel if there exists a scalar multiple between them. # # @example - # status = vector.parallel?(vector2) + # vector1 = Geom::Vector3d.new(1, 2, 4) + # vector2 = Geom::Vector3d.new(2, 4, 8) + # # Returns true + # status = vector1.parallel?(vector2) # - # @param [Geom::Vector3d] vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Boolean] # # @version SketchUp 6.0 - def parallel?(vector2) + def parallel?(vector3d) end - # The perpendicular? method is used to determine if this vector is - # perpendicular to another vector to within tolerance. + # The {#perpendicular?} method determines if two Geom::Vector3ds are perpendicular within a + # tolerance. Two vectors are considered perpendicular if their dot product is zero. # # @example - # vector = Geom::Vector3d.new(0,0,1) - # vector2 = Geom::Vector3d.new(0,1,0) - # status = vector.perpendicular?(vector2) + # vector1 = Geom::Vector3d.new(0, 0, 1) + # vector2 = Geom::Vector3d.new(0, 1, 0) + # status = vector1.perpendicular?(vector2) # - # @param [Geom::Vector3d] vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Boolean] # # @version SketchUp 6.0 - def perpendicular?(vector2) + def perpendicular?(vector3d) end - # The reverse method is used to return a new vector that is the reverse + # The {#reverse} method is used to return a new vector that is the reverse # of this vector, while leaving the original unchanged. # # @example - # vector2 = vector.reverse + # vector = Geom::Vector3d.new(3, 1, 0) + # new_vector = vector.reverse # - # @return [Geom::Vector3d] a Vector3d object that is the reverse of - # vector + # @return [Geom::Vector3d] a reverse Vector3d object # # @version SketchUp 6.0 def reverse end - # The reverse! method is used to reverse the vector in place. + # The {#reverse!} method is used to reverse the vector in place. # # @example + # vector = Geom::Vector3d.new(3, 1, 0) # vector.reverse! # - # @return [Geom::Vector3d] a Vector3d object that is the reverse of - # vector + # @return [Geom::Vector3d] a reverse Vector3d object # # @version SketchUp 6.0 def reverse! end - # The samedirection? method is used to determine if this vector is parallel to + # The {#samedirection?} method is used to determine if this vector is parallel to # and in the same direction as another vector to within tolerance. # # @example - # vector = Geom::Vector3d.new(0,0,1) - # vector2 = Geom::Vector3d.new(0,1,0) - # status = vector.samedirection?(vector2) + # vector1 = Geom::Vector3d.new(2, 4, 1) + # vector2 = Geom::Vector3d.new(2, 0, 1) + # # Returns false + # status = vector1.samedirection?(vector2) # - # @param [Geom::Vector3d] vector2 - # A Vector3d object. + # @param [Geom::Vector3d, Array(Float, Float, Float)] vector3d # # @return [Boolean] # # @version SketchUp 6.0 - def samedirection?(vector2) + def samedirection?(vector3d) end - # The set! method is used to set the coordinates of the vector. + # The {#set!} method is used to set the coordinates of the vector. # # @example This is a shortcut for writing: - # vec.x = x - # vec.y = y - # vec.z = z + # vector = Geom::Vector3d.new(0, 0, 1) + # vector.x = 2 + # vector.y = 4 + # vector.z = 0 # # @example You may also call this method with an array or another vector: - # vec.set!(x, y, z) - # vec.set!([x, y, z]) - # vec.set!(vec2) + # vector1 = Geom::Vector3d.new + # vector2 = Geom::Vector3d.new(2, 4, 0) + # vector1.set!(vector2) # # @example - # vector = Geom::Vector3d.new(0,0,1) - # vector.set! 1,0,0 - # - # @overload set!(array3d) - # - # @param [Array(Numeric, Numeric, Numeric)] array3d - # @return [Geom::Vector3d] + # vector = Geom::Vector3d.new(0, 0, 1) + # vector.set!(2, 4, 0) # is equivalent to vector.set!([2, 4, 0]) # # @overload set!(vector) # @@ -516,33 +486,37 @@ def samedirection?(vector2) # # @overload set!(x, y, z) # - # @param [Numeric] x - # @param [Numeric] y - # @param [Numeric] z + # @param [Float] x + # @param [Float] y + # @param [Float] z + # @return [Geom::Vector3d] + # + # @overload set!(array3d) + # + # @param [Array(Float, Float, Float)] array3d # @return [Geom::Vector3d] # # @version SketchUp 6.0 def set!(*args) end - # The to_a method retrieves the coordinates of the vector in an Array - # [x, y, z]. + # The {#to_a} method retrieves the coordinates of the vector in an Array[x, y, z]. # # @example - # a = vector.to_a + # vector = Geom::Vector3d.new(3, 0, 6) + # array = vector.to_a # - # @return [Array(Length, Length, Length)] the coordinates of the vector in an array + # @return [Array(Float, Float, Float)] the coordinates of the vector in an array # # @version SketchUp 6.0 def to_a end - # The to_s method is used to format the vector as a String. + # The {#to_s} method is used to format the vector as a String. # # @example - # vector = Geom::Vector3d.new(0,0,1) - # out_string = vector.to_s - # puts out_string + # vector = Geom::Vector3d.new(0, 0, 1) + # string = vector.to_s # # @return [String] a string representation of vector # @@ -550,11 +524,15 @@ def to_a def to_s end - # Apply a Transformation to a vector, returning a new vector. The original - # vector is unchanged by this method. + # The {#transform} method applies a Transformation to a vector, returning a new vector. The + # original vector is unchanged by this method. # # @example - # vector2 = vector.transform(transformation) + # vector = Geom::Vector3d.new(0, 2, 1) + # point = Geom::Point3d.new(2, 3, 1) + # transformation = Geom::Transformation.scaling(point, 2) + # # The result is a Vector3d(0, 4, 2) + # new_vector = vector.transform(transformation) # # @param [Geom::Transformation] transform # A Transformation object to apply to the vector. @@ -565,9 +543,13 @@ def to_s def transform(transform) end - # Apply a Transformation to a vector. The vector itself is modified. + # The {#transform!} method applies a Transformation to a vector. The vector itself is modified. # # @example + # vector = Geom::Vector3d.new(0, 2, 1) + # point = Geom::Point3d.new(2, 3, 1) + # transformation = Geom::Transformation.scaling(point, 2) + # # The result is a Vector3d(0, 4, 2) # vector.transform!(transformation) # # @param [Geom::Transformation] transform @@ -579,12 +561,13 @@ def transform(transform) def transform!(transform) end - # The unitvector? method is used to see if the vector is a unit vector. + # The {#unitvector?} method is used to see if the vector is a unit vector. # - # This is equivalent to vec.length == 1.0 + # This is equivalent to +vector.length == 1.0+ # # @example - # vector = Geom::Vector3d.new(0,0,1) + # vector = Geom::Vector3d.new(0, 0, 1) + # # Return false # status = vector.unitvector? # # @return [Boolean] @@ -593,15 +576,16 @@ def transform!(transform) def unitvector? end - # The valid? method is used to verify if a vector is valid. A vector is valid + # The {#valid?} method is used to verify if a vector is valid. A vector is valid # if its length is not zero. # # @example # # A zero length vector will be invalid - # vector = Geom::Vector3d.new(0,0,0) + # vector = Geom::Vector3d.new # status = vector.valid? + # # # A non-zero length vector is valid - # vector = Geom::Vector3d.new(0,0,1) + # vector = Geom::Vector3d.new(0, 0, 1) # status = vector.valid? # # @return [Boolean] @@ -610,81 +594,82 @@ def unitvector? def valid? end - # The x method is used to retrieve the x coordinate of the vector. + # The {#x} method is used to retrieve the x coordinate of the vector. # # @example + # vector = Geom::Vector3d.new(1, 2, 3) # x = vector.x # - # @return [Length] the x coordinate of the vector + # @return [Float] the x coordinate of the vector # # @version SketchUp 6.0 def x end - # The x= method is used to set the x coordinate of the vector. + # The {#x=} method is used to set the x coordinate of the vector. # # @example - # vector = Geom::Vector3d.new 1,2,3 - # x = vector.x = 10 + # vector = Geom::Vector3d.new(1, 2, 3) + # vector.x = 10 # - # @param [Numeric] x + # @param [Float] x # The x coordinate for the vector. # - # @return [Numeric] the newly set x coordinate for the vector + # @return [Float] the newly set x coordinate for the vector # # @version SketchUp 6.0 def x=(x) end - # The y method is used to retrieve the y coordinate of the vector. + # The {#y} method is used to retrieve the y coordinate of the vector. # # @example - # vector = Geom::Vector3d.new(1,2,3) + # vector = Geom::Vector3d.new(1, 2, 3) # y = vector.y # - # @return [Length] the y coordinate of the vector + # @return [Float] the y coordinate of the vector # # @version SketchUp 6.0 def y end - # Set the y coordinate of the vector. + # Set the {#y=} coordinate of the vector. # # @example - # vector = Geom::Vector3d.new(1,2,3) - # y = vector.y = 10 + # vector = Geom::Vector3d.new(1, 2, 3) + # vector.y = 10 # - # @param [Numeric] y + # @param [Float] y # The y coordinate for the vector. # - # @return [Numeric] the newly set y coordinate for the vector + # @return [Float] the newly set y coordinate for the vector # # @version SketchUp 6.0 def y=(y) end - # Get the z coordinate of the vector. + # Get the {#z} coordinate of the vector. # # @example - # vector = Geom::Vector3d.new(1,2,3) + # vector = Geom::Vector3d.new(1, 2, 3) # z = vector.z # - # @return [Length] the z coordinate of the vector + # @return [Float] the z coordinate of the vector # # @version SketchUp 6.0 def z end - # Set the z coordinate of the vector. + # Set the {#z=} coordinate of the vector. # # @example - # vector = Geom::Vector3d.new(1,2,3) - # z = vector.z = 10 + # vector = Geom::Vector3d.new(1, 2, 3) + # vector.z = 10 # - # @param [Numeric] z + # @param [Float] z # The z coordinate for the vector. # - # @return [Numeric] the newly set z coordinate for the vector + # @return [Float] the newly set z coordinate for the vector # # @version SketchUp 6.0 def z=(z) diff --git a/lib/sketchup-api-stubs/stubs/LanguageHandler.rb b/lib/sketchup-api-stubs/stubs/LanguageHandler.rb index 5a6eb26..aba9068 100644 --- a/lib/sketchup-api-stubs/stubs/LanguageHandler.rb +++ b/lib/sketchup-api-stubs/stubs/LanguageHandler.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The LanguageHandler class contains methods used to help make SketchUp diff --git a/lib/sketchup-api-stubs/stubs/Layout.rb b/lib/sketchup-api-stubs/stubs/Layout.rb index 5c8b161..97ca327 100644 --- a/lib/sketchup-api-stubs/stubs/Layout.rb +++ b/lib/sketchup-api-stubs/stubs/Layout.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The LayOut module is the root of the LayOut Ruby API. Many of the classes in diff --git a/lib/sketchup-api-stubs/stubs/Layout/AngularDimension.rb b/lib/sketchup-api-stubs/stubs/Layout/AngularDimension.rb index 393924f..58d49d6 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/AngularDimension.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/AngularDimension.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # References an angular dimension entity. An {Layout::AngularDimension} is diff --git a/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinition.rb b/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinition.rb index c5f2e2c..72f1337 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinition.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinition.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # References an auto-text definition. Some auto-text definitions are mandatory. @@ -451,8 +451,8 @@ def number_style=(number_style) # [+Layout::AutoTextDefinition::NUMBER_STYLE_LC_ROMAN+] # # @deprecated LayOut 2022.0 This method is deprecated in favor of the more generic {#number_style} - # method that also works on +Layout::AutoTextDefintion::TYPE_PAGE_COUNT+ and - # +Layout::AutoTextDefintion::TYPE_SEQUENCE+ {Layout::AutoTextDefinition}s. + # method that also works on +Layout::AutoTextDefinition::TYPE_PAGE_COUNT+ and + # +Layout::AutoTextDefinition::TYPE_SEQUENCE+ {Layout::AutoTextDefinition}s. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -460,7 +460,9 @@ def number_style=(number_style) # Layout::AutoTextDefinition::TYPE_PAGE_NUMBER) number_style = page_number_def.number_style # # @raise [ArgumentError] if the {Layout::AutoTextDefinition}'s type is not - # +Layout::AutoTextDefinition::TYPE_PAGE_NUMBER+. + # +Layout::AutoTextDefinition::TYPE_PAGE_NUMBER+, + # +Layout::AutoTextDefinition::TYPE_PAGE_COUNT+, or + # +Layout::AutoTextDefinition::TYPE_SEQUENCE+. # # @return [Integer] # @@ -480,8 +482,8 @@ def page_number_style # [+Layout::AutoTextDefinition::NUMBER_STYLE_LC_ROMAN+] # # @deprecated LayOut 2022.0 This method is deprecated in favor of the more generic {#number_style=} - # method that also works on +Layout::AutoTextDefintion::TYPE_PAGE_COUNT+ and - # +Layout::AutoTextDefintion::TYPE_SEQUENCE+ {Layout::AutoTextDefinition}s. + # method that also works on +Layout::AutoTextDefinition::TYPE_PAGE_COUNT+ and + # +Layout::AutoTextDefinition::TYPE_SEQUENCE+ {Layout::AutoTextDefinition}s. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -492,7 +494,9 @@ def page_number_style # @param [Integer] number_style # # @raise [ArgumentError] if the {Layout::AutoTextDefinition}'s type is not - # +Layout::AutoTextDefinition::TYPE_PAGE_NUMBER+. + # +Layout::AutoTextDefinition::TYPE_PAGE_NUMBER+, + # +Layout::AutoTextDefinition::TYPE_PAGE_COUNT+, or + # +Layout::AutoTextDefinition::TYPE_SEQUENCE+. # # @raise [ArgumentError] if +number_style+ is not a valid page numbering style # diff --git a/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinitions.rb b/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinitions.rb index fdd6a2b..c9fe741 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinitions.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinitions.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The AutoTextDefinitions class is a container class for all diff --git a/lib/sketchup-api-stubs/stubs/Layout/ConnectionPoint.rb b/lib/sketchup-api-stubs/stubs/Layout/ConnectionPoint.rb index feabc2f..731520f 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/ConnectionPoint.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/ConnectionPoint.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is the interface to a LayOut Connection Point. A diff --git a/lib/sketchup-api-stubs/stubs/Layout/Dictionary.rb b/lib/sketchup-api-stubs/stubs/Layout/Dictionary.rb new file mode 100644 index 0000000..1380eb3 --- /dev/null +++ b/lib/sketchup-api-stubs/stubs/Layout/Dictionary.rb @@ -0,0 +1,234 @@ +# Copyright:: Copyright 2026 Trimble Inc. +# License:: The MIT License (MIT) + +# This is the interface to a LayOut dictionary. A {Layout::Dictionary} wraps key/value pairs. +# +# @example +# dict = Layout::Dictionary.new +# +# @version LayOut 2026.0 +class Layout::Dictionary + + # Includes + + include Enumerable + + # Instance Methods + + # The {#[]} method retrieves the value for a given key. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary['test'] = 115 + # + # # value will contain 115 + # value = dictionary["test"] + # + # @param [String] key + # The name of the attribute. + # + # @return [String, Boolean, Integer, Float, Layout::Dictionary, nil] + # + # @version LayOut 2026.0 + def [](key) + end + + # The {#[]=} method sets a value for a given key. + # + # Creates a new dictionary entry for the given key if needed. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary['test'] = 110 + # value = dictionary['test2'] = 120 + # p value + # + # @param [String] key + # The valid key. + # + # @param [String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil] value + # + # @version LayOut 2026.0 + def []=(key, value) + end + + # The {#delete_key} method deletes a key/value pair from the dictionary. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary["attr_one"] = "one" + # dictionary["attr_two"] = "two" + # + # # Delete a key/value pair and get the deleted value. + # value = dictionary.delete_key("attr_one") + # + # @param [String] key + # The key to be deleted. + # + # @return [String, Boolean, Integer, Float, Layout::Dictionary, nil] + # + # @version LayOut 2026.0 + def delete_key(key) + end + + # The {#each_pair} method is an alias for {#each}. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary["attr_one"] = "one" + # dictionary["attr_two"] = "two" + # + # # iterates through all attributes and prints the key to the screen + # dictionary.each_pair { | key, value | + # puts "#{key} = #{value}" + # } + # + # @see #each + # + # @version LayOut 2026.0 + # + # @yield [key, value] + # + # @yieldparam [String] key + # + # @yieldparam [Object] value + def each + end + + # The {#each_key} method iterates through all of the dictionary keys. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary["attr_one"] = "one" + # dictionary["attr_two"] = "two" + # + # # iterates through all attributes and prints the key to the screen + # dictionary.each_key { |key| puts key } + # + # @version LayOut 2026.0 + # + # @yieldparam [String] key + def each_key + end + + # The {#each_pair} method is an alias for {#each}. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary["attr_one"] = "one" + # dictionary["attr_two"] = "two" + # + # # iterates through all attributes and prints the key to the screen + # dictionary.each_pair { | key, value | + # puts "#{key} = #{value}" + # } + # + # @see #each + # + # @version LayOut 2026.0 + # + # @yield [key, value] + # + # @yieldparam [String] key + # + # @yieldparam [Object] value + def each_pair + end + + # The {#empty?} method checks if the dictionary is empty. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary["attribute_one"] = "1" + # dictionary.empty? # Returns false + # + # @return [Boolean] + # + # @version LayOut 2026.0 + def empty? + end + + # The {#initialize} method creates a new {Layout::Dictionary}. + # + # @example + # doc = Layout::Dictionary.new + # doc2 = Layout::Dictionary.new({"String key" => "string value", "Number key" => 42}) + # + # @overload initialize + # + # @return [Layout::Dictionary] + # + # @overload initialize(dict) + # + # @param [Hash, Layout::Dictionary] hash + # @return [Layout::Dictionary] + # + # @raise [ArgumentError] if dict isn't a dictionary or hash + # + # @version LayOut 2026.0 + def initialize(*args) + end + + # The {#keys} method retrieves an array with all of the dictionary keys. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary["attr_one"] = "one" + # dictionary["attr_two"] = "two" + # + # # Gets an array of keys + # keys = dictionary.keys + # + # @return [Array] an array of keys within the dictionary if successful + # + # @version LayOut 2026.0 + def keys + end + + # The {#length} method retrieves the size (number of elements) of a dictionary. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary['Hello'] = 'World' + # number = dictionary.length + # + # @return [Integer] + # + # @see #size + # + # @version LayOut 2026.0 + def length + end + + # The {#length} method retrieves the size (number of elements) of a dictionary. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary['Hello'] = 'World' + # number = dictionary.length + # + # @return [Integer] + # + # @see #size + # + # @version LayOut 2026.0 + def size + end + + # The {#values} method retrieves an array with all of the dictionary values. + # + # @example + # dictionary = Layout::Dictionary.new + # dictionary["attr_one"] = "one" + # dictionary["attr_two"] = "two" + # + # # Gets an array of values + # values = dictionary.values + # + # @return [Array] an array of values within the dictionary if successful + # + # @version LayOut 2026.0 + def values + end + +end diff --git a/lib/sketchup-api-stubs/stubs/Layout/Document.rb b/lib/sketchup-api-stubs/stubs/Layout/Document.rb index a786306..a437d3e 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Document.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Document.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is the interface to a LayOut document. A {Layout::Document} is the 2D @@ -129,10 +129,33 @@ def ==(other) # # @raise [ArgumentError] if entity already belongs to a {Layout::Document} # + # @return [Layout::Entity] The {Layout::Entity} that was added to the {Layout::Document}. + # # @version LayOut 2018 def add_entity(*args) end + # The {#attribute_dictionary} method returns a copy of the document's attribute dictionary with the + # given name. + # + # is no attribute dictionary + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # doc.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # attributes = doc.attribute_dictionary("jane_doe_doc_maker") + # # Adding to this Layout::Dictionary does not apply to the document's attribute dictionary, use + # #Layout::Document#set_attribute. + # attributes.merge!(doc_id: 42) + # + # @param [String] name + # + # @return [Layout::Dictionary, nil] A copy of the document's attribute dictionary, or nil if there + # + # @version LayOut 2026.0 + def attribute_dictionary(name) + end + # The {#auto_text_definitions} method returns an array of # {Layout::AutoTextDefinition}'s in the {Layout::Document}. # @@ -146,6 +169,33 @@ def add_entity(*args) def auto_text_definitions end + # The {#delete_attribute} method is used to delete an attribute from a document. + # + # @overload delete_attribute(dictionary_name) + # + # @param [String] dictionary_name The name of an attribute dictionary. + # @return [Boolean] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # doc.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # doc.delete_attribute("jane_doe_doc_maker") + # + # @overload delete_attribute(dictionary_name, key) + # + # @param [String] dictionary_name The name of an attribute dictionary. + # @param [String] key An attribute key. + # @return [Boolean] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # doc.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # doc.delete_attribute("jane_doe_doc_maker", "made_by_doc_maker") + # + # @version LayOut 2026.0 + def delete_attribute(*args) + end + # The {#export} method exports the {Layout::Document} to a given file format. # It knows which format to export based on the file extension you place on the # file name. For example, a filename of "thing.pdf" will export a PDF file, @@ -157,47 +207,64 @@ def auto_text_definitions # doc = Layout::Document.open("c:/path/to/document.layout") # # # Export pdf file on a PC, with default settings. - # status = doc.export("c:/my_export.pdf") + # doc.export("c:/my_export.pdf") # # # Export pages one through three at high quality, compressing jpeg images # # at 0.75 compression quality (valid range is 0.0 - 1.0). Note that the # # first page of a {Layout::Document} is index 0. # options = { start_page: 1, # end_page: 3, - # compress_images: TRUE, + # compress_images: true, # compress_quality: 0.75 } # - # status = doc.export("c:/my_export.pdf", options) + # doc.export("c:/my_export.pdf", options) # # # Export pages one and three through five. Note that page_range starts at # # index 1. # # `page_range` support added in LayOut 2024.0. # options = { page_range: "1,3-5", - # compress_images: TRUE, + # compress_images: true, # compress_quality: 0.75 } # - # status = doc.export("c:/my_export.pdf", options) + # doc.export("c:/my_export.pdf", options) # # @example Image Set Export Examples # doc = Layout::Document.open("c:/path/to/document.layout") # # # Export png files on macOS, with default settings. - # status = doc.export("/Users//Desktop/pngs/page.png") + # doc.export("/Users//Desktop/pngs/page.png") # # # Export pages one through three at 300 dpi as JPGs. # options = { start_page: 1, # end_page: 3, # dpi: 300 } - # status = doc.export('c:/page.jpg', options) + # doc.export('c:/page.jpg', options) # # # Export pages one and three through five. Note that page_range starts at # # index 1. # # `page_range` support added in LayOut 2024.0. # options = { page_range: "1,3-5", - # compress_images: TRUE, + # compress_images: true, # compress_quality: 0.75 } # - # status = doc.export("c:/my_export.png", options) + # doc.export("c:/my_export.png", options) + # + # @option options [Integer] :start_page The first page to export. + # + # @option options [Integer] :end_page The last page to export. + # + # @option options [String] :page_range A string specifying the range of pages to export. The + # format can include individual page numbers and ranges of pages, separated by commas (e.g., + # "1,3-5"). This was added in LayOut 2024.0 + # + # @option options [Boolean] :compress_images Whether to compress images in the document. This is + # valid only for image compression for PDF exports. + # + # @option options [Float] :compress_quality The compression quality for JPEG images. This is + # valid only for the quality of the compression of images for PDF exports. + # + # @option options [Integer] :dpi The resolution in dots per inch for the exported images. This + # option is only valid for image exports. # # @param [String] file_path # The file or image set to create. The directory @@ -218,6 +285,37 @@ def auto_text_definitions def export(file_path, options = nil) end + # The {#get_attribute} method is used to retrieve the value of an attribute in + # the document's attribute dictionary. + # + # If the third parameter, +default_value+, is not passed and there is no + # attribute that matches the given name, it returns +nil+. + # + # If +default_value+ is provided and there is no matching attribute it returns + # the given value. It does not create an attribute with that name though. + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # # Read an attribute value from the document. In this case this will return the + # # default value provided: 42. + # doc.get_attribute("jane_doe_doc_maker", "doc_id", 42) + # + # @param [String] name + # The name of an attribute dictionary. + # + # @param [String] key + # An attribute key. + # + # @param [String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil] default_value + # A default + # value to return if no attribute is found. + # + # @return [String, Boolean, Integer, Float, Layout::Dictionary, nil] the retrieved value. + # + # @version LayOut 2026.0 + def get_attribute(name, key, default_value = nil) + end + # The {#grid} method returns the {Layout::Grid} for a {Layout::Document}. # # @example @@ -486,6 +584,22 @@ def render_mode_override=(render_mode) def save(*args) end + # The {#set_attribute} method adds an attribute to the document's attribute dictionary. + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # doc.set_attribute "jane_doe_doc_maker", "doc_id", 42 + # + # @param [String] name + # The name of an attribute dictionary. + # @param [String] key An attribute key. + # @param [String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil] value The value for the + # attribute. + # + # @version LayOut 2026.0 + def set_attribute(name, key, value) + end + # The {#shared_entities} method returns the {Layout::Entities} # that exist on shared {Layout::Layer}s in the {Layout::Document}. # diff --git a/lib/sketchup-api-stubs/stubs/Layout/Ellipse.rb b/lib/sketchup-api-stubs/stubs/Layout/Ellipse.rb index 5104eb1..30bd17c 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Ellipse.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Ellipse.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A simple elliptical shape entity. diff --git a/lib/sketchup-api-stubs/stubs/Layout/Entities.rb b/lib/sketchup-api-stubs/stubs/Layout/Entities.rb index 9bcdf18..e348705 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Entities.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Entities.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Entities class is a container class for {Layout::Entity}s. A diff --git a/lib/sketchup-api-stubs/stubs/Layout/Entity.rb b/lib/sketchup-api-stubs/stubs/Layout/Entity.rb index 5ffad11..2a35b33 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Entity.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Entity.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An entity is an object shown on a page of a LayOut document. @@ -34,6 +34,28 @@ class Layout::Entity def ==(other) end + # The {#attribute_dictionary} method returns a copy of the entity's attribute dictionary with the + # given name. + # + # no attribute dictionary + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # entity = doc.pages.first.entities.first + # entity.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # attributes = entity.attribute_dictionary("jane_doe_doc_maker") + # # Adding to this Layout::Dictionary does not apply to the entity's attribute dictionary, use + # #Layout::Entity#set_attribute. + # attributes.merge!(doc_id: 42) + # + # @param [String] name + # + # @return [Layout::Dictionary, nil] A copy of the entity's attribute dictionary, or nil if there is + # + # @version LayOut 2026.0 + def attribute_dictionary(name) + end + # The {#bounds} method returns the 2D rectangular bounds of the {Layout::Entity}. # # @example @@ -47,6 +69,35 @@ def ==(other) def bounds end + # The {#delete_attribute} method is used to delete an attribute from an entity. + # + # @overload delete_attribute(dictionary_name) + # + # @param [String] dictionary_name The name of an attribute dictionary. + # @return [Boolean] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # entity = doc.pages.first.entities.first + # entity.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # entity.delete_attribute("jane_doe_doc_maker") + # + # @overload delete_attribute(dictionary_name, key) + # + # @param [String] dictionary_name The name of an attribute dictionary. + # @param [String] key An attribute key. + # @return [Boolean] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # entity = doc.pages.first.entities.first + # entity.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # entity.delete_attribute("jane_doe_doc_maker", "made_by_doc_maker") + # + # @version LayOut 2026.0 + def delete_attribute(*args) + end + # The {#document} method returns the {Layout::Document} that the # {Layout::Entity} belongs to, or +nil+ if it is not in a {Layout::Document}. # @@ -76,6 +127,38 @@ def document def drawing_bounds end + # The {#get_attribute} method is used to retrieve the value of an attribute in + # the entity's attribute dictionary. + # + # If the third parameter, +default_value+, is not passed and there is no + # attribute that matches the given name, it returns +nil+. + # + # If +default_value+ is provided and there is no matching attribute it returns + # the given value. It does not create an attribute with that name though. + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # entity = doc.pages.first.entities.first + # # Read an attribute value from the entity. In this case this will return the + # # default value provided: 42. + # entity.get_attribute("jane_doe_doc_maker", "doc_id", 42) + # + # @param [String] name + # The name of an attribute dictionary. + # + # @param [String] key + # An attribute key. + # + # @param [String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil] default_value + # A default + # value to return if no attribute is found. + # + # @return [String, Boolean, Integer, Float, Layout::Dictionary, nil] the retrieved value. + # + # @version LayOut 2026.0 + def get_attribute(name, key, default_value = nil) + end + # The {#group} method returns the {Layout::Group} the {Layout::Entity} belongs # to, or +nil+ if it is not in a {Layout::Group}. # @@ -145,9 +228,12 @@ def locked? # # @example # doc = Layout::Document.open("C:/path/to/document.layout") - # entities = doc.pages.first.entities - # new_group = Layout::Group.new - # entities.first.move_to_group(new_group) + # # We consider that there are two rectangle objects in the entities. + # entities = doc.layers.first.layer_instance(doc.pages.first).entities + # # We move the first rectangle to a new group. + # group = Layout::Group.new([entities.first]) + # # We move the second rectangle to the same group. + # entities[1].first.move_to_group(new_group) # # @param [Layout::Group] group # @@ -246,6 +332,23 @@ def on_shared_layer? def page end + # The {#set_attribute} method adds an attribute to the entity's attribute dictionary. + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # entity = doc.pages.first.entities.first + # entity.set_attribute("jane_doe_doc_maker", "doc_id", 42) + # + # @param [String] name + # The name of an attribute dictionary. + # @param [String] key An attribute key. + # @param [String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil] value The value for the + # attribute. + # + # @version LayOut 2026.0 + def set_attribute(name, key, value) + end + # The {#style} method returns the {Layout::Style} of the {Layout::Entity}. If # the {Layout::Entity} is a {Layout::Group}, +nil+ will be returned, as they # do not have a {Layout::Style}. diff --git a/lib/sketchup-api-stubs/stubs/Layout/FormattedText.rb b/lib/sketchup-api-stubs/stubs/Layout/FormattedText.rb index ec7e927..167291b 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/FormattedText.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/FormattedText.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A formatted text entity. diff --git a/lib/sketchup-api-stubs/stubs/Layout/Grid.rb b/lib/sketchup-api-stubs/stubs/Layout/Grid.rb index 02869d6..812df0c 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Grid.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Grid.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Class that references a {Layout::Document}'s grid settings. diff --git a/lib/sketchup-api-stubs/stubs/Layout/Group.rb b/lib/sketchup-api-stubs/stubs/Layout/Group.rb index 4579ea0..8464471 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Group.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Group.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A group is a special type of {Layout::Entity} that does not belong to a @@ -92,7 +92,7 @@ def initialize(entities) def remove_scale_factor(resize_behavior) end - # The {#scale_factor} method returns the the scale factor associated with the + # The {#scale_factor} method returns the scale factor associated with the # {Layout::Group}. # # @example @@ -166,7 +166,7 @@ def scale_precision=(precision) def scale_units end - # The {#scale_units=} method sets the the units format for the scale of the + # The {#scale_units=} method sets the units format for the scale of the # {Layout::Group}. # # The units format can be any of the following values: @@ -197,7 +197,7 @@ def scale_units def scale_units=(units_format) end - # The {#set_scale_factor} method sets the the scale factor for the + # The {#set_scale_factor} method sets the scale factor for the # {Layout::Group}. # # The units format can be any of the following values: diff --git a/lib/sketchup-api-stubs/stubs/Layout/Image.rb b/lib/sketchup-api-stubs/stubs/Layout/Image.rb index fd46e7c..c8ad31c 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Image.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Image.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A raster image entity. diff --git a/lib/sketchup-api-stubs/stubs/Layout/Label.rb b/lib/sketchup-api-stubs/stubs/Layout/Label.rb index 5ff563b..1361de7 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Label.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Label.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is an interface to a label entity. A {Layout::Label} consists of a diff --git a/lib/sketchup-api-stubs/stubs/Layout/Layer.rb b/lib/sketchup-api-stubs/stubs/Layout/Layer.rb index af5e1c2..a34eec1 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Layer.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Layer.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is the interface to a LayOut Layer Definition. A layer definition diff --git a/lib/sketchup-api-stubs/stubs/Layout/LayerInstance.rb b/lib/sketchup-api-stubs/stubs/Layout/LayerInstance.rb index cd45220..fc5ec0c 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/LayerInstance.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/LayerInstance.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # References an instance of a {Layout::Layer}. A {Layout::LayerInstance} diff --git a/lib/sketchup-api-stubs/stubs/Layout/Layers.rb b/lib/sketchup-api-stubs/stubs/Layout/Layers.rb index 50027fd..6f02465 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Layers.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Layers.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Layers class is a container class for all layers in a {Layout::Document}. diff --git a/lib/sketchup-api-stubs/stubs/Layout/LinearDimension.rb b/lib/sketchup-api-stubs/stubs/Layout/LinearDimension.rb index ed3abfd..d87840a 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/LinearDimension.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/LinearDimension.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # References a linear dimension entity. A {Layout::LinearDimension} is composed @@ -22,6 +22,10 @@ class Layout::LinearDimension < Layout::Entity # Constants + DIMENSION_LINE_ALIGNED = nil # Stub value. + DIMENSION_LINE_HORIZONTAL = nil # Stub value. + DIMENSION_LINE_VERTICAL = nil # Stub value. + LEADER_LINE_TYPE_BEZIER = nil # Stub value. LEADER_LINE_TYPE_HIDDEN = nil # Stub value. LEADER_LINE_TYPE_SINGLE_SEGMENT = nil # Stub value. @@ -302,18 +306,33 @@ def entities # height = 1.0 # dim = Layout::LinearDimension.new(start_point, end_point, height) # - # @param [Geom::Point2d] start_point + # @overload initialize(start_point, end_point, height) # - # @param [Geom::Point2d] end_point + # @version LayOut 2018 + # @param [Geom::Point2d] start_point + # @param [Geom::Point2d] end_point + # @param [Numeric] height Distance from the start and end points to the + # dimension line # - # @param [Numeric] height - # Distance from the start and end points to the - # dimension line + # @overload initialize(start_point, end_point, height, alignment) # - # @return [Layout::LinearDimension] + # @version LayOut 2026.0 + # @param [Geom::Point2d] start_point + # @param [Geom::Point2d] end_point + # @param [Numeric] height Distance from the start and end points to the + # dimension line + # @param [Integer] alignment The alignment type for the dimension line # - # @version LayOut 2018 - def initialize(start_point, end_point, height) + # alignment can be one of the following: + # [+Layout::LinearDimension::DIMENSION_LINE_ALIGNED+] + # [+Layout::LinearDimension::DIMENSION_LINE_VERTICAL+] + # [+Layout::LinearDimension::DIMENSION_LINE_HORIZONTAL+] + # + # @raise [RangeError] if alignment is not a valid alignment type + # @raise [ArgumentError] if a dimension couldn't be created with the provided arguments + # + # @return [Layout::LinearDimension] + def initialize(*args) end # The {#leader_line_type} method returns the type of leader line the @@ -368,6 +387,34 @@ def leader_line_type def leader_line_type=(type) end + # The {#leader_line_visible?} method returns whether the leader line is currently visible. + # + # @example + # start_point = Geom::Point2d.new(1, 1) + # end_point = Geom::Point2d.new(1, 1.2) + # height = 1.0 + # dim = Layout::LinearDimension.new(start_point, end_point, height) + # dim.leader_line_type = Layout::LinearDimension::LEADER_LINE_TYPE_TWO_SEGMENT + # # Will be false since the text is not automatically positioned away from the dimension line + # visible = dim.leader_line_visible? + # + # # Position the text away from the dimension line. + # text_pos = Geom::Point2d.new(1, 1.5) + # anchor_type = Layout::FormattedText::ANCHOR_TYPE_TOP_LEFT + # dim.text = Layout::FormattedText.new("<>", text_pos, anchor_type) + # # Will be true since the text is positioned away from the dimension line + # visible = dim.leader_line_visible? + # + # dim.leader_line_type = Layout::LinearDimension::LEADER_LINE_TYPE_HIDDEN + # # Will be false, even though the text is positioned away from the dimension line + # visible = dim.leader_line_visible? + # + # @return [Boolean] + # + # @version LayOut 2026.0 + def leader_line_visible? + end + # The {#scale} method returns the scale being used for the # {Layout::LinearDimension}. # diff --git a/lib/sketchup-api-stubs/stubs/Layout/LockedEntityError.rb b/lib/sketchup-api-stubs/stubs/Layout/LockedEntityError.rb index 694726e..8ac4f4e 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/LockedEntityError.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/LockedEntityError.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is raised whenever a method attempts to modify any {Layout::Entity} diff --git a/lib/sketchup-api-stubs/stubs/Layout/LockedLayerError.rb b/lib/sketchup-api-stubs/stubs/Layout/LockedLayerError.rb index db52cd5..624b999 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/LockedLayerError.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/LockedLayerError.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is raised whenever a method attempts to modify any {Layout::Entity} diff --git a/lib/sketchup-api-stubs/stubs/Layout/Page.rb b/lib/sketchup-api-stubs/stubs/Layout/Page.rb index d520c74..cac6d45 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Page.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Page.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Class for a single page in a LayOut document. @@ -25,6 +25,56 @@ class Layout::Page def ==(other) end + # The {#attribute_dictionary} method returns a copy of the page's attribute dictionary with the + # given name. + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # page = doc.pages.first + # page.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # attributes = page.attribute_dictionary("jane_doe_doc_maker") + # # Adding to this Layout::Dictionary does not apply to the page's attribute dictionary, use + # # Layout::Page#set_attribute. + # attributes.merge!(doc_id: 42) + # + # @param [String] name + # + # @return [Layout::Dictionary, nil] A copy of the page's attribute dictionary, or nil if there is + # no attribute dictionary + # + # @version LayOut 2026.0 + def attribute_dictionary(name) + end + + # The {#delete_attribute} method is used to delete an attribute from a page. + # + # @overload delete_attribute(dictionary_name) + # + # @param [String] dictionary_name The name of an attribute dictionary. + # @return [Boolean] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # page = doc.pages.first + # page.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # page.delete_attribute("jane_doe_doc_maker") + # + # @overload delete_attribute(dictionary_name, key) + # + # @param [String] dictionary_name The name of an attribute dictionary. + # @param [String] key An attribute key. + # @return [Boolean] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # page = doc.pages.first + # page.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true) + # page.delete_attribute("jane_doe_doc_maker", "made_by_doc_maker") + # + # @version LayOut 2026.0 + def delete_attribute(*args) + end + # The {#document} method returns the {Layout::Document} that the {Layout::Page} # belongs to. # @@ -55,6 +105,38 @@ def document def entities end + # The {#get_attribute} method is used to retrieve the value of an attribute in + # the page's attribute dictionary. + # + # If the third parameter, +default_value+, is not passed and there is no + # attribute that matches the given name, it returns +nil+. + # + # If +default_value+ is provided and there is no matching attribute it returns + # the given value. It does not create an attribute with that name though. + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # page = doc.pages.first + # # Read an attribute value from the page. In this case this will return the + # # default value provided: 42. + # page.get_attribute("jane_doe_doc_maker", "doc_id", 42) + # + # @param [String] name + # The name of an attribute dictionary. + # + # @param [String] key + # An attribute key. + # + # @param [String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil] default_value + # A default + # value to return if no attribute is found. + # + # @return [String, Boolean, Integer, Float, Layout::Dictionary, nil] the retrieved value. + # + # @version LayOut 2026.0 + def get_attribute(name, key, default_value = nil) + end + # The {#in_presentation=} method sets whether the {Layout::Page} is included in # presentations. # @@ -156,6 +238,23 @@ def name=(name) def nonshared_entities end + # The {#set_attribute} method adds an attribute to the page's attribute dictionary. + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # page = doc.pages.first + # page.set_attribute("jane_doe_doc_maker", "doc_id", 42) + # + # @param [String] name + # The name of an attribute dictionary. + # @param [String] key An attribute key. + # @param [String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil] value The value for the + # attribute. + # + # @version LayOut 2026.0 + def set_attribute(name, key, value) + end + # The {#set_layer_visibility} method sets whether a {Layout::Layer} is visible # on the {Layout::Page}. # diff --git a/lib/sketchup-api-stubs/stubs/Layout/PageInfo.rb b/lib/sketchup-api-stubs/stubs/Layout/PageInfo.rb index fabc696..cbfa96a 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/PageInfo.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/PageInfo.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is the interface to a {Layout::Document}'s paper space information. The @@ -24,8 +24,7 @@ class Layout::PageInfo # Instance Methods - # The {bottom_margin} method returns the paper's bottom margin in document - # units. + # The {bottom_margin} method returns the paper's bottom margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -37,7 +36,7 @@ class Layout::PageInfo def bottom_margin end - # The {#bottom_margin=} method sets the paper's bottom margin in document units. + # The {#bottom_margin=} method sets the paper's bottom margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -114,7 +113,7 @@ def display_resolution def display_resolution=(resolution) end - # The {#height} method returns the paper height in document units. + # The {#height} method returns the paper height in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -126,7 +125,7 @@ def display_resolution=(resolution) def height end - # The {#height=} method sets the paper height in document units. + # The {#height=} method sets the paper height in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -212,7 +211,7 @@ def image_output_resolution def image_output_resolution=(resolution) end - # The {#left_margin} method returns the paper's left margin in document units. + # The {#left_margin} method returns the paper's left margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -224,7 +223,7 @@ def image_output_resolution=(resolution) def left_margin end - # The {#left_margin=} method sets the paper's left margin in document units. + # The {#left_margin=} method sets the paper's left margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -352,7 +351,7 @@ def print_paper_color=(print_paper_color) def print_paper_color? end - # The {#right_margin} method returns the paper's right margin in document units. + # The {#right_margin} method returns the paper's right margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -364,7 +363,7 @@ def print_paper_color? def right_margin end - # The {#right_margin=} sets the paper's right margin in document units. + # The {#right_margin=} sets the paper's right margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -403,7 +402,7 @@ def show_margins=(margins_visible) def show_margins? end - # The {#top_margin} method returns the paper's top margin in document units. + # The {#top_margin} method returns the paper's top margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -415,7 +414,7 @@ def show_margins? def top_margin end - # The {#top_margin} method sets the paper's top margin in document units. + # The {#top_margin} method sets the paper's top margin in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -430,7 +429,7 @@ def top_margin def top_margin=(margin) end - # The {#width} method returns the paper width in document units. + # The {#width} method returns the paper width in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") @@ -442,7 +441,7 @@ def top_margin=(margin) def width end - # The {#width=} method sets the paper width in document units. + # The {#width=} method sets the paper width in inches. # # @example # doc = Layout::Document.open("C:/path/to/document.layout") diff --git a/lib/sketchup-api-stubs/stubs/Layout/Pages.rb b/lib/sketchup-api-stubs/stubs/Layout/Pages.rb index fc057be..e9b0634 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Pages.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Pages.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Pages class is a container class for all pages in a {Layout::Document}. diff --git a/lib/sketchup-api-stubs/stubs/Layout/Path.rb b/lib/sketchup-api-stubs/stubs/Layout/Path.rb index 7aded8d..ebcb500 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Path.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Path.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A path entity represents a continuous, multi-segment polyline or bezier @@ -27,8 +27,8 @@ class Layout::Path < Layout::Entity # @example # center = Geom::Point2d.new(5, 5) # radius = 2.0 - # start_angle = 180.0 - # end_angle = 360.0 + # start_angle = 3.14159 + # end_angle = 6.28319 # arc = Layout::Path.new_arc(center, radius, start_angle, end_angle) # # @param [Geom::Point2d] center_point @@ -36,8 +36,10 @@ class Layout::Path < Layout::Entity # @param [Float] radius # # @param [Float] start_angle + # in radians # # @param [Float] end_angle + # in radians # # @raise [ArgumentError] if radius is less than or equal to zero # diff --git a/lib/sketchup-api-stubs/stubs/Layout/Rectangle.rb b/lib/sketchup-api-stubs/stubs/Layout/Rectangle.rb index 42bdea1..a781683 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Rectangle.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Rectangle.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A simple rectangular shape entity. diff --git a/lib/sketchup-api-stubs/stubs/Layout/ReferenceEntity.rb b/lib/sketchup-api-stubs/stubs/Layout/ReferenceEntity.rb index 791da14..8628398 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/ReferenceEntity.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/ReferenceEntity.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An entity that represents the data inserted from an external file. diff --git a/lib/sketchup-api-stubs/stubs/Layout/SketchUpModel.rb b/lib/sketchup-api-stubs/stubs/Layout/SketchUpModel.rb index d9c0a44..f22af24 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/SketchUpModel.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/SketchUpModel.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A SketchUp Model entity. This is an instance of a SketchUp Model that is diff --git a/lib/sketchup-api-stubs/stubs/Layout/Style.rb b/lib/sketchup-api-stubs/stubs/Layout/Style.rb index f55fcfa..f7c53dd 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Style.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Style.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # References a collection of style attributes that determine the visual @@ -102,6 +102,9 @@ class Layout::Style STROKE_PATTERN_SHORT_DASH = nil # Stub value. STROKE_PATTERN_SOLID = nil # Stub value. + STRIKETHROUGH_NONE = nil # Stub value. + STRIKETHROUGH_SINGLE = nil # Stub value. + SUPER_SCRIPT = nil # Stub value. SUB_SCRIPT = nil # Stub value. @@ -1471,6 +1474,49 @@ def text_italic def text_italic=(italic) end + # The {#text_strikethrough} method returns the text strike through type, or +nil+ if the + # {Layout::Style} does not have a value for that setting. + # + # The strikethrough type can be one of the following values: + # [+Layout::Style::STRIKETHROUGH_NONE+] + # [+Layout::Style::STRIKETHROUGH_SINGLE+] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # page = doc.pages.first + # entity = page.entities.first + # style = entity.style + # strikethrough_type = style.text_strikethrough + # + # @return [Integer, nil] + # + # @version LayOut 2026.0 + def text_strikethrough + end + + # The {#text_strikethrough=} method sets the text strike through type. + # + # The strikethrough type can be one of the following values: + # [+Layout::Style::STRIKETHROUGH_NONE+] + # [+Layout::Style::STRIKETHROUGH_SINGLE+] + # + # @example + # doc = Layout::Document.open("C:/path/to/document.layout") + # page = doc.pages.first + # entity = page.entities.first + # style = entity.style + # style.text_strikethrough = Layout::Style::STRIKETHROUGH_SINGLE + # # Set the style to apply changes + # entity.style = style + # + # @param [Integer] strikethrough_type + # + # @raise [ArgumentError] if strikethrough_type is not a valid strike through type + # + # @version LayOut 2026.0 + def text_strikethrough=(strikethrough_type) + end + # The {#text_underline} method returns the text underline type, or +nil+ if the # {Layout::Style} does not have a value for that setting. # diff --git a/lib/sketchup-api-stubs/stubs/Layout/Table.rb b/lib/sketchup-api-stubs/stubs/Layout/Table.rb index 6b77af5..2599450 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Table.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Table.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A {Layout::Table} is a series of rows and columns that holds data. diff --git a/lib/sketchup-api-stubs/stubs/Layout/TableCell.rb b/lib/sketchup-api-stubs/stubs/Layout/TableCell.rb index bb6f49c..ef813c3 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/TableCell.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/TableCell.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A {Layout::TableCell} is a single cell from a table that contains data. diff --git a/lib/sketchup-api-stubs/stubs/Layout/TableColumn.rb b/lib/sketchup-api-stubs/stubs/Layout/TableColumn.rb index 548a0cc..f7596d1 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/TableColumn.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/TableColumn.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A {Layout::TableColumn} is a single column from a table. diff --git a/lib/sketchup-api-stubs/stubs/Layout/TableRow.rb b/lib/sketchup-api-stubs/stubs/Layout/TableRow.rb index cc9282f..b8c812c 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/TableRow.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/TableRow.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A {Layout::TableColumn} is a single row from a table. diff --git a/lib/sketchup-api-stubs/stubs/Length.rb b/lib/sketchup-api-stubs/stubs/Length.rb index c05a0f8..8babe9e 100644 --- a/lib/sketchup-api-stubs/stubs/Length.rb +++ b/lib/sketchup-api-stubs/stubs/Length.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Because length units are used so often in SketchUp, a special class has been @@ -8,6 +8,8 @@ # 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. +# {Find more info about units and lengths in this +# article}[https://developer.sketchup.com/article-lengthsandunits]. # # The setting for the Length Format and Length Unit can be retrieved from the # {Sketchup::Model#options} by querying the +"UnitsOptions"+ @@ -56,6 +58,12 @@ # @note Prior to SketchUp 2015, +Length+ used to be derived from +Float+. This # is no longer the case. # +# @note When serializing a Length object to a string to save for later use, e.g. +# in a config file, first convert them to Float objects. The string representation +# of a Length is rounded and uses the local decimal separator which can lead to +# data loss and portability issues. The string representation is intended for +# humans, not computers. +# # @version SketchUp 6.0 class Length < Float diff --git a/lib/sketchup-api-stubs/stubs/Numeric.rb b/lib/sketchup-api-stubs/stubs/Numeric.rb index 678b154..1b75220 100644 --- a/lib/sketchup-api-stubs/stubs/Numeric.rb +++ b/lib/sketchup-api-stubs/stubs/Numeric.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A number of methods have been added to the Ruby Numeric class to do units diff --git a/lib/sketchup-api-stubs/stubs/Sketchup.rb b/lib/sketchup-api-stubs/stubs/Sketchup.rb index 1ee5dbe..882a841 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Sketchup module contains a number of important utility methods for use in @@ -22,10 +22,10 @@ # # Now that we have our handles, we can start pulling objects and making # # method calls that are useful. # first_entity = entities[0] -# UI.messagebox("First thing in your model is a " + first_entity.typename) +# puts "First thing in your model is a #{first_entity.typename}" # # number_materials = materials.length -# UI.messagebox("Your model has " + number_materials.to_s + " materials.") +# puts "Your model has #{number_materials} materials." # # new_edge = entities.add_line( [0,0,0], [500,500,0]) # @@ -43,7 +43,7 @@ module Sketchup # @example # model = Sketchup.active_model # if !model - # UI.messagebox("Failure") + # puts "Failure" # else # # code acting on the model # end @@ -221,12 +221,12 @@ def self.file_new # help_file = Sketchup.find_support_file("help.html", "Plugins/") # if help_file # # Print out the help_file full path - # UI.messagebox(help_file) + # puts help_file # # # Open the help_file in a web browser # UI.openURL("file://" + help_file) # else - # UI.messagebox("Failure") + # puts "Failure" # end # # @param [String] filename @@ -388,7 +388,7 @@ def self.format_length(*args) # # @example # number = 3.m * 4.m * 5.m # This will result in 60m3 in inches. - # formatted_volume = Sketchup.format_area(number) + # formatted_volume = Sketchup.format_volume(number) # # @param [Numeric] number # A number to be formatted. @@ -514,9 +514,9 @@ def self.get_shortcuts # begin # Sketchup.install_from_archive(path) # rescue Interrupt => error - # UI.messagebox("User said 'no': " + error) + # puts "User said 'no': #{error}" # rescue Exception => error - # UI.messagebox("Error during unzip: " + error) + # puts "Error during unzip: #{error}" # end # # @param [String] filepath @@ -577,7 +577,7 @@ def self.is_online # # @example # if Sketchup.is_pro? - # UI.messagebox("You are running SU Pro.") + # puts "You are running SU Pro." # end # # @note In SketchUp Make this method will return +true+ during the Pro trial @@ -604,13 +604,17 @@ def self.is_pro? def self.is_valid_filename?(filename) end - # The load method is used to include encrypted and nonencrypted ruby files. + # The {.load} method is used to load Ruby files. + # Unlike Ruby's own +load+ method it also supports SketchUp's encrypted .rbe files. # - # You do not need to include the file extension on the path. This method will + # You do not need to include the file extension in the path. This method will # look for .rb first (unencrypted) and then .rbe (encrypted) and finally .rbs # (the deprecated scrambled format) files. # See the "Distributing your Plugin" article for details. # + # @bug Unlike Ruby's +load+ method, this method currently can't load the same file twice. + # Instead works similar to Ruby's `require` method. + # # @example # sfile = "application_loader" # file extension not required # status = Sketchup.load(sfile) @@ -655,6 +659,19 @@ def self.load(path) # @return [Integer, false] status code if opening with +with_status+ set to +true+, # otherwise +true+ or +false+. # + # @overload open_file(filename, with_status: true, show_version_warning_dialog: true) + # + # Starting with SketchUp 2026.0 SketchUp we added control over displaying the + # messages about version compatibility. + # + # @version SketchUp 2026.0 + # @param [String] filename The model file to open. + # @param [Boolean] with_status + # @param [Boolean] show_version_warning_dialog by default set to true and will display the dialog + # box + # @return [Integer, false] status code if opening with +with_status+ set to +true+, + # otherwise +true+ or +false+. + # # @version SketchUp 6.0 def self.open_file(*args) end @@ -768,13 +785,18 @@ def self.plugins_disabled? def self.quit end - # The read_default method is used to retrieve the string associated with a + # The {.read_default} method is used to retrieve the string associated with a # value within the specified sub-section section of a .INI file or registry # (within the Software > SketchUp > SketchUp [Version] section). # # @example # result = Sketchup.read_default("section", "variable", "default") # + # @note Be aware that the method is not capable of handling Length objects. You + # can convert the value to a Float before writing and convert back to Length when + # reading the value. Don't store the value as a String as this rounds the value and formats it + # in a way that can't be read if the system setting for decimal separator changes. + # # @param [String] section # A section in an .INI or registry. # @@ -802,8 +824,8 @@ def self.read_default(section, variable, default = nil) def self.redo end - # The register_extension method is used to register an extension with - # SketchUp's extension manager (in SketchUp preferences). + # The {.register_extension} method is used to register an extension with + # SketchUp's Extension Manager. # # @example # utilities_extension = SketchupExtension.new("Utilities Tools", @@ -862,10 +884,10 @@ def self.register_importer(importer) def self.remove_observer(observer) end - # The require method is used to include encrypted and nonencrypted ruby files. - # This is an alias of the Sketchup.load method. + # The {.require} method is used to load Ruby files once. + # Unlike Ruby's own +require+ method it also supports SketchUp's encrypted .rbe files. # - # You do not need to include the file extension on the path. This method will + # You do not need to include the file extension in the path. This method will # look for .rbe first (encrypted) and then .rbs (the deprecated scrambled # format) and finally .rb (unencrypted) files. The loading order was changed # in SketchUp 2016 when the new .rbe encryption was introduced. Prior to @@ -892,10 +914,14 @@ def self.require(path) # # @bug In SketchUp 2023.1 this method didn't behave correctly on Windows. No known workarounds. # - # @example + # @example Physical pixels # model = Sketchup.active_model # Sketchup.resize_viewport(model, 800, 600) # + # @example Logical pixels + # model = Sketchup.active_model + # Sketchup.resize_viewport(model, 800, 600, logical_pixels: true) + # # @note In SketchUp 2024.0 and later this method doesn't behave correctly in all cases on Windows. # The passed values are internally converted to logical pixels, rounded and converted back to # physical pixels. This means certain sizes, such as 1000 px at 150% scaling, cannot be @@ -910,13 +936,19 @@ def self.require(path) # ((1500/1.5).round * 1.5).round # => 1500 # ((1500/1.25).round * 1.25).round # => 1500 # - # @param [Sketchup::Model] model + # @overload resize_viewport(model, width, height) + # + # @param [Sketchup::Model] model + # @param [Integer] width Width in physical pixels + # @param [Integer] height Height in physical pixels # - # @param [Integer] width - # Width in physical pixels + # @overload resize_viewport(model, width, height, logical_pixels: false) # - # @param [Integer] height - # Height in physical pixels + # @version SketchUp 2025.0 + # @param [Sketchup::Model] model + # @param [Integer] width + # @param [Integer] height + # @param [Boolean] logical_pixels Set to true to set size using logical pixels. # # @return [Boolean] +true+ on success. +false+ if the window couldn't reach the desired size, # e.g. because it wouldn't fit the screen. @@ -925,8 +957,10 @@ def self.require(path) # # @see Sketchup::View#vpheight # + # @see UI.scale_factor + # # @version SketchUp 2023.0 - def self.resize_viewport(model, width, height) + def self.resize_viewport(*args) end # The save_thumbnail method is used to generate a thumbnail for any SKP file - @@ -1059,7 +1093,7 @@ def self.save_thumbnail(skp_filename, img_filename) # - 10546: toggle Shadows toolbar # - 10551: toogle Large icons # - 10576: toggle Render Mode toolbar - # - 21019: hide Status bar and VCB + # - 21019: select the Eraser tool # - 21020: show Status bar and VCB # - 21022: hide Status bar and VCB # - 21023: place 3d text box @@ -1179,9 +1213,9 @@ def self.send_to_layout(file) # If no arguments are passed, the status bar content is cleared. Valid # positions are: # - # - +SB_PROMPT+ - the text will appear at the left-side of the status bar - # - +SB_VCB_LABEL+ - the text will appear in place of the VCB label - # - +SB_VCB_VALUE+ - the text will appear in the VCB + # - {SB_PROMPT} - the text will appear at the left-side of the status bar + # - {SB_VCB_LABEL} - the text will appear in place of the VCB label + # - {SB_VCB_VALUE} - the text will appear in the VCB # # @example # result = Sketchup.set_status_text("This is a Test", SB_VCB_VALUE) @@ -1328,11 +1362,6 @@ def self.vcb_value=(value) # # @example # version = Sketchup.version - # if (version) - # UI.messagebox version - # else - # return - # end # # @return [String] the decimal form of the version # @@ -1364,10 +1393,10 @@ def self.version # @return [Integer] the whole number form of the version # # @version SketchUp 6.0 - def self.version_number(*args) + def self.version_number end - # The write_default method is used to set the string associated with a + # The {.write_default} method is used to set the string associated with a # variable within the specified sub-section of a .plist file on the Mac # or the registry on Windows # (within the Software > SketchUp > SketchUp [Version] section). @@ -1375,6 +1404,12 @@ def self.version_number(*args) # @example # result = Sketchup.write_default("section", "key", "my_value") # + # @note Be aware that the method is not capable of handling Length objects. + # You can convert the value to a Float before writing and convert back to Length + # when reading the value. Don't store the value as a String as this rounds the + # value and formats it in a way that can't be read if the system setting for + # decimal separator changes. + # # @param [String] section # A section in a .plist file (Mac) or the registry # (Windows). diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Animation.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Animation.rb index 931fe55..924f9cc 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Animation.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Animation.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::Animation} interface is implemented to create animations @@ -6,24 +6,47 @@ # {Sketchup::View}. To make your own, build a Ruby class that contains the # methods described below: # -# # This is an example of a simple animation that floats the camera up to -# # a z position of 200". The only required method for an animation is -# # nextFrame. It is called whenever you need to show the next frame of -# # the animation. If nextFrame returns false, the animation will stop. -# class FloatUpAnimation +# # This example demonstrates a simple animation with implementation of +# # the optional callback method stop, which is invoked +# # by SketchUp during specific animation events. +# class SimpleFloatAnimation +# def initialize +# @speed = 1.0 # Camera movement speed +# puts "Animation initialized" +# end +# +# # Required method - called for each animation frame # def nextFrame(view) +# # Move camera upward # new_eye = view.camera.eye -# new_eye.z = new_eye.z + 1.0 +# new_eye.z = new_eye.z + @speed # view.camera.set(new_eye, view.camera.target, view.camera.up) # view.show_frame +# +# # Continue animation until reaching maximum height # return new_eye.z < 500.0 # end -# end # -# # This adds an item to the Camera menu to activate our custom animation. -# UI.menu("Camera").add_item("Run Float Up Animation") { -# Sketchup.active_model.active_view.animation = FloatUpAnimation.new -# } +# # Optional callback - called by SketchUp when animation is stopped +# # Note: This method is called automatically by SketchUp and cannot +# # be called directly to stop an animation +# def stop +# puts "Animation was stopped by SketchUp" +# # Cleanup code when animation ends +# end +# end +# +# # Add menu item to start the animation +# UI.menu("Camera").add_item("Start Animation") { +# animation = SimpleFloatAnimation.new +# Sketchup.active_model.active_view.animation = animation +# } +# +# # To stop the animation programmatically: +# UI.menu("Camera").add_item("Stop Animation") { +# # Setting animation to nil will trigger the stop method in our animation class +# Sketchup.active_model.active_view.animation = nil +# } # # {Sketchup::Animation} objects are activated by using the # {Sketchup::View#animation=} method on a {Sketchup::View} @@ -32,6 +55,35 @@ # # Sketchup.active_model.active_view.animation = nil # +# +# ==Managing Multiple Animations: +# +# While only one animation object can be active on a {Sketchup::View} at any +# given time, you can create a composite animation class to manage multiple +# animations simultaneously. This approach allows you to animate different +# elements, such as objects and the camera, within a single animation framework. +# +# Example: Combining Animations +# +# class CombinedAnimation +# def initialize(object_animation, camera_animation) +# @object_animation = object_animation +# @camera_animation = camera_animation +# end +# +# def nextFrame(view) +# @object_animation.nextFrame(view) +# @camera_animation.nextFrame(view) +# true +# end +# end +# +# # Usage +# object_animation = RotateAnimation.new +# camera_animation = RotateCamera.new(0.01) +# combined_animation = CombinedAnimation.new(object_animation, camera_animation) +# Sketchup.active_model.active_view.animation = combined_animation +# # @abstract Implement the methods described in this class to create a an # animation. You can not sub-class this class because it is not defined by # the API. @@ -131,7 +183,7 @@ def resume # end # end # - # @note Do not call {#Sketchup::View#animation=} from this method. This will + # @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+. # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/AppObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/AppObserver.rb index cf0c058..cda72e5 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/AppObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/AppObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to application events. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ArcCurve.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ArcCurve.rb index 4b48b68..ee6e6be 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ArcCurve.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ArcCurve.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An ArcCurve is a Curve that makes up part of a circle. This is the diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionaries.rb b/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionaries.rb index d69f030..b635810 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionaries.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionaries.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The AttributeDictionaries class is a collection of all of the @@ -33,14 +33,9 @@ class Sketchup::AttributeDictionaries < Sketchup::Entity # # @example # model = Sketchup.active_model + # value = model.set_attribute("my_dictionary", "test", 110) # attrdicts = model.attribute_dictionaries - # # Iterates through all dictionaries and prints to screen. # dict = attrdicts['my_dictionary'] - # if dict - # UI.messagebox("Found: " + dict.to_s) - # else - # UI.messagebox("No dictionary found.") - # end # # @param [String] key # The name of the attribute dictionary. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionary.rb b/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionary.rb index b4a0ac8..a20f8e5 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionary.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionary.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The AttributeDictionary class allows you to attach arbitrary collections of @@ -185,6 +185,20 @@ def each_key def each_pair end + # The {#empty?} method is used to check if the attribute dictionary is empty. + # + # @example + # model = Sketchup.active_model + # attribute_dictionary = model.attribute_dictionary("example", true) + # attribute_dictionary["attribute_one"] = "1" + # attribute_dictionary.empty? # Returns false + # + # @return [Boolean] true if the attribute dictionary is empty, false otherwise + # + # @version SketchUp 2025.0 + def empty? + end + # The keys method is used to retrieve an array with all of the attribute keys. # # @example @@ -231,8 +245,7 @@ def length # attrdict["attr_one"] = "one" # attrdict["attr_two"] = "two" # - # # Show the name. - # UI.messagebox attrdict.name + # puts attrdict.name # # @return [String] the name of the attribute dictionary if # successful diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Axes.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Axes.rb index ae9818c..6693e84 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Axes.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Axes.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # SketchUp's drawing axes consist of three colored lines (red, green, blue), @@ -29,18 +29,18 @@ class Sketchup::Axes < Sketchup::Entity def axes end - # The origin method returns the origin of the axes. + # The {#origin} method returns the origin of the axes. # # @example # point = Sketchup.active_model.axes.origin # - # @return Point3d - the origin for the axes. + # @return [Geom::Point3d] # # @version SketchUp 2016 def origin end - # The set method allows the axes to be manipulated. The axes must always be + # The {#set} method allows the axes to be manipulated. The axes must always be # orthogonal, otherwise an error is thrown. # # @example @@ -60,7 +60,7 @@ def origin # @param zaxis # Vector3d - The z axis to set. # - # @return Axes - the axes object being set. + # @return [Sketchup::Axes] - the axes object being set. # # @version SketchUp 2016 def set(origin, xaxis, yaxis, zaxis) @@ -90,7 +90,7 @@ def sketch_plane def to_a end - # The transformation method returns the transformation of the axes. This is + # The {#transformation} method returns the transformation of the axes. This is # useful when creating tools that respect the model's drawing axes. # # @example @@ -107,40 +107,40 @@ def to_a # points.each { |point| point.transform!(tr) } # Sketchup.active_model.active_entities.add_face(points) # - # @return Transformation - the transformation for the axes. + # @return [Geom::Transformation] - the transformation for the axes. # # @version SketchUp 2016 def transformation end - # The xaxis method returns the x axis of the axes. + # The {#xaxis} method returns the x axis of the axes. # # @example # vector = Sketchup.active_model.axes.xaxis # - # @return Vector3d - the x axis for the axes. + # @return [Geom::Vector3d] - the x axis for the axes. # # @version SketchUp 2016 def xaxis end - # The yaxis method returns the y axis of the axes. + # The {#yaxis} method returns the y axis of the axes. # # @example # vector = Sketchup.active_model.axes.yaxis # - # @return Vector3d - the y axis for the axes. + # @return [Geom::Vector3d] - the y axis for the axes. # # @version SketchUp 2016 def yaxis end - # The zaxis method returns the z axis of the axes. + # The {#zaxis} method returns the z axis of the axes. # # @example # vector = Sketchup.active_model.axes.zaxis # - # @return Vector3d - the z axis for the axes. + # @return [Geom::Vector3d] - the z axis for the axes. # # @version SketchUp 2016 def zaxis diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Behavior.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Behavior.rb index 016c096..e0457a2 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Behavior.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Behavior.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Behavior class is used to control the "behavior" of components, which @@ -52,26 +52,20 @@ def always_face_camera=(setting) # definitions = model.definitions # path = Sketchup.find_support_file "Bed.skp", # "Components/Components Sampler/" - # - # begin - # definition = definitions.load path - # rescue - # UI.messagebox $!.message - # end - # + # definition = definitions.load path # behavior = definition.behavior # b = behavior.always_face_camera? # if (b) - # UI.messagebox b + # puts "Component faces camera" # else - # UI.messagebox "Always Face Camera is equal to false" + # puts "Component does not face camera" # end # status = behavior.always_face_camera = true # b = behavior.always_face_camera? # if (b) - # UI.messagebox b + # puts "Alwas Face Camera is equal to true" # else - # UI.messagebox "Failure" + # puts "Failure" # end # # @return [Boolean] behavior - true if the component is set to always face @@ -236,8 +230,8 @@ def shadows_face_sun=(status) # "Components/Components Sampler/" # begin # definition = definitions.load path - # rescue - # UI.messagebox $!.message + # rescue => exception + # puts exception.message # end # # @return [Boolean] status - true if the component's is to be cast from the diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Camera.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Camera.rb index 66212e5..9336042 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Camera.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Camera.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Camera class contains methods for creating and manipulating a camera. @@ -66,7 +66,7 @@ def aspect_ratio=(ratio) # @example # Sketchup.active_model.active_view.camera.center_2d # - # @return [Geom::Point3d] ] + # @return [Geom::Point3d] # # @version SketchUp 2015 def center_2d @@ -312,8 +312,8 @@ def image_width=(image_width) def initialize(*args) end - # The {#is_2d?} method indicates if the camera two-point perspective or match photo - # mode. + # The {#is_2d?} method indicates whether the camera mode is two-point perspective or match photo + # mode, as opposed to a normal perspective or parallel projection camera. # # @example # Sketchup.active_model.active_view.camera.is_2d? @@ -365,7 +365,7 @@ def perspective? # @example # Sketchup.active_model.active_view.camera.scale_2d # - # @return float + # @return [Float] # # @version SketchUp 2015 def scale_2d @@ -388,7 +388,7 @@ def scale_2d # @param [Geom::Point3d] target # See {#target}. # - # @param [Geom::Point3d] up + # @param [Geom::Vector3d] up # See {#up}. # # @return [Sketchup::Camera] @@ -432,7 +432,7 @@ def up # camera = Sketchup::Camera.new # xaxis = camera.xaxis # - # @return [Geom::Vector3d] ] + # @return [Geom::Vector3d] # # @version SketchUp 6.0 def xaxis @@ -449,7 +449,7 @@ def xaxis # # 0.0, 1.0, 0.0 # yaxis = camera.yaxis # - # @return [Geom::Vector3d] ] + # @return [Geom::Vector3d] # # @version SketchUp 6.0 def yaxis @@ -462,14 +462,9 @@ def yaxis # @example # camera = Sketchup::Camera.new # # 0.0, 1.0, 0.0 - # v = camera.zaxis - # if (v) - # UI.messagebox v.to_s - # else - # UI.messagebox "Failure" - # end + # vector = camera.zaxis # - # @return vector - a Vector3d object if successful + # @return [Geom::Vector3d] # # @version SketchUp 6.0 def zaxis diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ClassificationSchema.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ClassificationSchema.rb index 579a883..91a7407 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ClassificationSchema.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ClassificationSchema.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The ClassificationSchema class represent schemas loaded in the model. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Classifications.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Classifications.rb index d080543..e8b3c03 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Classifications.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Classifications.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Classifications class is a container/manager for all classifications in @@ -77,7 +77,7 @@ def length # # @example # c = Sketchup.active_model.classifications - # file = Sketchup.find_support_file('IFC 4.skc', 'Classifications') + # file = Sketchup.find_support_file('IFC4.skc', 'Classifications') # status = c.load_schema(file) if !file.nil? # # @param file diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Color.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Color.rb index 71111ea..5c50719 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Color.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Color.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Color class is used to create and manipulate colors within SketchUp diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb index 16363c0..81462df 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::ComponentDefinition} class is used to define the contents for @@ -37,7 +37,7 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement # c2=Sketchup.find_support_file "Fence.skp", # "Components/Components Sampler/" # if c1 <=> c2 - # UI.messagebox("c1 sorts before c2") + # puts "c1 sorts before c2" # end # # @param [Sketchup::ComponentDefinition] compdef2 @@ -58,9 +58,7 @@ def <=>(compdef2) # "Components/Components Sampler/" # c2=Sketchup.find_support_file "Fence.skp", # "Components/Components Sampler/" - # if c1 == c2 - # UI.messagebox("These definitions are the same.") - # end + # c1 == c2 # # @param [Sketchup::ComponentDefinition] compdef2 # The second component definition in the comparison. @@ -258,8 +256,15 @@ def group? def guid end - # The hidden method is used to determine if this component definition should - # be hidden on the component browser. + # The {#hidden?} method is used to determine if this component definition is + # hidden in the component browser. + # + # This is based on how its instances are placed + # in the model hierarchy. For more details, see + # {this article}[https://developer.sketchup.com/article-hiddensubcomponents]. + # + # In addition, component definitions used by Groups and Images are always hidden + # in the Component Browser. See {#group?} and {#image?}. # # @example # componentdefinition = Sketchup.active_model.definitions[0] @@ -277,12 +282,6 @@ def hidden? # @example # componentdefinition = Sketchup.active_model.definitions[0] # status = componentdefinition.image? - # if (status) - # UI.messagebox "Component definition defines an image" - # else - # UI.messagebox status.to_s - # UI.messagebox "Component definition does not define an image" - # end # # @return [Boolean] # @@ -408,6 +407,21 @@ def invalidate_bounds def live_component? end + # The {#load_time} method gets the load time of the component definition. For an internal + # component definition, this is the time that it was created. For an external component + # definition, this is the time that it was added to the model. + # + # @example + # model = Sketchup.active_model + # definition = model.definitions.first + # definition.load_time + # + # @return [Time] + # + # @version SketchUp 2025.0 + def load_time + end + # The name method retrieves the name of the component definition. # # @example @@ -542,7 +556,7 @@ def remove_observer(observer) # See {Sketchup::Model#save} for supported values. # @version SketchUp 2022.0 # - # @return [Boolean] true if successful + # @return [Boolean] true if successful, false otherwise def save_as(*args) end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb index a21b408..b0448df 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::ComponentInstance} class is used to represent component @@ -109,12 +109,8 @@ def equals?(instance) # # @example # # Assuming 'instance' is a ComponentInstance object - # array = instance.explode - # if array - # UI.messagebox "Exploded the component instance" - # else - # UI.messagebox "Failure" - # end + # instance = Sketchup.active_model.active_entities.grep(Sketchup::ComponentInstance).first + # entities = instance.explode # # @return [Array, false] An array of entity objects if successful, +false+ if # unsuccessful @@ -519,13 +515,19 @@ def transformation # new_transformation = Geom::Transformation.new([100,0,0]) # componentinstance.transformation = new_transformation # + # @note As of SketchUp 2026, this will raise an error if the + # {Geom::Transformation} is not invertible. Prior to 2026 this would silently set the + # transformation possibly causing rendering or editing problems. + # # @param [Geom::Transformation] transformation # + # @raise ArgumentError if the {Geom::Transformation} is not invertible (as of Sketchup 2026) + # # @version SketchUp 6.0 def transformation=(transformation) end - # The trim method is used to compute the (non-destructive) boolean difference + # The {#trim} method is used to compute the (non-destructive) boolean difference # of the two instances representing manifold solid volumes (this - arg). If # the specified objects (this and arg) do not represent manifold volumes, this # method fails. @@ -536,6 +538,11 @@ def transformation=(transformation) # instance2 = entities[1] # result = instance1.trim(instance2) # + # @note Trimming object instance2 using instance1 results in a new trimmed version of instance2. + # If the trim is successful the original instance2 is erased and a newly trimmed + # version is created. This new version, derived from the trimming operation, + # will possess a new GUID and will be returned. + # # @note This method is not available in SketchUp Make. # # @param [Sketchup::ComponentInstance] instance diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Console.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Console.rb index 82553d6..fecdc30 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Console.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Console.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Console class is used by SketchUp to direct $stdout and $stderr to the diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionLine.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionLine.rb index e0d4467..a4e8ec4 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionLine.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionLine.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The ConstructionLine class contains methods for modifying construction @@ -20,11 +20,6 @@ class Sketchup::ConstructionLine < Sketchup::Drawingelement # point2 = Geom::Point3d.new(20,20,20) # constline = entities.add_cline(point1, point2) # vector = constline.direction - # if (vector) - # UI.messagebox(vector) - # else - # UI.messagebox("Failure") - # end # # @return vector - a Vector3d object if successful # @@ -83,12 +78,12 @@ def end # @example # model = Sketchup.active_model # entities = model.active_entities - # point1 = Geom::Point3d.new(0,0,0) - # point2 = Geom::Point3d.new(20,20,20) - # point3 = Geom::Point3d.new(10,10,10) + # point1 = Geom::Point3d.new(0, 0, 0) + # point2 = Geom::Point3d.new(20, 20, 20) + # point3 = Geom::Point3d.new(10, 10, 10) # constline = entities.add_cline(point1, point2) - # UI.messagebox(constline.end) - # # Will display point2 + # constline.end = point3 + # # Will shorten the line to [10, 10, 10] # # @overload end=(point) # @@ -225,7 +220,7 @@ def start=(arg) # constline = entities.add_cline(point1, point2) # puts constline.stipple # - # @return [String] + # @return [Integer] # # @version SketchUp 6.0 def stipple diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionPoint.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionPoint.rb index b5c06c3..969a9ed 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionPoint.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionPoint.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A construction point represents a point in the model that can be used to aid diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Curve.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Curve.rb index 65e2565..49e68c6 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Curve.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Curve.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Curve class is used by SketchUp to unite a series of Edge objects into diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionList.rb b/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionList.rb index 74e2e4f..dd84fad 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionList.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionList.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A DefinitionList object holds a list of all of the ComponentDefinition @@ -145,7 +145,7 @@ def count # 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] + # @return [Sketchup::ComponentDefinition] # # @version SketchUp 6.0 # @@ -233,7 +233,7 @@ def length # @param [String] path # The path where the component definition file is located. # - # @overload load(path, allow_newer: true) + # @overload load(path, allow_newer: false) # # Starting with SketchUp 2021.0 SketchUp attempts to load newer SketchUp # models. If a newer model is loaded some information might have been skipped @@ -268,13 +268,7 @@ def load(*args) # # This method throws an exception if an url string is not # given, or an error occurs during retrieval from URL and a - # +load_handler+ was not given. Optional second parameter +load_handler+ can be - # used to pass in a Ruby object that responds to the following methods: - # - # - +cancelled?+ - # - +onPercentChange(percent)+ - # - +onSuccess()+ - # - +onFailure(message_string)+ + # {Sketchup::LoadHandler load_handler} was not given. # # @bug Calling this method from an {UI::HtmlDialog}'s action callback on macOS will cause the # SketchUp application to become unresponsive or crash. To work around this, defer the call diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionObserver.rb index b20991e..35ea1f0 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to component definition diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionsObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionsObserver.rb index 8039164..a2a53a5 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionsObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionsObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to events on a definitions diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Dimension.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Dimension.rb index 1bf68d5..55ec41a 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Dimension.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Dimension.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Dimension class provides base functionality for classes DimensionLinear @@ -38,13 +38,14 @@ class Sketchup::Dimension < Sketchup::Drawingelement def add_observer(observer) end - # The arrow_type method retrieves the current arrow type of the dimension. - # Valid arrow types are class constants: - # - +Dimension::ARROW_NONE,+ - # - +Dimension::ARROW_SLASH+ - # - +Dimension::ARROW_DOT+ - # - +Dimension::ARROW_CLOSED+ - # - +Dimension::ARROW_OPEN+ + # The {#arrow_type} method retrieves the current arrow type of the dimension. + # + # Valid arrow types are: + # - {Sketchup::Dimension::ARROW_NONE} + # - {Sketchup::Dimension::ARROW_SLASH} + # - {Sketchup::Dimension::ARROW_DOT} + # - {Sketchup::Dimension::ARROW_CLOSED} + # - {Sketchup::Dimension::ARROW_OPEN} # # @example # type = dim.arrow_type @@ -58,13 +59,14 @@ def add_observer(observer) def arrow_type end - # The arrow_type= method sets the arrow type of the dimension. - # Valid arrow types are class constants: - # - +Dimension::ARROW_NONE,+ - # - +Dimension::ARROW_SLASH+ - # - +Dimension::ARROW_DOT+ - # - +Dimension::ARROW_CLOSED+ - # - +Dimension::ARROW_OPEN+ + # The {#arrow_type=} method sets the arrow type of the dimension. + # + # Valid arrow types are: + # - {Sketchup::Dimension::ARROW_NONE} + # - {Sketchup::Dimension::ARROW_SLASH} + # - {Sketchup::Dimension::ARROW_DOT} + # - {Sketchup::Dimension::ARROW_CLOSED} + # - {Sketchup::Dimension::ARROW_OPEN} # # @example # dim.arrow_type = Sketchup::Dimension::ARROW_CLOSED diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/DimensionLinear.rb b/lib/sketchup-api-stubs/stubs/Sketchup/DimensionLinear.rb index 4f02fae..0f6f1b7 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/DimensionLinear.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/DimensionLinear.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The DimensionLinear class represents linear dimensions. @@ -18,12 +18,12 @@ class Sketchup::DimensionLinear < Sketchup::Dimension # Instance Methods - # The aligned_text_position method returns the text position for dimensions + # The {#aligned_text_position} method returns the text position for dimensions # with aligned text (i.e. has_aligned_text? returns true). # Valid values are class constants: - # - DimensionLinear::ALIGNED_TEXT_ABOVE - # - DimensionLinear::ALIGNED_TEXT_CENTER - # - DimensionLinear::ALIGNED_TEXT_OUTSIDE + # - {Sketchup::DimensionLinear::ALIGNED_TEXT_ABOVE} + # - {Sketchup::DimensionLinear::ALIGNED_TEXT_CENTER} + # - {Sketchup::DimensionLinear::ALIGNED_TEXT_OUTSIDE} # # @example # pos = dim.aligned_text_position @@ -41,12 +41,12 @@ class Sketchup::DimensionLinear < Sketchup::Dimension def aligned_text_position end - # The aligned_text_position= method is used to set the text position for + # The {#aligned_text_position=} method is used to set the text position for # dimensions with aligned text (i.e. has_aligned_text? returns true). # Valid values are class constants: - # - DimensionLinear::ALIGNED_TEXT_ABOVE - # - DimensionLinear::ALIGNED_TEXT_CENTER - # - DimensionLinear::ALIGNED_TEXT_OUTSIDE + # - {Sketchup::DimensionLinear::ALIGNED_TEXT_ABOVE} + # - {Sketchup::DimensionLinear::ALIGNED_TEXT_CENTER} + # - {Sketchup::DimensionLinear::ALIGNED_TEXT_OUTSIDE} # # @example # dim.aligned_text_position = Sketchup::DimensionLinear::ALIGNED_TEXT_CENTER @@ -263,11 +263,11 @@ def start_attached_to def start_attached_to=(path) end - # The text_position method returns the position of the text along the dimension + # The {#text_position} method returns the position of the text along the dimension # line. Valid values are class constants: - # - DimensionLinear::TEXT_OUTSIDE_START - # - DimensionLinear::TEXT_CENTERED - # - DimensionLinear::TEXT_OUTSIDE_END + # - {Sketchup::DimensionLinear::TEXT_OUTSIDE_START} + # - {Sketchup::DimensionLinear::TEXT_CENTERED} + # - {Sketchup::DimensionLinear::TEXT_OUTSIDE_END} # # @example # pos = dim.text_position @@ -285,11 +285,11 @@ def start_attached_to=(path) def text_position end - # The text_position= method is used to set the position of the text along the + # The {#text_position=} method is used to set the position of the text along the # dimension line. Valid values are class constants: - # - DimensionLinear::TEXT_OUTSIDE_START - # - DimensionLinear::TEXT_CENTERED - # - DimensionLinear::TEXT_OUTSIDE_END + # - {Sketchup::DimensionLinear::TEXT_OUTSIDE_START} + # - {Sketchup::DimensionLinear::TEXT_CENTERED} + # - {Sketchup::DimensionLinear::TEXT_OUTSIDE_END} # # @example # dim.text_position = Sketchup::DimensionLinear::TEXT_CENTERED diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/DimensionObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/DimensionObserver.rb index e17b230..7876b33 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/DimensionObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/DimensionObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to changes in dimension text. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/DimensionRadial.rb b/lib/sketchup-api-stubs/stubs/Sketchup/DimensionRadial.rb index 429e97e..921bdf7 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/DimensionRadial.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/DimensionRadial.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The DimensionRadial class represents radius and diameter dimensions on @@ -37,7 +37,7 @@ def arc_curve def arc_curve=(arc_curve) end - # The leader_break_point method returns the break point on the leader where the + # The {#leader_break_point} method returns the break point on the leader where the # dimension text is attached. # # @example @@ -50,7 +50,7 @@ def arc_curve=(arc_curve) def leader_break_point end - # The leader_break_point= method is used to set the break point on the leader + # The {#leader_break_point=} method is used to set the break point on the leader # where the dimension text is attached. # # @example diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Drawingelement.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Drawingelement.rb index 18511a8..ac2bb95 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Drawingelement.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Drawingelement.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Drawingelement is a base class for an item in the model that can be @@ -60,7 +60,6 @@ def bounds # # # Make the face not cast shadows. # status = face.casts_shadows = false - # UI.messagebox status.to_s # # @param [Boolean] casts # true if you want the Drawingelement object to cast @@ -89,7 +88,6 @@ def casts_shadows=(casts) # # Add the face to the entities in the model # face = entities.add_face pts # status = face.casts_shadows? - # UI.messagebox status.to_s # # @return [Boolean] # @@ -176,7 +174,6 @@ def hidden=(hidden) # # Add the face to the entities in the model # face = entities.add_face pts # status = face.hidden? - # UI.messagebox "hidden? " + status.to_s # # @return [Boolean] # @@ -281,8 +278,8 @@ def material # # Returns nil if not successful, path if successful. # # Should return a texture object. # m.texture = "c:\\My Textures\\Carpet.jpg" - # rescue - # UI.messagebox $!.message + # rescue => exception + # puts exception.message # end # # You will see the material applied when you reverse the box's faces # material = face.material = m @@ -315,7 +312,6 @@ def material=(material) # # # Make the face not receive shadows. # status = face.receives_shadows = false - # UI.messagebox status.to_s # # @param [Boolean] receive # true if you want the Drawingelement object to @@ -343,7 +339,6 @@ def receives_shadows=(receive) # # Add the face to the entities in the model # face = entities.add_face pts # status = face.receives_shadows? - # UI.messagebox status.to_s # # @return [Boolean] # @@ -351,7 +346,7 @@ def receives_shadows=(receive) def receives_shadows? end - # The visible= method is used to set the visible status for an element. This + # The {#visible=} method is used to set the visible status for an element. This # method performs an opposite function to the hidden= method. # # @example @@ -370,16 +365,16 @@ def receives_shadows? # status = face.visible = false # # @param [Boolean] visibility - # true if you want to hide the element, false if not - # - # @return [Boolean] true if the element has been hidden, false if - # the element has not been hidden. + # true if you want to make the element visible, false if not # # @version SketchUp 6.0 def visible=(visibility) end - # The visible? method is used to get the visible status for an element. + # The {#visible?} method checks if a Drawingelement object is not explicitly hidden (i.e. its + # hidden property is false). However, this method's return value alone does not guarantee that the + # element is visible in the model view. Its tag or parent elements can also be hidden. Some element + # types can also be hidden by rendering options (Styles). # # @example # depth = 100 @@ -399,6 +394,8 @@ def visible=(visibility) # # @return [Boolean] # + # @see Sketchup::Model#drawing_element_visible? + # # @version SketchUp 6.0 def visible? end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Edge.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Edge.rb index fbed646..cfe10a3 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Edge.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Edge.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Edge class contains methods modifying and extracting information for @@ -324,7 +324,7 @@ def soft=(value) def soft? end - # The split method is used to to split an edge into two or more distinct + # The {#split} method is used to split an edge into two or more distinct # edges. If a Point3d is given, it must be a point that is on the Edge. # # If a Float is given, it is a number between 0 and 1 that gives the diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/EdgeUse.rb b/lib/sketchup-api-stubs/stubs/Sketchup/EdgeUse.rb index 6a4d442..ed3ff9d 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/EdgeUse.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/EdgeUse.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The EdgeUse class defines how an Edge is used in the definition of a Face. @@ -23,7 +23,7 @@ class Sketchup::EdgeUse < Sketchup::Entity # edgeuse = edgeuses[0] # edge = edgeuse.edge # - # @return edge - an Edge object used by this edge use + # @return [Sketchup::Edge] an Edge object used by this edge use # # @version SketchUp 6.0 def edge @@ -45,7 +45,7 @@ def edge # edgeuse = edgeuses[0] # vector3d = edgeuse.end_vertex_normal # - # @return vector3d - a vector3d object if successful. + # @return [Geom::Vector3d] a vector3d object if successful. # # @version SketchUp 6.0 def end_vertex_normal @@ -66,7 +66,7 @@ def end_vertex_normal # edgeuse = edgeuses[0] # face = edgeuse.face # - # @return face - a Face object used by this edge use + # @return [Sketchup::Face] a Face object used by this edge use # # @version SketchUp 6.0 def face @@ -87,7 +87,7 @@ def face # edgeuse = edgeuses[0] # loop = edgeuse.loop # - # @return loop - a Loop object that contains this edge use. + # @return [Sketchup::Loop] a Loop object that contains this edge use. # # @version SketchUp 6.0 def loop @@ -108,7 +108,7 @@ def loop # edgeuse = edgeuses[0] # next_edgeuse = edgeuse.next # - # @return edgeuse - the next EdgeUse object in a loop + # @return [Sketchup::EdgeUse] the next EdgeUse object in a loop # # @version SketchUp 6.0 def next @@ -136,7 +136,7 @@ def next # edgeuse = edgeuses[1] # partners = edgeuse.partners # - # @return array - an array of partner Edge Use objects. + # @return [Array] an array of partner Edge Use objects. # # @version SketchUp 6.0 def partners @@ -157,7 +157,7 @@ def partners # edgeuse = edgeuses[0] # previous_edgeuse = edgeuse.previous # - # @return edgeuse - the previous Edge Use object in the loop + # @return [Sketchup::EdgeUse] the previous Edge Use object in the loop # # @version SketchUp 6.0 def previous @@ -180,7 +180,7 @@ def previous # edgeuse = edgeuses[0] # reversed = edgeuse.reversed? # - # @return [Boolean] boolean - true if reversed, false if not reversed. + # @return [Boolean] true if reversed, false if not reversed. # # @version SketchUp 6.0 def reversed? @@ -202,7 +202,7 @@ def reversed? # edgeuse = edgeuses[0] # vector3d = edgeuse.start_vertex_normal # - # @return vector3d - a vector3d object if successful. + # @return [Geom::Vector3d] a vector3d object if successful. # # @version SketchUp 6.0 def start_vertex_normal diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb index b22418c..d8d401c 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::Entities} class is a collection of Entity objects, either in a @@ -520,8 +520,7 @@ def add_face(*args) def add_faces_from_mesh(polygon_mesh, smooth_flags = Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES, f_material = nil, b_material = nil) end - # The add_group method is used to create an empty group or a group with - # entities. + # The {#add_group} method is used to create a new group. # # @example # model = Sketchup.active_model @@ -582,8 +581,8 @@ def add_group(*args) def add_image(path, point, width, height = 0.0) end - # The add_instance method adds a component instance to the collection of - # entities. + # The {#add_instance} method adds a group or component instance to the collection of + # entities using an existent definition. # # @example # model = Sketchup.active_model @@ -694,7 +693,9 @@ def add_ngon(center, normal, radius, numsides = 24) def add_observer(observer) end - # The add_section_plane method adds a section plane object to the entities. + # Adds a section plane object to the entities. + # + # Refer to the {Geom} module for information on how planes are represented. # # @example # # Create a section plane @@ -705,16 +706,53 @@ def add_observer(observer) # # Make sure section planes are visible # model.rendering_options['DisplaySectionPlanes'] = true # - # @param plane - # the geometric plane where the SectionPlane object is to - # be created. Refer to the Geom module for information on - # how planes are represented. + # @overload add_section_plane(point, vector) + # + # @param [Geom::Point3d] point + # @param [Geom::Vector3d] vector + # + # @overload add_section_plane(plane) # - # @return [Sketchup::SectionPlane, nil] the created SectionPlane object if - # successful, nil on failure. + # @param [Array(Geom::Point3d), Geom::Vector3d]] plane + # + # @overload add_section_plane(plane) + # + # @param [Array(Integer, Integer, Integer, Integer)] plane + # Plane coefficents. + # + # @return [Sketchup::SectionPlane, nil] # # @version SketchUp 2014 - def add_section_plane(plane) + def add_section_plane(*args) + end + + # The {#add_snap} method is used to create a new {Sketchup::Snap}. + # + # @example + # entities = Sketchup.active_model.entities + # snap = entities.add_snap(ORIGIN, X_AXIS) + # + # @overload add_snap(position, direction) + # + # With a position and a direction vector provided, but no up vector, SketchUp tries + # to keep the Snap upright. + # @param [Geom::Point3d] position + # @param [Geom::Vector3d] direction + # + # @overload add_snap(position, direction, up) + # + # @param [Geom::Point3d] position + # @param [Geom::Vector3d] direction + # @param [Geom::Vector3d] up + # + # @raise ArgumentError if +direction+ and +up+ are parallel. + # + # @return [Sketchup::Snap] + # + # @see Sketchup::Snap + # + # @version SketchUp 2025.0 + def add_snap(*args) end # The {#add_text} method adds a note or label text entity to the entities. @@ -825,9 +863,9 @@ def at(entity_index) # } # # @note While using {Sketchup::Entities#build} it is important to not - # add or remove vertices by other means of the builder. Also don't modify the - # position of the vertices in the {Sketchup::Entities} container geometry is - # added to. Doing so can break the vertex-cache that de-duplicates the vertices. + # add or remove vertices by other means than the builder. Also don't modify the + # position of the vertices in the {Sketchup::Entities} collection. Doing so can break the + # vertex-cache that de-duplicates the vertices. # # @return [nil] # @@ -1001,8 +1039,10 @@ def erase_entities(*args) def fill_from_mesh(polygon_mesh, weld_vertices = true, smooth_flags = Geom::PolygonMesh::AUTO_SOFTEN|Geom::PolygonMesh::SMOOTH_SOFT_EDGES, f_material = nil, b_material = nil) end - # The intersect_with method is used to intersect an entities, component - # instance, or group object with a entities object. + # The {#intersect_with} method is used to intersect a Sketchup::Entities, Sketchup::Component, + # or Sketchup::Group object with a entities object. + # + # empty if no intersection(s) were found. # # @example # model = Sketchup.active_model @@ -1048,7 +1088,7 @@ def fill_from_mesh(polygon_mesh, weld_vertices = true, smooth_flags = Geom::Poly # @param [Sketchup::Entity, Array] entities2 # A single entity, or an array of entities. # - # @return [nil] + # @return [Array] The intersecting edges created. This array may be # # @version SketchUp 6.0 def intersect_with(recurse, transform1, entities1, transform2, hidden, entities2) diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb b/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb index b9d4381..8003eb8 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::EntitiesBuilder} is an interface to generate bulk geometry diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.rb index 0cc4b1a..cfe2ea1 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to {Sketchup::Entities} diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb index ecca93c..5b48bb4 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is the base class for all SketchUp entities. Entities are basically @@ -26,7 +26,7 @@ # end # } # -# UI.messagebox("There are " + face_count.to_s + " faces selected.") +# "There are #{face_count} faces selected." # # @version SketchUp 6.0 class Sketchup::Entity @@ -297,7 +297,7 @@ def model # The parent method is used to retrieve the parent of the entity. # - # The parent will be a ComponentDefinition, a Group, or a Model, whatever + # The parent will be a ComponentDefinition, a Group, a Model, or whatever # the entity is contained within. # # @example diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/EntityObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/EntityObserver.rb index d08bcc1..feeb677 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/EntityObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/EntityObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to entity events. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Environment.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Environment.rb new file mode 100644 index 0000000..7f43094 --- /dev/null +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Environment.rb @@ -0,0 +1,406 @@ +# Copyright:: Copyright 2026 Trimble Inc. +# License:: The MIT License (MIT) + +# An {Sketchup::Environment} object represents an environment in the model. Environments are used +# to control the background and lighting of the model. Environments can be used as skydomes, for +# reflections, and to link the sun to the environment. +# +# @version SketchUp 2025.0 +class Sketchup::Environment < Sketchup::Entity + + # Instance Methods + + # The {#description} method gets the description for an {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.description # Outputs "" + # + # @return [String] description + # + # @version SketchUp 2025.0 + def description + end + + # The {#description=} method sets the description for an {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # environment.description = 'This is an example of description' + # puts environment.description # Outputs "This is an example of description" + # + # @param [String] description + # the new description for the environment + # + # @version SketchUp 2025.0 + def description=(description) + end + + # The {#linked_sun=} method is used to set if the {Sketchup::Environment} is linked to the sun. + # Shadow lighting is used to create realistic shadows in the scene, enhancing the visual quality. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # environment.linked_sun = true + # puts environment.linked_sun? # Outputs true + # + # @param [Boolean] linked_sun + # true if the environment should be linked to the sun, false otherwise + # + # @version SketchUp 2025.0 + def linked_sun=(linked_sun) + end + + # The {#linked_sun?} method is used to determine if the {Sketchup::Environment} is linked to the + # sun. This function returns a boolean value indicating whether the shadow light + # feature is currently enabled in the environment. Shadow lighting is used + # to create realistic shadows in the scene, enhancing the visual quality. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.linked_sun? # Outputs false + # + # @return [Boolean] true if the environment is linked to the sun, false otherwise + # + # @version SketchUp 2025.0 + def linked_sun? + end + + # The {#linked_sun_position} method is used to get the position of the sun linked to the + # {Sketchup::Environment}. The position is a {Geom::Point3d} where the x must be in range + # +[0.0, 1.0]+ and y must be in range +[-1.0, 1.0]+. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.linked_sun_position # Outputs Geom::Point3d(0, 0, 0) + # + # @return [Geom::Point3d] the position of the sun linked to the environment + # + # @version SketchUp 2025.0 + def linked_sun_position + end + + # The {#linked_sun_position=} method is used to set the position of the sun linked to the + # {Sketchup::Environment}. The position is a {Geom::Point3d} where the x must be in range + # +[0.0, 1.0]+ and y must be in range +[-1.0, 1.0]+. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # environment.linked_sun_position = Geom::Point3d.new(0, 1) + # puts environment.linked_sun_position # Outputs Geom::Point3d(0, 1, 0) + # + # @param [Geom::Point3d] sun_position + # the new position of the sun linked to the environment + # + # @return [Geom::Point3d] the new position of the sun linked to the environment + # + # @version SketchUp 2025.0 + def linked_sun_position=(sun_position) + end + + # The {#name} method retrieves the name of the {Sketchup::Environment}. This is the + # unique internal name of the object which should be used for retrieving + # the {Sketchup::Environment} from the model's {Sketchup::Environments}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.name # Outputs "Example" + # + # @return [String] the name of the environment + # + # @version SketchUp 2025.0 + def name + end + + # The {#name=} method sets the name for an {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # environment.name = 'New Name' + # puts environment.name # Outputs "New Name" + # + # @param [String] name + # the new name for the environment + # + # @return [String] the new name of the environment + # + # @version SketchUp 2025.0 + def name=(name) + end + + # The {#path} method is used to get the file name of the image or SKE file used for the + # {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.path # Outputs 'environment.hdr' + # + # @return [String] the file name of the image or SKE file used for the environment + # + # @version SketchUp 2025.0 + def path + end + + # The {#reflection_exposure} method is used to get the exposure of the {Sketchup::Environment} for + # reflections. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.reflection_exposure # Outputs 1 + # environment.reflection_exposure = 0.5 + # puts environment.reflection_exposure # Outputs 0.5 + # + # @note Reflection exposure is a value between +0.0+ and +10.0+, where +0.0+ is no exposure and + # +10.0+ is full exposure. + # + # @return [Float] the exposure of the environment for reflections + # + # @version SketchUp 2025.0 + def reflection_exposure + end + + # The {#reflection_exposure=} method is used to set the exposure of the {Sketchup::Environment} for + # reflections. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.reflection_exposure # Outputs 1 + # environment.reflection_exposure = 0.5 + # puts environment.reflection_exposure # Outputs 0.5 + # + # @note Reflection exposure is a value between +0.0+ and +10.0+, where +0.0+ is no exposure and + # +10.0+ is full exposure. + # + # @param [Float] reflection_exposure + # the new exposure of the environment for reflections + # + # @return [Float] the new exposure of the environment for reflections + # + # @version SketchUp 2025.0 + def reflection_exposure=(reflection_exposure) + end + + # The {#rotation} method is used to get the vertical rotation angle in degrees to apply to the + # {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.rotation # Outputs 0.0 degrees + # environment.rotation = 90.0 + # puts environment.rotation # Outputs 90.0 degrees + # + # @return [Float] rotation in degrees + def rotation + end + + # The {#rotation=} method is used to set the the vertical rotation angle in degrees to apply to the + # {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.rotation # Outputs 0.0 degrees + # environment.rotation = 90.0 + # puts environment.rotation # Outputs 90.0 degrees + # + # @note Rotation is a value between +0.0+ and +360.0+ degrees. + # + # @param [Float] rotation + # + # @return [Float] + # + # @version SketchUp 2025.0 + def rotation=(rotation) + end + + # The {#skydome_exposure} method is used to get the exposure of the {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.skydome_exposure # Outputs 1 + # environment.skydome_exposure = 0.5 + # puts environment.skydome_exposure # Outputs 0.5 + # + # @note Skydome exposure is a value between +0.0+ and +20.0+, where +0.0+ is no exposure and +20.0+ + # is full exposure. + # + # @return [Float] the exposure of the environment + # + # @version SketchUp 2025.0 + def skydome_exposure + end + + # The {#skydome_exposure=} method is used to set the exposure of the {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.skydome_exposure # Outputs 1 + # environment.skydome_exposure = 0.5 + # puts environment.skydome_exposure # Outputs 0.5 + # + # @note Skydome exposure is a value between +0.0+ and +20.0+, where +0.0+ is no exposure and +20.0+ + # is full exposure. + # + # @param [Float] skydome_exposure + # the new exposure of the environment + # + # @return [Float] the new exposure of the environment + # + # @version SketchUp 2025.0 + def skydome_exposure=(skydome_exposure) + end + + # The {#thumbnail} method is used to get the thumbnail image of the {Sketchup::Environment}. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # thumbnail = environment.thumbnail + # + # @return [Sketchup::ImageRep] + # + # @version SketchUp 2025.0 + def thumbnail + end + + # The {#use_as_skydome=} method is used to set if the {Sketchup::Environment} is used as a skydome. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # environment.use_as_skydome = true + # puts environment.use_as_skydome? # Outputs true + # + # @param [Boolean] use_as_skydome + # true if the environment should be used as a skydome, false + # otherwise + # + # @version SketchUp 2025.0 + def use_as_skydome=(use_as_skydome) + end + + # The {#use_as_skydome?} method is used to determine if the {Sketchup::Environment} + # is used as a skydome. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.use_as_skydome? # Outputs false + # + # @return [Boolean] true + # + # @version SketchUp 2025.0 + def use_as_skydome? + end + + # The {#use_for_reflections=} method is used to set if the {Sketchup::Environment} is used for + # reflections. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # environment.use_for_reflections = true + # puts environment.use_for_reflections? # Outputs true + # + # @param [Boolean] use_for_reflection + # true if the environment should be used for reflections, false + # otherwise + # + # @version SketchUp 2025.0 + def use_for_reflections=(use_for_reflection) + end + + # The {#use_for_reflections?} method is used to determine if the {Sketchup::Environment} + # is used for reflections. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # puts environment.use_for_reflections? # Outputs false + # + # @return [Boolean] true if the environment is used for reflections, false otherwise + # + # @version SketchUp 2025.0 + def use_for_reflections? + end + + # The {#write_hdr} method writes the HDR, EXR or SKE image of the environment to a file in its + # original file type. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('Example', path) + # environment.write_hdr('path/to/directory') + # + # @param [String] path + # the directory where the image should be written + # + # @raise [ArgumentError] if the image is invalid. + # + # @raise [ArgumentError] if the file name is empty. + # + # @raise [RuntimeError] if the file cannot be written. + # + # @return [String] the full path of the written file + # + # @version SketchUp 2025.0 + def write_hdr(path) + end + +end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Environments.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Environments.rb new file mode 100644 index 0000000..4f1e441 --- /dev/null +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Environments.rb @@ -0,0 +1,185 @@ +# Copyright:: Copyright 2026 Trimble Inc. +# License:: The MIT License (MIT) + +# An {Sketchup::Environments} object is a collection of {Sketchup::Environment} objects. +# It is used to manage the environments in a model. +# +# An {Sketchup::Environment} object represents an environment in the model. Environments are +# used to control the background and lighting of the model. Environments can be used as skyboxes, +# for reflections, and to link the sun to the environment. +# +# @version SketchUp 2025.0 +class Sketchup::Environments < Sketchup::Entity + + # Includes + + include Enumerable + + # Instance Methods + + # The {#[]} method is used to retrieve an {Sketchup::Environment} by name. + # + # @example + # environments = Sketchup.active_model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('My Environment', path) + # result = environments['My Environment'] + # + # @param [String] name + # The name of the {Sketchup::Environment}. + # + # @return [Sketchup::Environment, nil] + # + # @version SketchUp 2025.0 + def [](name) + end + + # The {#add} method adds an {Sketchup::Environment} to the {Sketchup::Environments}. + # + # @note The supported file formats are HDR, EXR and SKE. + # + # @overload add(name, path) + # + # @param [String] name the name of the environment. + # @param [String] path the path to the image or SKE file used for the environment + # @example + # environments = Sketchup.active_model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('My Environment', path) + # + # @overload add(path) + # + # @since SketchUp 2026.0 + # @param [String] path the path to the image or SKE file used for the environment + # @example + # environments = Sketchup.active_model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add(path) + # + # @raise ArgumentError if the file could not be loaded. + # + # @return [Sketchup::Environment] the newly created environment + # + # @version SketchUp 2025.0 + def add(*args) + end + + # The {#add_observer} method is used to add an observer to the environments + # collection. + # + # @example + # environments = Sketchup.active_model.environments + # status = environments.add_observer(observer) + # + # @return [Boolean] true if successful, false if unsuccessful. + # + # @version SketchUp 2025.0 + def add_observer(arg) + end + + # The {#current} method is used to get the current environment in the + # {Sketchup::Environments}. + # + # @example + # environments = Sketchup.active_model.environments + # current = environments.current + # + # @return [Sketchup::Environment, nil] the current environment + # + # @version SketchUp 2025.0 + def current + end + + # The {#current=} method is used to set the current environment in the + # {Sketchup::Environments}. + # + # @example + # environments = Sketchup.active_model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('My Environment', path) + # environments.current = environment + # + # @param [Sketchup::Environment, nil] environment + # the new current environment + # + # @return [Sketchup::Environment, nil] the new current environment + # + # @version SketchUp 2025.0 + def current=(environment) + end + + # The {#each} method is used to iterate over all the environments in the + # {Sketchup::Environments}. + # + # @example + # environments = Sketchup.active_model.environments + # environments.each { |environment| puts environment.name } + # + # @return [Sketchup::Environments] + # + # @version SketchUp 2025.0 + # + # @yield [environment] + # + # @yieldparam [Sketchup::Environment] environment + # the environment + def each + end + + # The {#purge_unused} method is used to remove unused environments. + # + # @example + # environments = Sketchup.active_model.environments + # environments.purge_unused + # + # @return [Sketchup::Environments] + # + # @version SketchUp 2025.0 + def purge_unused + end + + # The {#remove} method removes an {Sketchup::Environment} from the {Sketchup::Environments}. + # + # @example + # environments = Sketchup.active_model.environments + # path = 'path/to/environment.hdr' + # environment = environments.add('My Environment', path) + # environments.remove(environment) + # + # @param [Sketchup::Environment] environment + # the environment to remove + # + # @return [Boolean] true if the environment was removed, false if it was not found + # + # @version SketchUp 2025.0 + def remove(environment) + end + + # The {#remove_observer} method is used to remove an observer from the current + # object. + # + # @example + # environments = Sketchup.active_model.environments + # status = environments.remove_observer(observer) + # + # @return [Boolean] true if successful, false if unsuccessful. + # + # @version SketchUp 2025.0 + def remove_observer(arg) + end + + # The {#size} method retrieves the number of environments in the + # {Sketchup::Environments}. + # + # @example + # environments = Sketchup.active_model.environments + # number = environments.size + # + # @return [Integer] the number of environments + # + # @version SketchUp 2025.0 + def size + end + alias_method :length, :size + +end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/EnvironmentsObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/EnvironmentsObserver.rb new file mode 100644 index 0000000..85cfbf0 --- /dev/null +++ b/lib/sketchup-api-stubs/stubs/Sketchup/EnvironmentsObserver.rb @@ -0,0 +1,113 @@ +# Copyright:: Copyright 2026 Trimble Inc. +# License:: The MIT License (MIT) + +# This observer interface is implemented to react to {Sketchup::Environment} 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 +# {Sketchup::Environment} object. +# +# @example +# class MyEnvironmentsObserver < Sketchup::EnvironmentsObserver +# def onEnvironmentChange(environments, environment) +# puts "onEnvironmentChange: #{environment}" +# end +# end +# +# Sketchup.active_model.environments.add_observer(MyEnvironmentsObserver.new) +# +# @see Sketchup::Environments#add_observer +# +# @version SketchUp 2025.0 +class Sketchup::EnvironmentsObserver + + # Instance Methods + + # The {#onEnvironmentAdd} method is called whenever an environment is added to the + # {Sketchup::Environments}. + # + # @example + # class MyEnvironmentsObserver < Sketchup::EnvironmentsObserver + # def onEnvironmentAdd(environments, environment) + # puts "onEnvironmentAdd: #{environment}" + # end + # end + # + # Sketchup.active_model.environments.add_observer(MyEnvironmentsObserver.new) + # + # @param [Sketchup::Environments] environments + # + # @param [Sketchup::Environment] environment + # + # @return [nil] + # + # @version SketchUp 2025.0 + def onEnvironmentAdd(environments, environment) + end + + # The {#onEnvironmentChange} method is called whenever the environment properties + # are changed. + # + # @example + # class MyEnvironmentsObserver < Sketchup::EnvironmentsObserver + # def onEnvironmentChange(environments, environment) + # puts "onEnvironmentChange: #{environment}" + # end + # end + # + # Sketchup.active_model.environments.add_observer(MyEnvironmentsObserver.new) + # + # @param [Sketchup::Environments] environments + # + # @param [Sketchup::Environment] environment + # + # @return [nil] + # + # @version SketchUp 2025.0 + def onEnvironmentChange(environments, environment) + end + + # The {#onEnvironmentRemove} method is called whenever an environment is removed from the + # {Sketchup::Environments}. + # + # @example + # class MyEnvironmentsObserver < Sketchup::EnvironmentsObserver + # def onEnvironmentRemove(environments, environment) + # puts "onEnvironmentRemove: #{environment}" + # end + # end + # + # Sketchup.active_model.environments.add_observer(MyEnvironmentsObserver.new) + # + # @param [Sketchup::Environments] environments + # + # @param [Sketchup::Environment] environment + # + # @return [nil] + # + # @version SketchUp 2025.0 + def onEnvironmentRemove(environments, environment) + end + + # The {#onEnvironmentSetCurrent} method is called whenever the current environment is changed. + # + # @example + # class MyEnvironmentsObserver < Sketchup::EnvironmentsObserver + # def onEnvironmentSetCurrent(environments, environment) + # puts "onEnvironmentSetCurrent: #{environment}" + # end + # end + # + # Sketchup.active_model.environments.add_observer(MyEnvironmentsObserver.new) + # + # @param [Sketchup::Environments] environments + # + # @param [Sketchup::Environment] environment + # + # @return [nil] + # + # @version SketchUp 2025.0 + def onEnvironmentSetCurrent(environments, environment) + end + +end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ExtensionsManager.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ExtensionsManager.rb index 0484231..33d9efd 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ExtensionsManager.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ExtensionsManager.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The ExtensionsManager class provides a way of accessing the @@ -21,7 +21,7 @@ class Sketchup::ExtensionsManager # # @example # manager = Sketchup.extensions - # extension = manager[1] + # extension = manager[0] # if (extension) # puts extension.name # else @@ -34,7 +34,7 @@ class Sketchup::ExtensionsManager # # You can also get extensions by ID. # my_extension = manager['2475A758-6503-46D5-AC5E-16AEA0A3162A'] # - # @note Index starts at 1. + # @note Index starts at 0. # # @param [Integer, String] index_or_name # The index, name or ID of the SketchupExtension object. @@ -83,9 +83,6 @@ def each # @example # manager = Sketchup.extensions # keys = manager.keys - # for key in keys - # UI.messagebox('The next extension is named: ' + key) - # end # # @return keys - Array of string keys # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Face.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Face.rb index 1b0a4a1..c8a4d77 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Face.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Face.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Faces in SketchUp are flat, 2-sided polygons with 3 or more sides. @@ -162,7 +162,7 @@ def back_material=(material) # puts "#{pt.to_s} is outside the face" # end # - # # Check a point that should be outside inside the face. + # # Check a point that should be inside the face. # pt = Geom::Point3d.new(1, 1, 0) # result = face.classify_point(pt) # if result == Sketchup::Face::PointInside @@ -227,6 +227,27 @@ def clear_texture_position(front) def clear_texture_projection(frontside) end + # The {#coplanar_with?} method is used determine whether a face is coplanar with `other_face`. + # + # @example + # model = Sketchup.active_model + # entities = model.active_entities + # + # # Add the faces to the entities in the model + # face = entities.add_face([0, 0, 0], [4, 0, 0], [4, 5, 0]) + # other_face = entities.add_face([5, 0, 0], [9, 0, 0], [9, 6, 0]) + # + # face.coplanar_with?(other_face) + # + # @param [Sketchup::Face] other_face + # The face to compare with. + # + # @return [Boolean] + # + # @version SketchUp 2025.0 + def coplanar_with?(other_face) + end + # The edges method is used to get an array of edges that bound the face. # # @example @@ -337,12 +358,12 @@ def get_UVHelper(*args) # The get_glued_instances method returns an Array any ComponentInstances # that are glued to the face. # - # ComponentInstance objects that are currently glued to the face. - # # @example # # Create a series of points that define a new face. # model = Sketchup.active_model # entities = model.active_entities + # + # # Create a rectangle face # pts = [] # pts[0] = [0, 0, 0] # pts[1] = [9, 0, 0] @@ -351,9 +372,27 @@ def get_UVHelper(*args) # # # Add the face to the entities in the model # face = entities.add_face(pts) + # + # # Create a component definition with 3D geometry + # component_definition = model.definitions.add("ComponentExample") + # component_entities = component_definition.entities + # + # comp_face = component_entities.add_face([0, 0, 0], [2, 0, 0], [2, 2, 0], [0, 2, 0]) + # comp_face.pushpull(2) + # + # # Place the component instance on the face + # component_instance = entities.add_instance(component_definition, Geom::Transformation.new([3, + # 3, 0])) + # + # # Enable gluing behavior and glue component to face + # component_definition.behavior.is2d = true + # component_instance.glued_to = face + # + # # Get all component instances glued to the face # glued_array = face.get_glued_instances # # @return [Array] An array of + # ComponentInstance objects that are currently glued to the face. # # @version SketchUp 7.0 M1 def get_glued_instances @@ -372,25 +411,37 @@ def get_glued_instances # pts[0] = [0, 0, 1] # pts[1] = [10, 0, 1] # pts[2] = [10, 10, 1] + # pts[3] = [0, 10, 1] # face = entities.add_face(pts) # - # # Export an image to use as a texture - # path = Sketchup.temp_dir - # full_name = File.join(path, "temp_image.jpg") - # model.active_view.write_image(full_name, 500, 500, false, 0.0) + # view = model.active_view + # screenshot_path = File.join(Dir.tmpdir,"screenshot.png") + # view.write_image(screenshot_path) # - # # Create a material and assign the texture to it # material = materials.add("Test Material") - # material.texture = full_name + # material.texture = screenshot_path # # # Assign the new material to our face we created # face.material = material # # # Set the projection of the applied material - # face.set_texture_projection(face.normal, true) + # mapping = [ + # Geom::Point3d.new(0, 0, 0), # Model coordinate + # Geom::Point3d.new(0, 0, 0), # UV coordinate + # Geom::Point3d.new(10, 0, 0), # Model coordinate + # Geom::Point3d.new(1, 0, 0), # UV coordinate + # Geom::Point3d.new(0, 10, 0), # Model coordinate + # Geom::Point3d.new(0, 1, 0) # UV coordinate + # ] + # + # direction = Geom::Vector3d.new(0, 0, 1) # Adjust direction vector + # + # on_front = true + # face.position_material(material, mapping, on_front, direction) # # # Get the projection of the applied material # vector = face.get_texture_projection(true) + # puts "Texture projection vector : #{vector.inspect}" # # @param [Boolean] frontside # +true+ for front side, +false+ for back side. @@ -410,19 +461,32 @@ def get_texture_projection(frontside) # face. # # @example - # depth = 100 - # width = 100 # model = Sketchup.active_model - # entities = model.active_entities - # pts = [] - # pts[0] = [0, 0, 0] - # pts[1] = [width, 0, 0] - # pts[2] = [width, depth, 0] - # pts[3] = [0, depth, 0] + # entities= model.active_entities # - # # Add the face to the entities in the model - # face = entities.add_face(pts) - # loops = face.loops + # # Define points for the outer loop + # outer_points = [] + # outer_points << Geom::Point3d.new(0, 0, 0) + # outer_points << Geom::Point3d.new(100, 0, 0) + # outer_points << Geom::Point3d.new(100, 100, 0) + # outer_points << Geom::Point3d.new(0, 100, 0) + # + # # Create the outer face + # outer_face = entities.add_face(outer_points) + # + # # Define points for the inner loop (hole) + # inner_points = [] + # inner_points << Geom::Point3d.new(25, 25, 0) + # inner_points << Geom::Point3d.new(75, 25, 0) + # inner_points << Geom::Point3d.new(75, 75, 0) + # inner_points << Geom::Point3d.new(25, 75, 0) + # + # # Create the inner face and erase it to create a second loop + # inner_face = entities.add_face(inner_points) + # inner_face.erase! + # + # # Get all loops of the outer face + # loops = outer_face.loops # # @return [Array] an array of Loop objects if successful # @@ -644,6 +708,7 @@ def plane # @overload position_material(material, points, on_front) # # This variant positions a material on the face's plane without projection. + # @version SketchUp 6.0 # # @param [Sketchup::Material] material # @@ -658,7 +723,7 @@ def plane # # @overload position_material(material, points, on_front, projection) # - # @version SketchUp 2021.1 + # @version SketchUp 6.0 # # This variant positions a material on the face's plane with projection. # @@ -691,8 +756,6 @@ def plane # @see #get_texture_projection # # @see #clear_texture_projection - # - # @version SketchUp 6.0 def position_material(*args) end @@ -794,10 +857,16 @@ def set_texture_projection(vector, frontside) # @example # model = Sketchup.active_model # entities = model.active_entities + # + # # Filter the entities to get only the faces # faces = entities.grep(Sketchup::Face).select { |face| + # # Select faces that have manually positioned textures + # # Check both in front face (true) and the back face (false) # face.texture_positioned?(true) || face.texture_positioned?(false) # } # + # # 'faces' will contain all faces with manually positioned textures + # # @param [Boolean] front # +true+ Checks the front side of the face, +false+ # the back side. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/FrameChangeObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/FrameChangeObserver.rb index 2f3eade..c3e16c0 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/FrameChangeObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/FrameChangeObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to changes in camera @@ -75,7 +75,7 @@ class Sketchup::FrameChangeObserver # if percent_done == 0.0 # puts "Animating to scene '#{to_scene.name}':" # else - # puts format("% 7.2f %",percent_done*100) + # puts format("% 7.2f %%",percent_done*100) # end # end # end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Group.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Group.rb index 8269eeb..bee6991 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Group.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Group.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A Group class contains methods for manipulating groups of entities. @@ -113,11 +113,6 @@ def description # face = entities2.add_face pts # group.description = "This is a Group with a 2d Face" # description = group.description - # if (description) - # UI.messagebox description - # else - # UI.messagebox "Failure" - # end # # @param [String] description # A string description. @@ -150,11 +145,6 @@ def description=(description) # # Add a face to within the group # face = entities2.add_face pts # entities = group.entities - # if (entities) - # UI.messagebox entities - # else - # UI.messagebox "Failure" - # end # # @return [Sketchup::Entities] an Entities object if successful # @@ -188,11 +178,6 @@ def equals?(group) # group.entities.add_line([0,0,0],[100,100,100]) # # array = group.explode - # if array - # UI.messagebox "Exploded the group" - # else - # UI.messagebox "Failure" - # end # # @return [Array] An array of entity objects if successful, false if # unsuccessful. @@ -346,7 +331,6 @@ def locked=(lock) # # Add the group to the entities in the model # group = entities.add_group # status = group.locked? - # UI.messagebox status # # @return [Boolean] # @@ -449,7 +433,7 @@ def move!(transformation) def name end - # The name= method is used to set the description for the group. + # The {#name=} method is used to set the name for the group. # # @example # # Add a group to the model. @@ -632,13 +616,8 @@ def to_component # # Add a face to within the group # face = entities2.add_face pts # UI.messagebox "Group before Move" - # group = group.transform! t - # if (group) - # UI.messagebox "Group after move" - # UI.messagebox group - # else - # UI.messagebox "Failure" - # end + # group.transform! t + # puts "Group after move\r\n" + group.to_s # # @param [Geom::Transformation] transform # A Transformation object. @@ -676,13 +655,19 @@ def transformation # new_transformation = Geom::Transformation.new([100,0,0]) # group.transformation = new_transformation # + # @note As of SketchUp 2026, this will raise an error if the + # {Geom::Transformation} is not invertible. Prior to 2026 this would silently set the + # transformation possibly causing rendering or editing problems. + # # @param [Geom::Transformation] transformation # + # @raise ArgumentError if the {Geom::Transformation} is not invertible (as of Sketchup 2026) + # # @version SketchUp 6.0 def transformation=(transformation) end - # The trim method is used to compute the (non-destructive) boolean difference + # The {#trim} method is used to compute the (non-destructive) boolean difference # of the two groups representing manifold solid volumes (this - arg). If # the specified objects (this and arg) do not represent manifold volumes, this # method fails. @@ -693,6 +678,11 @@ def transformation=(transformation) # group2 = entities[1] # result = group1.trim(group2) # + # @note Trimming object group2 using group1 results in a new trimmed version of group2. + # If the trim is successful the original group2 is erased and a newly trimmed + # version is created. This new version, derived from the trimming operation, + # will possess a new GUID and will be returned. + # # @note This method is not available in SketchUp Make. # # @param [Sketchup::Group, Sketchup::ComponentInstance] group diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Http.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Http.rb index d64fa08..2b48f1e 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Http.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Http.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::Http} module provides interfaces to create asynchronous HTTP diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Http/Request.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Http/Request.rb index d9cb563..4b8aa8d 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Http/Request.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Http/Request.rb @@ -1,7 +1,7 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) -# Http::Request objects allows you to send HTTP request to HTTP servers. +# {Sketchup::Http::Request} objects allows you to send HTTP request to HTTP servers. # # @version SketchUp 2017 class Sketchup::Http::Request @@ -52,6 +52,8 @@ def body=(body) # # @request.cancel # + # @note Do not {#cancel} the request in the response callback. + # # @return [true] # # @version SketchUp 2017 @@ -93,17 +95,17 @@ def headers def headers=(headers) end - # The default port is 80, to use a different port define it in the URL when + # The default port is +80+, to use a different port define it in the URL when # creating a new {Sketchup::Http::Request}. # - # The +method+ parameter accepts any custom HTTP method or one of the + # The {#method} parameter accepts any custom HTTP method or one of the # following: - # * +Sketchup::Http::GET+ - # * +Sketchup::Http::POST+ - # * +Sketchup::Http::PUT+ - # * +Sketchup::Http::DELETE+ - # * +Sketchup::Http::HEAD+ - # * +Sketchup::Http::OPTIONS+ + # - {Sketchup::Http::GET} + # - {Sketchup::Http::POST} + # - {Sketchup::Http::PUT} + # - {Sketchup::Http::DELETE} + # - {Sketchup::Http::HEAD} + # - {Sketchup::Http::OPTIONS} # # @example # @request = Sketchup::Http::Request.new("http://localhost:8080", Sketchup::Http::GET) @@ -116,6 +118,8 @@ def headers=(headers) # making the download silently fail. This is especially noticeable for larger downloads that # takes longer time. # + # @note Do not {#cancel} the request in the response callback. + # # @param [String] url # # @param [String] method @@ -142,13 +146,14 @@ def method end # Sets the HTTP method that is going to be used when sending the request. + # # The value can be any custom HTTP method or one of the following: - # * +Sketchup::Http::GET+ - # * +Sketchup::Http::POST+ - # * +Sketchup::Http::PUT+ - # * +Sketchup::Http::DELETE+ - # * +Sketchup::Http::HEAD+ - # * +Sketchup::Http::OPTIONS+ + # - {Sketchup::Http::GET} + # - {Sketchup::Http::POST} + # - {Sketchup::Http::PUT} + # - {Sketchup::Http::DELETE} + # - {Sketchup::Http::HEAD} + # - {Sketchup::Http::OPTIONS} # # @example # @request = Sketchup::Http::Request.new("http://localhost:8080") @@ -184,7 +189,7 @@ def method=(method) # # @request.start # - # @note +total+ is -1 if the server doesn't specify a file size in the response header. + # @note +total+ is +-1+ if the server doesn't specify a file size in the response header. # # @return [Boolean] # @@ -236,6 +241,8 @@ def set_upload_progress_callback # puts "body: #{response.body}" # end # + # @note Do not {#cancel} the request in the response callback. + # # @return [Boolean] # # @version SketchUp 2017 diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Http/Response.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Http/Response.rb index f66073e..ce36112 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Http/Response.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Http/Response.rb @@ -1,18 +1,20 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) -# Http::Response objects allows you to get the response information from the -# server, you can only receive the Http::Response if you have attached a -# callback block when calling start from the Http::Request object. +# {Sketchup::Http::Response} objects allows you to get the response information from the +# server, you can only receive the {Sketchup::Http::Response} if you have attached a +# callback block when calling start from the {Sketchup::Http::Request} object. +# +# @note Do not {Sketchup::Http::Request#cancel} the request in the response callback. # # @version SketchUp 2017 class Sketchup::Http::Response # Instance Methods - # Gets the http body that was received from the server as a string encoded - # using the charset provided in the Content-Type of the server response, if - # no charset is specified, ASCII-8BIT will be used. + # Gets the HTTP body that was received from the server as a string encoded + # using the charset provided in the +"Content-Type"+ header of the server response, + # if no charset is specified, +Encoding::ASCII_8BIT+ will be used. # # @example # @request = Sketchup::Http::Request.new("http://localhost:8080") @@ -27,7 +29,7 @@ class Sketchup::Http::Response def body end - # Returns the http headers that were sent by the server. + # Returns the HTTP headers that were sent by the server. # # @example # @request = Sketchup::Http::Request.new("http://localhost:8080") @@ -50,7 +52,7 @@ def headers # @request = Sketchup::Http::Request.new("http://localhost:8080") # # @request.start do |request, response| - # puts "http status code: #{response.status_code}" + # puts "HTTP status code: #{response.status_code}" # end # # @return [Integer] diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Image.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Image.rb index a781cb7..54d145b 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Image.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Image.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An Image object represents a raster image placed in the Model. @@ -97,11 +97,6 @@ def glued_to=(drawing_element) # entities = model.active_entities # image = entities.add_image path, pt, 300 # height = image.height - # if (height) - # UI.messagebox height - # else - # UI.messagebox "Failure" - # end # # @return height - the height of the model if successful # @@ -121,11 +116,6 @@ def height # image = entities.add_image path, pt, 300 # UI.messagebox "Before adjustment" # height = image.height = 400 - # if (height) - # UI.messagebox height - # else - # UI.messagebox "Failure" - # end # # @param height # The height, in inches, to set the image. @@ -166,11 +156,6 @@ def image_rep # entities = model.active_entities # image = entities.add_image path, pt, 300 # vector = image.normal - # if (vector) - # UI.messagebox vector - # else - # UI.messagebox "Failure" - # end # # @return vector - a Vector3d object if successful # @@ -188,11 +173,7 @@ def normal # entities = model.active_entities # image = entities.add_image path, pt, 300 # origin = image.origin - # if (origin) - # UI.messagebox origin - # else - # UI.messagebox "Failure" - # end + # puts origin.inspect # # @return point - a Point3d object containing the origin location # if successful @@ -201,7 +182,7 @@ def normal def origin end - # The origin= method is used to set the 3D point as the origin of the image. + # The {#origin=} method is used to set the 3D point as the origin of the image. # # @example # model = Sketchup.active_model @@ -212,11 +193,7 @@ def origin # image = entities.add_image path, pt, 300 # UI.messagebox "Before Move" # origin = image.origin=pt2 - # if (origin) - # UI.messagebox origin - # else - # UI.messagebox "Failure" - # end + # puts origin.inspect # # @param point # A Point3d object with the new origin. @@ -237,11 +214,6 @@ def origin=(point) # entities = model.active_entities # image = entities.add_image path, pt, 300 # path = image.path - # if (path) - # UI.messagebox path - # else - # UI.messagebox "Failure" - # end # # @return path - the path for the image file if successful # @@ -259,11 +231,6 @@ def path # entities = model.active_entities # image = entities.add_image path, pt, 300 # pixelheight = image.pixelheight - # if (pixelheight) - # UI.messagebox pixelheight - # else - # UI.messagebox "Failure" - # end # # @return height - the height of the image in pixels if # successful @@ -282,11 +249,6 @@ def pixelheight # entities = model.active_entities # image = entities.add_image path, pt, 300 # pixelwidth = image.pixelwidth - # if (pixelwidth) - # UI.messagebox pixelwidth - # else - # UI.messagebox "Failure" - # end # # @return width - the width of the image in pixels if successful # @@ -304,11 +266,6 @@ def pixelwidth # image = entities.add_image path, pt, 300 # UI.messagebox "Before Resize" # size = image.size= 500,500 - # if (size) - # UI.messagebox size - # else - # UI.messagebox "Failure" - # end # # @param width # The width of the image. @@ -335,11 +292,6 @@ def size=(width, height) # image = entities.add_image path, pt, 300 # UI.messagebox "Before Move" # image = image.transform! t - # if (image) - # UI.messagebox image - # else - # UI.messagebox "Failure" - # end # # @param transform # A Transformation object. @@ -404,11 +356,6 @@ def transformation=(transform) # entities = model.active_entities # image = entities.add_image path, pt, 300 # width = image.width - # if (width) - # UI.messagebox width - # else - # UI.messagebox "Failure" - # end # # @return width - the width of the image if successful # @@ -428,11 +375,6 @@ def width # image = entities.add_image path, pt, 300 # UI.messagebox "Before adjustment" # width = image.width=400 - # if (width) - # UI.messagebox width - # else - # UI.messagebox "Failure" - # end # # @param width # The width, in inches, to set the image. @@ -453,11 +395,6 @@ def width=(width) # entities = model.active_entities # image = entities.add_image path, pt, 300 # zrotation = image.zrotation - # if (zrotation) - # UI.messagebox zrotation - # else - # UI.messagebox "Failure" - # end # # @return vector - a Vector3d object if successful # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ImageRep.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ImageRep.rb index 2874b76..4af31d2 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ImageRep.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ImageRep.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # References an image representation object. @@ -203,7 +203,7 @@ def save_file(filepath) # # @note The encoding of the pixel_data {String} parameter should be ASCII-8BIT. # Any other encoding could corrupt the binary data. Using - # `Array#pack("C*")` gives correct encoding. + # +Array#pack("C*")+ gives correct encoding. # # @param [Integer] width # The width of the pixel data. Must be greater than 0. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Importer.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Importer.rb index 88cb059..bf9ae29 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Importer.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Importer.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Importer interface lets you build your own importers for SketchUp. To @@ -52,7 +52,7 @@ # # to import. This is where you do the real work of opening and # # processing the file. # def load_file(file_path, status) -# UI.messagebox(file_path) +# # This where you do your import logic. # # return Sketchup::Importer::ImportSuccess # end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb b/lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb index a8784b1..65d06b1 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::InputPoint} class is used to pick 3d points and/or entities @@ -271,30 +271,56 @@ def instance_path # # @example # view = Sketchup.active_model.active_view - # x = 100 - # y = 100 + # x = 100 # Screen coordinate + # y = 200 # Screen coordinate # inputpoint = view.inputpoint(x, y) - # inputpoint2 = Sketchup::InputPoint.new(Geom::Point3d.new(100, 200, 300)) + # inputpoint2 = Sketchup::InputPoint.new(Geom::Point3d.new(100, 250, 300)) # inputpoint.pick(view, x, y) # inputpoint.pick(view, x, y, inputpoint2) # # @overload pick(view, x, y) # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # The first form just uses the screen position to compute the InputPoint. It + # is used when you don't want the InputPoint to be dependent on another + # InputPoint. + # @param [Sketchup::View] view + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # + # @overload pick(view, x, y, inputpoint) + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # The second form uses the screen position and another InputPoint. It will + # find additional inferences such as along one of the axis directions from the + # first point. + # @param [Sketchup::View] view + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::InputPoint] inputpoint + # A second input point used as a reference for the pick. + # + # @overload pick(view, x, y) + # + # @version SketchUp 2025.0 # The first form just uses the screen position to compute the InputPoint. It # is used when you don't want the InputPoint to be dependent on another # InputPoint. # @param [Sketchup::View] view - # @param [Integer] x - # @param [Integer] y + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. # # @overload pick(view, x, y, inputpoint) # + # @version SketchUp 2025.0 # The second form uses the screen position and another InputPoint. It will # find additional inferences such as along one of the axis directions from the # first point. # @param [Sketchup::View] view - # @param [Integer] x - # @param [Integer] y + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. # @param [Sketchup::InputPoint] inputpoint # A second input point used as a reference for the pick. # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/InstanceObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/InstanceObserver.rb index c2cfef2..91a8eb5 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/InstanceObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/InstanceObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to component instance diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/InstancePath.rb b/lib/sketchup-api-stubs/stubs/Sketchup/InstancePath.rb index 0bfdb2e..44732c9 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/InstancePath.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/InstancePath.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::InstancePath} class represent the instance path to a given @@ -152,7 +152,8 @@ def initialize(path) # # @raise [TypeError] if the instance path refer to deleted entities. # - # @return [Sketchup::Entity] + # @return [Sketchup::Entity, nil] Nil if the last item of the instance path is a group or + # component, otherwise {Sketchup::Entity}. # # @version SketchUp 2017 def leaf @@ -212,7 +213,7 @@ def persistent_id_path # # @raise [TypeError] if the instance path refer to deleted entities. # - # @return [Sketchup::Group, Sketchup::ComponentInstance, nil] + # @return [Sketchup::Group, Sketchup::ComponentInstance, Sketchup::Image, nil] # # @version SketchUp 2017 def root diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Layer.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Layer.rb index 72e89a9..e6d173a 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Layer.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Layer.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Layer class contains methods modifying and extracting information for a @@ -83,7 +83,7 @@ def ==(other) def color end - # The {#color=} method is used to set the name of a layer. + # The {#color=} method is used to set the color of a layer. # # @example # model = Sketchup.active_model @@ -98,6 +98,7 @@ def color=(color) end # The {#display_name} method is used to retrieve the display name of the layer. + # This is the name shown to the user in the Sketchup UI. # # @example # model = Sketchup.active_model @@ -105,6 +106,10 @@ def color=(color) # new_layer = layers.add ("test layer") # name = new_layer.display_name # + # @note The display name and internal name of layers should share the same value except for the + # Layer0. From version 2020.0 onwards the display name of Layer0 is "Untagged" and it is + # localized. + # # @return [String] # # @see #name @@ -115,8 +120,6 @@ def display_name # The {#folder} method is used to return the parent layer folder of a layer. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -137,8 +140,6 @@ def folder # This will trigger +onParentFolderChanged+ in normal cases and # +onLayerChanged+ during undo/redo. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -180,7 +181,8 @@ def line_style def line_style=(line_style) end - # The {#name} method is used to retrieve the name of the layer. + # The {#name} method return the internal name of the layer which is handled by the model. + # Its use is for scripting and internal references. # # @example # model = Sketchup.active_model @@ -188,7 +190,11 @@ def line_style=(line_style) # new_layer = layers.add "test layer" # name = new_layer.name # - # @return [String] + # @note The internal layer and display name of layers should share the same value except for the + # Layer0. From version 2020.0 onwards the display name of Layer0 is "Untagged" and it is + # localized. + # + # @return [String] representing the name of the layer # # @see #display_name # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/LayerFolder.rb b/lib/sketchup-api-stubs/stubs/Sketchup/LayerFolder.rb index c5ef7b3..bdda3f6 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/LayerFolder.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/LayerFolder.rb @@ -1,10 +1,8 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Allows layers to be organized in folders. Folders may have duplicate names. # -# @api TagFolder -# # @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". @@ -21,8 +19,6 @@ class Sketchup::LayerFolder < Sketchup::Entity # The {#<=>} method is used to compare two layer folders based on their names. # This enables the Ruby +Array#sort+ method to sort SketchUp layer folders. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -45,13 +41,11 @@ def <=>(other) # The {#==} method is used to determine if two layer folders are the same. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers - # folder1 = layers.add('Folder1') - # folder2 = layers.add('Folder2') + # folder1 = layers.add_folder('Folder1') + # folder2 = layers.add_folder('Folder2') # equal = folder1 == folder2 # # @param [Object] other @@ -64,8 +58,6 @@ def ==(other) # The {#add_folder} method adds or moves a layer folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder1 = manager.add_folder('Doors') @@ -95,8 +87,6 @@ def add_folder(arg) # The {#add_layer} method adds a layer to a folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # layer = manager.add_layer('Inner Doors') @@ -119,8 +109,6 @@ def add_layer(layer) # The {#count_folders} method retrieves the number of child folders in the # folder. # - # @api TagFolder - # # @example # layers = Sketchup.active_model.layers # folder1 = layers.add_folder('Hello') @@ -135,8 +123,6 @@ def count_folders # The {#count_layers} method retrieves the number of layers in the folder. # - # @api TagFolder - # # @example # layers = Sketchup.active_model.layers # layer = layers.add_layer('World') @@ -159,8 +145,6 @@ def count_layers # The {#each_folder} method is used to iterate through the folders that are # direct children to the folder. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -179,8 +163,6 @@ def each_folder # The {#each_layer} method is used to iterate through the layers that are # direct children to the folder. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -201,8 +183,6 @@ def each_layer # The {#folder} method is used to return the parent layer folder of a layer # folder. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -224,8 +204,6 @@ def folder # # This will trigger +onLayerFolderRemoved+ followed by +onLayerFolderAdded+. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -244,8 +222,6 @@ def folder=(parent) # The {#folders} returns the direct child-folders of the folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder1 = manager.add_folder('Doors') @@ -260,8 +236,6 @@ def folders # The {#layers} method retrieves the child layers of a folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Hello') @@ -278,8 +252,6 @@ def layers # The {#name} method gets the name of the folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Doors') @@ -294,8 +266,6 @@ def name # The {#name=} method sets the name of the folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Doors') @@ -312,8 +282,6 @@ def name=(name) # The {#remove_folder} method removes the folder from the model. All children # are preserved, but move up one level. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder1 = manager.add_folder('Doors') @@ -333,8 +301,6 @@ def remove_folder(folder) # The {#remove_layer} method removes a layer from a folder. The layer will be # parent to the layer manager. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # layer = manager.add_layer('Inner Doors') @@ -353,8 +319,6 @@ def remove_layer(layer) # The {#visible=} method is used to set if the layer folder is visible. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -369,8 +333,6 @@ def visible=(visible) # The {#visible?} method is used to determine if the layer folder is visible. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -386,8 +348,6 @@ def visible? # The {#visible_on_new_pages=} method is used to set if the layer folder is by # default visible on new pages. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -405,8 +365,6 @@ def visible_on_new_pages=(visible) # The {#visible_on_new_pages?} method is used to determine if the layer folder # is by default visible on new pages. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb index 25df3c0..e609a98 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Layers collection allows you to see and manage all of the layers in a @@ -63,8 +63,6 @@ def add(layer_name) # The {#add_folder} method adds or moves a layer folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Doors') @@ -143,8 +141,6 @@ def count # The {#count_folders} method counts the number of folders which are direct # children of the layer manager. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Doors') @@ -158,8 +154,6 @@ def count_folders # The {#count_layers} method retrieves the number of layers not in a folder. # - # @api TagFolder - # # @example # layers = Sketchup.active_model.layers # number = layers.count_layers @@ -199,8 +193,6 @@ def each # The {#each_folder} method is used to iterate through the folders that are # direct children to the layer manager. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Doors') @@ -220,8 +212,6 @@ def each_folder # The {#each_layer} method is used to iterate through the layers that are not # inside a layer folder. # - # @api TagFolder - # # @example # model = Sketchup.active_model # layers = model.layers @@ -238,8 +228,6 @@ def each_layer # The {#folders} method returns the folders of the layer manager. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # manager.add_folder('Doors') @@ -257,8 +245,6 @@ def folders # The {#layers} method retrieves the layers not in a folder. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # layers = manager.layers @@ -301,8 +287,6 @@ def purge_unused # The {#purge_unused_folders} method is used to remove all layer folder with # no children. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Doors') @@ -353,8 +337,6 @@ def remove(layer, remove_geometry = false) # The {#remove_folder} method removes the folder from the model. All children are # preserved, but moved up one level. # - # @api TagFolder - # # @example # manager = Sketchup.active_model.layers # folder = manager.add_folder('Doors') diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/LayersObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/LayersObserver.rb index 14b9045..e341e8f 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/LayersObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/LayersObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to layers events. @@ -92,8 +92,6 @@ def onLayerChanged(layers, layer) # The {#onLayerFolderAdded} method is called when a layer folder is added # to a model. # - # @api TagFolder - # # @example # class MyLayersObserver < Sketchup::LayersObserver # def onLayerFolderAdded(layers, layer_folder) @@ -118,8 +116,6 @@ def onLayerFolderAdded(layers, layer_folder) # The {#onLayerFolderChanged} method is called when a layer folder changes # one of its properties. # - # @api TagFolder - # # @example # class MyLayersObserver < Sketchup::LayersObserver # def onLayerFolderChanged(layers, layer_folder) @@ -146,8 +142,6 @@ def onLayerFolderChanged(layers, layer_folder) # The {#onLayerFolderRemoved} method is called when a layer folder is removed # from a model. # - # @api TagFolder - # # @example # class MyLayersObserver < Sketchup::LayersObserver # def onLayerFolderRemoved(layers, layer_folder) @@ -196,8 +190,6 @@ def onLayerRemoved(layers, layer) # The {#onParentFolderChanged} method is called when a layer changes parent # folder. # - # @api TagFolder - # # @example # class MyLayersObserver < Sketchup::LayersObserver # def onParentFolderChanged(layers, layer) diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Licensing.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Licensing.rb index 53c5489..2f04f5c 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Licensing.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Licensing.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The +Sketchup::Licensing+ module contains methods for @@ -25,7 +25,14 @@ module Sketchup::Licensing # Class Methods - # Acquires a license for a given extension. + # Gets a license for a given extension. + # + # Starting in SketchUp 2025.0, this method automatically tries to fetch a license from Extension + # Warehouse if the extension doesn't have a license on the current device. This only works if the + # user is signed in. In earlier SketchUp versions, the user has to go to Extension Manager, expand + # the extension in question and press Update License if the license is missing. + # (For performance reasons this automatic fetching is skipped during SU startup. Make sure to do a + # license check when the user interacts with the extension). # # @example # ext_id = "4e215280-dd23-40c4-babb-b8a8dd29d5ee" @@ -38,7 +45,7 @@ module Sketchup::Licensing # The Extension Warehouse UUID for the desired extension. # # @return [Sketchup::Licensing::ExtensionLicense] An object representing - # licensing state for the extension. Do not store this object, retrieve + # licensing state for the extension. Do not store this object; retrieve # it again when needed since licensing state may have changed. # # @version SketchUp 2015 diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Licensing/ExtensionLicense.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Licensing/ExtensionLicense.rb index aa8a063..2c4fe87 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Licensing/ExtensionLicense.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Licensing/ExtensionLicense.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Sketchup::Licensing::ExtensionLicense class is used to store extension diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/LineStyle.rb b/lib/sketchup-api-stubs/stubs/Sketchup/LineStyle.rb index e458137..eb767ba 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/LineStyle.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/LineStyle.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This provides a way for SketchUp to customize a line style and be set on a diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/LineStyles.rb b/lib/sketchup-api-stubs/stubs/Sketchup/LineStyles.rb index f1dd7ce..49829c8 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/LineStyles.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/LineStyles.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Provides access to the different line style objects in the model. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/LoadHandler.rb b/lib/sketchup-api-stubs/stubs/Sketchup/LoadHandler.rb new file mode 100644 index 0000000..ed50e75 --- /dev/null +++ b/lib/sketchup-api-stubs/stubs/Sketchup/LoadHandler.rb @@ -0,0 +1,70 @@ +# Copyright:: Copyright 2026 Trimble Inc. +# License:: The MIT License (MIT) + +# The main purpose of the +LoadHandler+ interface is to be used as an optional second parameter of +# the {Sketchup::DefinitionList#load_from_url} method. +# +# Its methods that require implementation handle the process of downloading and managing the +# state of the load operation, including progress updates and error handling. +# +# @abstract Implement the methods described in this class to create a tool. +# You can not sub-class this class because it is not defined by the API. +# +# @version SketchUp 6.0 +class Sketchup::LoadHandler + + # Instance Methods + + # This method is called when the download is canceled by the user. + # + # @example + # def cancelled? + # # You could, for example, show a messagebox after X seconds asking if the + # # user wants to cancel the download. If this method returns true, then + # # the download cancels. + # return false + # end + # + # @return [Boolean] + def cancelled? + end + + # This method is called when the download unsuccessfully completes + # + # @example + # def onFailure(message) + # self.error = message + # Sketchup::set_status_text('') + # end + # + # @param [String] message + # + # @return [Boolean] + def onFailure(message) + end + + # This method is triggered whenever the percent value updates. + # + # @example + # def onPercentChange(percent) + # Sketchup::set_status_text("loading: #{percent.round}%") + # end + # + # @param [Float] percent + # + # @return [nil] + def onPercentChange(percent) + end + + # This method is called when the download successfully completes + # + # @example + # def onSuccess + # Sketchup::set_status_text('') + # end + # + # @return [nil] + def onSuccess + end + +end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Loop.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Loop.rb index 751339c..3743d9f 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Loop.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Loop.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Loop is a low level topology class that will not need to be used often. A diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Material.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Material.rb index d479593..80a4dc5 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Material.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Material.rb @@ -1,17 +1,23 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) -# The Material class represents a texture or color that can be applied to -# Drawingelements. It is most often applied to Faces. +# The {Sketchup::Material} class represents a {Sketchup::Texture} +# or {Sketchup::Color} that can be applied to {Sketchup::Drawingelement}s. +# It is most often applied to {Sketchup::Face}s. # # You can pass any object that can be used as a material to a method that -# requires a material. Objects include actual materials, color, and classes -# that can be converted to a color. -# -# The following are valid (assuming the existence of a Material mat1.) +# requires a material. Objects include actual {Sketchup::Material}, +# {Sketchup::Color}, and classes that can be converted to a color. # # @example -# face.material = mat1 +# model = Sketchup.active_model +# face = model.entities.add_face([0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0]) +# material = model.materials.add('Example') +# # The following will all assign a red material to the face: +# material.color = Sketchup::Color.new(255, 0, 0) +# face.material = material +# face.material = Sketchup::Color.new(255, 0, 0) +# face.material = [255, 0, 0] # face.material = "red" # face.material = 0xff0000 # @@ -31,115 +37,261 @@ class Sketchup::Material < Sketchup::Entity MATERIAL_SOLID = nil # Stub value. MATERIAL_TEXTURED = nil # Stub value. + NORMAL_STYLE_DIRECTX = nil # Stub value. + NORMAL_STYLE_OPENGL = nil # Stub value. + OWNER_IMAGE = nil # Stub value. OWNER_LAYER = nil # Stub value. OWNER_MANAGER = nil # Stub value. + WORKFLOW_CLASSIC = nil # Stub value. + WORKFLOW_PBR_METALLIC_ROUGHNESS = nil # Stub value. + # Instance Methods - # The <=> method is used to compare two materials based on name. The number - # returned relates to the "string distance" between the names. + # The {#<=>} method is used to compare two materials based on #{display_name}. # # @example - # model = Sketchup.active_model - # materials = model.materials + # materials = Sketchup.active_model.materials # m1 = materials.add('Joe') # m2 = materials.add('Fred') - # p m1 <=> m2 + # m1 <=> m2 + # # > 1 # - # @param [Sketchup::Material] material2 - # A Material object. + # @param [Sketchup::Material] material # - # @return [Integer] 0 if they are equal, positive number if - # material1 > material2, negative if material1 < material2 + # @return [Integer] +0+ if they are equal, + # +1+ if material1 > material2, +-1+ if material1 < material2 # # @version SketchUp 6.0 - def <=>(material2) + def <=>(material) end - # The == method is used to test if two materials are the same. + # The {#==} method is used to test if two materials are the same. # # @example # model = Sketchup.active_model # materials = model.materials # m1 = materials.add('Joe') # m2 = materials.add('Fred') - # if (m1 == m2) - # UI.messagebox('The Materials are equal.') - # else - # UI.messagebox('The Materials are not equal.') - # end + # m1 == m2 + # # > false # - # @param [Sketchup::Material] material2 - # A Material object. + # @param [Sketchup::Material] material # - # @return [Boolean] true if the materials are the same, false if - # they are different + # @return [Boolean] # # @version SketchUp 6.0 - def ==(material2) + def ==(material) end - # The alpha method is used to get the opacity of the material. + # The {#alpha} method is used to get the opacity of the material. # - # The value will be between 0.0 and 1.0. A value of 0.0 means that the material is - # completely transparent. A value of 1.0 means that the Material is completely - # opaque. + # The value will be between +0.0+ and +1.0+. A value of +0.0+ means that the + # material is completely transparent. A value of +1.0+ means that the material + # is completely opaque. # # @example - # alpha_value = Sketchup.active_model.materials[0].alpha + # material = Sketchup.active_model.materials.add('Example') + # material.alpha + # # > 1.0 # - # @return [Float] a number between 0 and 1 + # @return [Float] A value between +0.0+ and +1.0+. + # + # @see #use_alpha? # # @version SketchUp 6.0 def alpha end - # The alpha= method is used to set the opacity of the material. + # The {#alpha=} method is used to set the opacity of the material. # - # The value must be between 0.0 and 1.0. A value of 0.0 means that the material is - # completely transparent. A value of 1.0 means that the Material is completely - # opaque. + # The value must be between +0.0+ and +1.0+. A value of +0.0+ means that the + # material is completely transparent. A value of +1.0+ means that the material + # is completely opaque. # # @example - # model = Sketchup.active_model - # materials = model.materials - # material = materials.add('Joe') + # material = Sketchup.active_model.materials.add('Example') # material.alpha = 0.5 # # @param [Float] alpha - # An opacity value. + # An alpha value between +0.0+ and +1.0+. + # + # @return [Float] # - # @return [Float] the newly set opacity value + # @see #use_alpha? # # @version SketchUp 6.0 def alpha=(alpha) end - # The color method is used to retrieve the color of the material. # - # If it uses a Texture, this will return the average color. + # @example + # material = Sketchup.active_model.materials.add("Material") + # material.ao_enabled = true + # + # @raise [ArgumentError] if the ambient occlusion texture is not set before enabling ambient + # occlusion. + # + # @see ao_enabled? + # + # @see #ao_texture + # + # @see #ao_texture= + # + # @see #ao_strength + # + # @see #ao_strength= + # + # @version SketchUp 2025.0.2 + def ao_enabled=(enabled) + end + # # @example - # model = Sketchup.active_model - # materials = model.materials - # material = materials.add('Joe') + # material = Sketchup.active_model.materials.add("Material") + # material.ao_enabled? + # # > false + # + # @note There is no setter for this property. Instead it's dictated whether a + # {#ao_texture} is set. + # + # @return [Boolean] + # + # @see #ao_enabled= + # + # @see #ao_texture + # + # @see #ao_texture= + # + # @see #ao_strength + # + # @see #ao_strength= + # + # @version SketchUp 2025.0 + def ao_enabled? + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.ao_texture = 'path/to/ao_texture.png' + # material.ao_strength + # # > 1.0 + # + # @return [Float] A value between +0.0+ and +1.0+. + # + # @see #ao_enabled? + # + # @see #ao_texture + # + # @see #ao_texture= + # + # @version SketchUp 2025.0 + def ao_strength + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.ao_texture = 'path/to/ao_texture.png' + # material.ao_strength = 1.0 + # + # @param [Float] strenght + # A value between +0.0+ and +1.0+. + # + # @see #ao_enabled? + # + # @see #ao_texture + # + # @see #ao_texture= + # + # @version SketchUp 2025.0 + def ao_strength=(strenght) + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.ao_texture = 'path/to/ao_texture.png' + # material.ao_texture + # # > nil + # + # @return [Sketchup::Texture] + # + # @see #ao_enabled? + # + # @see #ao_strength + # + # @see #ao_strength= + # + # @version SketchUp 2025.0 + def ao_texture + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.texture = 'path/to/texture.png' + # material.ao_texture = 'path/to/ao_texture.png' + # + # @overload ao_texture=(image_path) + # + # @param [String] image_path + # + # @overload ao_texture=(image_rep) + # + # @param [Sketchup::ImageRep] image_rep + # + # @overload ao_texture=(texture) + # + # Copies another texture to this texture. + # @param [Sketchup::Texture] texture + # + # @raise [ArgumentError] if the image data of the texture is invalid or corrupt. + # + # @see #ao_enabled? + # + # @see #ao_strength + # + # @see #ao_strength= + # + # @version SketchUp 2025.0 + def ao_texture=(texture) + end + + # The {#color} method is used to retrieve the color of the material. + # + # If it uses a colorized {Sketchup::Texture}, this will return the average + # color of the texture. + # + # @example + # materials = Sketchup.active_model.materials.add('Example') # material.color = 'red' # color = material.color # - # @return [Sketchup::Color] a Color object + # @note The alpha value of the {Sketchup::Color} object is not used for the + # material's transparency. This is controlled by the {#alpha} property in + # order for textured materials to also have transparency. + # + # @return [Sketchup::Color] + # + # @see #alpha + # + # @see #texture # # @version SketchUp 6.0 def color end - # The color= method is used to set the color of the material. + # The {#color=} method is used to set the color of the material. # - # If the Material has a texture, then this turns it into a colorized + # If the material has a {Sketchup::Texture}, then this turns it into a colorized # texture. # - # To reset the color of a Material with a texture, set the color - # to nil. + # To reset the color of a material with a colorized texture, set the color + # to +nil+. If the texture is not colorized it'll be reset to some undefined + # default color. # # @example # model = Sketchup.active_model @@ -147,19 +299,33 @@ def color # material = materials.add('Joe') # material.color = 'red' # - # @param [Sketchup::Color, String, nil] color - # A Color object. + # @note The alpha value of the {Sketchup::Color} object is not used for the + # material's transparency. This is controlled by the {#alpha} property in + # order for textured materials to also have transparency. + # + # @param [Sketchup::Color, String, Array(Numeric, Numeric, Numeric, Numeric), Integer, nil] color + # Any value you can create a {Sketchup::Color} from or +nil+. + # + # @see #alpha= # - # @return [Sketchup::Color, String, nil] the newly set Color object + # @see #texture= + # + # @see #colorize_deltas + # + # @see #colorize_type + # + # @see #materialType + # + # @see Sketchup::Color#initialize # # @version SketchUp 6.0 def color=(color) end - # The colorize_deltas method retrieves the HLS delta for colorized materials. + # The {#colorize_deltas} method retrieves the HLS delta for colorized materials. # # @example - # material = Sketchup.active_model.materials[0] + # material = Sketchup.active_model.materials.add('Example') # h, l, s = material.colorize_deltas # # @return [Array(Float, Float, Float)] An array of floats representing the HLS delta. @@ -168,50 +334,52 @@ def color=(color) def colorize_deltas end - # The colorize_type method retrieves the type of colorization of the material. - # This value is only relevant when the materialType is set to 2 - # (colorized textured). - # Types include: + # The {#colorize_type} method retrieves the type of colorization of the material. + # + # {Material Colorize Types}[#normal_style_summary]: # - # - 0 = shift (Sketchup::Material::COLORIZE_SHIFT), - # - 1 = tint (Sketchup::Material::COLORIZE_TINT), + # - {Sketchup::Material::COLORIZE_SHIFT} + # - {Sketchup::Material::COLORIZE_TINT} # # @example - # material = Sketchup.active_model.materials[0] + # material = Sketchup.active_model.materials.add('Example') # type = material.colorize_type # - # @return [Integer] the colorize type for the Material object. + # @note This value is only relevant when the {#materialType} is set to + # {Sketchup::Material::MATERIAL_COLORIZED_TEXTURED}. + # + # @return [Integer] One of +Sketchup::Material::COLORIZE_*+ values. # # @version SketchUp 2015 def colorize_type end - # The colorize_type method set the type of colorization of the material. - # This value is only relevant when the materialType is set to 2 - # (colorized textured). - # Types include: + # The {#colorize_type=} method set the type of colorization of the material. + # + # {Material Colorize Types}[#normal_style_summary]: # - # - 0 = shift (Sketchup::Material::COLORIZE_SHIFT), - # - 1 = tint (Sketchup::Material::COLORIZE_TINT), + # - {Sketchup::Material::COLORIZE_SHIFT} + # - {Sketchup::Material::COLORIZE_TINT} # # @example - # material = Sketchup.active_model.materials[0] + # material = Sketchup.active_model.materials.add('Example') # material.colorize_type = Sketchup::Material::COLORIZE_TINT # - # @param [Integer] type - # the new colorize type for the Material object. + # @note This value is only relevant when the {#materialType} is set to + # {Sketchup::Material::MATERIAL_COLORIZED_TEXTURED}. # - # @return [Integer] the colorize type for the Material object. + # @param [Integer] type + # One of +Sketchup::Material::COLORIZE_*+ values. # # @version SketchUp 2015 def colorize_type=(type) end - # The display_name method retrieves the name that is displayed within SketchUp + # The {#display_name} method retrieves the name that is displayed within SketchUp # for the material. # # This should be used when presenting the name in the UI, but the returned name - # cannot be used as a key in model.materials. + # cannot be used as a key in {Sketchup::Model#materials}. # # @example # model = Sketchup.active_model @@ -223,36 +391,175 @@ def colorize_type=(type) # # to the UI like SketchUp does. # puts material.display_name # Outputs "Joe" # - # @return [String] the display name for the material + # @return [String] + # + # @see #name # # @version SketchUp 6.0 def display_name end - # The materialType method retrieves the type of the material. Types include: + # The {#materialType} method retrieves the type of the material. + # + # {Material Types}[#material_type_constant_summary]: # - # - 0 = solid (Sketchup::Material::MATERIAL_SOLID), - # - 1 = textured (Sketchup::Material::MATERIAL_TEXTURED), - # - 2 = colorized textured (Sketchup::Material::MATERIAL_COLORIZED_TEXTURED). + # - +0+ = solid ({Sketchup::Material::MATERIAL_SOLID}) + # - +1+ = textured ({Sketchup::Material::MATERIAL_TEXTURED}) + # - +2+ = colorized textured ({Sketchup::Material::MATERIAL_COLORIZED_TEXTURED}) # - # The constants where added in SketchUp 2015. + # The constants were added in SketchUp 2015. # # @example - # material = Sketchup.active_model.materials[0] - # type = material.materialType + # material = Sketchup.active_model.materials.add('Example') + # material.materialType == Sketchup::Material::MATERIAL_SOLID + # # > true # - # @return [Integer] the material type for the Material object. See - # summary for details. + # @return [Integer] One of +Sketchup::Material::MATERIAL_*+ values. # # @version SketchUp 6.0 def materialType end - # The name method retrieves the name of the material. This is the - # internal name of the object which should be used for retrieving + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.metalness_enabled = true + # material.metallic_factor + # # > 1.0 + # + # @return [Float] A value between +0.0+ and +1.0+. + # + # @see #metalness_enabled? + # + # @see #metalness_enabled= + # + # @see #metallic_texture + # + # @see #metallic_texture= + # + # @version SketchUp 2025.0 + def metallic_factor + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.metalness_enabled = true + # material.metallic_factor = 1.0 + # + # @param [Float] factor + # A value between +0.0+ and +1.0+. + # + # @see #metalness_enabled? + # + # @see #metalness_enabled= + # + # @see #metallic_texture + # + # @see #metallic_texture= + # + # @version SketchUp 2025.0 + def metallic_factor=(factor) + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.metalness_enabled = true + # material.metallic_texture + # # > nil + # + # @return [Sketchup::Texture] + # + # @see #metalness_enabled? + # + # @see #metalness_enabled= + # + # @see #metallic_factor + # + # @see #metallic_factor= + # + # @version SketchUp 2025.0 + def metallic_texture + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.texture = 'path/to/texture.png' + # material.metallic_texture = 'path/to/metallic_texture.png' + # + # @overload metallic_texture=(image_path) + # + # @param [String] image_path + # + # @overload metallic_texture=(image_rep) + # + # @param [Sketchup::ImageRep] image_rep + # + # @overload metallic_texture=(texture) + # + # Copies another texture to this texture. + # @param [Sketchup::Texture] texture + # + # @raise [ArgumentError] if the image data of the texture is invalid or corrupt. + # + # @see #metalness_enabled? + # + # @see #metalness_enabled= + # + # @see #metallic_factor + # + # @see #metallic_factor= + # + # @version SketchUp 2025.0 + def metallic_texture=(texture) + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.metalness_enabled = true + # + # @param [Boolean] enabled + # + # @see #metallic_texture + # + # @see #metallic_texture= + # + # @see #metallic_factor + # + # @see #metallic_factor= + # + # @version SketchUp 2025.0 + def metalness_enabled=(enabled) + end + + # + # @example + # material = Sketchup.active_model.materials.add("Material") + # material.metalness_enabled? + # # > false + # + # @return [Boolean] + # + # @see #metallic_texture + # + # @see #metallic_texture= + # + # @see #metallic_factor + # + # @see #metallic_factor= + # + # @version SketchUp 2025.0 + def metalness_enabled? + end + + # The {#name} method retrieves the name of the material. This is the + # unique internal name of the object which should be used for retrieving # the material from the model's material list. # - # Use .display_name to display the name in the UI. + # Use {#display_name} to display the name in the UI. # # @example # model = Sketchup.active_model @@ -264,7 +571,9 @@ def materialType # # to the UI like SketchUp does. # puts material.display_name # Outputs "Joe" # - # @return [String] the name of the Material object + # @return [String] + # + # @see #display_name # # @version SketchUp 6.0 def name @@ -272,36 +581,248 @@ def name # The {#name=} method sets the name of the material. # + # @bug SketchUp 2018 would raise an error if you named material the name it + # already had. + # # @example Safely change name without raising errors # materials = Sketchup.active_model.materials # material = materials.add("Joe") # material.name = materials.unique_name('Jeff') # - # @note Since SketchUp 2018 this method will raise an `ArgumentError` if the + # @note Since SketchUp 2018 this method will raise an +ArgumentError+ if the # name is not unique. # - # @note SketchUp 2018 would raise an error if you named material the name it - # already had. - # # @param [String] str # the new material name # # @raise [ArgumentError] if the name is not unique to the model. # (Added in SU2018) # - # @return [String] the newly set material name. + # @return [String] # # @version SketchUp 8.0 M1 def name=(str) end - # The {#owner_type} method is used to determine if the material is owned - # by a {Sketchup::Materials}. # - # Returned value is one of: - # * +Sketchup::Material::OWNER_MANAGER+ - # * +Sketchup::Material::OWNER_IMAGE+ - # * +Sketchup::Material::OWNER_LAYER+ + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.normal_enabled = true + # + # @param [Boolean] enabled + # + # @raise [ArgumentError] if the normal texture is not set before enabling normal mapping. + # + # @see #normal_enabled? + # + # @see #normal_texture + # + # @see #normal_texture= + # + # @see #normal_scale + # + # @see #normal_scale= + # + # @see #normal_style + # + # @see #normal_style= + # + # @version SketchUp 2025.0.2 + def normal_enabled=(enabled) + end + + # + # @example + # material = Sketchup.active_model.materials.add("Material") + # material.normal_enabled? + # # > false + # + # @return [Boolean] + # + # @see #normal_enabled= + # + # @see #normal_texture + # + # @see #normal_texture= + # + # @see #normal_scale + # + # @see #normal_scale= + # + # @see #normal_style + # + # @see #normal_style= + # + # @version SketchUp 2025.0 + def normal_enabled? + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.normal_texture = 'path/to/normal_texture.png' + # material.normal_scale + # # > 1.0 + # + # @return [Float] A value larger than or equal to +0.0+. + # + # @see #normal_enabled? + # + # @see #normal_texture + # + # @see #normal_texture= + # + # @see #normal_style + # + # @see #normal_style= + # + # @version SketchUp 2025.0 + def normal_scale + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.normal_texture = 'path/to/normal_texture.png' + # material.normal_scale = 1.0 + # + # @param [Float] scale + # A value larger than or equal to +0.0+. + # + # @see #normal_enabled? + # + # @see #normal_texture + # + # @see #normal_texture= + # + # @see #normal_style + # + # @see #normal_style= + # + # @version SketchUp 2025.0 + def normal_scale=(scale) + end + + # {Material Normal Styles}[#normal_style_summary]: + # + # - {NORMAL_STYLE_OPENGL} + # - {NORMAL_STYLE_DIRECTX} + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.normal_texture = 'path/to/normal_texture.png' + # material.normal_style + # # > Sketchup::Material::NORMAL_STYLE_OPENGL + # + # @return [Integer] One of +Sketchup::Material::NORMAL_STYLE_*+ values. + # + # @see #normal_enabled? + # + # @see #normal_texture + # + # @see #normal_texture= + # + # @see #normal_scale + # + # @see #normal_scale= + # + # @version SketchUp 2025.0 + def normal_style + end + + # {Material Normal Styles}[#normal_style_summary]: + # + # - {NORMAL_STYLE_OPENGL} + # - {NORMAL_STYLE_DIRECTX} + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.normal_texture = 'path/to/normal_texture.png' + # material.normal_style = Sketchup::Material::NORMAL_STYLE_DIRECTX + # + # @param [Integer] style + # + # @see #normal_enabled? + # + # @see #normal_texture + # + # @see #normal_texture= + # + # @see #normal_scale + # + # @see #normal_scale= + # + # @version SketchUp 2025.0 + def normal_style=(style) + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.normal_texture = 'path/to/normal_texture.png' + # material.normal_texture + # # > # + # + # @return [Sketchup::Texture] + # + # @see #normal_enabled? + # + # @see #normal_scale + # + # @see #normal_scale= + # + # @see #normal_style + # + # @see #normal_style= + # + # @version SketchUp 2025.0 + def normal_texture + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.texture = 'path/to/texture.png' + # material.normal_texture = 'path/to/normal_texture.png' + # + # @overload normal_texture=(image_path) + # + # @param [String] image_path + # + # @overload normal_texture=(image_rep) + # + # @param [Sketchup::ImageRep] image_rep + # + # @overload normal_texture=(texture) + # + # Copies another texture to this texture. + # @param [Sketchup::Texture] texture + # + # @raise [ArgumentError] if the image data of the texture is invalid or corrupt. + # + # @raise [ArgumentError] if the image data is not 24 bits per pixels or higher. + # + # @see #normal_enabled? + # + # @see #normal_scale + # + # @see #normal_scale= + # + # @see #normal_style + # + # @see #normal_style= + # + # @version SketchUp 2025.0 + def normal_texture=(texture) + end + + # The {#owner_type} method is used to determine what owns the material. + # + # {Material Owner Types}[#owner_type_constant_summary]: + # + # - {Sketchup::Material::OWNER_MANAGER} + # - {Sketchup::Material::OWNER_IMAGE} + # - {Sketchup::Material::OWNER_LAYER} # # @return [Integer] # @@ -309,52 +830,187 @@ def name=(str) def owner_type end - # The {#save_as} method is used to write a material to a SKM file. # - # You must remember to append ".skm" to the filename as this will not be done - # automatically. + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.roughness_enabled = true + # + # @param [Boolean] enabled + # + # @see #roughness_texture + # + # @see #roughness_texture= + # + # @see #roughness_factor + # + # @see #roughness_factor= + # + # @version SketchUp 2025.0 + def roughness_enabled=(enabled) + end + + # + # @example + # material = Sketchup.active_model.materials.add("Material") + # material.roughness_enabled? + # # > false + # + # @return [Boolean] + # + # @see #roughness_texture + # + # @see #roughness_texture= + # + # @see #roughness_factor + # + # @see #roughness_factor= + # + # @version SketchUp 2025.0 + def roughness_enabled? + end + # # @example - # filename = File.join(ENV['HOME'], 'Desktop', 'su_test.skm') + # material = Sketchup.active_model.materials.add("PBR Material") + # material.roughness_enabled = true + # material.roughness_factor + # # > 1.0 + # + # @return [Float] A value between +0.0+ and +1.0+. + # + # @see #roughness_enabled? + # + # @see #roughness_enabled= + # + # @see #roughness_texture + # + # @see #roughness_texture= + # + # @version SketchUp 2025.0 + def roughness_factor + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.roughness_enabled = true + # material.roughness_factor = 1.0 + # + # @param [Float] factor + # A value between +0.0+ and +1.0+. + # + # @see #roughness_enabled? + # + # @see #roughness_enabled= + # + # @see #roughness_texture + # + # @see #roughness_texture= + # + # @version SketchUp 2025.0 + def roughness_factor=(factor) + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.roughness_enabled = true + # material.roughness_texture + # # > nil + # + # @return [Sketchup::Texture] + # + # @see #roughness_enabled? + # + # @see #roughness_enabled= + # + # @see #roughness_factor + # + # @see #roughness_factor= + # + # @version SketchUp 2025.0 + def roughness_texture + end + + # + # @example + # material = Sketchup.active_model.materials.add("PBR Material") + # material.texture = 'path/to/texture.png' + # material.roughness_texture = 'path/to/roughness_texture.png' + # + # @overload roughness_texture=(image_path) + # + # @param [String] image_path + # + # @overload roughness_texture=(image_rep) + # + # @param [Sketchup::ImageRep] image_rep + # + # @overload roughness_texture=(texture) + # + # Copies another texture to this texture. + # @param [Sketchup::Texture] texture + # + # @raise [ArgumentError] if the image data of the texture is invalid or corrupt. + # + # @see #roughness_enabled? + # + # @see #roughness_enabled= + # + # @see #roughness_factor + # + # @see #roughness_factor= + # + # @version SketchUp 2025.0 + def roughness_texture=(texture) + end + + # The {#save_as} method is used to write a material to a SKM file. + # + # @example + # filename = File.join(Sketchup.temp_dir, 'su_test.skm') # materials = Sketchup.active_model.materials # material = materials.add("Hello World") # material.color = 'red' # material.save_as(filename) # + # @note You must remember to append ".skm" to the filename as this will not be + # done automatically. + # # @param [String] filename # the path to the SKM file to load. # - # @return [Boolean] `true` if successful + # @return [Boolean] # # @version SketchUp 2017 def save_as(filename) end - # The texture method retrieves the texture of the material. + # The {#texture} method retrieves the texture of the material. # # @example # model = Sketchup.active_model # materials = model.materials # material = materials.add('Joe') - # material.texture = "C:/Materials/Carpet.jpg" + # material.texture = 'path/to/metallic_texture.png' # texture = material.texture # - # @return [Sketchup::Texture, nil] the Texture object within the Material. - # Returns nil if the Material does not have a texture. + # @return [Sketchup::Texture, nil] # # @version SketchUp 6.0 def texture end - # The texture= method sets the texture for the material. + # The {#texture=} method sets the texture for the material. # - # Setting the texture to +nil+ will turn it into a solid color + # Setting the texture to +nil+ will turn remove it and the material will use + # {#color}. # # @example # model = Sketchup.active_model # materials = model.materials # material = materials.add('Joe') - # material.texture = "C:/Materials/Carpet.jpg" + # material.texture = 'path/to/metallic_texture.png' # # @overload texture=(filename) # @@ -364,51 +1020,96 @@ def texture # @overload texture=(properties) # # @param [Array(String, Length, Length)] properties - # An array with the texture file path and optionally the width and height. + # An array with the texture file path and optionally a width and height + # which sets {Sketchup::Texture#width} and {Sketchup::Texture#height}. + # + # @overload texture=(properties) + # + # @param [Array(String, Length)] properties + # An array with the texture file path and optionally a size + # which sets {Sketchup::Texture#width} and {Sketchup::Texture#height}. # # @overload texture=(image_rep) # + # @version SketchUp 2018 # @param [Sketchup::ImageRep] image_rep The pixel data representing the - # texture. (Added in SketchUp 2018) + # texture. # # @version SketchUp 6.0 def texture=(arg) end - # The use_alpha? method tells if the material uses transparency. - # - # Note that this is not affected by the alpha value of the color object. Only - # the .alpha value and transparent texture will make this method return true. + # The {#use_alpha?} method tells if the material uses transparency. It uses + # some tolerance checking to account for floating point precision noise. # # @example - # material = Sketchup.active_model.materials[0] - # is_alpha = material.use_alpha? + # material = Sketchup.active_model.materials.add('Example') + # material.use_alpha? + # # > false + # + # material.alpha = 0.5 + # material.use_alpha? + # # > true + # + # @note that this is not affected by the alpha value of the {#color} object. + # Only the {#alpha} value will make this method return +true+. # # @return [Boolean] # + # @see #alpha + # + # @see #alpha= + # # @version SketchUp 6.0 def use_alpha? end - # The write_thumbnail method writes a bitmap thumbnail to the given file name. + # {Material Workflows}[#workflow_constant_summary]: + # + # - {WORKFLOW_CLASSIC} + # - {WORKFLOW_PBR_METALLIC_ROUGHNESS} + # + # When the workflow returns +WORKFLOW_PBR_METALLIC_ROUGHNESS+ the properties + # listed under {PBR Metallic Roughness Workflow}[#pbr_metallic_roughness_workflow] + # are relevant. + # + # @example Classic material + # material = Sketchup.active_model.materials.add("Material") + # workflow = material.workflow + # # > workflow == Sketchup::Material::WORKFLOW_CLASSIC + # + # @example PBR material + # material = Sketchup.active_model.materials.add("PBR Material") + # material.metalness_enabled = true # Or any of the other PBR properties. + # workflow = material.workflow + # # > workflow == Sketchup::Material::WORKFLOW_PBR_METALLIC_ROUGHNESS + # + # @return [Integer] One of +Sketchup::Material::WORKFLOW_*+ values. + # + # @version SketchUp 2025.0 + def workflow + end + + # The {#write_thumbnail} method writes a bitmap thumbnail to the given file name. # # @example # model = Sketchup.active_model # model.materials.each { |material| - # thumbnail_file = "C:/tmp/materials/#{material.display_name}.png" + # thumbnail_file = File.join(Sketchup.temp_dir, "#{material.display_name}.png") # material.write_thumbnail(thumbnail_file, 128) # } # # @param [String] path # The file path for the thumbnail. # - # @param [Integer] resolution - # The resolution of the thumbnail. + # @param [Integer] max_size + # The maximum width or height of the generated image. # - # @return [Boolean] true if successful, false if unsuccessful. + # @return [Boolean, nil] +true+ if successful, +false+ if unsuccessful. + # +nil+ if arguments are invalid. # # @version SketchUp 8.0 M1 - def write_thumbnail(path, resolution) + def write_thumbnail(path, max_size) end end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb index 65767d9..aadb9b3 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A collection of Materials objects. Each model contains a Materials collection @@ -162,7 +162,7 @@ def current=(material) # 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] + # @return [Sketchup::Materials] # # @version SketchUp 6.0 # @@ -193,9 +193,18 @@ def length # If a matching material exist in the model it will be returned instead. # # @example - # # Load a material from the shipped SketchUp library. (SketchUp 2016) - # filename = 'Materials/Brick, Cladding and Siding/Cinder Block.skm' - # path = Sketchup.find_support_file(filename) + # # Load a material from the shipped SketchUp library. + # materials_template = Sketchup.find_support_file('Materials/MaterialTemplate.skp') + # if materials_template && File.exist?(materials_template) + # # Newer SketchUp versions. + # materials_path = File.dirname(materials_template) + # files = Dir.glob(File.join(materials_path, '**', '*.skm')) + # path = files.first + # else + # # Older SketchUp versions. + # filename = 'Materials/Brick, Cladding and Siding/Cinder Block.skm' + # path = Sketchup.find_support_file(filename) + # end # materials = Sketchup.active_model.materials # material = materials.load(path) # @@ -224,24 +233,28 @@ def purge_unused # Remove a given material. # - # NOTE: On SketchUp versions prior to 2014 there is a bug in this method that - # could potentially lead to file corruption. If you call Materials.remove on a - # material that is painted onto any entity in the active model (e.g. faces, - # edges, groups, ...), then calling this method will not successfully unpaint - # the entity and remove the material from the model. - # You must first unpaint all of the entities that respond to .material - # and .back_material before calling Materials.remove. - # - # @example - # if entity.respond_to?(:material) do - # if entity.material.equal?(material_to_remove) do - # entity.material = nil + # @bug On SketchUp versions prior to 2014 there is a bug in this method that + # could potentially lead to file corruption. If you call {#remove} on a + # material that is painted onto any entity in the active model (e.g. faces, + # edges, groups, ...), then calling this method will not successfully unpaint + # the entity and remove the material from the model. + # You must first unpaint all of the entities that respond to +.material+ + # and +.back_material+ before calling {#remove}. + # + # @example Logic for removing a given material of an entity: + # # @param [Sketchup::Entity] entity + # # @param [Sketchup::Material] material_to_remove + # def remove_material(entity, material_to_remove) + # if entity.respond_to?(:material) do + # if entity.material.equal?(material_to_remove) do + # entity.material = nil + # end # end - # end - # # for entities that have a back material - # if entity.respond_to?(:back_material) do - # if entity.back_material.equal?(material_to_remove) do - # entity.back_material = nil + # # for entities that have a back material + # if entity.respond_to?(:back_material) do + # if entity.back_material.equal?(material_to_remove) do + # entity.back_material = nil + # end # end # end # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/MaterialsObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/MaterialsObserver.rb index de53068..9a009b2 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/MaterialsObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/MaterialsObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to materials events. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Menu.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Menu.rb index 02de72e..7ef64ca 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Menu.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Menu.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An interface to a menu. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb index 0999601..2959743 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This is the interface to a SketchUp model. The model is the 3D drawing that @@ -7,13 +7,6 @@ # current model, and from there you can use the model-level methods to start # getting information and making changes. # -# Constants: -# Product Family -# - Model::ProTrial -# - Model::ProLicensed -# - Model::MakeTrial -# - Model::MakeTrialExpired -# # @bug Prior to SketchUp 2019.0 this class would yield +TypeError+ for all # method calls if +#singleton_class+ was called on the model object. # @@ -32,10 +25,10 @@ # # Now that we have our handles, we can start pulling objects and making # # method calls that are useful. # first_entity = entities[0] -# UI.messagebox("First thing in your model is a #{first_entity.typename}") +# puts "First thing in your model is a #{first_entity.typename}" # # number_materials = materials.length -# UI.messagebox("Your model has #{number_materials} materials.") +# puts "Your model has #{number_materials} materials." # # new_edge = entities.add_line([0,0,0], [500,500,0]) # @@ -178,9 +171,9 @@ def active_path # on the given path. A definition cannot be edited if any of its instances # are locked. # - # @note Since changing the active entities in SketchUp also changes what - # coordinate system is used, entities can't be modified in the same operation - # as the active entities changes. The API handles this automatically by + # @note When changing the active entities in SketchUp, the coordinate system + # also changes. Therefore, entities cannot be modified in the same operation + # as the active entities change. The API handles this automatically by # starting and committing transparent operations as needed. # # If the API user tries to do this: @@ -228,6 +221,24 @@ def active_path def active_path=(instance_path) end + # The {#active_section_planes} method returns all of the active section planes in the model. + # + # @example SketchUp 2025 and newer + # model = Sketchup.active_model + # section_planes = model.active_section_planes + # + # @example SketchUp 2024 and older + # # In older SketchUp versions, you can achieve the same result with: + # model = Sketchup.active_model + # entities_collections = [Sketchup.active_model.entities] + model.definitions.map(&:entities) + # section_planes = entities_collections.map(&:active_section_plane).compact + # + # @return [Array] + # + # @version Sketchup 2026.0 + def active_section_planes + end + # The {#active_view} method returns the active View object for this model. # # @example @@ -498,6 +509,9 @@ def description=(description) # The {#drawing_element_visible?} method reports whether the given drawing # element in an instance path is visible given the current model options. # + # @bug Prior to version 2026.0 the method throws an exception when the last + # element in the instance path is a {Sketchup::Group} or {Sketchup::ComponentInstance}. + # # @example Traversing every visible entity in the model # module Example # @@ -575,6 +589,19 @@ def edit_transform def entities end + # The {#environments} method is used to retrieve the {Sketchup::Environments} object for + # this model. + # + # @example + # model = Sketchup.active_model + # environments = model.environments + # + # @return [Sketchup::Environments] + # + # @version SketchUp 2025.0 + def environments + end + # The export method is used to export a given file format. It knows which # format to export based on the file extension you place on the file name. # For example, a filename of "thing.obj" will export an OBJ file, whereas @@ -588,10 +615,15 @@ def entities # * SketchUp Pro 2015+ added IFC export capability. # * SketchUp Pro 2016+ added PDF export capability. # * SketchUp Pro 2018+ added options for all 3D exporters. + # * SketchUp 2024+ added glb and usdz exporters. + # * SketchUp 2026+ the IFC exporter has been replaced with a new implementation + # that provides specific export options. # # See the {file:pages/exporter_options.md Exporter Options} file for information # on creating a valid hash for the various exporters. # + # @bug IFC export on ARM macs isn't working for SketchUp 2022-2025. + # # @example General use # model = Sketchup.active_model # show_summary = true @@ -621,10 +653,11 @@ def entities # # @example IFC Example # model = Sketchup.active_model - # # If no IFC types are passed in, then no geometry will be exported. - # options_hash = { :hidden_geometry => true, - # :ifc_mapped_items => true, - # :ifc_types => ['IfcBuilding', 'IfcDoor']} + # options_hash = { :ifc_version => "IFC 4", + # :standard_ifc_hierarchy => true, + # :selectionset_only => false, + # :hidden_geometry => true, + # :tessellated_geometry => true } # status = model.export('c:/my_export.ifc', options_hash) # # @overload export(path, show_summary = false) @@ -720,8 +753,9 @@ def find_entity_by_id(ids_or_array) # @param [Array] ids_or_array Pass either a series of ids or a # single array containing persistent ids. # - # @return [Array] Returns an array with - # {Sketchup::Entity} objects for each id found and nil otherwise. + # @return [Sketchup::Entity, Array, nil] Returns an {Sketchup::Entity} if a + # single PID was given or an array of {Sketchup::Entity} objects for each id found or nil if + # nothing was found. # # @overload find_entity_by_persistent_id(ids_or_array, **scope) # @@ -730,23 +764,24 @@ def find_entity_by_id(ids_or_array) # single array containing persistent ids. # @param [Hash] scope Limit the scope of the search to the # given scope categories. - # @option [Boolean] scope :entities Search entities parent to + # @option scope [Boolean] :entities Search entities parent to # {Sketchup::Entities}. - # @option [Boolean] scope :layers Search {Sketchup::Layers} for + # @option scope [Boolean] :layers Search {Sketchup::Layers} for # {Sketchup::Layer} entities. - # @option [Boolean] scope :layer_folders Search {Sketchup::Layers} for + # @option scope [Boolean] :layer_folders Search {Sketchup::Layers} for # {Sketchup::LayerFolder} entities. - # @option [Boolean] scope :materials Search {Sketchup::Materials} for + # @option scope [Boolean] :materials Search {Sketchup::Materials} for # {Sketchup::Material} entities. - # @option [Boolean] scope :pages Search {Sketchup::Pages} for + # @option scope [Boolean] :pages Search {Sketchup::Pages} for # {Sketchup::Page} entities. - # @option [Boolean] scope :styles Search {Sketchup::Styles} for + # @option scope [Boolean] :styles Search {Sketchup::Styles} for # {Sketchup::Style} entities. - # @option [Boolean] scope :definitions Search {Sketchup::DefinitionList} for + # @option scope [Boolean] :definitions Search {Sketchup::DefinitionList} for # {Sketchup::ComponentDefinition} entities. # - # @return [Array] Returns an array with - # {Sketchup::Entity} objects for each id found and nil otherwise. + # @return [Sketchup::Entity, Array, nil] Returns an {Sketchup::Entity} if a + # single PID was given or an array of {Sketchup::Entity} objects for each id found if multiple + # PIDs were given or nil if nothing was found. # # @version SketchUp 2017 def find_entity_by_persistent_id(*args) @@ -755,11 +790,8 @@ def find_entity_by_persistent_id(*args) # This methods determines if the model is georeferenced. # # @example - # if model.georeferenced? - # UI.messagebox('This model is georeferenced.') - # else - # UI.messagebox('This model is NOT georeferenced.') - # end + # model = Sketchup.active_model + # model.georeferenced? # # @return [Boolean] # @@ -812,7 +844,16 @@ def get_datum # Returns a value which indicates the product family of the installed SketchUp # application. - # As of SketchUp 2013, the return values are: + # + # The constants for possible return values since SketchUp 2016: + # + # - {Sketchup::Model::ProTrial} + # - {Sketchup::Model::ProLicensed} + # - {Sketchup::Model::MakeTrial} + # - {Sketchup::Model::Make} + # + # In earlier SketchUp versions there were no defined constants and additional + # values could be returned. As of SketchUp 2013, the return values were: # - +0+ = Unknown # - +1+ = Pro Trial # - +2+ = Pro @@ -822,9 +863,6 @@ def get_datum # - +6+ = Make # - +7+ = Pro License Unavailable # - # The Model class defines some of these values as constants as of SketchUp - # 2016. - # # @example # model = Sketchup.active_model # product_family = model.get_product_family @@ -1101,8 +1139,6 @@ def number_faces def options end - # - # @api Overlays # # @example # Sketchup.active_model.overlays.each { |overlay| @@ -1146,6 +1182,10 @@ def path # The place_component method places a new component in the Model using the # component placement tool. # + # @bug Before SketchUp 2026.0, attempting to place an empty component + # would crash SketchUp. This function will now raise an ArgumentError + # when called with an empty component definition. + # # @example # model.place_component componentdefinition, repeat # @@ -1157,6 +1197,10 @@ def path # If set to true, stay in the component # placement tool and place multiple components. # + # @raise [ArgumentError] if the component cannot not be placed + # (for example, if it is an empty component definition). + # Added in SketchUp 2026.0. + # # @return [Sketchup::Model, nil] The model object on success or Nil # # @version SketchUp 6.0 @@ -1205,31 +1249,26 @@ def point_to_latlong(point) def point_to_utm(point) end - # The raytest method is used to cast a ray (line) through the model and return + # The {#raytest} method is used to cast a ray (line) through the model and return # the first thing that the ray hits. # # A ray is a two element array containing a point and a vector - # [Geom::Point3d(), Geom::Vector3d()]. The point defines the start point of + # +[Geom::Point3d, Geom::Vector3d]+. The point defines the start point of # the ray and the vector defines the direction. If direction can not be - # normalized (e.g. direction = [0, 0, 0]), direction is taken as a point the + # normalized (e.g. +direction = [0, 0, 0]+), direction is taken as a point the # ray intersects. # - # first value is a Point3d where the item that the ray passed through exists. The second element is - # the instance path array of the entity that the ray hit. For example, if the ray hits a face that - # is contained by a component instance the instance path would be [Component1]. If the ray hit a - # face that is contained by a component instance, which - # is contained by another component instance and so on, - # the instance path would be [Component1, Component2, - # Component3...]. + # @example Using a pickray from the view + # model = Sketchup.active_model + # ray = model.active_view.pickray(200, 400) # Screen coordinates + # item = model.raytest(ray) # - # @example + # @example Using an arbitrary ray # model = Sketchup.active_model # ray = [Geom::Point3d.new(1, 2, 3), Geom::Vector3d.new(4, 5, 6)] # item = model.raytest(ray, false) # Consider hidden geometry when # # computing intersections. # - # @note The parameter wysiwyg_flag was added in SU8 M1. - # # @param [Array(Geom::Point3d, Geom::Vector3d)] ray # A two element array containing a point and a vector. # @@ -1240,7 +1279,15 @@ def point_to_utm(point) # defaults to true (WYSIWYG) - i.e. hidden geometry is # not intersected against. # - # @return [Array(Geom::Point3d, Array), nil] an array of two values. The + # @return [Array(Geom::Point3d, Array), nil] The first value is + # a {Geom::Point3d} where the item that the ray passed through exists. The second element is + # the instance path array of the entity that the ray hit. For example, if the ray hits a face + # that is contained by a component instance the instance path would be [Component1]. + # If the ray hit a face that is contained by a component instance, which is contained by + # another component instance and so on, the instance path would be [Component1, Component2, + # Component3...]. + # + # @see Sketchup::View#pickray # # @version SketchUp 6.0 def raytest(ray, wysiwyg_flag = true) @@ -1321,23 +1368,25 @@ def rendering_options # @param [String] path # @param [Integer] version # 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 + # - {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} # # @return [Boolean] +true+ if successful, +false+ if unsuccessful + # + # @see #save_copy def save(*args) end @@ -1353,16 +1402,25 @@ def save(*args) # path = File.join(ENV['Home'], 'Desktop', 'mysketchupcopy_v8.skp') # status = model.save_copy(path, Sketchup::Model::VERSION_8) # - # @param [String] path - # The path of the file to save the model copy to. + # @overload save_copy(path) + # + # @param [String] path + # The path of the file to save the model copy to. + # + # @overload save_copy(path, version) + # + # @param [String] path + # The path of the file to save the model copy to. # - # @param [Integer] version - # See {Sketchup::Model#save} for supported values. + # @param [Integer] version + # See {Sketchup::Model#save} for supported values. # # @return [Boolean] true if successful, false if unsuccessful # + # @see #save + # # @version SketchUp 2014 - def save_copy(path, version) + def save_copy(*args) end # The save_thumbnail method is used to save a thumbnail image to a file. @@ -1383,22 +1441,23 @@ def save_copy(path, version) def save_thumbnail(filename) end - # This method is used to select a SketchUp Tool object s the active tool. You - # must implement the SketchUp Tool interface to create a tool prior to calling - # this method. + # The {#select_tool} method is used to select a SketchUp Tool object as the active tool. + # To activate the native Select tool, pass nil as the argument. + # + # Before calling this method, you need to implement the SketchUp Tool interface + # and create a tool object. Then, pass the tool object to this method to activate it. # - # The select tool is activated if you pass nil to the select_tool method. You - # must implement the SketchUp Tool interface to create a tool, prior to calling - # this method, and then instance the tool implementation and pass the object to - # this method. If you attempt to set the select_tool to nil in the initialize - # method of a tool you have written, it will be ignored. + # the native Select tool. # # @example # model = Sketchup.active_model # tool = model.select_tool(nil) # + # @note If you call select_tool from within the initialize method of a custom tool, the call will + # be ignored. + # # @param [Object] tool - # The Tool object you want to select. + # A tool instance object to activate, or nil to activate # # @return [Sketchup::Model] The Model object. # @@ -1586,7 +1645,7 @@ def tags def tags=(tags) end - # The tile method retrieves the name of the model. If the model is saved on + # The {#title} method retrieves the name of the model. If the model is saved on # disk, returns the file name without extension. Otherwise returns an empty # string. # @@ -1641,11 +1700,6 @@ def utm_to_point(utm) # # This is a silly example since the active model is generally going to # # be valid, but it illustrates the idea. # model = Sketchup.active_model - # if model.valid? - # UI.messagebox('This model is valid.') - # else - # UI.messagebox('This model is NOT valid.') - # end # # @return [Boolean] # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ModelObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ModelObserver.rb index ae137ad..22b0be9 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ModelObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ModelObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to model events. @@ -168,22 +168,37 @@ def onEraseAll(model) def onExplode(model) end - # The {#onPidChanged} method is invoked when a persistent id in the model - # changes. For example when entities are grouped. + # The {#onPidChanged} method is invoked when a {Sketchup::Entity#persistent_id persistent id} of + # an entity changes within the model. # # @example - # def onPidChanged(model, old_pid, new_pid) - # puts "onPidChanged: #{model}, #{old_pid} => #{new_pid}" + # class PidObserver < Sketchup::ModelObserver + # def onPidChanged(model, old_pid, new_pid) + # entity = model.find_entity_by_persistent_id(new_pid) + # puts "Entity with new PID #{new_pid}: #{entity}" + # end # end # + # model = Sketchup.active_model + # model.add_observer(PidObserver.new) + # + # @note This callback is useful for tracking changes to entities that result in new PIDs, such as + # grouping or other modifications that result in new entities. + # # @param [Sketchup::Model] model # # @param [Integer] old_pid + # The old persistent ID of the entity. # # @param [Integer] new_pid + # The new persistent ID of the entity. # # @return [nil] # + # @see Sketchup::Model#find_entity_by_persistent_id + # + # @see Sketchup::Entity#persistent_id + # # @version SketchUp 2017 def onPidChanged(model, old_pid, new_pid) end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/OptionsManager.rb b/lib/sketchup-api-stubs/stubs/Sketchup/OptionsManager.rb index 4a6ec3e..0460dd3 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/OptionsManager.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/OptionsManager.rb @@ -1,9 +1,22 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The OptionsManager class manages various kinds of OptionsProviders on a # Model. # +# To get the OptionsProvider key list, run the following code in the ruby console: +# +# @example +# options_manager = Sketchup.active_model.options +# options_manager.keys.each { |provider_name| +# options_provider = options_manager[provider_name] +# puts provider_name +# options_provider.each { |key, value| +# puts " #{key} - #{value}" +# } +# puts +# } +# # @version SketchUp 6.0 class Sketchup::OptionsManager @@ -25,11 +38,6 @@ class Sketchup::OptionsManager # model = Sketchup.active_model # manager = model.options # provider = manager[0] - # if (provider) - # UI.messagebox provider.name - # else - # UI.messagebox "Failure" - # end # # @overload [](index) # @@ -86,11 +94,6 @@ def each # model = Sketchup.active_model # manager = model.options # optionproviderarray = manager.keys - # if (optionproviderarray) - # UI.messagebox optionproviderarray - # else - # UI.messagebox "Failure" - # end # # @return keys - Array of string keys # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProvider.rb b/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProvider.rb index f828bc1..2a038ab 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProvider.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProvider.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An +OptionsProvider+ class provides various kinds of options on a diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProviderObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProviderObserver.rb index bee7330..64f2f5b 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProviderObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProviderObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to operations provider diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb index baadd9b..29c552c 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An Overlay provides contextual model information directly in the viewport. @@ -13,8 +13,6 @@ # 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 # @@ -64,8 +62,6 @@ class Sketchup::Overlay # 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}" @@ -80,8 +76,6 @@ def description # 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}" @@ -96,8 +90,6 @@ def description=(description) # # @abstract It is called whenever the view updates. # - # @api Overlays - # # @example # class ExampleOverlay < Sketchup::Overlay # @@ -143,8 +135,6 @@ def description=(description) 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 @@ -160,8 +150,6 @@ def draw(view) def enabled=(enabled) end - # - # @api Overlays # # @example # Sketchup.active_model.overlays.each { |overlay| @@ -189,8 +177,6 @@ def enabled? # 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 # @@ -221,8 +207,6 @@ def enabled? def getExtents end - # - # @api Overlays # # @example # class ExampleOverlay < Sketchup::Overlay @@ -256,8 +240,6 @@ def initialize(id, name, description: "") # 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?}" @@ -275,8 +257,6 @@ def name # @abstract It can be used by implementing sub-classes to react to # mouse movement in the viewport. # - # @api Overlays - # # @example # class ExampleOverlay < Sketchup::Overlay # @@ -315,8 +295,6 @@ def onMouseEnter(flags, x, y, view) # @abstract It can be used by implementing sub-classes to react to # mouse movement in the viewport. # - # @api Overlays - # # @example # class ExampleOverlay < Sketchup::Overlay # @@ -342,8 +320,6 @@ def onMouseLeave(view) # @abstract It can be used by implementing sub-classes to react to # mouse movement in the viewport. # - # @api Overlays - # # @example # class ExampleOverlay < Sketchup::Overlay # @@ -360,24 +336,29 @@ def onMouseLeave(view) # # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onMouseMove(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 2023.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onMouseMove(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 2023.0 - def onMouseMove(flags, x, y, view) + def onMouseMove end - # - # @api Overlays # # @example Implementing # class ExampleOverlay < Sketchup::Overlay @@ -402,8 +383,6 @@ def overlay_id # 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})" @@ -419,8 +398,6 @@ def source # @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 # @@ -442,8 +419,6 @@ def start # @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 # @@ -464,8 +439,6 @@ def stop # 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 diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/OverlaysManager.rb b/lib/sketchup-api-stubs/stubs/Sketchup/OverlaysManager.rb index 4be3880..2c67f08 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/OverlaysManager.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/OverlaysManager.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # An overlay added to a model is invalidated once it's removed from the model. @@ -10,8 +10,6 @@ # # A model can not have multiple overlays with the same id. # -# @api Overlays -# # @example # Sketchup.active_model.overlays.each { |overlay| # puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}" @@ -29,8 +27,6 @@ class Sketchup::OverlaysManager # Instance Methods - # - # @api Overlays # # @example # overlay = Sketchup.active_model.overlays[0] @@ -42,8 +38,6 @@ def [](index) end alias_method :at, :[] - # - # @api Overlays # # @example # class ExampleOverlay < Sketchup::Overlay @@ -63,8 +57,6 @@ def [](index) def add(service) end - # - # @api Overlays # # @example # Sketchup.active_model.overlays.each { |overlay| @@ -79,8 +71,6 @@ def add(service) def each end - # - # @api Overlays # # @example # class ExampleOverlay < Sketchup::Overlay @@ -100,8 +90,6 @@ def each def remove(service) end - # - # @api Overlays # # @example # num_overlays = Sketchup.active_model.overlays.size diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Page.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Page.rb index ca7f333..e77c2f9 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Page.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Page.rb @@ -1,31 +1,71 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) -# The Page class contains methods to extract information and modify the -# properties of an individual page. +# The Page class contains methods to extract information and modify the properties of +# an individual page. # # Note that inside the SketchUp user interface pages are called "Scenes". # +# Since SketchUp 2026.0, modifying the {Sketchup::Axes}, {Sketchup::Camera}, +# {Sketchup::RenderingOptions}, and {Sketchup::ShadowInfo} properties of a page is an undoable +# operation and should be wrapped between {Sketchup::Model#start_operation} and +# {Sketchup::Model#commit_operation}. +# Example: +# model = Sketchup.active_model +# pages = model.pages +# origin = Geom::Point3d.new(10, 0, 0) +# +# model.start_operation("Set Page Properties") +# page = pages.add("My Page") +# page.axes.set(origin, Y_AXIS, X_AXIS, Z_AXIS) +# page.camera.fov = 56.78 +# page.shadow_info["City"] = "Brasov, Romania" +# page.rendering_options["BackgroundColor"] = "Pink" +# model.commit_operation +# # @version SketchUp 6.0 class Sketchup::Page < Sketchup::Entity # Instance Methods + # The {#active_section_planes} method is used to retrieve the active section + # plane for the {Sketchup::Page}. + # + # @example + # model = Sketchup.active_model + # pages = model.pages + # page = pages.add('My Page') + # page.active_section_planes + # + # @return [Array, nil] Returns +nil+ if the page does + # not use section planes. + # + # @version SketchUp 2026.0 + def active_section_planes + end + # The axes method returns the drawing axes for the page. # + # Since SketchUp 2026.0, modifying the axes of a scene is an undoable operation. + # # @example - # page = Sketchup.active_model.pages.add("Example Page") + # model = Sketchup.active_model + # page = model.pages.add("Example Page") # xaxis = Geom::Vector3d.new(3, 5, 0) # yaxis = xaxis * Z_AXIS # page.axes.set([10,0,0], xaxis, yaxis, Z_AXIS) + # page.update(PAGE_USE_ALL) + # page.axes # - # @return Axes - the axes for the page. + # @return [Sketchup::Axes] # # @version SketchUp 2016 def axes end - # The camera method retrieves the camera for a particular page. + # The {#camera} method retrieves the camera for a particular page. + # + # Since SketchUp 2026.0, modifying the camera properties of a scene is an undoable operation. # # @example # model = Sketchup.active_model @@ -33,8 +73,7 @@ def axes # page = pages.add "My Page" # camera = page.camera # - # @return camera - a Camera object if successful, nil if the page - # does not save camera information + # @return [Sketchup::Camera] # # @version SketchUp 6.0 def camera @@ -114,6 +153,40 @@ def description def description=(description) end + # The {#environment} method is used to retrieve the {Sketchup::Environment} + # for the scene. + # + # @example + # model = Sketchup.active_model + # pages = model.pages + # page = pages.add('My Page') + # page.environment + # + # @return [Sketchup::Environment] + # + # @version SketchUp 2025.0 + def environment + end + + # The {#environment=} method is used to set the {Sketchup::Environment} + # for the scene. + # + # @example + # model = Sketchup.active_model + # pages = model.pages + # page = pages.add('My Page') + # path = 'path/to/environment.hdr' + # environment = model.environments.add('My Environment', path) + # page.environment = environment + # + # @param [Sketchup::Environment] environment + # + # @return [Sketchup::Environment] + # + # @version SketchUp 2025.0 + def environment=(environment) + end + # The {#get_drawingelement_visibility} method is used to get the visibility # of a drawing element on a particular page. # @@ -126,6 +199,19 @@ def description=(description) # page = pages.add("My Page") # result = page.get_drawingelement_visibility(constpoint) # + # @example + # # SketchUp 2020.1 is required + # def element_visible_in_page?(element, page) + # case element + # when Sketchup::ComponentInstance, Sketchup::Group + # return unless page.use_hidden_objects? + # else + # return unless page.use_hidden_geometry? + # return unless element.parent == Sketchup.active_model + # end + # page.get_drawingelement_visibility(element) + # end + # # @param [Sketchup::Drawingelement] element # # @return [Boolean] - true if visible, false if not. @@ -142,8 +228,8 @@ def get_drawingelement_visibility(element) # page = pages.add "My Page" # entities = page.hidden_entities # - # @return entities - an Entities object containing hidden - # entities on the page. + # @return [Array] an array of drawing elements that are + # *hidden* on the page. # # @version SketchUp 6.0 def hidden_entities @@ -248,7 +334,10 @@ def layers def name end - # The name= method sets the name for a page's tab. + # The {#name=} method sets the name for a page's tab. If the name is already used by another page, + # a unique name is created. + # + # @bug Prior to SketchUp 2026.0 this method did not make the name unique. # # @example # model = Sketchup.active_model @@ -268,13 +357,20 @@ def name=(name) # The rendering_options method retrieves a RenderingOptions object for the # page. # + # Since SketchUp 2026.0, modifying rendering_options of a scene is an undoable operation. + # # @example # model = Sketchup.active_model # pages = model.pages - # page = pages.add "My Page" + # page = pages.add("My Page") # renderingoptions = page.rendering_options # - # @return renderingoptions - a RenderingOptions object + # @note Most rendering options of a scene are also present in {Sketchup::Style} and are governed by + # the selected style. Those options should not be changed from the scene. + # The ones not related to {Sketchup::Style} like fog (+DisplayFog+, + # +FogColor+) are safe to be changed from the scene. + # + # @return [Sketchup::RenderingOptions] # # @version SketchUp 6.0 def rendering_options @@ -331,7 +427,9 @@ def set_drawingelement_visibility(element, visibility) def set_visibility(arg1, arg2) end - # The shadow_info method retrieves the ShadowInfo object for the page. + # The {#shadow_info} method retrieves the ShadowInfo object for the page. + # + # Since SketchUp 2026.0, modifying shadow_info of a scene is an undoable operation. # # @example # model = Sketchup.active_model @@ -339,8 +437,11 @@ def set_visibility(arg1, arg2) # page = pages.add "My Page" # shadowinfo = page.shadow_info # - # @return shadowinfo - a ShadowInfo object if successful, nil if - # the page does not save shadow information + # @note While certain shadow settings, such as those available in the Shadows panel, can be + # controlled on a per-page basis, global settings like north + # angle, latitude, and longitude are managed at the model level and are not page-specific. + # + # @return [Sketchup::ShadowInfo] # # @version SketchUp 6.0 def shadow_info @@ -410,6 +511,7 @@ def transition_time=(trans_time) # PAGE_USE_LAYER_VISIBILITY # Visible Layers # PAGE_USE_SECTION_PLANES # Active Section Planes # PAGE_USE_ALL # All possible scene properties + # PAGE_USE_ENVIRONMENT # Environment settings # # @example # model = Sketchup.active_model @@ -503,6 +605,46 @@ def use_camera=(setting) def use_camera? end + # The {#use_environment=} method is used to set if the {Sketchup::Environment} + # settings are used in the scene. + # + # @example + # model = Sketchup.active_model + # pages = model.pages + # page = pages.add('My Page') + # page.use_environment? + # # => true + # page.use_environment = false + # page.use_environment? + # # => false + # + # @param [Boolean] use_environment + # + # @return [Boolean] + # + # @version SketchUp 2025.0 + def use_environment=(use_environment) + end + + # The {#use_environment?} method is used to determine if the {Sketchup::Environment} + # settings are used in the scene. + # + # @example + # model = Sketchup.active_model + # pages = model.pages + # page = pages.add('My Page') + # page.use_environment? + # # => true + # page.use_environment = false + # page.use_environment? + # # => false + # + # @return [Boolean] + # + # @version SketchUp 2025.0 + def use_environment? + end + # The use_hidden= method sets the page's hidden property. # # @deprecated The functionality is replaced by {use_hidden_geometry=} diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Pages.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Pages.rb index 46fe16d..a7f7875 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Pages.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Pages.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Pages class contains methods for manipulating a collection of Pages @@ -17,16 +17,6 @@ class Sketchup::Pages < Sketchup::Entity include Enumerable - # Constants - - ImageEmbedded = nil # Stub value. - ImageEmbeddedAndLinked = nil # Stub value. - ImageLinked = nil # Stub value. - - UnitsNormalizedX = nil # Stub value. - UnitsNormalizedY = nil # Stub value. - UnitsPixels = nil # Stub value. - # Class Methods # The {.add_frame_change_observer} method is used to add a new frame change @@ -82,11 +72,6 @@ def self.remove_frame_change_observer(observer_id) # status = pages.add "Page 1" # status = pages.add "Page 2" # page = pages["Page 2"] - # if (page) - # UI.messagebox page - # else - # UI.messagebox "Failure" - # end # # @param index_or_name # The index or the string name of the specific page. @@ -103,6 +88,8 @@ def [](index_or_name) # new Pages. If a name is given, then a new Page with that name is # added. # + # If the name is already used by another page, a unique name is created. + # # If the flags parameter is given, it controls which properties are saved with # the Page. See the {Page#update} method for a description of the flags that # can be set. @@ -110,16 +97,13 @@ def [](index_or_name) # If index is given, it specifies the position in the page list that the new # page is added. Otherwise the new page is added to the end. # + # @bug Prior to SketchUp 2026.0 this method didn't make the name unique. + # # @example # model = Sketchup.active_model # pages = model.pages # status = pages.add "Page 1" # status = pages.add "Page 2" - # if (status) - # UI.messagebox status - # else - # UI.messagebox "Failure" - # end # # @param [String] name # The name of the specific page. @@ -270,6 +254,31 @@ def parent def remove_observer(observer) end + # The {#reorder} method is used to reorder an existing {Sketchup::Page} object inside collection. + # + # +new_index+ specifies the new position of the page. It should be a value + # between +0+ and the max index of the {Sketchup::Pages} collection. + # Negative indices can be used to specify an index from the end of the list. + # + # @example + # model = Sketchup.active_model + # pages = model.pages + # pages.reorder(model.pages[0], 2) + # + # @param [Sketchup::Page] page + # The page to be reordered. + # + # @param [Integer] new_index + # Index of where to replace the page. + # + # @raise [IndexError] if the given +new_index+ is out of range. + # + # @return nil + # + # @version SketchUp 2025.0 + def reorder(page, new_index) + end + # The selected_page method is used to retrieve the currently selected page. # # @example @@ -358,4 +367,22 @@ def size def slideshow_time end + # The {#unique_name} method is used to generate a unique name for the page based on a base_name + # string. For example, a base name of "Joe" might return "Joe 2" if "Joe" already exists. + # + # @example + # model = Sketchup.active_model + # pages = model.pages + # page = pages.add('Joe') + # page.unique_name('Joe') + # + # @param [String] base_name + # The base name to use for the unique name. + # + # @return [String] The unique name. + # + # @version SketchUp 2026.0 + def unique_name(base_name) + end + end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/PagesObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/PagesObserver.rb index 43cca96..426d24b 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/PagesObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/PagesObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to pages events. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/PickHelper.rb b/lib/sketchup-api-stubs/stubs/Sketchup/PickHelper.rb index dc9daae..19b63fc 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/PickHelper.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/PickHelper.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::PickHelper} class is used to pick entities that reside under @@ -137,28 +137,33 @@ def count def depth_at(index) end - # The do_pick method is used to perform the initial pick. This method is + # The {#do_pick} method is used to perform the initial pick. This method is # generally called before any other methods in the PickHelper class. # - # Returns the number of entities picked. The x and y values are the screen - # coordinates of the point at which would want to do a pick. - # # @example - # ph = view.pick_helpernum = ph.do_pick(x, y) + # ph = view.pick_helper + # num = ph.do_pick(x, y) + # entity = ph.best_picked # - # @param x - # X screen coordinate for the pick. + # @overload do_pick(x, y, aperture = 0) # - # @param y - # Y screen coordinate for the pick. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Integer] aperture The size of the aperture in physical pixels. + # @return [Integer] Number of entities picked. # - # @param aperture - # The size of the pick-aperture. + # @overload do_pick(x, y, aperture = 0.0) # - # @return Integer - The number of Entity objects picked + # @version SketchUp 2025.0 + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Float] aperture The size of the aperture in logical pixels. + # @return [Integer] Number of entities picked. # # @version SketchUp 6.0 - def do_pick(x, y, aperture = 0) + def do_pick(*args) end # The element_at method is used to retrieve a specific entity in the list of @@ -190,8 +195,6 @@ def element_at(index) # You do not normally need to call this method, but you can use this if you # want to call {#test_point} or {#pick_segment} on a lot of points. # - # If the optional aperture is given, it is given in pixels. - # # @example # ph = view.pick_helper # ph.init(x, y, 5) @@ -200,19 +203,27 @@ def element_at(index) # ph.test_point(point) # } # - # @param [Integer] x - # X screen coordinate for the pick. + # @overload init(x, y, aperture = 0) + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Integer] aperture The size of the aperture in physical pixels. + # This is the width and height of the square picking aperture. # - # @param [Integer] y - # Y screen coordinate for the pick. + # @overload init(x, y, aperture = 0.0) # - # @param [Integer] aperture - # aperture in pixels. + # @version SketchUp 2025.0 + # @param [Integer] x Screen coordinate in logical pixels. + # @param [Integer] y Screen coordinate in logical pixels. + # @param [Integer] aperture The size of the aperture in logical pixels. + # This is the width and height of the square picking aperture. # # @return [Sketchup::PickHelper] # # @version SketchUp 6.0 - def init(x, y, aperture = 0) + def init(*args) end # The leaf_at method retrieves the deepest thing in a pick path. @@ -305,7 +316,7 @@ def path_at(index) # # @param [Array] points A series of points in the polyline as # a list of parameters or an array containing Point3d - # objects. + # objects. Model coordinates. # @param [Integer] x screen mouse position in pixels. # @param [Integer] y (required if x given) screen mouse position # in pixels. @@ -343,13 +354,17 @@ def picked_edge # ph.do_pick(x, y) # entity = ph.picked_element # - # @param index + # @overload picked_element() + # # - # @return element - a drawing element that is not an edge or face - # if successful + # @overload picked_element(index) + # + # @param [Integer] index + # + # @return [Sketchup::Drawingelement, nil] a drawing element that is not an edge or face # # @version SketchUp 6.0 - def picked_element(index) + def picked_element(*args) end # The picked_face method is used to retrieve the best face picked. @@ -387,17 +402,19 @@ def picked_face # This is more efficient if you want to test a lot of points using the same # screen point. But you *must* have called the {#init} method first for this # to work. - # @param [Geom::Point3d] point + # @param [Geom::Point3d] point Model coordinate. # # @overload test_point(point, x, y, aperture = 0) # - # @param [Geom::Point3d] point - # @param [Integer] x - # @param [Integer] y - # @param [Integer] aperture + # @param [Geom::Point3d] point Model coordinate. + # @param [Integer] x X screen coordinate for the pick. + # @param [Integer] y Y screen coordinate for the pick. + # @param [Integer] aperture aperture in pixels. # # @return [Boolean] # + # @see #init + # # @version SketchUp 6.0 def test_point(*args) end @@ -453,25 +470,29 @@ def view # Used to pick a set of entities from a model based on a screen coordinate # rectangular area defined by two points. The pick criteria can be for # completely-contained or partially-contained entities, similar to how - # the Selection tool works. The z value of the points passed in are ignored. + # the Selection tool works. The +z+ value of the points passed in are ignored. # # @example # ph = Sketchup.active_model.active_view.pick_helper # start_point = Geom::Point3d.new(100, 100, 0) # end_point = Geom::Point3d.new(500, 500, 0) # num_picked = ph.window_pick(start_point, end_point, Sketchup::PickHelper::PICK_CROSSING) + # picked_entities = ph.all_picked + # + # @note Prior to SketchUp 2025.0 this method expected physical screen coordinates. + # As of SketchUp 2025.0 they are expected to be logical screen coordinates. # - # @param start_point + # @param [Geom::Point3d] start_point # First screen coordinate point. # - # @param end_point + # @param [Geom::Point3d] end_point # Second screen coordinate point. # - # @param pick_type - # PICK_INSIDE to select entities completely contained or - # PICK_CROSSING to select entities partially contained. + # @param [Integer] pick_type + # {PICK_INSIDE} to select entities completely contained or + # {PICK_CROSSING} to select entities partially contained. # - # @return The number of Entity objects picked + # @return [Integer] The number of {Sketchup::Drawingelement} objects picked. # # @version SketchUp 2016 def window_pick(start_point, end_point, pick_type) diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/RegionalSettings.rb b/lib/sketchup-api-stubs/stubs/Sketchup/RegionalSettings.rb index 9705150..a830bd7 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/RegionalSettings.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/RegionalSettings.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::RegionalSettings} module contains methods getting information about the diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptions.rb b/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptions.rb index 0cec52c..75a8dbd 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptions.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptions.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The RenderingOptions class contains method to extract the rendering @@ -25,6 +25,9 @@ # - +EdgeColorMode+ # - +EdgeDisplayMode+ # - +EdgeType+ +# - Accepted values (Integer): +# - 0: Standard edges +# - 1: Sketchy edges # - +ExtendLines+ # - +FaceBackColor+ # - +FaceFrontColor+ @@ -90,6 +93,10 @@ # - +AmbientOcclusionDistance+ # - +AmbientOcclusionIntensity+ # +# Added in SketchUp 2026.0: +# - +AmbientOcclusionColor+ +# - +AmbientOcclusionMultiplier+ +# # @version SketchUp 6.0 class Sketchup::RenderingOptions < Sketchup::Entity @@ -105,9 +112,12 @@ class Sketchup::RenderingOptions < Sketchup::Entity ROPDrawHiddenObjects = nil # Stub value. ROPEditComponent = nil # Stub value. ROPSectionDisplayTurnedOff = nil # Stub value. + ROPSetAOColor = nil # Stub value. + ROPSetAOColorEnabled = nil # Stub value. ROPSetAODistance = nil # Stub value. ROPSetAOEnabled = nil # Stub value. ROPSetAOIntensity = nil # Stub value. + ROPSetAOMultiplier = nil # Stub value. ROPSetBackgroundColor = nil # Stub value. ROPSetConstructionColor = nil # Stub value. ROPSetDepthQueEdges = nil # Stub value. @@ -138,6 +148,7 @@ class Sketchup::RenderingOptions < Sketchup::Entity ROPSetGroundColor = nil # Stub value. ROPSetGroundTransparency = nil # Stub value. ROPSetHideConstructionGeometry = nil # Stub value. + ROPSetHideSpaces = nil # Stub value. ROPSetHighlightColor = nil # Stub value. ROPSetHorizonColor = nil # Stub value. ROPSetJitterEdges = nil # Stub value. @@ -148,6 +159,7 @@ class Sketchup::RenderingOptions < Sketchup::Entity ROPSetLockedColor = nil # Stub value. ROPSetMaterialTransparency = nil # Stub value. ROPSetModelTransparency = nil # Stub value. + ROPSetModelingGrid = nil # Stub value. ROPSetPhotomatchBackgroundOpacity = nil # Stub value. ROPSetPhotomatchDrawBackground = nil # Stub value. ROPSetPhotomatchDrawOverlay = nil # Stub value. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptionsObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptionsObserver.rb index 9540c89..fae1277 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptionsObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptionsObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to rendering options events. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/SectionPlane.rb b/lib/sketchup-api-stubs/stubs/Sketchup/SectionPlane.rb index 8cf7012..dd4ebc1 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/SectionPlane.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/SectionPlane.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The SectionPlane class represents a section plane in a SketchUp model. Note diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb index 759dade..dceb1b2 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb @@ -1,11 +1,11 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) -# A set of the currently selected entities. Use the Model.selection method -# to get a Selection object. Note that the order of entities +# A set of the currently selected drawing elements. Use the Model.selection method +# to get a Selection object. Note that the order of drawing elements # (selection[0], selection[1] and so on) in the set # is in no particular order and should not be assumed to be in the same order -# as the user selected the entities. +# as the user selected the drawing elements. # # @example # # Get a handle to the selection set. @@ -21,8 +21,8 @@ class Sketchup::Selection # Instance Methods - # The {#[]} method is used to retrieve an {Sketchup::Entity} from the selection - # by index. Index 0 is the first entity in the selection. + # The {#[]} method is used to retrieve a {Sketchup::Drawingelement} from the selection + # by index. Index 0 is the first Drawingelement in the selection. # # This method is not very efficient. If you need to look at every entity in # the selection, consider using {#each} instead of using this method @@ -36,9 +36,9 @@ class Sketchup::Selection # p selection[0] # # @param [Integer] index - # The index of the Entity object to retrieve. + # The index of the Drawingelement object to retrieve. # - # @return [Sketchup::Entity, nil] + # @return [Sketchup::Drawingelement, nil] # # @see #at # @@ -46,36 +46,32 @@ class Sketchup::Selection def [](index) end - # The add method is used to add entities to the selection. Entities that are + # The {#add} method is used to add Drawingelement to the selection. Drawingelements that are # added to the Selection are visually indicated by the selection bounding box. # - # You can pass it individual Entities or an Array of Entities: - # Note that the add, remove, and toggle methods are all aliases for one - # another. So if you call remove on an entity that is not selected, it will - # be toggled to be selected, not removed! Be cautious when writing your code to - # not make the assumption about the currently selected state of a given entity. + # You can pass it individual Drawingelements or an Array of Drawingelements. # # @example - # # Add by listing the entities... + # # Add by listing the Drawingelements... # ss.add(e1, e2, e3) # - # # ...or add by passing an Array of entities. + # # ...or add by passing an Array of Drawingelements. # ss.add([e1, e2, e3]) # # @example - # entities = model.active_entities - # entity = entities[0] - # status = selection.add entity + # model = Sketchup.active_model + # edge = model.active_entities.add_line([0, 0, 0], [9, 9, 9]) + # model.selection.add(edge) # - # @overload add(entities) + # @overload add(drawing_elements) # - # @param [Array] entities + # @param [Array] drawing_elements # - # @overload add(*entities) + # @overload add(*drawing_elements) # - # @param [Array] entities + # @param [Array] drawing_elements # - # @return [Integer] the number of Entity objects added + # @return [Integer] the number of Drawingelement objects added # # @version SketchUp 6.0 def add(*args) @@ -106,9 +102,9 @@ def add_observer(observer) # p selection.at(0) # # @param [Integer] index - # The index of the Entity object to retrieve. + # The index of the Drawingelement object to retrieve. # - # @return [Sketchup::Entity, nil] + # @return [Sketchup::Drawingelement, nil] # # @see #[] # @@ -130,7 +126,7 @@ def at(index) def clear end - # The {contains?} method is and alias of {#include?}. + # The {#contains?} method is and alias of {#include?}. # # @example # model = Sketchup.active_model @@ -139,14 +135,14 @@ def clear # selection.add(entity) # p selection.contains?(entity) # - # @param [Sketchup::Entity] entity + # @param [Sketchup::Drawingelement] drawing_element # # @return [Boolean] # # @see #include? # # @version SketchUp 6.0 - def contains?(entity) + def contains?(drawing_element) end # @@ -166,13 +162,13 @@ def contains?(entity) def count end - # The {#each} method is used to iterate through all of the selected entities. + # The {#each} method is used to iterate through all of the selected Drawingelements. # - # If you want to do something with all of the selected Entities, this is more + # If you want to do something with all of the selected Drawingelements, this is more # efficient than using {#[]}. # # @example - # selection.each { |entity| puts entity } + # selection.each { |drawing_element| puts drawing_element } # # @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 @@ -183,15 +179,15 @@ def count # # @version SketchUp 6.0 # - # @yieldparam [Sketchup::Entity] entity + # @yieldparam [Sketchup::Drawingelement] drawing_element def each end - # The empty? method is used to determine if there are entities in the + # The {#empty?} method is used to determine if there are drawing elements in the # selection. # # @example - # status = selection.add entity + # status = selection.add drawing_element # status = selection.empty # # @return [Boolean] @@ -200,23 +196,23 @@ def each def empty? end - # The first method is used to retrieve the first selected entity + # The {#first} method is used to retrieve the first selected Drawingelement # # Returns nil if nothing is selected. This method is useful when you know that - # only a single entity is selected, or you are only interested in the first - # selected entity. + # only a single Drawingelement is selected, or you are only interested in the first + # selected Drawingelement. # # @example - # status = selection.add entity - # entity = selection.first + # status = selection.add drawing_element + # drawing_element = selection.first # - # @return [Sketchup::Entity] the first selected Entity object if successful + # @return [Sketchup::Drawingelement] the first selected Drawingelement object if successful # # @version SketchUp 6.0 def first end - # The {include?} method is used to determine if a given {Sketchup::Entity} is + # The {#include?} method is used to determine if a given {Sketchup::Drawingelement} is # in the selection. # # @example @@ -226,14 +222,14 @@ def first # selection.add(entity) # p selection.include?(entity) # - # @param [Sketchup::Entity] entity + # @param [Sketchup::Drawingelement] drawing_element # # @return [Boolean] # # @see #contains? # # @version SketchUp 6.0 - def include?(entity) + def include?(drawing_element) end # The {#invert} method is used to invert the selection. @@ -257,11 +253,11 @@ def include?(entity) def invert end - # The is_curve? method is used to determine if the selection contains all + # The {#is_curve?} method is used to determine if the selection contains all # edges that belong to a single curve. # # @example - # selection.add entity + # selection.add drawing_element # status = selection.is_curve? # # @return [Boolean] @@ -270,11 +266,11 @@ def invert def is_curve? end - # The is_surface? method is used to determine if the selection contains only + # The {#is_surface?} method is used to determine if the selection contains only # all of the faces that are part of a single curved surface. # # @example - # selection.add entity + # selection.add drawing_element # status = selection.is_surface # # @return [Boolean] @@ -283,7 +279,7 @@ def is_curve? def is_surface? end - # The {#length} method is used to retrieve the number of selected entities. + # The {#length} method is used to retrieve the number of selected drawing elements. # # @example # selection = Sketchup.active_model.selection @@ -299,7 +295,7 @@ def is_surface? def length end - # The model method retrieves the model for the selection. + # The {#model} method retrieves the model for the selection. # # @example # model = selection.model @@ -325,35 +321,33 @@ def model def nitems end - # The remove method is used to remove entities from the selection. - # - # You can pass it individual Entities or an Array of Entities: - # Note that the add, remove, and toggle methods are all aliases for one - # another. So if you call remove on an entity that is not selected, it will - # be toggled to be selected, not removed! Be cautious when writing your code to - # not make the assumption about the currently selected state of a given entity. + # The {#remove} method is used to remove Drawingelements from the selection. + # You can pass it individual Drawingelements or an Array of Drawingelements. # # @example - # # Remove by listing the entities... + # # Remove by listing the Drawingelements... # ss.remove(e1, e2, e3) # - # # ...or remove by passing an Array of entities. + # # ...or remove by passing an Array of Drawingelements. # ss.remove([e1, e2, e3]) # # @example - # entities = model.active_entities - # entity = entities[0] - # status = selection.add entity + # model = Sketchup.active_model + # face = model.active_entities.add_line([0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0]) + # edges = face.all_connected + # model.selection.add(edges) # - # @overload remove(entities) + # model.selection.remove(edges.first) # - # @param [Array] entities + # @overload remove(drawing_elements) # - # @overload remove(*entities) + # @param [Array] drawing_elements # - # @param [Array] entities + # @overload remove(*drawing_elements) # - # @return [Integer] the number of Entity objects removed + # @param [Array] drawing_elements + # + # @return [Integer] the number of Drawingelement objects removed # # @version SketchUp 6.0 def remove(*args) @@ -375,25 +369,25 @@ def remove(*args) def remove_observer(observer) end - # The shift method is used to remove the first entity from the selection and + # The {#shift} method is used to remove the first Drawingelement from the selection and # returns it. # # @example - # status = selection.add entity + # status = selection.add drawing_element # UI.messagebox "Ready to remove item from selection set" - # entity = selection.shift + # drawing_element = selection.shift # - # @return [Sketchup::Entity] the first Entity object in the selection set + # @return [Sketchup::Drawingelement] the first Drawingelement object in the selection set # if successful # # @version SketchUp 6.0 def shift end - # The single_object? method is used to determine if the selection contains a + # The {#single_object?} method is used to determine if the selection contains a # single object. # - # It can either be a single Entity or a group of Entities for which is_curve? + # It can either be a single DrawingElement or a group of DrawingElements for which is_curve? # or is_surface? will return true. # # @example @@ -419,37 +413,36 @@ def single_object? def size end - # The toggle method is used to change whether an entity is part of the - # selection. Entities that are not already selected - # are added. Entities that are already selected are removed. + # The {#toggle} method is used to change whether a Drawingelement is part of the + # selection. Drawingelements that are not already selected + # are added. Drawingelements that are already selected are removed. # - # You can pass it individual Entities or an Array of Entities: - # Note that the add, remove, and toggle methods are all aliases for one - # another. So if you call remove on an entity that is not selected, it will - # be toggled to be selected, not removed! Be cautious when writing your code to - # not make the assumption about the currently selected state of a given entity. + # You can pass it individual Drawingelements or an Array of Drawingelements. # # @example - # # Toggle by listing the entities... + # # Toggle by listing the Drawingelements... # ss.toggle(e1, e2, e3) # - # # ...or toggle by passing an Array of entities. + # # ...or toggle by passing an Array of Drawingelements. # ss.toggle([e1, e2, e3]) # # @example - # entities = model.active_entities - # entity = entities[0] - # status = selection.add entity + # model = Sketchup.active_model + # face = model.active_entities.add_line([0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0]) + # edges = face.all_connected + # model.selection.add(edges) + # + # model.selection.toggle(edges.first) # - # @overload toggle(entities) + # @overload toggle(drawings_elements) # - # @param [Array] entities + # @param [Array] drawing_elements # - # @overload toggle(*entities) + # @overload toggle(*drawing_elements) # - # @param [Array] entities + # @param [Array] drawing_elements # - # @return [Integer] the number of Entity objects changed + # @return [Integer] the number of Drawingelement objects changed # # @version SketchUp 6.0 def toggle(*args) diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/SelectionObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/SelectionObserver.rb index d9c44ca..4ebd4a5 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/SelectionObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/SelectionObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to selection events. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Set.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Set.rb index 8644d24..8c6632c 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Set.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Set.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The set class represents a collection of unique objects. This class is useful @@ -201,7 +201,6 @@ def size # set.insert('Hello') # set.insert('World') # my_array = set.to_a - # UI.messagebox my_array # # @return array - The Array of the entities in the Set. # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb index 50fdf4e..25f73d1 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::ShadowInfo} class contains method to extract the shadow @@ -96,10 +96,7 @@ def [](key) # @example # model = Sketchup.active_model # shadowinfo = model.shadow_info - # value = shadowinfo["City"] - # UI.messagebox value - # value = shadowinfo["City"]="Denver, CO" - # UI.messagebox value + # shadowinfo["City"]="Denver, CO" # # @param [String] key # The key of the shadowinfo value to set. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfoObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfoObserver.rb index d3bc82d..0cf76d0 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfoObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfoObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to changes to the shadow diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Skp.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Skp.rb index c90ea99..d6b1fbb 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Skp.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Skp.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The {Sketchup::Skp} module is used to read metadata from external SketchUp diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Snap.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Snap.rb new file mode 100644 index 0000000..a652a9c --- /dev/null +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Snap.rb @@ -0,0 +1,125 @@ +# Copyright:: Copyright 2026 Trimble Inc. +# License:: The MIT License (MIT) + +# A Snap is a custom grip used by SketchUp's Move tool. +# Snaps can be added at strategic places such as connectors to help +# assembling objects. +# +# rdoc-image:../images/snaps.png +# +# {#direction} is the direction a snap is "pointing". This can be thought of as +# the normal direction of the snap. It can also be thought of as the direction +# you move an object when plugging it into another object, e.g. inserting a +# power coord. +# +# {#up} controls the rotation around the Snap's axis. +# +# When two objects are snapped together, the Snaps have opposite +# {#direction} vectors but matching {#up} vectors. +# +# @example +# # Copy all snaps from source group/component to the corresponding +# # location in a target group/component, as if the objects have +# # have been snapped together. +# # +# # @param [Sketchup::Group, Sketchup::ComponentInstance] source +# # @param [Sketchup::Group, Sketchup::ComponentInstance] target +# def copy_snap(source, target) +# # Transformation for going from the coordinate system of the source to +# # that of the target. +# transformation = +# target.transformation.inverse * source.transformation +# +# source.definition.entities.grep(Sketchup::Snap) do |source_snap| +# # Transform position and orientation between local coordinate systems. +# position = source_snap.position.transform(transformation) +# # Direction vector is reversed between two connected snaps; +# # the snaps point "into" each other. +# direction = source_snap.direction.transform(transformation).reverse +# # Up vector is aligned between two connected snaps. +# up = source_snap.up.transform(transformation) +# +# target.entities.add_snap(position, direction, up) +# end +# end +# +# @version SketchUp 2025.0 +class Sketchup::Snap < Sketchup::Drawingelement + + # Instance Methods + + # The {#direction} method is used to get the direction this Snap is "pointing". + # + # When two Snaps are snapped into each other, they have the opposite {#direction}. + # + # @example + # snap = Sketchup.active_model.entities.add_snap(ORIGIN) + # direction = snap.direction + # + # @return [Geom::Vector3d] + # + # @version SketchUp 2025.0 + def direction + end + + # The {#position} method is used to get the position of this Snap. + # + # @example + # snap = Sketchup.active_model.entities.add_snap(ORIGIN) + # position = snap.position + # + # @return [Geom::Point3d] + # + # @version SketchUp 2025.0 + def position + end + + # The {#set} method is used to move and/or reorient a Snap. + # + # @example + # snap = Sketchup.active_model.entities.add_snap(ORIGIN) + # snap.set(Geom::Point3d.new(1.m, 0, 0)) + # + # @overload set(position) + # + # With only a position provided, the Snap keeps its current orientation. + # @param [Geom::Point3d] position + # + # @overload set(position, direction) + # + # With a position and a direction vector provided, but no up vector, SketchUp + # tries to keep the Snap upright. + # @param [Geom::Point3d] position + # @param [Geom::Vector3d] direction + # + # @overload set(position, direction, up) + # + # @param [Geom::Point3d] position + # @param [Geom::Vector3d] direction + # @param [Geom::Vector3d] up + # + # @raise ArgumentError if +direction+ and +up+ are parallel. + # + # @return [Sketchup::Snap] self + # + # @version SketchUp 2025.0 + def set(*args) + end + + # The {#up} method is used to get a vector representing the rotation of this + # Snap along its axis. + # + # When two Snaps are snapped into each other, they have the same aligned {#up} + # direction. + # + # @example + # snap = Sketchup.active_model.entities.add_snap(ORIGIN) + # up = snap.up + # + # @return [Geom::Vector3d] + # + # @version SketchUp 2025.0 + def up + end + +end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Style.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Style.rb index 8a47886..ffe65c3 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Style.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Style.rb @@ -1,10 +1,16 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Style class contains methods for modifying information about a specific # style. Styles are a collection of display settings that tell SketchUp how to # draw the model. # +# In SketchUp, there are two important style objects in a model: +# The {Sketchup::Styles#selected_style} is the style currently selected in the Styles Browser. +# The {Sketchup::Styles#active_style} is a temporary copy of the selected style that allows +# editing without committing changes. Changes to the active style are not saved unless you call +# {Sketchup::Styles#update_selected_style}. +# # @example # styles = Sketchup.active_model.styles # puts "Your first style is named #{styles.first.name}" @@ -66,4 +72,17 @@ def name def name=(name) end + # The {#path} method gets the file path the {Sketchup::Style} was loaded from. + # + # @example + # styles = Sketchup.active_model.styles + # style = styles.first + # name = style.path + # + # @return [String] path The file path the style was loaded from. + # + # @version SketchUp 2025.0 + def path + end + end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Styles.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Styles.rb index 5d89887..a682aaf 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Styles.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Styles.rb @@ -1,9 +1,16 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Styles class contains methods for manipulating a collection of styles in # a model. Typically, you will access this via the active_model: # +# There are two objects of this class that play important roles: the {#selected_style} and the +# {#active_style}. +# +# The latter is a temporary copy made from the {#selected_style} that allows the user to edit +# the style without committing to save anything. To save the changes, one should use +# {#update_selected_style}. +# # @example # styles = Sketchup.active_model.styles # puts "There are #{styles.size} styles in your model." @@ -71,21 +78,33 @@ def active_style_changed # The {#add_style} method is used to create and load a style from the given # file. # - # @example + # @example For SketchUp 2025.0 and older # filename = File.expand_path('./MyStyle.style') # styles = Sketchup.active_model.styles # status = styles.add_style(filename, true) # - # @param [String] filename + # @example For SketchUp 2026.0 and newer + # filename = File.expand_path('./MyStyle.style') + # styles = Sketchup.active_model.styles + # style = styles.add_style(filename, true) + # + # @overload add_style(filename, select) # - # @param [Boolean] select - # +true+ if you want to set the style to be the - # active style. + # @note Signature for versions prior to SketchUp 2026.0. + # @version SketchUp 6.0 + # @param [String] filename The file path to the style file. + # @param [Boolean] select +true+ if you want to set the style to be the active style. + # @return [Boolean] # - # @return [Boolean] + # @overload add_style(filename, select = false) # - # @version SketchUp 6.0 - def add_style(filename, select) + # @version SketchUp 2026.0 + # @param [String] filename The file path to the style file. + # @param [Boolean] select +true+ if you want to set the style to be the active style. + # + # @return [Sketchup::Style, nil] The newly created style or +nil+ if the the style could not be + # added. + def add_style(*args) end # @@ -151,12 +170,32 @@ def parent # styles = Sketchup.active_model.styles # styles.purge_unused # - # @return [true] + # @return [nil] # # @version SketchUp 6.0 def purge_unused end + # The {#remove_style} method is used to remove a {Sketchup::Style} from the {Sketchup::Styles}. + # + # @example + # filename = File.expand_path('./MyStyle.style') + # styles = Sketchup.active_model.styles + # status = styles.add_style(filename, true) + # styles.remove(styles.first) + # + # @param [Sketchup::Style] style + # + # @raise [ArgumentError] If the style is not found in the Styles collection. + # + # @raise [ArgumentError] If the styles contains only one style. + # + # @return [nil] + # + # @version SketchUp 2026.0 + def remove_style(style) + end + # The {#selected_style} method is used to retrieve the style currently # selected in the Styles Browser. # @@ -172,13 +211,20 @@ def selected_style # The {#selected_style=} method is used to set the currently selected style. # + # @bug Prior to SketchUp 2025.0 setting the {#selected_style=} to the {#active_style} would chrash + # SketchUp. + # # @example # styles = Sketchup.active_model.styles - # styles.selected_style = styles.last + # filename = File.expand_path('./MyStyle.style') + # styles.add_style(filename, true) + # styles.selected_style = styles['[MyStyle]'] # # @param [Sketchup::Style] style # - # @return [false] + # @raise [ArgumentError] If \p style is the {#active_style}. + # + # @return [nil] # # @version SketchUp 6.0 def selected_style=(style) @@ -206,7 +252,7 @@ def size # styles = Sketchup.active_model.styles # styles.update_selected_style # - # @return [true] + # @return [nil] # # @see #selected_style # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb index c90f9cc..1f2ba65 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Text class contains method to manipulate a Text entity object. @@ -11,8 +11,12 @@ class Sketchup::Text < Sketchup::Drawingelement # The arrow_type method retrieves the current arrow type used for the leader # text. # - # Valid arrow types are 0 for none, 2 for dot, 3 for closed arrow, 4 for open - # arrow. + # Valid arrow types are: + # - {Sketchup::Dimension::ARROW_NONE} (Deprecated: {DimensionArrowNone}) + # - {Sketchup::Dimension::ARROW_SLASH} (Deprecated: {DimensionArrowSlash}) + # - {Sketchup::Dimension::ARROW_DOT} (Deprecated: {DimensionArrowDot}) + # - {Sketchup::Dimension::ARROW_CLOSED} (Deprecated: {DimensionArrowClosed}) + # - {Sketchup::Dimension::ARROW_OPEN} (Deprecated: {DimensionArrowOpen}) # # @example # type = text.arrow_type=0 @@ -26,8 +30,12 @@ def arrow_type # The arrow_type= method sets the arrow type used for leader text. # - # Valid arrow types are 0 for none, 2 for dot, 3 for closed arrow, 4 for open - # arrow. + # Valid arrow types are: + # - {Sketchup::Dimension::ARROW_NONE} (Deprecated: {DimensionArrowNone}) + # - {Sketchup::Dimension::ARROW_SLASH} (Deprecated: {DimensionArrowSlash}) + # - {Sketchup::Dimension::ARROW_DOT} (Deprecated: {DimensionArrowDot}) + # - {Sketchup::Dimension::ARROW_CLOSED} (Deprecated: {DimensionArrowClosed}) + # - {Sketchup::Dimension::ARROW_OPEN} (Deprecated: {DimensionArrowOpen}) # # @example # arrow = text.arrow_type=type @@ -110,7 +118,12 @@ def display_leader? def has_leader? end - # The leader_type method retrieves the currently set leader type. + # The {#leader_type} method retrieves the currently set leader type. + # + # Valid leaders types are: + # - {ALeaderNone} + # - {ALeaderView} + # - {ALeaderModel} # # @example # leader = text.leader_type @@ -122,17 +135,25 @@ def has_leader? def leader_type end - # The leader_type = method sets the leader type. + # The {#leader_type=} method sets the leader type. # - # Valid leader types are 0 for none, 1 for View-based, and 2 for Pushpin + # Valid leaders types are: + # - {ALeaderNone} + # - {ALeaderView} + # - {ALeaderModel} # # @example # leader = text.leader_type=1 # + # @note {ALeaderModel} cannot be set. It is only used internally as a default value. + # Trying to set it will raise a warning. + # # @param [Integer] type # A numerical value representing the leader type to be # set. # + # @raise [RangeError] if the value is other than (ALeaderView, or ALeaderModel). + # # @return [Integer] a numerical value representing the leader type # you just set. # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Texture.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Texture.rb index 8bae55c..a03e803 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Texture.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Texture.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Texture class contains methods for obtaining information about textures @@ -23,16 +23,11 @@ class Sketchup::Texture < Sketchup::Entity # # Returns nil if not successful, path if successful # m.texture = "c:\\Materials\\Carpet.jpg" # rescue - # UI.messagebox $!.message + # puts $!.message # end # texture = m.texture # # Returns a color object # color = texture.average_color - # if (color) - # UI.messagebox color - # else - # UI.messagebox "Failure: No average color" - # end # # @return [Sketchup::Color, nil] a color object (if successful), nil if # unsuccessful. @@ -41,8 +36,15 @@ class Sketchup::Texture < Sketchup::Entity def average_color end - # The {#filename} method retrieves the entire path, including the file, for a - # texture object. + # The {#filename} method retrieves the full path, if available, for a texture object. + # + # Textures for materials shipping with SketchUp might only have a filename, + # since the path would be invalid on the end user's machine. Textures + # dynamically created from ImageRep objects may have an empty path unless + # saved with {Sketchup::ImageRep#save_file} or until the texture is saved with + # {Sketchup::Texture#write}. + # + # If you need only the filename of the texture use +filename = File.basename(texture.filename)+. # # @example # model = Sketchup.active_model @@ -79,11 +81,6 @@ def height # # @example # imageheight = texture.image_height - # if (imageheight) - # UI.messagebox imageheight - # else - # UI.messagebox "Failure" - # end # # @return [Integer] the height, in pixels, of the texture # pattern @@ -113,11 +110,6 @@ def image_rep(colorized = false) # # @example # imagewidth = texture.image_width - # if (imagewidth) - # UI.messagebox imagewidth - # else - # UI.messagebox "Failure" - # end # # @return [Integer] the width, in pixels, of the texture # pattern @@ -134,18 +126,13 @@ def image_width # imagewidth = texture.width # # if (imagewidth) - # UI.messagebox imagewidth + # puts imagewidth # else - # UI.messagebox "Failure" + # puts "Failure" # end # # # Using two values which will not preserve ratio # width_height = texture.size = [10,100] - # if (width_height) - # UI.messagebox width_height - # else - # UI.messagebox "Failure" - # end # # @param [Integer, Array(Integer, Integer)] size # The size, in inches, of the texture. This number will @@ -168,11 +155,6 @@ def size=(size) # # @example # status = texture.valid? - # if (status) - # UI.messagebox status - # else - # UI.messagebox status - # end # # @return [Boolean] # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/TextureWriter.rb b/lib/sketchup-api-stubs/stubs/Sketchup/TextureWriter.rb index eac3f84..98a56b9 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/TextureWriter.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/TextureWriter.rb @@ -1,12 +1,12 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The TextureWriter class is used primarily for writing the textures used in a # SketchUp model out to files as part of an export for use in another # application. These methods are usually invoked in this order: # -# - 1. load - load one or more textures from a model into the TextureWriter. -# - 2. write_all or write - write the texture(s) to file. +# 1. {#load} - load one or more textures from a model into the TextureWriter. +# 2. {#write_all} or {#write} - write the texture(s) to file. # # @example # # This code snippet sets up a texture writer and some variables that are @@ -159,9 +159,9 @@ def load(*args) # This method will return one of the following status messages. (These are # constants that are defined by the API.) # - # - 0 = FILE_WRITE_OK - # - 1 = FILE_WRITE_FAILED_INVALID_TIFF - # - 2 = FILE_WRITE_FAILED_UNKNOWN + # - 0 = {FILE_WRITE_OK} + # - 1 = {FILE_WRITE_FAILED_INVALID_TYPE} + # - 2 = {FILE_WRITE_FAILED_UNKNOWN} # # @example # tw.load(texturable_entities[0]) @@ -211,9 +211,9 @@ def write(*args) # The write_all method is used to write all of the textures within the texture # writer to files. It will return one of three status numbers: # - # - 0 = FILE_WRITE_OK - # - 1 = FILE_WRITE_FAILED_INVALID_TIFF - # - 2 = FILE_WRITE_FAILED_UNKNOWN + # - 0 = {FILE_WRITE_OK} + # - 1 = {FILE_WRITE_FAILED_INVALID_TYPE} + # - 2 = {FILE_WRITE_FAILED_UNKNOWN} # # @example # tw.load(texturable_entities[0] diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb index 869a1e1..3897fe2 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # Tool is the interface that you implement to create a SketchUp tool. @@ -27,12 +27,12 @@ # The following table contains several constants you can use when check for # certain key presses inside the keyboard handling callbacks: # -# - +CONSTRAIN_MODIFIER_KEY+ = Shift Key -# - +CONSTRAIN_MODIFIER_MASK+ = Shift Key -# - +COPY_MODIFIER_KEY+ = Alt/Option on Mac, Ctrl on PC -# - +COPY_MODIFIER_MASK+ = Alt/Option on Mac, Ctrl on PC -# - +ALT_MODIFIER_KEY+ = Command on Mac, Alt on PC -# - +ALT_MODIFIER_MASK+ = Command on Mac, Alt on PC +# - {CONSTRAIN_MODIFIER_KEY} = Shift Key +# - {CONSTRAIN_MODIFIER_MASK} = Shift Key +# - {COPY_MODIFIER_KEY} = Alt/Option on Mac, Ctrl on PC +# - {COPY_MODIFIER_MASK} = Alt/Option on Mac, Ctrl on PC +# - {ALT_MODIFIER_KEY} = Command on Mac, Alt on PC +# - {ALT_MODIFIER_MASK} = Command on Mac, Alt on PC # # @abstract Implement the methods described in this class to create a tool. # You can not sub-class this class because it is not defined by the API. @@ -130,10 +130,6 @@ def enableVCB? # the tool 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 tool will do and then return it. - # # @example # def getExtents # bb = Sketchup.active_model.bounds @@ -181,11 +177,6 @@ def getInstructorContentDirectory # implement this method. Implement this method if you want a context-click to # display something other than this default context menu. # - # In SketchUp 2015 the flags, x, y and view parameters were added. They are - # needed if you need to pick the entities under the mouse position. The new - # parameters are optional, but if you need to use one you must include them - # all. - # # @example # if Sketchup.version.to_i < 15 # # Compatible with SketchUp 2014 and older: @@ -209,21 +200,36 @@ def getInstructorContentDirectory # end # end # + # @note In SketchUp 2015 the flags, x, y and view parameters were added. They are + # needed if you need to pick the entities under the mouse position. The new + # parameters are optional, but if you need to use one you must include them + # all. + # # @overload getMenu(menu) # # @param [Sketchup::Menu] menu # # @overload getMenu(menu, flags, x, y, view) # + # @note Signature for versions prior to SketchUp 2025.0 # @version SketchUp 2015 # @param [Sketchup::Menu] menu # @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 [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view + # + # @overload getMenu(menu, flags, x, y, view) + # + # @version SketchUp 2025.0 + # @param [Sketchup::Menu] menu + # @param [Integer] flags + # A bit mask that tells the state of the modifier keys and other mouse + # buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. # @param [Sketchup::View] view # # @return [nil] @@ -276,22 +282,22 @@ def onCancel(reason, view) # "virtual keys" defined as constants you can use. Their use is cross # platform. They are: # - # - +VK_ALT+ - # - +VK_COMMAND+ - # - +VK_CONTROL+ - # - +VK_DELETE+ - # - +VK_DOWN+ - # - +VK_END+ - # - +VK_HOME+ - # - +VK_INSERT+ - # - +VK_LEFT+ - # - +VK_MENU+ - # - +VK_NEXT+ - # - +VK_PRIOR+ - # - +VK_RIGHT+ - # - +VK_SHIFT+ - # - +VK_SPACE+ - # - +VK_UP+ + # - {VK_ALT} + # - {VK_COMMAND} + # - {VK_CONTROL} + # - {VK_DELETE} + # - {VK_DOWN} + # - {VK_END} + # - {VK_HOME} + # - {VK_INSERT} + # - {VK_LEFT} + # - {VK_MENU} + # - {VK_NEXT} + # - {VK_PRIOR} + # - {VK_RIGHT} + # - {VK_SHIFT} + # - {VK_SPACE} + # - {VK_UP} # # V6: There is a bug on Windows where the typematic effect does # not work. Typematic effects work fine on a Mac. @@ -368,20 +374,27 @@ def onKeyUp(key, repeat, flags, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onLButtonDoubleClick(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onLButtonDoubleClick(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onLButtonDoubleClick(flags, x, y, view) + def onLButtonDoubleClick end # The {#onLButtonDown} method is called by SketchUp when the left mouse button @@ -395,20 +408,27 @@ def onLButtonDoubleClick(flags, x, y, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onLButtonDown(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onLButtonDown(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onLButtonDown(flags, x, y, view) + def onLButtonDown end # The {#onLButtonUp} method is called by SketchUp when the left mouse button is @@ -422,20 +442,27 @@ def onLButtonDown(flags, x, y, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onLButtonUp(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onLButtonUp(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onLButtonUp(flags, x, y, view) + def onLButtonUp end # The {#onMButtonDoubleClick} method is called by SketchUp when the middle @@ -457,20 +484,27 @@ def onLButtonUp(flags, x, y, view) # for now in the hopes of fixing the implementation, but you won't have any # luck trying to use it in SU7 and earlier. # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onMButtonDoubleClick(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onMButtonDoubleClick(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onMButtonDoubleClick(flags, x, y, view) + def onMButtonDoubleClick end # The {#onMButtonDown} method is called by SketchUp when the middle mouse @@ -488,20 +522,27 @@ def onMButtonDoubleClick(flags, x, y, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onMButtonDown(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onMButtonDown(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onMButtonDown(flags, x, y, view) + def onMButtonDown end # The {#onMButtonUp} method is called by SketchUp when the middle mouse button @@ -520,20 +561,27 @@ def onMButtonDown(flags, x, y, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onMButtonUp(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onMButtonUp(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onMButtonUp(flags, x, y, view) + def onMButtonUp end # The {#onMouseEnter} method is called by SketchUp when the mouse enters the @@ -578,20 +626,27 @@ def onMouseLeave(view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onMouseMove(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onMouseMove(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onMouseMove(flags, x, y, view) + def onMouseMove end # The {#onMouseWheel} method is called by SketchUp when the mouse scroll wheel @@ -642,27 +697,34 @@ def onMouseMove(flags, x, y, view) # # Sketchup.active_model.select_tool(ExampleTool.new) # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. - # - # @param [Integer] delta - # Either +1+ or +-1+ depending on which direction the - # mouse wheel scrolled. + # @overload onMouseWheel(flags, delta, x, y, view) # - # @param [Float] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 2019.2 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] delta Either +1+ or +-1+ depending on which direction the + # mouse wheel scrolled. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Float] y - # The Y coordinate on the screen where the event occurred. + # @overload onMouseWheel(flags, delta, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] delta Either +1+ or +-1+ depending on which direction the + # mouse wheel scrolled. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @return [Boolean] Return +true+ to prevent SketchUp from performing default # zoom action. # # @version SketchUp 2019.2 - def onMouseWheel(flags, delta, x, y, view) + def onMouseWheel end # The {#onRButtonDoubleClick} is called by SketchUp when the user double clicks @@ -676,20 +738,27 @@ def onMouseWheel(flags, delta, x, y, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onRButtonDoubleClick(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onRButtonDoubleClick(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onRButtonDoubleClick(flags, x, y, view) + def onRButtonDoubleClick end # The {#onRButtonDown} method is called by SketchUp when the user presses @@ -705,20 +774,27 @@ def onRButtonDoubleClick(flags, x, y, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onRButtonDown(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onRButtonDown(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onRButtonDown(flags, x, y, view) + def onRButtonDown end # The {#onRButtonUp} method is called by SketchUp when the user releases the @@ -732,20 +808,27 @@ def onRButtonDown(flags, x, y, view) # puts " view = #{view}" # end # - # @param [Integer] flags - # A bit mask that tells the state of the modifier - # keys and other mouse buttons at the time. + # @overload onRButtonUp(flags, x, y, view) # - # @param [Integer] x - # The X coordinate on the screen where the event occurred. + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::View] view # - # @param [Integer] y - # The Y coordinate on the screen where the event occurred. + # @overload onRButtonUp(flags, x, y, view) # - # @param [Sketchup::View] view + # @version SketchUp 2025.0 + # @param [Integer] flags A bit mask that tells the state of the modifier + # keys and other mouse buttons at the time. + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::View] view # # @version SketchUp 6.0 - def onRButtonUp(flags, x, y, view) + def onRButtonUp end # The {#onReturn} method is called by SketchUp when the user hit the Return key diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Tools.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Tools.rb index 776fed7..65e2433 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Tools.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Tools.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Tools class contains methods to manipulate a collection of SketchUp diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ToolsObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ToolsObserver.rb index d3f0d38..b700f41 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ToolsObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ToolsObserver.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This observer interface is implemented to react to tool events. diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/UVHelper.rb b/lib/sketchup-api-stubs/stubs/Sketchup/UVHelper.rb index 033faca..df4c404 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/UVHelper.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/UVHelper.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The UV Helper class contains methods allowing you to determine the location diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Vertex.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Vertex.rb index d9b3f42..12e7e0a 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Vertex.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Vertex.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # A Vertex. A Vertex represents the end of an Edge or a point inside a Face. @@ -12,17 +12,15 @@ class Sketchup::Vertex < Sketchup::Entity # vertex and another vertex # # @example - # edge = entities[0] + # model = Sketchup.active_model + # entities = model.active_entities + # edge = entities.add_line([0, 0, 0], [20, 20, 20], [40, 40, 40]) + # # # returns array of vertices that make up the line - # verticies = edge.vertices - # vertex1 = verticies[0] - # vertex2 = verticies[1] - # edge = vertex1.common_edge vertex2 - # if (edge) - # UI.messagebox edge - # else - # UI.messagebox "Failure" - # end + # vertices = edge.vertices + # vertex1 = vertices[0] + # vertex2 = vertices[1] + # edge = vertex1.common_edge(vertex2) # # @param [Sketchup::Vertex] vertex2 # A Vertex object. @@ -39,23 +37,26 @@ def common_edge(vertex2) # interior of a Curve. # # @example - # edge = entities[0] - # # returns array of vertices that make up the line - # verticies = edge.vertices - # vertex1 = verticies[0] + # centerpoint = Geom::Point3d.new + # # Create a circle perpendicular to the normal or Z axis + # vector = Geom::Vector3d.new(0, 0, 1) + # vector2 = vector.normalize! + # model = Sketchup.active_model + # entities = model.entities + # edgearray = entities.add_circle(ORIGIN, Z_AXIS, 10) + # edge = edgearray[0] + # curve = edge.curve + # vertices = curve.vertices + # # returns array of vertices that make up the circle + # vertices = edge.vertices + # vertex1 = vertices[0] # status = vertex1.curve_interior? - # if (status) - # UI.messagebox status - # else - # #returns nil if vertex is not on interior of a Curve - # UI.messagebox "Failure" - # end # # @note This method doesn't actually return a boolean as the question mark # post-fix would normally indicate. But the result still evaluates to # truthy or falsy. # - # @return [Boolean] + # @return [Sketchup::ArcCurve, nil] # # @version SketchUp 6.0 def curve_interior? diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/View.rb b/lib/sketchup-api-stubs/stubs/Sketchup/View.rb index 35829a2..bea75c2 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/View.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/View.rb @@ -1,12 +1,13 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # This class contains methods to manipulate the current point of view of the -# model. The drawing methods here (draw_line, draw_polyline, etc) are meant to -# be invoked within a tool's Tool.draw method. Calling them outside Tool.draw -# will have no effect. +# model. The drawing methods here ({#draw_line}, {#draw_polyline}, etc) are +# meant to be invoked within a tool's {Sketchup::Tool#draw} method. Calling +# them outside {Sketchup::Tool#draw} will have no effect. # -# You access the View by calling the Model.active_view method. +# You access the {Sketchup::View} by calling the {Sketchup::Model#active_view} +# method. # # @example # view = Sketchup.active_model.active_view @@ -14,6 +15,13 @@ # @version SketchUp 6.0 class Sketchup::View + # Constants + + CORNER_BOTTOM_LEFT = nil # Stub value. + CORNER_BOTTOM_RIGHT = nil # Stub value. + CORNER_TOP_LEFT = nil # Stub value. + CORNER_TOP_RIGHT = nil # Stub value. + # Instance Methods # The add_observer method is used to add an observer to the current object. @@ -95,45 +103,95 @@ def camera def camera=(arg) end - # The center method is used to retrieve the coordinates of the center of the - # view in pixels. It is returned as an array of 2 values for x and y. + # The {#center} method is used to retrieve the coordinates of the center of the + # view in pixels. # # @example # model = Sketchup.active_model # view = model.active_view - # c = view.center + # center = view.center # - # @return [Geom::Point3d] the center of the view + # @overload center() # - # @version SketchUp 6.0 + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @return [Array(Integer, Integer)] Physical pixels. + # + # @overload center() + # + # @version SketchUp 2025.0 + # @return [Array(Float, Float)] Logical pixels. def center end - # The corner method is used to retrieve the coordinates of one of the corners - # of the view. The argument is an index between 0 and 3 that identifies which + # The {#corner} method is used to retrieve the coordinates of one of the corners + # of the view. The argument is an index between +0+ and +3+ that identifies which # corner you want. This method returns an array with two integers which are - # the coordinates of the corner of the view in the view space. If the view - # uses a Camera with a fixed aspect ratio, then the corners are the corners of - # the viewing are of the camera which might be different than the actual - # corners of the view itself. - # - # The index numbers are as follows: - # - 0: top left, - # - 1: top right, - # - 2: bottom left, - # - 3: bottom right. + # the coordinates of the corner of the view in the view space. + # + # The indices are as follows: + # - 0: {CORNER_TOP_LEFT} + # - 1: {CORNER_TOP_RIGHT} + # - 2: {CORNER_BOTTOM_LEFT} + # - 3: {CORNER_BOTTOM_RIGHT} + # + # @example New preferred style using constants + # # From SketchUp 2025.0: + # point = Sketchup.active_model.active_view.corner(Sketchup::View::CORNER_BOTTOM_LEFT) + # + # @example Old style using hard coded indices + # # For SketchUp 2024.0 and older: (Works with newer versions too) + # point = Sketchup.active_model.active_view.corner(2) + # + # @note If the view uses a {Sketchup::Camera} with a fixed aspect ratio, then the + # corners are the corners of the viewing are of the camera which might be different + # than the actual corners of the view itself. + # + # @overload corner(index) + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] index + # A value between (or including) +0+ and +3+ identifying the + # corner whose coordinate you want to retrieve. + # @return [Array(Integer, Integer)] a 2D array +[x, y]+ representing the screen point in physical + # pixels. + # + # @overload corner(index) + # + # @version SketchUp 2025.0 + # @param [Integer] index + # A value between (or including) +0+ and +3+ identifying the + # corner whose coordinate you want to retrieve. + # @return [Array(Float, Float)] a 2D array +[x, y]+ representing the screen point in logical + # pixels. + def corner(arg) + end + + # The {#device_height} method is used to retrieve the height of the viewport for the + # view in physical pixels. # # @example - # point = view.corner index + # model = Sketchup.active_model + # view = model.active_view + # height = view.device_height + # + # @return [Integer] the height of the viewport in physical pixels. # - # @param [Integer] index - # A value between (or including) 0 and 3 identifying the - # corner whose coordinate you want to retrieve. + # @version SketchUp 2025.0 + def device_height + end + + # The {#device_width} method is used to retrieve the width of the viewport for the + # view in physical pixels. + # + # @example + # width = view.device_width # - # @return [Array(Integer, Integer)] a 2d array [w,h] representing the screen point + # @return [Integer] the width of the viewport in physical pixels. # - # @version SketchUp 6.0 - def corner(index) + # @version SketchUp 2025.0 + def device_width end # The {#draw} method is used to do basic drawing. This method can only be @@ -275,6 +333,7 @@ def draw(*args) # The second parameter is an {Array} of {Geom::Point3d} objects (or several # individual {Geom::Point3d} objects). These {Geom::Point3d} objects are in # screen space, not 3D space. + # # The X value corresponds to the number of pixels from the left edge of the # drawing area. The Y value corresponds to the number of pixels down from # the top of the drawing area. The Z value is not used. @@ -284,10 +343,16 @@ def draw(*args) # Geom::Point3d.new(0, 0, 0), # Geom::Point3d.new(8, 0, 0), # Geom::Point3d.new(8, 4, 0), - # Geom::Point3d.new(0, 4, 0) + # Geom::Point3d.new(0, 4, 0), # ] # view.draw2d(GL_LINE_STRIP, points) # + # @note Prior to SketchUp 2025.0 this method accepted the +points+ as physical + # screen coordinates. As of SketchUp 2025.0 the +points+ are expected to be + # in logical screen coordinates. Older versions need to apply the scaling + # factor from {UI.scale_factor} to the points before passing them to this + # method. + # # @overload draw2d(openglenum, points) # # @param [Integer] openglenum @@ -394,23 +459,31 @@ def draw_line(*args) def draw_lines(*args) end - # This method is used to draw points. - # - # This method is usually invoked within the draw method of a tool. + # This method is used to draw points in model space. # # @example - # point3 = Geom::Point3d.new 0,0,0 - # # returns a view - # status = view.draw_points(point3, 10, 1, "red") + # point = Geom::Point3d.new(0, 0, 0) + # view.draw_points(point, 10, 1, "red") + # + # @note Prior to SketchUp 2025.0 this method accepted the +size+ as physical + # pixels. As of SketchUp 2025.0 the +points+ are expected to be in logical pixels. + # Older versions need to apply the scaling factor from {UI.scale_factor} to the + # size before passing them to this method. # # @param [Array] points + # Model coordinates. # # @param [Integer] size # Size of the point in pixels. # # @param [Integer] style - # 1 = open square, 2 = filled square, 3 = "+", 4 = "X", 5 = "*", - # 6 = open triangle, 7 = filled triangle. + # - +1+ = open square + # - +2+ = filled square + # - +3+ = plus shape "+" + # - +4+ = cross shape "X" + # - +5+ = star shape "*" + # - +6+ = open triangle + # - +7+ = filled triangle # # @param [Sketchup::Color] color # @@ -490,7 +563,15 @@ def draw_polyline(*args) # end # end # - # @example Cross Platform Font Size + # @example Cross Platform Font Size in SketchUp 2025.0 and newer + # class ExampleTool + # def draw(view) + # draw_text(view, [100, 200, 0], "Hello Pixel World", pixel_size: 20) + # draw_text(view, [100, 250, 0], "Hello Point World", point_size: 20) + # end + # end + # + # @example Cross Platform Font Size in SketchUp 2024.0 and older # class ExampleTool # IS_WIN = Sketchup.platform == :platform_win # @@ -523,7 +604,8 @@ def draw_polyline(*args) # # @note The font size is platform dependent. On Windows the method expects # points, where on Mac it's pixels. See "Cross Platform Font Size" example - # for details. + # for details. As of SketchUp 2025.0 you can use the +:pixel_size+ or + # +:point_size+ options to specify the size in pixels or points respectively. # # @overload draw_text(point, text) # @@ -541,7 +623,13 @@ def draw_polyline(*args) # named arguments of options. # @option options [String] :font The name of the font to use. If it does not # exist on the system, a default font will be used instead. - # @option options [Integer] :size The size of the font in points + # @option options [Integer] :size Legacy: The size of the font in + # system-dependent units. On Windows this is in points, on Mac it's in + # pixels. + # @option options [Integer] :pixel_size Added SketchUp 2025.0: The + # size of the font in pixels. + # @option options [Integer] :point_size Added SketchUp 2025.0: The + # size of the font in points. # @option options [Boolean] :bold Controls the Bold property of the font. # @option options [Boolean] :italic Controls the Italic property of the font. # @option options [Sketchup::Color] :color The color to draw the text with. @@ -554,8 +642,13 @@ def draw_polyline(*args) # some fonts on Mac might not align as expected due to the system # reporting incorrect font metrics. # + # @raise [ArgumentError] if combining usage of +:size+, +:pixel_size+ or + # +:point_size+ options. + # # @return [Sketchup::View] # + # @see #text_bounds + # # @version SketchUp 6.0 def draw_text(*args) end @@ -648,12 +741,16 @@ def graphics_engine # The guess_target method is used to guess at what the user is looking at when # you have a perspective view. # - # This method is useful when writing a viewing tool. See also camera.rb which - # is part of the film and stage ruby scripts. - # # @example # target = view.guess_target # + # @overload guess_target + # + # + # @overload guess_target(screen_point) + # + # @param [Geom::Point3d] screen_point + # # @return [Geom::Point3d] a Point3d object representing the point in the # model that the user is likely interested in. # @@ -675,28 +772,77 @@ def guess_target(*args) def inference_locked? end - # The inputpoint method is used to retrieve an input point. + # The {#inputpoint} method is used to retrieve an {Sketchup::InputPoint}. # # This will normally be used inside one of the mouse event handling methods in - # a tool. Usually, it is preferable to create the InputPoint first and then - # use the pick method on it. + # a tool. Usually, it is preferable to create the {Sketchup::InputPoint} first + # and then use the pick method on it. # # @example - # inputpoint = view.inputpoint x, y, inputpoint1 + # class ExampleTool + # def onMouseMove(flags, x, y, view) + # inputpoint = view.inputpoint(x, y) + # instance_path = ip.instance_path + # end + # end + # + # @example Inference from another input point + # class ExampleTool + # + # def onLButtonUp(flags, x, y, view) + # @picked_input = view.inputpoint(x, y) + # end # - # @param [Numeric] x - # A x value. + # def onMouseMove(flags, x, y, view) + # # Note: It is preferrable to initialize input points using + # # Sketchup::InputPoint.new in `initialize` and reuse them doing the + # # picking using the `pick` method. + # if @inputpoint + # @inputpoint = view.inputpoint(x, y, @picked_input) + # else + # @inputpoint = view.inputpoint(x, y) + # end + # end # - # @param [Numeric] y - # A y value. + # def draw(view) + # if @inputpoint + # @inputpoint.draw(view) if @inputpoint.display? + # else + # @picked_input.draw(view) if @picked_input.display? + # end + # end + # end # - # @param [Sketchup::InputPoint] inputpoint1 - # An InputPoint object. + # @overload inputpoint(x, y) # - # @return [Sketchup::InputPoint] + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. # - # @version SketchUp 6.0 - def inputpoint(x, y, inputpoint1) + # @overload inputpoint(x, y, inputpoint1) + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Sketchup::InputPoint] inputpoint1 + # + # @overload inputpoint(x, y) + # + # @version SketchUp 2025.0 + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # + # @overload inputpoint(x, y, inputpoint1) + # + # @version SketchUp 2025.0 + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Sketchup::InputPoint] inputpoint1 + # + # @return [Sketchup::InputPoint] + def inputpoint(*args) end # The invalidate method is used mark the view as in need of a redraw. @@ -721,6 +867,13 @@ def invalidate # @example # time = view.last_refresh_time # + # @overload last_refresh_time + # + # + # @overload last_refresh_time(full) + # + # @param [Boolean] full + # # @return [Float] time in milliseconds # # @version SketchUp 6.0 @@ -764,10 +917,14 @@ def line_stipple=(pattern) # @note As of SU2017 this will automatically scale the line width by the same # factor as {UI.scale_factor}. # - # @param [Integer] width + # @note As of Sketchup 2026.0 positive values will be clamped to a minimum of 1.0. + # + # @param [Numeric] width # The width in pixels. # - # @return [Integer] + # @raise [ArgumentError] if the width is negative. + # + # @return [Numeric] # # @version SketchUp 6.0 def line_width=(width) @@ -852,8 +1009,7 @@ def load_texture(image_rep) # @param [Sketchup::InputPoint] inputpoint2 # @example # # Lock inference to X axis. - # # The points can be anywhere; only the vector between them affects - # # the result. + # # The points define a line in space, and the inference is locked to this line. # view.lock_inference( # Sketchup::InputPoint.new(ORIGIN), # Sketchup::InputPoint.new(Geom::Point3d.new(1, 0, 0)) @@ -876,10 +1032,7 @@ def lock_inference(*args) def model end - # The pick_helper method is used to retrieve a pick helper for the view. See - # the PickHelper class for information on pick helpers. - # - # This call returns an initialized PickHelper. + # The {#pick_helper} method is used to retrieve a pick helper for the view. # # @example # model = Sketchup.active_model @@ -888,41 +1041,75 @@ def model # # @overload pick_helper # - # @return [Sketchup::PickHelper] a PickHelper object + # @return [Sketchup::PickHelper] # # @overload pick_helper(x, y, aperture = 0) # - # @param [Integer] x - # @param [Integer] y - # @param [Integer] aperture - # @return [Sketchup::PickHelper] a PickHelper object + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @param [Integer] aperture The size of the aperture in physical pixels. + # @return [Sketchup::PickHelper] + # + # @overload pick_helper(x, y, aperture = 0.0) + # + # @version SketchUp 2025.0 + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. + # @param [Float] aperture The size of the aperture in logical pixels. + # @return [Sketchup::PickHelper] + # + # @see Sketchup::PickHelper # # @version SketchUp 6.0 def pick_helper(*args) end - # The pickray method is used to retrieve a ray passing through a given screen + # The {#pickray} method is used to retrieve a ray passing through a given screen # position in the viewing direction. # # @example - # ray = view.pickray x, y + # ray = view.pickray(x, y) + # result = model.raytest(ray) # # @overload pickray(screen_point) # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 # @param [Array(Integer, Integer)] screen_point + # Screen coordinates in physical pixels. + # @return [Array(Geom::Point3d, Geom::Vector3d)] a ray + # + # @overload pickray(x, y) + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Integer] x Screen coordinate in physical pixels. + # @param [Integer] y Screen coordinate in physical pixels. + # @return [Array(Geom::Point3d, Geom::Vector3d)] a ray + # + # @overload pickray(screen_point) + # + # @version SketchUp 2025.0 + # @param [Array(Float, Float)] screen_point + # Screen coordinates in logical pixels. # @return [Array(Geom::Point3d, Geom::Vector3d)] a ray # # @overload pickray(x, y) # - # @param [Integer] x - # @param [Integer] y + # @version SketchUp 2025.0 + # @param [Float] x Screen coordinate in logical pixels. + # @param [Float] y Screen coordinate in logical pixels. # @return [Array(Geom::Point3d, Geom::Vector3d)] a ray # + # @see Sketchup::Model#raytest + # # @version SketchUp 6.0 def pickray(*args) end - # The pixels_to_model method is used to compute a model size from a pixel size + # The {#pixels_to_model} method is used to compute a model size from a pixel size # at a given point. # # This method is useful for deciding how big to draw something based on a @@ -935,10 +1122,10 @@ def pickray(*args) # factor as {UI.scale_factor}. # # @param [Numeric] pixels - # The pixel size. + # Logical pixels since SketchUp 2017. # # @param [Geom::Point3d] point - # A Point3d object where the size will be calculated from. + # A model point where the size will be calculated from. # # @return [Float] the model size # @@ -1016,23 +1203,36 @@ def release_texture(texture_id) def remove_observer(observer) end - # The screen_coords method is used to retrieve the screen coordinates of the + # The {#screen_coords} method is used to retrieve the screen coordinates of the # given point on the screen. # - # The x and y values returned correspond to the x and y screen coordinates. - # Ignore the z values. If the referenced point is not in the current - # viewport, the x and/or y value may be negative. + # The +x+ and +y+ values returned correspond to the +x+ and +y+ screen coordinates. + # Ignore the +z+ values. If the referenced point is not in the current + # viewport, the +x+ and/or +y+ value may be negative. # # @example + # view = Sketchup.active_model.active_view # point = view.screen_coords(ORIGIN) # - # @param [Geom::Point3d] point3d - # A Point3d object. + # @note Prior to SketchUp 2025.0 this method returned the points as physical + # screen coordinates. As of SketchUp 2025.0 the points are returned in + # logical screen coordinates. + # + # @overload screen_coords(model_point) + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @param [Geom::Point3d] model_point Model coordinate. + # @return [Geom::Point3d] Screen coordinate in physical pixels. # - # @return [Geom::Point3d] A Point3d containing the screen position + # @overload screen_coords(model_point) + # + # @version SketchUp 2025.0 + # @param [Geom::Point3d] model_point Model coordinate. + # @return [Geom::Point3d] Screen coordinate in logical pixels. # # @version SketchUp 6.0 - def screen_coords(point3d) + def screen_coords(model_point) end # Set the drawing color for the view based on the direction of a line that you @@ -1089,10 +1289,10 @@ def show_frame(delay) # class ExampleTool # TEXT_OPTIONS = { # :font => "Arial", - # :size => 20, + # :pixel_size => 20, # Use :size for SketchUp 2024.0 and older. # :bold => true, # :align => TextAlignRight, - # :align => TextVerticalAlignBaseline + # :vertical_align => TextVerticalAlignBaseline # } # # # Since `draw` is called frequently it can be useful to pre-compute and @@ -1132,7 +1332,15 @@ def show_frame(delay) # @option options [String] :font The name of the font to use. If it does not # exist on the system, a default font will be used instead. # - # @option options [Integer] :size The size of the font in points + # @option options [Integer] :size Legacy: The size of the font in + # system-dependent units. On Windows this is in points, on Mac it's in + # pixels. + # + # @option options [Integer] :pixel_size Added SketchUp 2025.0: The + # size of the font in pixels. + # + # @option options [Integer] :point_size Added SketchUp 2025.0: The + # size of the font in points. # # @option options [Boolean] :bold Controls the Bold property of the font. # @@ -1157,6 +1365,9 @@ def show_frame(delay) # The text can be customized by providing a hash or # named arguments of options. # + # @raise [ArgumentError] if combining usage of +:size+, +:pixel_size+ or + # +:point_size+ options. + # # @return [Geom::Bounds2d] # # @see #draw_text @@ -1180,7 +1391,7 @@ def text_bounds(point, text, options = {}) def tooltip=(string) end - # The vpheight method is used to retrieve the height of the viewport for the + # The {#vpheight} method is used to retrieve the height of the viewport for the # view. # # @example @@ -1188,19 +1399,46 @@ def tooltip=(string) # view = model.active_view # height = view.vpheight # - # @return [Integer] the height of the viewport in physical pixels. + # @note Prior to SketchUp 2025.0 this method returned the size as physical + # screen coordinates. As of SketchUp 2025.0 the size are returned in + # logical screen coordinates. + # + # @overload vpheight + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @return [Integer] the height of the viewport in physical pixels. + # + # @overload vpheight + # + # @version SketchUp 2025.0 + # @return [Float] the height of the viewport in logical pixels. # # @version SketchUp 6.0 def vpheight end - # The vpwidth method is used to retrieve the width of the viewport for the + # The {#vpwidth} method is used to retrieve the width of the viewport for the # view. # # @example + # view = Sketchup.active_model.active_view # width = view.vpwidth # - # @return [Integer] the width of the viewport in physical pixels. + # @note Prior to SketchUp 2025.0 this method returned the size as physical + # screen coordinates. As of SketchUp 2025.0 the size are returned in + # logical screen coordinates. + # + # @overload vpwidth + # + # @note Signature for versions prior to SketchUp 2025.0 + # @version SketchUp 6.0 + # @return [Integer] the width of the viewport in physical pixels. + # + # @overload vpwidth + # + # @version SketchUp 2025.0 + # @return [Float] the width of the viewport in logical pixels. # # @version SketchUp 6.0 def vpwidth @@ -1208,11 +1446,12 @@ def vpwidth # The {#write_image} method is used to write the current view to an image file. # - # Supported file types are `.png`, `.jpg`, `.jpeg`, `gif`, `.bmp`, `.tif`. - # For other file formats available from the GUI in File > Export > 2D - # Graphics, .e.g `.pdf`, use {Sketchup::Model#export}. + # Supported file types are +.png+, +.jpg+, +.jpeg+, +gif+, +.bmp+, +.tif+. + # For other file formats available from the GUI in +File > Export > 2D Graphics+, + # .e.g +.pdf+, use {Sketchup::Model#export}. + # + # @overload write_image(filename, width = view.vpwidth, height = view.vpheight, antialias = false, compression = 1.0) # - # compression = 1.0) # @note Prefer the overload with option hash instead of this variant. This # overload is not updated with new options. # @@ -1234,9 +1473,6 @@ def vpwidth # @param [Float] compression # Compression factor for JPEG images, between +0.0+ and +1.0+. # - # @overload write_image(filename, width = view.vpwidth, height = view.vpheight, antialias = false, - # - # # @overload write_image(options) # # @example diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ViewObserver.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ViewObserver.rb index 753d2fb..469e2ab 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ViewObserver.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ViewObserver.rb @@ -1,39 +1,65 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) -# This observer interface is implemented to react to view events. +# This observer interface is implemented to react to {Sketchup::View} 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 -# view object. +# {Sketchup::View} object. # # @example -# # This is an example of an observer that watches tool interactions. # class MyViewObserver < Sketchup::ViewObserver # def onViewChanged(view) # puts "onViewChanged: #{view}" # end # end # -# # Attach the observer. # Sketchup.active_model.active_view.add_observer(MyViewObserver.new) # +# @see Sketchup::View#add_observer +# # @version SketchUp 6.0 class Sketchup::ViewObserver # Instance Methods + # The {#onScaleFactorChange} method is called whenever the view DPI of the view + # changes. This can be the SketchUp window being moved to another monitor with + # a different DPI or the user changing the DPI settings of the monitor. + # + # @example + # class MyViewObserver < Sketchup::ViewObserver + # def onScaleFactorChange(view) + # puts "onScaleFactorChange: #{view}" + # puts "UI.scale_factor(view): #{UI.scale_factor(view)}" + # end + # end + # + # Sketchup.active_model.active_view.add_observer(MyViewObserver.new) + # + # @param [Sketchup::View] view + # + # @return [nil] + # + # @version SketchUp 2025.0 + def onScaleFactorChange(view) + end + # The {#onViewChanged} method is called whenever the view is altered, such as - # when the user uses the Pan, Orbit, or Zoom tools are used. + # when the user uses the Pan, Orbit, or Zoom tools. # # @bug Prior to SketchUp 2019.2 this event did not trigger when the viewport # size changed. # # @example - # def onViewChanged(view) - # puts "onViewChanged: #{view}" + # class MyViewObserver < Sketchup::ViewObserver + # def onViewChanged(view) + # puts "onViewChanged: #{view}" + # end # end # + # Sketchup.active_model.active_view.add_observer(MyViewObserver.new) + # # @param [Sketchup::View] view # # @return [nil] diff --git a/lib/sketchup-api-stubs/stubs/SketchupExtension.rb b/lib/sketchup-api-stubs/stubs/SketchupExtension.rb index a83a698..66a248f 100644 --- a/lib/sketchup-api-stubs/stubs/SketchupExtension.rb +++ b/lib/sketchup-api-stubs/stubs/SketchupExtension.rb @@ -1,10 +1,10 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The SketchupExtension class contains methods allowing you to create and # manipulate SketchUp extensions. Extensions are Ruby scripts that can be # loaded and unloaded using the Extension manager (Extensions panel of the -# Preferences dialog box). Generally you should register your ruby scripts as +# Extension Manager dialog box). Generally you should register your ruby scripts as # an extension to give SketchUp users the ability to disable it through the # user interface. # @@ -40,11 +40,11 @@ class SketchupExtension # Loads the extension, meaning the underlying ruby script is immediately # interpreted. This is the equivalent of checking the extension's checkbox - # in the Preferences > Extensions list. + # in the Extension Manager. # # @example # # This will register the extension, a necessary step for it to appear - # # in SketchUp's Preferences > Extensions list + # # in SketchUp's Extension Manager > Extensions list # ext_c = SketchupExtension.new('Stair Tools C', 'StairTools/core.rb') # Sketchup.register_extension(ext_c, false) # @@ -214,9 +214,9 @@ def initialize(title, path) # # @example # ext = SketchupExtension.new('Stair Tools', 'StairTools/core.rb') - # UI.messagebox("load_on_start? is false: #{ext.load_on_start?.to_s}") + # puts "load_on_start? is false: #{ext.load_on_start?.to_s}" # Sketchup.register_extension(ext, true) - # UI.messagebox("load_on_start? is now true: #{ext.load_on_start?.to_s}") + # puts "load_on_start? is now true: #{ext.load_on_start?.to_s}" # # @return [Boolean] # @@ -229,9 +229,9 @@ def load_on_start? # # @example # ext = SketchupExtension.new('Stair Tools', 'StairTools/core.rb') - # UI.messagebox("loaded? is false: #{ext.loaded?.to_s}") + # puts "loaded? is false: #{ext.loaded?.to_s}" # Sketchup.register_extension(ext, true) - # UI.messagebox("loaded? is now true: #{ext.loaded?.to_s}") + # puts "loaded? is now true: #{ext.loaded?.to_s}" # # @return [Boolean] # @@ -277,9 +277,9 @@ def name=(name) # # @example # ext = SketchupExtension.new('Stair Tools', 'StairTools/core.rb') - # UI.messagebox("My registered? is false: #{ext.registered?.to_s}") + # puts "My registered? is false: #{ext.registered?.to_s}" # Sketchup.register_extension(ext, true) - # UI.messagebox("Now registered? is now true: #{ext.registered?.to_s}") + # puts "Now registered? is now true: #{ext.registered?.to_s}" # # @return [Boolean] # @@ -288,7 +288,7 @@ def registered? end # Unloads the extension. This is the equivalent of unchecking the extension's - # checkbox in the Preferences > Extensions list. + # checkbox in the Extension Manager > Extensions list. # # Note that technically the extension is not "unloaded" in the sense that it # stops running during the current SketchUp session, but the next time the diff --git a/lib/sketchup-api-stubs/stubs/String.rb b/lib/sketchup-api-stubs/stubs/String.rb index acab6d2..05377f8 100644 --- a/lib/sketchup-api-stubs/stubs/String.rb +++ b/lib/sketchup-api-stubs/stubs/String.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The String class contains a method used to parse a string as a length value. diff --git a/lib/sketchup-api-stubs/stubs/UI.rb b/lib/sketchup-api-stubs/stubs/UI.rb index 0f9c6c6..257601a 100644 --- a/lib/sketchup-api-stubs/stubs/UI.rb +++ b/lib/sketchup-api-stubs/stubs/UI.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The UI module contains a number of methods for creating simple UI elements @@ -56,11 +56,12 @@ def self.beep # the specified location. This must be called from within a custom # tool. See the {Sketchup::Tool} documentation for a complete example. # - # The size of the cursor images should be 32x32 pixels. + # The size of the cursor images should be 32x32 pixels. Any size different + # from that will be scaled using the shrink-to-fit policy. # - # The coordinates for the cursor's hotspot is based from it's top left corner. + # The coordinates for the cursor's hotspot are based from it's top left corner, starting at (0, 0). # For example, a value of (hot_x, hot_y) = (5, 10) would identify the hotpoint - # of the cursor at 6 pixels from the left edge of your cursor image and 11 + # of the cursor at 5 pixels from the left edge of your cursor image and 10 # pixels from the top edge of your cursor image. # # @bug On macOS raster cursors are always displayed at 24x24. @@ -94,12 +95,15 @@ def self.beep # File path to an image. # # @param [Integer] hot_x - # An x coordinate that is the "hotpoint" for the cursor - # computed from the left edge of your cursor image. + # The x-coordinate of the "hotpoint" of the cursor, computed from the left edge of your cursor + # image. # # @param [Integer] hot_y - # A y coordinate that is the "hotpoint" for the cursor - # computed from the top edge of the of your cursor image. + # The y-coordinate of the "hotpoint" of the cursor, computed from the top edge of your cursor + # image. + # + # @raise [RangeError] if @param hot_x or @param hot_y are negative or larger than the max value of + # an Integer. # # @return [Integer] Id associated with the cursor. # Use this with {UI.set_cursor} in {Sketchup::Tool#onSetCursor}. @@ -144,6 +148,10 @@ def self.get_clipboard_data # list = ["", "", "Male|Female"] # input = UI.inputbox(prompts, defaults, list, "Tell me about yourself.") # + # @note The method intelligently handles various types for default values and lists, automatically + # attempting to convert provided inputs to match the type of the default value. This ensures + # consistency in data types throughout the operation. + # # @overload inputbox(prompts, defaults, title) # # @param [Array] prompts @@ -252,7 +260,7 @@ def self.menu(menu_name = "Extensions") # @example # result = UI.messagebox('Do you like cheese?', MB_YESNO) # if result == IDYES - # UI.messagebox('SketchUp likes cheese too!') + # puts 'SketchUp likes cheese too!' # end # # @param [String] message @@ -291,8 +299,16 @@ def self.model_info_pages # not perform URL encoding and the API user is expected to provide a valid # URL. # - # @example - # status = UI.openURL("http://www.sketchup.com") + # @example Open plain(non-encoded) URL + # status = UI.openURL("https://www.sketchup.com") + # + # @example Open encoded URL + # status = UI.openURL("https://example.com/api?query=test&test=test") + # + # @example Open a local URL + # # To open a local file one must add file:/// in front of the path of the file to make it an + # # URL. + # status = UI.openURL("file:///path/to/the/file/file.skp") # # @param [String] url # @@ -450,7 +466,20 @@ def self.savepanel(title, directory, filename) # Returns the scaling factor SketchUp uses on high DPI monitors. Useful for # things like {Sketchup::View#draw2d}. # - # @example + # @example Per Monitor DPI + # # Scale a set of points representing 2d screen points to account for high + # # DPI monitors. + # points2d = [ + # Geom::Point3d.new(0, 0, 0), + # Geom::Point3d.new(8, 0, 0), + # Geom::Point3d.new(8, 4, 0), + # Geom::Point3d.new(0, 4, 0), + # ] + # scale = UI.scale_factor(Sketchup.active_model.active_view) + # tr = Geom::Transformation.scaling(UI.scale_factor) + # points2d.each { |point| point.transform!(tr) } + # + # @example Deprecated legacy API # # Scale a set of points representing 2d screen points to account for high # # DPI monitors. # points2d = [ @@ -460,15 +489,28 @@ def self.savepanel(title, directory, filename) # Geom::Point3d.new(0, 4, 0) # ] # tr = Geom::Transformation.scaling(UI.scale_factor) - # points2d.each { |point| point.transform!(tr) + # points2d.each { |point| point.transform!(tr) } # # @note SU2017M0 will automatically scale up line width and text size, but will # not scale up the points provided to {Sketchup::View#draw2d}. # + # @overload scale_factor + # + # @version SketchUp 2017 + # @deprecated Use the overload that takes a {Sketchup::View} instead. + # This returns a scale factor determined when SketchUp starts from the + # monitor it started on. It does not change for the duration of the + # application session. + # + # @overload scale_factor(view) + # + # @version SketchUp 2025.0 + # @param [Sketchup::View] view + # # @return [Float] # # @version SketchUp 2017 - def self.scale_factor + def self.scale_factor(*args) end # The {.select_directory} method is used to display the OS dialog for selecting diff --git a/lib/sketchup-api-stubs/stubs/UI/Command.rb b/lib/sketchup-api-stubs/stubs/UI/Command.rb index 0fddc83..4635e48 100644 --- a/lib/sketchup-api-stubs/stubs/UI/Command.rb +++ b/lib/sketchup-api-stubs/stubs/UI/Command.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Command class is the preferred class for adding tools to the menus and @@ -124,8 +124,11 @@ def initialize(menutext) # toolbar = UI::Toolbar.new "Test" # # This command displays Hello World on the screen when clicked # cmd = UI::Command.new("Test") { UI.messagebox("Hello World") } - # cmd.small_icon = "ToolPencilSmall.png" - # cmd.large_icon = "ToolPencilLarge.png" + # # Use __dir__ to set the icon paths relative to the current file's directory + # # __dir__ returns the directory of the file where it is called + # # File.join is used to construct file paths in a platform-independent way + # cmd.small_icon = File.join(__dir__, "icons", "ToolPencilSmall.png") + # cmd.large_icon = File.join(__dir__, "icons", "ToolPencilLarge.png") # toolbar = toolbar.add_item cmd # toolbar.show # puts cmd.large_icon @@ -149,8 +152,11 @@ def large_icon # toolbar = UI::Toolbar.new "Test" # # This command displays Hello World on the screen when clicked # cmd = UI::Command.new("Test") { UI.messagebox("Hello World") } - # cmd.small_icon = "ToolPencilSmall.png" - # cmd.large_icon = "ToolPencilLarge.png" + # # Use __dir__ to set the icon paths relative to the current file's directory + # # __dir__ returns the directory of the file where it is called + # # File.join is used to construct file paths in a platform-independent way + # cmd.small_icon = File.join(__dir__, "icons", "ToolPencilSmall.png") + # cmd.large_icon = File.join(__dir__, "icons", "ToolPencilLarge.png") # toolbar = toolbar.add_item cmd # toolbar.show # @@ -260,8 +266,11 @@ def set_validation_proc # toolbar = UI::Toolbar.new "Test" # # This toolbar command displays Hello World on the screen when clicked. # cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") } - # cmd.small_icon = "ToolPencilSmall.png" - # cmd.large_icon = "ToolPencilLarge.png" + # # Use __dir__ to set the icon paths relative to the current file's directory + # # __dir__ returns the directory of the file where it is called + # # File.join is used to construct file paths in a platform-independent way + # cmd.small_icon = File.join(__dir__, "icons", "ToolPencilSmall.png") + # cmd.large_icon = File.join(__dir__, "icons", "ToolPencilLarge.png") # toolbar = toolbar.add_item cmd # toolbar.show # puts cmd.small_icon @@ -285,8 +294,11 @@ def small_icon # toolbar = UI::Toolbar.new "Test" # # This toolbar command displays Hello World on the screen when clicked. # cmd = UI::Command.new("Tester") { UI.messagebox("Hello World") } - # cmd.small_icon = "ToolPencilSmall.png" - # cmd.large_icon = "ToolPencilLarge.png" + # # Use __dir__ to set the icon paths relative to the current file's directory + # # __dir__ returns the directory of the file where it is called + # # File.join is used to construct file paths in a platform-independent way + # cmd.small_icon = File.join(__dir__, "icons", "ToolPencilSmall.png") + # cmd.large_icon = File.join(__dir__, "icons", "ToolPencilLarge.png") # toolbar = toolbar.add_item cmd # toolbar.show # diff --git a/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb b/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb index 61d028b..b7a6c70 100644 --- a/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb +++ b/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Ruby HtmlDialog class allows you to create and interact with HTML dialog @@ -21,6 +21,8 @@ # # HtmlDialog uses the following versions of CEF (Chromium Embedded Framework): # +# [SketchUp 2025.0] +# CEF 128 # [SketchUp 2024.0] # CEF 112 # [SketchUp 2021.1] @@ -68,6 +70,7 @@ class UI::HtmlDialog # dialog.add_action_callback("say") { |action_context, param1, param2| # puts "JavaScript said #{param1} and #{param2}" # } + # dialog.show # should be called directly after binding callbacks # # @example JavaScript # sketchup.say('Hello World', 42); @@ -79,8 +82,32 @@ class UI::HtmlDialog # } # }); # + # @example A complete example containing both Ruby and JavaScript + # html = <<-HTML + #

Hello World

+ #

+ #

+ # HTML + # + # options = { + # :dialog_title => "Example Dialog", + # :preferences_key => "example.htmldialog", + # :style => UI::HtmlDialog::STYLE_DIALOG + # } + # + # dialog = UI::HtmlDialog.new(options) + # dialog.set_html(html) + # dialog.center + # + # dialog.add_action_callback("say") { |action_context, param1, param2| + # puts "JavaScript said #{param1} and #{param2}" + # } + # + # dialog.show # should be called directly after binding callbacks + # # @note When an HtmlDialog is closed, all callbacks to that instance are - # cleared. Re-attach them if you need to open the dialog again. + # cleared. Attach or re-attach them before you show the dialog. # # @param [String] callback_name # The name of the callback method to be invoked from the html dialog. @@ -257,7 +284,7 @@ def get_size # :max_height => 1000, # :style => UI::HtmlDialog::STYLE_DIALOG # }) - # dialog.set_url("http://www.sketchup.com") + # dialog.set_url("https://www.sketchup.com") # dialog.show # # @example With keyword style argument @@ -335,6 +362,8 @@ def initialize(properties) # # @return [Boolean] # + # @see #set_on_closed + # # @version SketchUp 2017 # # @yieldreturn [Boolean] Return a boolean to indicate if the dialogs should @@ -394,13 +423,19 @@ def set_html(html_string) # The {#set_on_closed} method is used to attach a block that will be # executed when a dialog is already in the process of closing, do any last - # minute operations within this block such as saving the current state. + # minute operations within this block such as releasing resources or performing cleanup tasks. # # @example - # dialog.set_on_closed { save_selection } + # dialog.set_on_closed do + # File.delete('temp_file.txt') if File.exist?('temp_file.txt') + # end + # + # @note For saving state before window closes use {#set_can_close} instead. # # @return [Boolean] # + # @see #set_can_close + # # @version SketchUp 2017 def set_on_closed end diff --git a/lib/sketchup-api-stubs/stubs/UI/Notification.rb b/lib/sketchup-api-stubs/stubs/UI/Notification.rb index cba9056..0fc1ca3 100644 --- a/lib/sketchup-api-stubs/stubs/UI/Notification.rb +++ b/lib/sketchup-api-stubs/stubs/UI/Notification.rb @@ -1,11 +1,20 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # {UI::Notification} objects allows you to show native notifications in the # desktop. Notifications can have a message, icon and accept and/or dismiss # buttons with callback blocks. # +# Supported icon formats include: .bmp, .png, .jpg. +# Vector icons are supported as .svg on Windows and .pdf on Mac. +# Recommended icon size is 48x48 pixels. Icons larger than these sizes will be automatically +# downscaled to fit within the limits. +# +# @bug Prior to SketchUp 2026.0 oversized icons are cropped on Windows. +# # @example +# sketchup_extension = Sketchup.extensions[extension_id] +# Sketchup.register_extension(sketchup_extension, true) # # For consistency, the accept (yes) and the dismiss (no) buttons # # are always displayed in the same order. # message = "A new version of pizza is available. Install now?" @@ -107,6 +116,7 @@ def icon_tooltip=(icon_tooltip) # @notification.show # # @note In order to insert line breaks into the message you need to use +\\r\\n+. + # From SketchUp 2019 and onwards +\\n+ also works on both Mac and Windows. # # @param [SketchupExtension] sketchup_extension # {SketchupExtension} instance used to identify @@ -150,6 +160,7 @@ def message # @notification.show # # @note In order to insert line breaks into the message you need to use +\\r\\n+. + # From SketchUp 2019 and onwards +\\n+ also works on both Mac and Windows. # # @param [String] message # String providing the new message. @@ -163,7 +174,7 @@ def message=(message) # Shows a button in the notification with the given title and callback block, # both arguments are required. # - # @bug Prior to SketchUp 2019 both the accept and dismiss buttons were + # @bug Prior to SketchUp 2019 both the Accept and Dismiss buttons were # displayed, even if only one had been implemented. # # @example @@ -178,7 +189,7 @@ def message=(message) # # @param [Proc] block # Sets the action callback, this will be called when - # the user clicks on the dismiss button. + # the user clicks on the accept button. # # @raise [RuntimeError] When calling on_accept when the notification has # already been shown. diff --git a/lib/sketchup-api-stubs/stubs/UI/Toolbar.rb b/lib/sketchup-api-stubs/stubs/UI/Toolbar.rb index df004a3..cc6bf86 100644 --- a/lib/sketchup-api-stubs/stubs/UI/Toolbar.rb +++ b/lib/sketchup-api-stubs/stubs/UI/Toolbar.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Toolbar class contains methods to create and manipulate SketchUp @@ -113,12 +113,29 @@ def each # The get_last_state method is used to determine if the toolbar was hidden or # visible in the previous session of SketchUp. # - # Valid states are 1 for visible, 0 for hidden, -1 for before never shown. + # Valid states are {TB_VISIBLE} (1) for visible, {TB_HIDDEN} (0) for hidden, + # {TB_NEVER_SHOWN} (-1) for before never shown. # # @example # state = toolbar.get_last_state + # case state + # when TB_VISIBLE + # puts "Toolbar was visible in the last session." + # when TB_HIDDEN + # puts "Toolbar was hidden in the last session." + # when TB_NEVER_SHOWN + # puts "Toolbar was never shown in the last session." + # else + # puts "Unknown toolbar state: #{state}" + # end # - # @return [Boolean] the last state of the toolbar (see comments) + # @return [Integer] the last state of the toolbar (see constants above) + # + # @see TB_VISIBLE + # + # @see TB_HIDDEN + # + # @see TB_NEVER_SHOWN # # @version SketchUp 6.0 def get_last_state diff --git a/lib/sketchup-api-stubs/stubs/UI/WebDialog.rb b/lib/sketchup-api-stubs/stubs/UI/WebDialog.rb index 271244c..41ba0a6 100644 --- a/lib/sketchup-api-stubs/stubs/UI/WebDialog.rb +++ b/lib/sketchup-api-stubs/stubs/UI/WebDialog.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) # The Ruby WebDialog class allows you to create and interact with DHTML dialog @@ -9,7 +9,7 @@ # than inside a dialog in SketchUp. # # See this blog post for a detailed, step-by-step example: -# http://sketchupapi.blogspot.com/2008/02/sharing-data-between-sketchup-ruby-and.html +# https://sketchupapi.blogspot.com/2008/02/sharing-data-between-sketchup-ruby-and.html # # Under Windows the IE render mode is different in webdialogs than from what # you see in the normal browser. It will by default pick an older render mode @@ -29,7 +29,7 @@ # would like to direct the user to install that extension. # # For example, to launch an extension's page whose URL is: -# http://extensions.sketchup.com/en/content/advanced-camera-tools +# https://extensions.sketchup.com/en/content/advanced-camera-tools # The link would be: # # @deprecated Please use {UI::HtmlDialog} that was introduced in @@ -180,7 +180,7 @@ def get_element_value(element_id) # @example # dlg = UI::WebDialog.new("Show sketchup.com", true, # "ShowSketchupDotCom", 739, 641, 150, 150, true); - # dlg.set_url "http://www.sketchup.com" + # dlg.set_url "https://www.sketchup.com" # dlg.show # # @note Since SU2017 the position and size of the dialog is DPI aware - it will @@ -385,7 +385,7 @@ def navigation_buttons_enabled? # method. # # @example - # data = dialog.post_url("http://www.mydomain.com/formchecker.cgi",data) + # data = dialog.post_url("https://www.mydomain.com/formchecker.cgi",data) # # @param [String] url # The url to send the data. @@ -482,6 +482,9 @@ def set_html(html_string) # @example # dialog.set_on_close{ UI.messagebox("Closing the webDialog") } # + # @note {UI::WebDialog#close} method should not be called from the {UI::WebDialog#set_on_close} + # callback. That would make it trigger itself recursively. + # # @return [nil] # # @version SketchUp 6.0 @@ -535,7 +538,7 @@ def set_size(w, h) # specific URL. This method allows you to load web sites in a webdialog. # # @example - # dialog.set_url "http://www.sketchup.com" + # dialog.set_url "https://www.sketchup.com" # # @param [String] url # The URL for a specific web site. diff --git a/lib/sketchup-api-stubs/stubs/_top_level.rb b/lib/sketchup-api-stubs/stubs/_top_level.rb index 447a8ff..d3d070a 100644 --- a/lib/sketchup-api-stubs/stubs/_top_level.rb +++ b/lib/sketchup-api-stubs/stubs/_top_level.rb @@ -1,4 +1,4 @@ -# Copyright:: Copyright 2024 Trimble Inc. +# Copyright:: Copyright 2026 Trimble Inc. # License:: The MIT License (MIT) @@ -146,6 +146,7 @@ PAGE_NO_CAMERA = nil # Stub value. PAGE_USE_ALL = nil # Stub value. PAGE_USE_CAMERA = nil # Stub value. + PAGE_USE_ENVIRONMENT = nil # Stub value. PAGE_USE_HIDDEN = nil # Stub value. PAGE_USE_HIDDEN_GEOMETRY = nil # Stub value. PAGE_USE_HIDDEN_OBJECTS = nil # Stub value. @@ -178,24 +179,23 @@ TextVerticalAlignCapHeight = nil # Stub value. TextVerticalAlignCenter = nil # Stub value. + VK_ALT = nil # Stub value. + VK_COMMAND = nil # Stub value. + VK_CONTROL = nil # Stub value. VK_DELETE = nil # Stub value. VK_DOWN = nil # Stub value. VK_END = nil # Stub value. VK_HOME = nil # Stub value. VK_INSERT = nil # Stub value. VK_LEFT = nil # Stub value. + VK_MENU = nil # Stub value. VK_NEXT = nil # Stub value. VK_PRIOR = nil # Stub value. VK_RIGHT = nil # Stub value. + VK_SHIFT = nil # Stub value. VK_SPACE = nil # Stub value. VK_UP = nil # Stub value. - VK_ALT = nil # Stub value. - VK_COMMAND = nil # Stub value. - VK_CONTROL = nil # Stub value. - VK_MENU = nil # Stub value. - VK_SHIFT = nil # Stub value. - X_AXIS_2D = nil # Stub value. Y_AXIS_2D = nil # Stub value. diff --git a/pages/ReleaseNotes.md b/pages/ReleaseNotes.md index a32c0ce..68ef4d6 100644 --- a/pages/ReleaseNotes.md +++ b/pages/ReleaseNotes.md @@ -19,7 +19,16 @@ Though our adoption rate to the latest version is quite high, it can take time a Here are the build numbers for recent SketchUp releases. Note that build numbers in languages besides English are larger for each release, so it is best to check for builds that are greater than or equal to the numbers here. +- **SU2026.0** = BUILD_NUMBER_WIN on Windows 64-bit, BUILD_NUMBER_MAC on Mac 64-bit. + +- **SU2025.0.3** = 25.0.660 on Windows 64-bit, 25.0.659 on Mac 64-bit. +- **SU2025.0.2** = 25.0.634 on Windows 64-bit, 25.0.633 on Mac 64-bit. +- **SU2025.0** = 25.0.571 on Windows 64-bit, 25.0.570 on Mac 64-bit. + +- **SU2024.0.2** = 24.0.594 on Windows 64-bit, 24.0.595 on Mac 64-bit. +- **SU2024.0.1** = 24.0.553 on Windows 64-bit, 24.0.554 on Mac 64-bit. - **SU2024.0** = 24.0.484 on Windows 64-bit, 24.0.483 on Mac 64-bit. + - **SU2023.1.3** = 23.1.340 on Windows 64-bit, 23.1.341 on Mac 64-bit. - **SU2023.1.2** = 23.1.315 on Windows 64-bit, 23.1.314 on Mac 64-bit. - **SU2023.1.1** = 23.1.313 on Windows 64-bit, 23.1.312 on Mac 64-bit. @@ -28,6 +37,7 @@ Here are the build numbers for recent SketchUp releases. Note that build numbers - **SU2023.0** = 23.0.367 on Windows 64-bit, 23.0.366 on Mac 64-bit. - **SU2022.0.1** = 22.0.354 on Windows 64-bit, 22.0.353 on Mac 64-bit. - **SU2022.0** = 22.0.316 on Windows 64-bit, 22.0.315 on Mac 64-bit. + - **SU2021.1.2** = 21.1.332 on Windows 64-bit, 21.1.331 on Mac 64-bit. (Contained no Ruby API changes) - **SU2021.1.1** = 21.1.299 on Windows 64-bit, 21.1.298 on Mac 64-bit. - **SU2021.1** = 21.1.279 on Windows 64-bit, 21.1.278 on Mac 64-bit. @@ -73,8 +83,221 @@ Here are the build numbers for recent SketchUp releases. Note that build numbers - **SU6 M6** = 6.4.265 on Windows, 6.4.263 on Mac. + +# What's new in SketchUp 2026.0 + +## Breaking changes +* Modifying the properties {Sketchup::Axes}, {Sketchup::Camera}, {Sketchup::RenderingOptions}, and {Sketchup::ShadowInfo} of a {Sketchup::Page} is now an undoable operation. Scene changes are expected to be called between {Sketchup::Model#start_operation} and {Sketchup::Model#commit_operation} to not flood the undo stack. +Extensions that don't follow this requirement will be rejected for updates or publication to the Extension Warehouse. +* Additional error checking is performed regarding non-invertible transforms (typically this means the matrix has zero scale on + one or more axes). Calling {Geom::Transformation#inverse} or + {Geom::Transformation#invert!} with a non-invertible transform will raise an `ArgumentError`. In addition, calling {Sketchup::ComponentInstance#transformation=}, + {Sketchup::ComponentInstance#move!}, {Sketchup::Group#transformation=}, or {Sketchup::Group#move!} with a non-invertible transform as an argument will also raise an `ArgumentError`. + + +## Ruby API Additions and Improvements + +* Added {Sketchup::Model#active_section_planes}. +* Added {Sketchup::Page#active_section_planes}. +* Added {Sketchup::Styles#remove_style}. +* Added a new optional parameter for {Layout::LinearDimension#initialize} to specify the dimension line's alignment on creation. Alignment can be + specified using one of the following constants: + * {Layout::LinearDimension::DIMENSION_LINE_ALIGNED} + * {Layout::LinearDimension::DIMENSION_LINE_VERTICAL} + * {Layout::LinearDimension::DIMENSION_LINE_HORIZONTAL} +* Added {Layout::LinearDimension#leader_line_visible?}. +* Added {Layout::Style#text_strikethrough}. +* Added {Layout::Style#text_strikethrough=}. +* Added constants for the valid values for {Layout::Style#text_strikethrough=} + * {Layout::Style::STRIKETHROUGH_NONE} + * {Layout::Style::STRIKETHROUGH_SINGLE} +* Modified {Sketchup::Styles#add_style} to return the added style. +* Added `:show_version_warning_dialog` optional argument to {Sketchup.open_file} to control whether the version compatibility dialog can appear. +* Added {Sketchup::Pages#unique_name}. +* Modified {Sketchup::Pages#add} so that when adding a new {Sketchup::Page}, if the specified name is already taken, it automatically modifies the name to ensure it is unique. +* Modified {Sketchup::Page#name=} so that if the given name is already used by another {Sketchup::Page}, it automatically adjusts the name to make it unique. +* Fixed {Sketchup::ComponentDefinition#save_as} and {Sketchup::ComponentDefinition#save_copy} to return false when saving did not work. +* Modified {Sketchup::Model#export} to use a new IFC exporter which comes with the following option changes: + * new supported options: `:ifc_version`, `:standard_ifc_hierarchy`, `:selectionset_only`, `:tessellated_geometry`. + * options no longer supported: `:doublesided_faces`, `:ifc_mapped_items`, `:ifc_types`. +* Added {Sketchup::Environments#add} overload that accepts just the file path. Environment name will be derived from the file being imported. +* Added {Layout::Entity#set_attribute}. +* Added {Layout::Entity#get_attribute} . +* Added {Layout::Entity#delete_attribute}. +* Added {Layout::Entity#attribute_dictionary}. +* Added {Layout::Document#set_attribute}. +* Added {Layout::Document#get_attribute}. +* Added {Layout::Document#delete_attribute}. +* Added {Layout::Document#attribute_dictionary}. +* Added {Layout::Page#set_attribute}. +* Added {Layout::Page#get_attribute}. +* Added {Layout::Page#delete_attribute}. +* Added {Layout::Page#attribute_dictionary}. +* Added {Layout::Dictionary}. +* Added rendering options support for Ambient Occlusion: + * {Sketchup::RenderingOptions} keys added: + * `"AmbientOcclusionColor"` + * `"AmbientOcclusionMultiplier"` + * {Sketchup::RenderingOptionsObserver} constants: + * {Sketchup::RenderingOptions::ROPSetAOColor} + * {Sketchup::RenderingOptions::ROPSetAOMultiplier} + +## Ruby API Bug Fixes + +* Fixed a crash in {Sketchup::Model#place_component} when placing an empty component. +* Fixed SketchUp 2021.1 regression in {Sketchup::Model#drawing_element_visible?} throwing an exception when the last element of an instance path was a + {Sketchup::Group} or {Sketchup::ComponentInstance}. +* Fixed an undo crash when using {Sketchup::Classifications#load_schema} and {Sketchup::ComponentDefinition#add_classification} in the same operation. +* Fixed a bug that involves using a {Geom::Transformation} that is not invertible. Now calling {Geom::Transformation#inverse} or + {Geom::Transformation#invert!} with a non-invertible transform will raise an `ArgumentError`. In addition, calling {Sketchup::ComponentInstance#transformation=} or + {Sketchup::Group#transformation=} with a non-invertible transform as an argument will also raise an `ArgumentError`. +* Fixed a crash in {Layout::SketchUpModel} when attempting to render a model containing an environment when that viewport was not yet added to a {Layout::Document}. +* Fixed a crash when setting line width with {Sketchup::View#line_width=} to 0.0 with the new graphics engine. Negative values will raise an `ArgumentError` and positive values will be clamped to a minimum of 1.0. + +# What's new in SketchUp 2025.0.3 + +## Ruby API Bug Fixes + +* Fixed crash using the LayOut Ruby API to add entities to a LayOut document. + +# What's new in SketchUp 2025.0.2 + +## Update OpenSSL to 3.4.1 + +The version of OpenSSL in Ruby was updated to 3.4.1. + +## Ruby API Additions and Improvements +* Added {Sketchup::Material#normal_enabled=}. +* Added {Sketchup::Material#ao_enabled=}. + +## Ruby API Bug Fixes +* Fixed {Sketchup::Environments#current=} to allow unsetting the current environment. + +# What's new in SketchUp 2025.0 + +## Update OpenSSL to 3.3.1 + +The version of OpenSSL in Ruby was updated to 3.3.1. + +## Ruby API Additions and Improvements + +* Made {Sketchup::Licensing.get_extension_license} automatically try to fetch a license from Extension Warehouse if needed. +* Added support for Snaps: + * {Sketchup::Snap} + * {Sketchup::Entities#add_snap} +* Added support for PBR materials: + * {Sketchup::Material#ao_enabled?} + * {Sketchup::Material#ao_strength} + * {Sketchup::Material#ao_strength=} + * {Sketchup::Material#ao_texture} + * {Sketchup::Material#ao_texture=} + * {Sketchup::Material#metallic_factor} + * {Sketchup::Material#metallic_factor=} + * {Sketchup::Material#metallic_texture} + * {Sketchup::Material#metallic_texture=} + * {Sketchup::Material#metalness_enabled=} + * {Sketchup::Material#metalness_enabled?} + * {Sketchup::Material#normal_enabled?} + * {Sketchup::Material#normal_scale} + * {Sketchup::Material#normal_scale=} + * {Sketchup::Material#normal_style} + * {Sketchup::Material#normal_style=} + * {Sketchup::Material#normal_texture} + * {Sketchup::Material#normal_texture=} + * {Sketchup::Material#roughness_enabled=} + * {Sketchup::Material#roughness_enabled?} + * {Sketchup::Material#roughness_factor} + * {Sketchup::Material#roughness_factor=} + * {Sketchup::Material#roughness_texture} + * {Sketchup::Material#roughness_texture=} + * {Sketchup::Material#workflow} +* Added {Sketchup::Pages#reorder}. +* Added {Sketchup::Style#path}. +* Added {Sketchup::Face#coplanar_with?}. +* Added {Sketchup::AttributeDictionary#empty?}. +* Added {Sketchup::ComponentDefinition#load_time}. +* Added support for environment lighting (IBL): + * {Sketchup::Environment} + * {Sketchup::Environments} + * {Sketchup::EnvironmentsObserver} + * {Sketchup::Model#environments} + * {Sketchup::Page#use_environment?} + * {Sketchup::Page#use_environment=} + * {Sketchup::Page#environment} + * {Sketchup::Page#environment=} +* Added `:pixel_size` and `:point_size` options to {Sketchup::View#draw_text} + and {Sketchup::View#text_bounds} for consistent font size across platforms. +* Added constants for the valid values for {Sketchup::View#corner}: + * {Sketchup::View::CORNER_TOP_LEFT} + * {Sketchup::View::CORNER_TOP_RIGHT} + * {Sketchup::View::CORNER_BOTTOM_LEFT} + * {Sketchup::View::CORNER_BOTTOM_RIGHT} +* Upgraded CEF (used by {UI::HtmlDialog}) to version 128. +* Fixed issue of {Sketchup::Styles#selected_style=} for case where trying to set the the {Sketchup::Styles#selected_style=} to the {Sketchup::Styles#active_style}. + +### Breaking Changes - Per Monitor DPI support + +SketchUp 2025.0 introduced support for different DPI per monitor on Windows. + +Related to this we have made changes to the Ruby API such that all screen +coordinates are now in logical pixels. These changes are applied across Windows +and macOS. Note that in this release only the Windows build will update the application +DPI scaling factor to match the monitor the window is on. + +`Integer` arguments and return values for screen coordinates that are in pixels +have been changed to be logical pixels. This means that the values are now scaled +by `UI.scale_factor(view)`. + +The old `UI.scale_factor` will return `1.0` as a compatibility shim. + +These changes should require no or minimal changes to extensions. We also +expect that many extensions that were never made DPI aware to now behave better +with different DPI settings. + +* Added {Sketchup::View#device_width} returning physical pixels. +* Added {Sketchup::View#device_height} returning physical pixels. +* Added {Sketchup::ViewObserver#onScaleFactorChange} +* Added optional option to {Sketchup.resize_viewport}: + `Sketchup.resize_viewport(model, width, height, logical_pixels: false)` +* Added overload to {UI.scale_factor}: `UI::scale_factor(view)` +* Changed {UI.scale_factor} always return `1.0` as a compatibility shim. This + should ensure that existing extensions that took `UI.scale_factor` into account + continue to work without modifications. +* Changed {Sketchup::View#center} to return logical pixels. +* Changed {Sketchup::View#corner} to return logical pixels. +* Changed {Sketchup::View#draw2d} to use logical pixels. +* Changed {Sketchup::View#inputpoint} to use logical pixels. +* Changed {Sketchup::View#pick_helper} to use logical pixels. +* Changed {Sketchup::View#pickray} to use logical pixels. +* Changed {Sketchup::View#screen_coords} to return logical pixels. +* Changed {Sketchup::View#vpwidth} to return logical pixels. +* Changed {Sketchup::View#vpheight} to return logical pixels. +* Changed {Sketchup::PickHelper#do_pick} to use logical pixels. +* Changed {Sketchup::PickHelper#init} to use logical pixels. +* Changed {Sketchup::PickHelper#window_pick} to use logical pixels. +* Changed {Sketchup::InputPoint#pick} to use logical pixels. +* Changed {Sketchup::Tool} mouse events to use logical pixels. +* Changed {Sketchup::Overlay} mouse events to use logical pixels. + +## Ruby API Bug Fixes + +* Fixed SketchUp 2024 regression in {Sketchup::View#draw2d} with {GL_POINTS} that draw the points in model space instead of view space. +* Fixed SketchUp 2023-2024 regression in {Sketchup::Face#area} reporting incorrect value when there are glued components on the outer loop. + +# What's new in SketchUp 2024.0.2 + +## Update OpenSSL to 3.2.2 + +The version of OpenSSL in Ruby was updated to 3.2.2. + +# What's new in SketchUp 2024.0.1 + +No Ruby API changes. + # What's new in SketchUp 2024.0 +## Upgrade Ruby to 3.2.2 + ## Ruby API Additions and Improvements * Added support for export option `:page_range` for {Layout::Document#export}. @@ -85,9 +308,9 @@ Here are the build numbers for recent SketchUp releases. Note that build numbers * `"AmbientOcclusionDistance"` * `"AmbientOcclusionIntensity"` * {Sketchup::RenderingOptionsObserver} constants: - * `ROPSetAOEnabled` - * `ROPSetAODistance` - * `ROPSetAOIntensity` + * {Sketchup::RenderingOptions::ROPSetAOEnabled} + * {Sketchup::RenderingOptions::ROPSetAODistance} + * {Sketchup::RenderingOptions::ROPSetAOIntensity} * {Sketchup::RenderingOptions#[]=} will now raise an `ArgumentError` if the given value cannot be set for the given key. This is a breaking change since earlier versions of the API would not indicate any failures for such erroneous calls. @@ -174,6 +397,7 @@ The version of OpenSSL in Ruby was updated to 1.1.1o. ## Ruby API Bug Fixes * In SketchUp 2022.0 a bug might lead to an available component definition name being incorrectly renamed. Or a name that should be unavailable would be duplicated. This was fixed in SketchUp 2022.0.1. +* Fixed a bug where {Sketchup::Tool#onKeyDown} and {Sketchup::Tool#onKeyUp} events were being incorrectly sent to a Ruby tool when the input focus was inside an {UI.inputbox}. # What's new in SketchUp 2022.0 @@ -465,6 +689,8 @@ For more details refer to the C API documentation. * Updated Ruby from 2.5.1 to 2.5.5 to address a logic bug in Ruby * Fixed possible crash in {Sketchup::Entities#clear!} * Fixed a bug in .skm serialisation where arrays in material attributes were not written out to file +* It is no longer possible to assign {Sketchup::Image} materials to entities. +* {Sketchup::ViewObserver#onViewChanged} now triggers when the viewport changes size. # What's new in SketchUp 2019.1 @@ -629,6 +855,20 @@ SketchUp core added a feature called Advanced Attributes. This adds some new att * Fixed a crash in {UI.create_cursor} that would happen if the length was less than 4 characters. * Fixed a rare crash in {Sketchup::MaterialsObserver}. +# What's new in SketchUp 2017 M2 + +### Fixes/Improvements General + +* (Mac) Fixed issue where SKM files lost attribute dictionaries when saved from + "In Model" to local library. + +### Ruby API + +* Fixed an issue with HtmlDialogs where SketchUp would crash when the + dialog was closed before all callbacks were processed. +* Fixed an issue where extensions with multiple periods in filenames would + not load. + # What's new in SketchUp 2017 M0 ## Ruby 2.2 @@ -706,11 +946,59 @@ Visual Studio 2015 SP1 (targeting Windows 7). On MacOs we are using XCode 7.2.1 * {UI.show_model_info} no longer opens a Model Info page for `"Extensions"` as that page is now replaced by the Extension Manager dialog. +# What's new in SketchUp 2016 M1 + +## API Additions + +### New Module For Access To Regional Settings +* Added {Sketchup::RegionalSettings} module + * Added {Sketchup::RegionalSettings.decimal_separator} method + * Added {Sketchup::RegionalSettings.list_separator} method + +## Bug Fixes + +### Extensions +* Fixed issue where the {Sketchup.register_extension} method's `load_on_start` parameter was not being honored on extensions that were manually placed within the Plugins folder. +* Fixed issue where extensions installed in the `"Plugins"` directory were not respecting the extension's `load_on_start` property. +* Fixed issue where extensions fail to load / gave errors on launch if you have certain non-English characters in your Ruby path (which can occur if your Windows user name has certain non-English characters). If you’re still seeing an error with the **Trimble Connect** extension, please {https://help.sketchup.com/en/extension-warehouse/managing-extensions update that extension} in the Extension Warehouse. +* Fixed issue where the **Trimble Connect** Extension fails to load due to an invalid byte sequence error. Users will need to update to SketchUp 2016 M1 and update the Trimble Connect Extension to version 1.1.1 (via the **Extension Warehouse**) to see this change. +* (Win) Fixed issue where the unchecking an extension within the **Extensions** panel of the **Preferences** dialog caused the list to scroll back to the top of the list. +* Fixed issue where unchecking an extension within the **Extensions** panel of the **Preferences** dialog did not change the appearance of the checkbox. +* Fixed issue where the **Extensions Policy** panel of the **Preferences** dialog incorrectly stated a user was under the "Identified Extensions Only" policy. +* Updated dialog content for extensions that were installed but not loaded. The dialog now clearly states that the user must load the extension in order to use it. +* Fixed issue where an extra dialog appeared on startup when loading an uncertified extension that was previously certified. +* (Mac) Fixed issue where the "Uncertified Extension detected" dialog did not appear when installing an extension through the **Extensions** panel of the **Preferences** dialog. +* Prevent the unsigned extension dialog from appearing unless the number of unsigned and loaded extensions has changed. + +### Exporters +* (Mac) Fixed issue where exporter progress dialog had the incorrect title of "Import progress". + +### Importers +* (Mac) Fixed issue where custom image importers were not being honored. + +### LanguageHandler +* Fixed issue where the {LanguageHandler} class treated all double slashes (`//`) as comments. + +### Ruby +* (Win) Fixed issue where third party DLLs in Windows system folders could override the Ruby standard library DLLs. +* Fixed issue where {Sketchup.require}/{Sketchup.load load} fails to indicate a load failure. +* For {Sketchup.require}/{Sketchup.load load}, modified the Ruby file loading priority to be **`.rbe`**, **`.rbs`** then **`.rb`**. + +### Startup Cycle +* On startup, modified load policy for these files from the SketchUp binary path `"Tools"` subdirectory: **`extensions.rb`**, **`langhandler.rb`** and **`sketchup.rb`** + - The the above 3 files in this directory are now digitally signed. + - **Only these 3 files** will be loaded by SketchUp during the startup cycle. + - On startup, users will be prompted if any of the above 3 files have been modified since being digitally signed. + +### UI +* (Win) {UI.preferences_pages} will now include `"Extensions Policy"` +* (Win) {UI.show_preferences UI.show_preferences("Extensions Policy")} will now open the correct property page. + # What's new in SketchUp 2016 M0 ## A new LayOut API -We’re proud to announce our first step towards an extension ecosystem for LayOut. Using this new API developers can now open, create, modify, save, and export .layout files. Practically, this means that other applications can import or export the .layout file format using the C API. (This includes creating a .layout file from SketchUp). We have several sample scripts for developers to try out at release. Check out the API documentation in the [Developer Center](http://extensions.sketchup.com/developer_center/layout_c_api/layout/index.html) for more information. +We’re proud to announce our first step towards an extension ecosystem for LayOut. Using this new API developers can now open, create, modify, save, and export .layout files. Practically, this means that other applications can import or export the .layout file format using the C API. (This includes creating a .layout file from SketchUp). We have several sample scripts for developers to try out at release. Check out the API documentation in the [Developer Center](https://extensions.sketchup.com/developers/layout_c_api/layout/index.html) for more information. ## Digitally Signing Extensions - Extensions Loading Policy @@ -722,17 +1010,17 @@ SketchUp 2016 M0 installs in "Unrestricted" mode by default. To digitally sign your extension, simply upload your .rbz package to our new Digital Signature and Encryption page and we will sign it and return it to you. Visit the new [Extension Digital Signature page](https://extensions.sketchup.com/en/developer_center/extension_signature). -You will need to sign your extension each time you make code changes and want to re-release it. You will need to be a registered Developer on the Extension Warehouse to be able to sign or encrypt extensions. [Apply here!](http://http://extensions.sketchup.com/en/developer) +You will need to sign your extension each time you make code changes and want to re-release it. You will need to be a registered Developer on the Extension Warehouse to be able to sign or encrypt extensions. [Apply here!](https://extensions.sketchup.com/application) ## Ruby Encryption 2.0 -Goodbye .rbs and Hello .rbe! We have added a new encryption that you can use to help protect your extension Intellectual Property (IP). SketchUp 2016 can read both .rbe and .rbs filetypes. This should help make sure that we maintain backwards compatibility for authors who need some time to re-encrypt their extensions. To use our new encryption, simply upload an unencrypted version of your .rbz package to our new Digital Signature and Encryption page and we will encrypt it and return it to you. Visit the new [Extension Digital Signature page](https://extensions.sketchup.com/en/developer_center/extension_signature) page here for more information. +Goodbye .rbs and Hello .rbe! We have added a new encryption that you can use to help protect your extension Intellectual Property (IP). SketchUp 2016 can read both .rbe and .rbs filetypes. This should help make sure that we maintain backwards compatibility for authors who need some time to re-encrypt their extensions. To use our new encryption, simply upload an unencrypted version of your .rbz package to our new Digital Signature and Encryption page and we will encrypt it and return it to you. Visit the new [Extension Digital Signature page](https://extensions.sketchup.com/extension/sign) page here for more information. You will need to be a registered Developer on the Extension Warehouse to be able to sign or encrypt extensions. [Apply here!](http://extensions.sketchup.com/en/developer) ## Developer Center -Between the new Extension Digital Signature Page, the new LayOut C API and a whole lot of future ideas and potential, we have decided to create a new central location to organize our developer resources, API documentation, etc. Visit (and bookmark!): [https://extensions.sketchup.com/en/developer_center](https://extensions.sketchup.com/en/developer_center) +Between the new Extension Digital Signature Page, the new LayOut C API and a whole lot of future ideas and potential, we have decided to create a new central location to organize our developer resources, API documentation, etc. Visit (and bookmark!): [https://extensions.sketchup.com/en/developer_center](https://developer.sketchup.com/) ## Observer Upgrades diff --git a/pages/TOS.md b/pages/TOS.md index ff503e7..e431318 100644 --- a/pages/TOS.md +++ b/pages/TOS.md @@ -2,7 +2,4 @@ # SketchUp Ruby API Terms of Service -The SketchUp Ruby API is now owned by -[Trimble Navigation Limited](http://www.trimble.com/) and subjected to their -Terms of Service. Please see their -[Terms of Service here](http://www.sketchup.com/intl/en/developer/api-terms-of-service.pdf). \ No newline at end of file +The SketchUp Ruby API is owned by [Trimble Inc](https://www.trimble.com/) and subject to these [Terms of Service](https://www.trimble.com/legal/developer-terms). \ No newline at end of file diff --git a/pages/exporter_options.md b/pages/exporter_options.md index 70dadc4..c37c053 100644 --- a/pages/exporter_options.md +++ b/pages/exporter_options.md @@ -6,9 +6,6 @@ The SketchUp Ruby API has different exporter plugins that are shipped with the product. Below is a list of the **valid** options that each exporter will accept. If an **invalid** option is provided, it will be silently ignored. -## All Exporters -- `:show_summary` - Boolean to indicate whether to show the summary dialog. - ## 3ds Max (3DS) - `:units` - Specifies the export units. - values: `"model"`, `"inch"`, `"foot"`, `"yard"`, `"mile"`, `"mm"`, `"cm"`, `"m"`, or `"km"` @@ -22,6 +19,18 @@ If an **invalid** option is provided, it will be silently ignored. - `:preserve_texture_coords` - Boolean to indicate whether texture coordinates are to be preserved. - `:cameras` - Boolean to indicate whether to export cameras from Scenes. - `:selectionset_only` - Boolean to indicate whether to export the selected entities. +- `:show_summary` - Boolean to indicate whether to show the summary dialog. + +## 3D Autocad (DWG/DXF) +- `:acad_version` - Specifies the autocad_version to export. + - values: `"acad_12"`, `"acad_13"`, `"acad_14"`, `"acad_2000"`, `"acad_2004"`, `"acad_2007"`, `"acad_2010"`, `"acad_2013"` +- `:faces_flag` - Boolean to indicate whether to export faces. +- `:construction_geometry` - Boolean to indicate whether to export construction geometry. +- `:dimensions` - Boolean to indicate whether to export dimensions. +- `:text` - Boolean to indicate whether to export text objects. +- `:edges` - Boolean to indicate whether to export edges. +- `:materials` - Boolean to indicate whether to export materials. Added in SketchUp 2019.0. +- `:show_summary` - Boolean to indicate whether to show the summary dialog. ## Collada (DAE) - `:triangulated_faces` - Boolean to indicate whether to export triangulated faces. @@ -34,66 +43,48 @@ If an **invalid** option is provided, it will be silently ignored. - `:selectionset_only` - Boolean to indicate whether to export the selected entities. - `:camera_lookat` - Boolean to indicate whether to export the camera looking at the target. -## 3D Autocad (DWG/DXF) -- `:acad_version` - Specifies the autocad_version to export. - - values: `"acad_12"`, `"acad_13"`, `"acad_14"`, `"acad_2000"`, `"acad_2004"`, `"acad_2007"`, `"acad_2010"`, `"acad_2013"` -- `:faces_flag` - Boolean to indcate whether to export faces. -- `:construction_geometry` - Boolean to indicate whether to export construction geometry. -- `:dimensions` - Boolean to indicate whether to export dimensions. -- `:text` - Boolean to indicate whether to export text objects. -- `:edges` - Boolean to indicate whether to export edges. - ## Filmbox Autodesk (FBX) - `:units` - Specifies the export units. - values: `"model"`, `"inch"`, `"foot"`, `"yard"`, `"mile"`, `"mm"`, `"cm"`, `"m"` or `"km"` - `:triangulated_faces` - Boolean to indicate whether to export triangulated faces. - `:doublesided_faces` - Boolean to indicated whether to export 2-sided faces. - `:texture_maps` - Boolean to indicate whether to export texture maps. -- `:seperate_disconnected_faces` - Boolean to indicate whether to export separate disconnected faces. +- `:separate_disconnected_faces` - Boolean to indicate whether to export separate disconnected faces. - `:swap_yz` - Boolean to indicate whether to swap Y and Z coordinates (Y is up). - `:selectionset_only` - Boolean to indicate whether to export the selected entities. - -## Industry Foundation Classes (IFC) -- `:hidden_geometry` - Boolean to indicate whether to export hidden geometry. -- `:doublesided_faces` - Boolean to indicate whether to export 2-sided faces. -- `:ifc_mapped_items` - Boolean to indicate whether to export IFC mapped items. -- `:ifc_types` - An Array of strings indicating IFC elements to export. One or more of the following values can be in the array. If there are no values in the array, no geometry will be exported. - - values: `"IfcNonDefined"`, `"IfcBeam"`, `"IfcBuilding"`, `"IfcBuildingElementProxy"`, `"IfcBuildingStorey"`, `"IfcColumn"`, `"IfcCurtainWall"`, `"IfcDoor"`, `"IfcFooting"`, `"IfcFurnishingElement"`, `"IfcMember"`, `"IfcPile"`, `"IfcPlate"`, `"IfcProject"`, `"IfcRailing"`, `"IfcRamp"`, `"IfcRampFlight"`, `"IfcRoof"`, `"IfcSite"`, `"IfcSlab"`, `"IfcSpace"`, `"IfcStair"`, `"IfcStairFlight"`, `"IfcWall"`, `"IfcWallStandardCase"`, `"IfcWindow"` +- `:show_summary` - Boolean to indicate whether to show the summary dialog. ## Google Earth (KMZ) - `:author_attribution` - Boolean to indicate whether to export model credits. - `:hidden_geometry` - Boolean to indicate whether to export hidden geometry -## OBJ -- `:units` - Specifies the export units. - - values: `"model"`, `"inch"`, `"foot"`, `"yard"`, `"mile"`, `"mm"`, `"cm"`, `"m"`, or `"km"` -- `:triangulated_faces` - Boolean to indicate whether to export triangulated faces. -- `:doublesided_faces` - Boolean to indicate whether to export 2-sided faces. -- `:edges` - Boolean to indicate whether to export edges. -- `:texture_maps` - Boolean to indicate whether to export texture maps. -- `:swap_yz` - Boolean to indicate whether to swap Y and Z coordinates (Y is up). -- `:selectionset_only` - Boolean to indicate whether to export the selected entities. +## Graphics Library Transmission Format Binary File (GLB) +- No options supported -## Softimage XSI 3D Image (XSI) -- `:units` - Specifies the export units. - - values: `"model"`, `"inch"`, `"foot"`, `"yard"`, `"mile"`, `"mm"`, `"cm"`, `"m"`, or `"km"` -- `:triangulated_faces` - Boolean to indicate whether to export triangulated faces. -- `:doublesided_faces` - Boolean to indicate whether to export 2-sided faces. -- `:edges` - Boolean to indicate whether to export edges. -- `:texture_maps` - Boolean to indicate whether to export texture maps. -- `:swap_yz` - Boolean to indicate whether to swap Y and Z coordinates (Y is up). -- `:selectionset_only` - Boolean to indicate whether to export the selected entities. +## Industry Foundation Classes (IFC) +### Options for SketchUp 2026+ +- `:ifc_version` - Specifies the IFC version to export. + - values: `"IFC 2x3"`, `"IFC 4"` +- `:standard_ifc_hierarchy` - Boolean to indicate whether to generate a standard IFC spatial hierarchy. +- `:selectionset_only` - Boolean to indicate whether to export only the selected entities. +- `:hidden_geometry` - Boolean to indicate whether to export hidden geometry. +- `:tessellated_geometry` - Boolean to indicate whether to use tessellation for geometry representation. It is only applicable to IFC 4. +- `:show_summary` - Boolean to indicate whether to show the summary dialog. -## Virtual Reality Modeling Language (WRL) +### Options for older SketchUp versions +- `:hidden_geometry` - Boolean to indicate whether to export hidden geometry. - `:doublesided_faces` - Boolean to indicate whether to export 2-sided faces. -- `:cameras` - Boolean to indicate whether to export cameras. -- `:use_vrml_orientation` - Boolean to indicate whether to use VRML standard orientation. -- `:edges` - Boolean to indicate whether to export edges. -- `:texture_maps` - Boolean to indicate whether to export texture maps. -- `:allow_mirrored_components` - Boolean to indicate whether to allow mirrored components. -- `:material_override` - Boolean to indicate whether to check for material overrides. +- `:ifc_mapped_items` - Boolean to indicate whether to export IFC mapped items. +- `:ifc_types` - An Array of strings indicating IFC elements to export. One or more of the following values can be in the array. If there are no values in the array, no geometry will be exported. + - values: `"IfcNonDefined"`, `"IfcBeam"`, `"IfcBuilding"`, `"IfcBuildingElementProxy"`, `"IfcBuildingStorey"`, `"IfcColumn"`, `"IfcCurtainWall"`, `"IfcDoor"`, `"IfcFooting"`, `"IfcFurnishingElement"`, `"IfcMember"`, `"IfcPile"`, `"IfcPlate"`, `"IfcProject"`, `"IfcRailing"`, `"IfcRamp"`, `"IfcRampFlight"`, `"IfcRoof"`, `"IfcSite"`, `"IfcSlab"`, `"IfcSpace"`, `"IfcStair"`, `"IfcStairFlight"`, `"IfcWall"`, `"IfcWallStandardCase"`, `"IfcWindow"` +- `:show_summary` - Boolean to indicate whether to show the summary dialog. + +## Portable Document Format (PDF) - Mac +- `:line_weight` (default = `0.5`) +- `:image_width` (default = `50.0`) +- `:image_height` (default = `50.0`) -## PDF (Windows) +## Portable Document Format (PDF) - Windows - `:output_profile_lines` (default = `true`) - `:output_section_lines` (default = `true`) - `:edge_extensions` (default = `true`) @@ -114,15 +105,45 @@ If an **invalid** option is provided, it will be silently ignored. - `:length_in_model` (default = `1.0`) - `:window_height` (default = `1.0`) -## PDF (Mac) -- `:line_weight` (default = `0.5`) -- `:imageWidth` (default = `50`) -- `:imageHeight` (default = `50`) - ## STereoLithography (STL) - `:units` - Specifies the export units. - values: `"model"`, `"inch"`, `"feet"`, `"mm"`, `"cm"`, `"m"` - `:format` - Specifies how the data is represented in the file. - values: `"ascii"`, `"binary"` - `:selectionset_only` - Boolean to indicate whether to export the selected entities. -- `:swap_yz` - Boolean to indicate whether to swap Y and Z coordinates (Y is up). \ No newline at end of file +- `:swap_yz` - Boolean to indicate whether to swap Y and Z coordinates (Y is up). +- `:show_summary` - Boolean to indicate whether to show the summary dialog. + +## Softimage XSI 3D Image (XSI) +- `:units` - Specifies the export units. + - values: `"model"`, `"inch"`, `"foot"`, `"yard"`, `"mile"`, `"mm"`, `"cm"`, `"m"`, or `"km"` +- `:triangulated_faces` - Boolean to indicate whether to export triangulated faces. +- `:doublesided_faces` - Boolean to indicate whether to export 2-sided faces. +- `:edges` - Boolean to indicate whether to export edges. +- `:texture_maps` - Boolean to indicate whether to export texture maps. +- `:swap_yz` - Boolean to indicate whether to swap Y and Z coordinates (Y is up). +- `:selectionset_only` - Boolean to indicate whether to export the selected entities. + +## Universal Scene Description (USDZ) +- No options supported + +## Virtual Reality Modeling Language (WRL) +- `:doublesided_faces` - Boolean to indicate whether to export 2-sided faces. +- `:cameras` - Boolean to indicate whether to export cameras. +- `:use_vrml_orientation` - Boolean to indicate whether to use VRML standard orientation. +- `:edges` - Boolean to indicate whether to export edges. +- `:texture_maps` - Boolean to indicate whether to export texture maps. +- `:allow_mirrored_components` - Boolean to indicate whether to allow mirrored components. +- `:material_override` - Boolean to indicate whether to check for material overrides. +- `:show_summary` - Boolean to indicate whether to show the summary dialog. + +## Wavefront Object (OBJ) +- `:units` - Specifies the export units. + - values: `"model"`, `"inch"`, `"foot"`, `"yard"`, `"mile"`, `"mm"`, `"cm"`, `"m"`, or `"km"` +- `:triangulated_faces` - Boolean to indicate whether to export triangulated faces. +- `:doublesided_faces` - Boolean to indicate whether to export 2-sided faces. +- `:edges` - Boolean to indicate whether to export edges. +- `:texture_maps` - Boolean to indicate whether to export texture maps. +- `:swap_yz` - Boolean to indicate whether to swap Y and Z coordinates (Y is up). +- `:selectionset_only` - Boolean to indicate whether to export the selected entities. +- `:show_summary` - Boolean to indicate whether to show the summary dialog. \ No newline at end of file diff --git a/pages/extension_requirements.md b/pages/extension_requirements.md index 81317d4..bb0f020 100644 --- a/pages/extension_requirements.md +++ b/pages/extension_requirements.md @@ -2,15 +2,25 @@ # Extension Requirements -SketchUp extensions are distributed as RBZ files. These are the specifications for creating a valid RBZ file that can be used by SketchUp or shared on the Extension Warehouse. +These are the requirements for publishing an extension to Extension Warehouse, but we recommend you follow these wherever you may publish your extension. Ignoring these requirements comes with the risk of your extension malfunctioning or causing other extensions to malfunction. ## The Basics ### File Structure -An RBZ file is a normal ZIP archive with the .rbz file extension. To create one, you can use the ZIP archive tool of your choice, including right clicking the target files and sending them to a ZIP archive, and then rename the file. You may need to change a system setting to display the file extension to be able to change it. +SketchUp extensions are distributed as RBZ files. An RBZ file is a normal ZIP archive with the .rbz file extension. To create one, you can use the ZIP archive tool of your choice, including right clicking the target files and sending them to a ZIP archive, and then rename the file. You may need to change a system setting to display the file extension to be able to change it. -The RBZ archive must contain exactly two items, a root RB file and a support folder by the same name (excluding the .rb extension). The root RB file contains the extension metadata. The support folder contains the main code. +The RBZ archive must contain exactly two items, a root RB file and a support folder by the same name (excluding the .rb extension). The root RB file contains the extension metadata, such as name and author. The support folder contains the rest of the extension. + +*File Structure* + +``` +nn_cuber_maker.rbz +├── nn_cuber_maker.rb (root RB file) +└── nn_cuber_maker (support folder containing everything else) + ├── main.rb + └── some_other_support_file.rb +``` *Root RB file* @@ -19,11 +29,11 @@ The RBZ archive must contain exactly two items, a root RB file and a support fol module NameyNamesson module CubeMaker - EXTENSION = SketchupExtension.new("NN Cube Maker", "nn_cube_maker/main.rb") + EXTENSION = SketchupExtension.new("NN Cube Maker", "nn_cube_maker/main") EXTENSION.creator = "Namey Namesson" EXTENSION.description = "Make cubes in just a few clicks." EXTENSION.version = "1.0.0" - EXTENSION.copyright = "2023 Name Namesson" + EXTENSION.copyright = "2025 Name Namesson" Sketchup.register_extension(EXTENSION, true) end end @@ -55,6 +65,33 @@ module NameyNamesson end ``` +### Requiring Files + +When requiring Ruby files within your extension, prefer the `Sketchup.require` method over Ruby's own `require` or `require_relative`. +By default Extension Warehouse encrypts extensions, convering `.rb` files into `.rbe` files. +By omitting the file extension, `Sketchup.require` will look for both `.rb`, `.rbe` and `.rbs` files. + +Hardcoding the `.rb` extension while also encrypting the extension leads to a load error. + +```ruby +# Bad +require "nn_cube_maker/some_other_file.rb" +require_relative "some_other_file.rb" + +# Good +Sketchup.require "nn_cube_maker/some_other_file" +``` + +The same applies to the path when creating the extension object. + +```ruby +# Bad +SketchupExtension.new("NN Cube Maker", "nn_cube_maker/main.rb") + +# Good +SketchupExtension.new("NN Cube Maker", "nn_cube_maker/main") +``` + ### Undo Stack When your extension makes several low level draw calls, join them together as one entry to the undo stack using the `start_operation` and `commit_operation` methods. If the user activates it as a single high level action, let them also undo it in a single step. @@ -77,16 +114,43 @@ def draw_cube end ``` +## Functioning as Advertised + +Extensioins will be rejected from Extension Warehouse if they malfunction or cannot be used. + ### Global Variables Since SketchUp extensions run in a shared environment, global variables risk clashing between extensions and are not permitted. Instead use instance variables or class variables. +### Printing to the Console + +Printing to the Ruby console can be useful for debugging. But if everyone does it, the console gets cluttered and you can't easily see what information comes from your extension and what comes from some other extension. + +Remove or disable `puts`, `print` and `p` before publishing your extension. + +```ruby +# Bad +puts "testing testing" + +# Good +# (Not using puts) + +# Also good +DEBUG_MODE = false +puts "testing testing" if DEBUG_MODE +``` + ### Dependency to Another Extension Ideally, avoid your extension depending on another extension. Prefer duplicating any shared logic between your extensions over publishing a "library extension", to make installation easier for end users. If your extension does require another extension to work, make sure to clearly state this in its documentation and also show an error message if the dependency is missing. ## The Nitty Gritty Stuff +### Encryption + +Do not use the SketchUp Extension Signature Portal to encrypt an extension before submitting it to Extension Warehouse. +Extension Warehouse by default applies this encryption after your extension is submitted. + ### Monkey Patching the SketchUp Ruby API Since SketchUp extensions run in a shared environment, changing the modules and classes of the Ruby API from one extension can clash with another extension. Don't change these modules and classes. @@ -113,6 +177,12 @@ These recommendations make it harder but not impossible to crack the extension. This is not a complete list of everything an extension can be denied for. See the below links for more details and use your good judgment when developing. +## RuboCop + +[RuboCop-SetchUp](https://github.com/SketchUp/rubocop-sketchup) is a static code analyser helping you find issues with your code and comform to these requirements. + +RuboCop-SketchUp is used by the Extension Warehouse review team but you can use it yourself before submitting, to find issues earlier and save time. + ## Further Reading [Extension Code Examples](https://github.com/SketchUp/sketchup-ruby-api-tutorials) From c46600d0bd9b868627f1eea489b47d8fef2bf659 Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Thu, 5 Feb 2026 13:18:58 +0100 Subject: [PATCH 2/6] Fix typo in one `@version` tag. --- lib/sketchup-api-stubs/stubs/Sketchup/Model.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb index 2959743..5b7aaf1 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb @@ -235,7 +235,7 @@ def active_path=(instance_path) # # @return [Array] # - # @version Sketchup 2026.0 + # @version SketchUp 2026.0 def active_section_planes end From bd732e0085309cab04a2a3f38c049cdccc433e1d Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Thu, 5 Feb 2026 13:29:25 +0100 Subject: [PATCH 3/6] SketchUp 2026.1. --- lib/sketchup-api-stubs/stubs/Layout/Entity.rb | 5 +++ .../stubs/Sketchup/Model.rb | 4 ++ .../stubs/Sketchup/ShadowInfo.rb | 7 ++++ lib/sketchup-api-stubs/stubs/Sketchup/Text.rb | 2 +- lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb | 7 ++++ lib/sketchup-api-stubs/stubs/Sketchup/View.rb | 5 ++- lib/sketchup-api-stubs/stubs/UI.rb | 21 ++++++++++ lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb | 40 +++++++++++++++++++ pages/ReleaseNotes.md | 32 ++++++++++++--- pages/extension_requirements.md | 6 +-- 10 files changed, 117 insertions(+), 12 deletions(-) diff --git a/lib/sketchup-api-stubs/stubs/Layout/Entity.rb b/lib/sketchup-api-stubs/stubs/Layout/Entity.rb index 2a35b33..48556b2 100644 --- a/lib/sketchup-api-stubs/stubs/Layout/Entity.rb +++ b/lib/sketchup-api-stubs/stubs/Layout/Entity.rb @@ -386,6 +386,9 @@ def style=(style) # transform = Geom::Transformation2d.new([1.0, 0.0, 0.0, 1.0, 1.0, 1.0]) # entity = entities.first.transform!(transform) # + # @note Since LayOut 2026.1, passing a non-invertible transformation raises + # an `ArgumentError`. + # # @param [Geom::Transformation2d] transformation # # @raise [LockedLayerError] if the {Layout::Entity} is on a locked @@ -393,6 +396,8 @@ def style=(style) # # @raise [LockedEntityError] if the {Layout::Entity} is locked # + # @raise [ArgumentError] if the transformation matrix is not invertible + # # @version LayOut 2018 def transform!(transformation) end diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb index 5b7aaf1..7b4f869 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb @@ -978,6 +978,8 @@ def instance_path_from_pid_path(pid_path) # A 2-element array containing first the longitude then # the latitude. # + # @return [Geom::Point3d] A Point3d in model coordinates. + # # @return [Geom::Point3d] a point3d object if successful, false if # unsuccessful. # @@ -1224,6 +1226,8 @@ def place_component(componentdef, repeat = false) # @param [Geom::Point3d] point # A Point3d object. # + # @return [Geom::Point3d] Point3d[longitude_deg, latitude_deg, altitude_m] + # # @return [Geom::Point3d, Geom::LatLong] a LatLong or Point3d object. See # details for information. # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb b/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb index 25f73d1..f23e011 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb @@ -93,6 +93,9 @@ def [](key) # The set value []= method is used to set the value in the array of shadow # info options. # + # For numeric properties like "Dark", "Light", "Latitude", and "Longitude", + # this method is flexible and accepts any +Numeric+ value (+Integer+ or +Float+). + # # @example # model = Sketchup.active_model # shadowinfo = model.shadow_info @@ -104,6 +107,10 @@ def [](key) # @param [Object] value # The value to be set. # + # @raise A KeyError is raised if the key is invalid or read-only. + # + # @raise [TypeError] if the value is not the correct type for the key. + # # @return [Object] the value that was set if successful, or false # if unsuccessful. # diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb index 1f2ba65..74ae4d6 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb @@ -145,7 +145,7 @@ def leader_type # @example # leader = text.leader_type=1 # - # @note {ALeaderModel} cannot be set. It is only used internally as a default value. + # @note {ALeaderNone} cannot be set. It is only used internally as a default value. # Trying to set it will raise a warning. # # @param [Integer] type diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb b/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb index 3897fe2..0cec01c 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb @@ -302,6 +302,10 @@ def onCancel(reason, view) # V6: There is a bug on Windows where the typematic effect does # not work. Typematic effects work fine on a Mac. # + # @bug SketchUp 2026.0 (Windows) introduced a regression in {Sketchup::Tool#onKeyDown} + # where the event didn't trigger when Return/Enter was pressed. This was fixed + # in SketchUp 2026.1. + # # @example # def onKeyDown(key, repeat, flags, view) # puts "onKeyDown: key = #{key}" @@ -835,6 +839,9 @@ def onRButtonUp # to complete an operation in the tool. This method will rarely need to be # implemented. # + # @bug SketchUp 2025.0 (Windows) introduced a regression where the event didn't + # trigger when Return/Enter was pressed. This was fixed in SketchUp 2026.0. + # # @example # def onReturn(view) # puts "onReturn(#{view})" diff --git a/lib/sketchup-api-stubs/stubs/Sketchup/View.rb b/lib/sketchup-api-stubs/stubs/Sketchup/View.rb index bea75c2..c4c8395 100644 --- a/lib/sketchup-api-stubs/stubs/Sketchup/View.rb +++ b/lib/sketchup-api-stubs/stubs/Sketchup/View.rb @@ -1223,13 +1223,14 @@ def remove_observer(observer) # @note Signature for versions prior to SketchUp 2025.0 # @version SketchUp 6.0 # @param [Geom::Point3d] model_point Model coordinate. - # @return [Geom::Point3d] Screen coordinate in physical pixels. # # @overload screen_coords(model_point) # # @version SketchUp 2025.0 # @param [Geom::Point3d] model_point Model coordinate. - # @return [Geom::Point3d] Screen coordinate in logical pixels. + # + # @return [Geom::Point3d] Screen coordinate in pixels (physical prior to SketchUp 2025.0, logical + # from 2025.0). # # @version SketchUp 6.0 def screen_coords(model_point) diff --git a/lib/sketchup-api-stubs/stubs/UI.rb b/lib/sketchup-api-stubs/stubs/UI.rb index 257601a..9e27e39 100644 --- a/lib/sketchup-api-stubs/stubs/UI.rb +++ b/lib/sketchup-api-stubs/stubs/UI.rb @@ -621,6 +621,27 @@ def self.set_toolbar_visible(name, visible) def self.show_extension_manager end + # Show the Extension Warehouse dialog inside SketchUp. If an extension UUID is provided + # the dialog navigates directly to that extension's page. If no UUID is provided it opens + # the Extension Warehouse home page. + # + # @example + # # Open EW home + # UI.show_extension_warehouse + # + # @example + # # Open a specific extension by UUID (taken from the EW URL) + # UI.show_extension_warehouse("a97d22f8-5968-4f43-bcf9-4f322fa7a8cb") + # + # @param [String, nil] extension_id + # Optional Extension Warehouse UUID. If nil or omitted the EW home page is shown. + # + # @return [nil] + # + # @version SketchUp 2026.1 + def self.show_extension_warehouse(extension_id = nil) + end + # The {.show_inspector} method is used to display the inspector with the given # name. You can get the list of valid inspectors with UI.inspector_names. # diff --git a/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb b/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb index b7a6c70..28a2781 100644 --- a/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb +++ b/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb @@ -34,6 +34,28 @@ # [SketchUp 2017.0] # CEF 52 # +# Starting with SketchUp 2026.1, HtmlDialog exposes a small set of built-in callbacks (mirroring +# the legacy +skp:+ protocol used by {UI::WebDialog}). +# +# * +sketchup.launchEW(id)+ – Opens the Extension Warehouse dialog and show a specified +# extension's page. +# * +sketchup.installRBZ(url)+ – Downloads and installs a Ruby extension +# from the given +.rbz+ URL. (User will be prompted just like using the +# Extension Manager.) +# +# @example +# html = <<-HTML +# +# +# HTML +# dlg = UI::HtmlDialog.new(dialog_title: 'EW Example') +# dlg.set_html(html) +# dlg.show +# # @note The window size is not guaranteed to be pixel perfect in all SketchUp # versions and operating systems. Prefer responsive designs that can take # up some fluctuations in size. @@ -224,6 +246,24 @@ def get_position def get_size end + # The {#hide} method is used to hide a dialog box without closing it. + # This preserves the dialog's state and allows it to be shown again later + # without recreating the dialog. + # + # @example + # dialog.hide + # + # @note Modal dialogs cannot be hidden. Attempting to hide a modal dialog + # will raise an ArgumentError. + # + # @raise [ArgumentError] if the dialog is modal + # + # @return [nil] + # + # @version SketchUp 2026.1 + def hide + end + # The new method is used to create a new HtmlDialog. # # In SketchUp 2021.1 +use_content_size+ was added. diff --git a/pages/ReleaseNotes.md b/pages/ReleaseNotes.md index 68ef4d6..c9de2ee 100644 --- a/pages/ReleaseNotes.md +++ b/pages/ReleaseNotes.md @@ -19,7 +19,8 @@ Though our adoption rate to the latest version is quite high, it can take time a Here are the build numbers for recent SketchUp releases. Note that build numbers in languages besides English are larger for each release, so it is best to check for builds that are greater than or equal to the numbers here. -- **SU2026.0** = BUILD_NUMBER_WIN on Windows 64-bit, BUILD_NUMBER_MAC on Mac 64-bit. +- **SU2026.1** = BUILD_NUMBER_WIN on Windows 64-bit, BUILD_NUMBER_MAC on Mac 64-bit. +- **SU2026.0** = 26.0.429 on Windows 64-bit, 26.0.428 on Mac 64-bit. - **SU2025.0.3** = 25.0.660 on Windows 64-bit, 25.0.659 on Mac 64-bit. - **SU2025.0.2** = 25.0.634 on Windows 64-bit, 25.0.633 on Mac 64-bit. @@ -83,16 +84,35 @@ Here are the build numbers for recent SketchUp releases. Note that build numbers - **SU6 M6** = 6.4.265 on Windows, 6.4.263 on Mac. +# What's new in SketchUp 2026.1 + +## Breaking changes + +## Ruby API Additions and Improvements + +* Added {UI.show_extension_warehouse} which opens the Extension Warehouse home when called without arguments, or navigates directly to a specific extension when given its extension identifier (UUID). +* Modified {Sketchup::ShadowInfo#[]=} to be stricter and provide better error feedback. It will now raise a `KeyError` for invalid or read-only keys, and a `TypeError` for values of an incorrect type. +* Added built-in JavaScript callbacks `sketchup.launchEW(id)` and `sketchup.installRBZ(url)` for HtmlDialog. `launchEW` with a UUID string opens that extension's page. `installRBZ` downloads and installs the `.rbz` at the given URL. +* Added {UI::HtmlDialog#hide} to hide dialogs without closing them, preserving their state. + +## Ruby API Bug Fixes + +* Fixed a regression in {Sketchup::Tool#onKeyDown} introduced in SketchUp 2026.0 (Windows) where the event didn't trigger when Return/Enter was pressed. +* Fixed silent failures when passing non-invertible transformations (e.g. zero-scale transforms). The following methods now correctly raise an `ArgumentError`: + * {Sketchup::ComponentInstance#transform!} + * {Sketchup::Group#transform!} + * {Sketchup::Image#transform!} + * {Sketchup::Image#transformation=} + * {Sketchup::Entities#transform_entities} + * {Sketchup::Entities#add_instance} +* Fixed {Layout::Entity#transform!} to raise an `ArgumentError` when given a non-invertible {Geom::Transformation2d}. # What's new in SketchUp 2026.0 ## Breaking changes * Modifying the properties {Sketchup::Axes}, {Sketchup::Camera}, {Sketchup::RenderingOptions}, and {Sketchup::ShadowInfo} of a {Sketchup::Page} is now an undoable operation. Scene changes are expected to be called between {Sketchup::Model#start_operation} and {Sketchup::Model#commit_operation} to not flood the undo stack. Extensions that don't follow this requirement will be rejected for updates or publication to the Extension Warehouse. -* Additional error checking is performed regarding non-invertible transforms (typically this means the matrix has zero scale on - one or more axes). Calling {Geom::Transformation#inverse} or - {Geom::Transformation#invert!} with a non-invertible transform will raise an `ArgumentError`. In addition, calling {Sketchup::ComponentInstance#transformation=}, - {Sketchup::ComponentInstance#move!}, {Sketchup::Group#transformation=}, or {Sketchup::Group#move!} with a non-invertible transform as an argument will also raise an `ArgumentError`. +* Additional error checking is performed regarding non-invertible transforms (typically this means the matrix has zero scale on one or more axes). Calling {Geom::Transformation#inverse} or {Geom::Transformation#invert!} with a non-invertible transform will raise an `ArgumentError`. In addition, calling {Sketchup::ComponentInstance#transformation=}, or {Sketchup::Group#transformation=} with a non-invertible transform as an argument will also raise an `ArgumentError`. ## Ruby API Additions and Improvements @@ -233,7 +253,7 @@ The version of OpenSSL in Ruby was updated to 3.3.1. * {Sketchup::View::CORNER_BOTTOM_LEFT} * {Sketchup::View::CORNER_BOTTOM_RIGHT} * Upgraded CEF (used by {UI::HtmlDialog}) to version 128. -* Fixed issue of {Sketchup::Styles#selected_style=} for case where trying to set the the {Sketchup::Styles#selected_style=} to the {Sketchup::Styles#active_style}. +* Fixed issue of {Sketchup::Styles#selected_style=} for case where trying to set the the {Sketchup::Styles#selected_style=} to the {Sketchup::Styles#active_style}. ### Breaking Changes - Per Monitor DPI support diff --git a/pages/extension_requirements.md b/pages/extension_requirements.md index bb0f020..57b8242 100644 --- a/pages/extension_requirements.md +++ b/pages/extension_requirements.md @@ -68,7 +68,7 @@ end ### Requiring Files When requiring Ruby files within your extension, prefer the `Sketchup.require` method over Ruby's own `require` or `require_relative`. -By default Extension Warehouse encrypts extensions, convering `.rb` files into `.rbe` files. +By default Extension Warehouse encrypts extensions, converting `.rb` files into `.rbe` files. By omitting the file extension, `Sketchup.require` will look for both `.rb`, `.rbe` and `.rbs` files. Hardcoding the `.rb` extension while also encrypting the extension leads to a load error. @@ -116,7 +116,7 @@ end ## Functioning as Advertised -Extensioins will be rejected from Extension Warehouse if they malfunction or cannot be used. +Extensions will be rejected from Extension Warehouse if they malfunction or cannot be used. ### Global Variables @@ -179,7 +179,7 @@ This is not a complete list of everything an extension can be denied for. See th ## RuboCop -[RuboCop-SetchUp](https://github.com/SketchUp/rubocop-sketchup) is a static code analyser helping you find issues with your code and comform to these requirements. +[RuboCop-SketchUp](https://github.com/SketchUp/rubocop-sketchup) is a static code analyser helping you find issues with your code and conform to these requirements. RuboCop-SketchUp is used by the Extension Warehouse review team but you can use it yourself before submitting, to find issues earlier and save time. From ed11fc349df3104bf27a7a1b65818ceb5e3b0a8a Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Thu, 5 Feb 2026 13:31:27 +0100 Subject: [PATCH 4/6] Update github action. --- .github/workflows/rake.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/rake.yaml b/.github/workflows/rake.yaml index 7e7ce44..c73ae14 100644 --- a/.github/workflows/rake.yaml +++ b/.github/workflows/rake.yaml @@ -27,8 +27,8 @@ jobs: strategy: fail-fast: false matrix: - os: [ macos-12, windows-2022 ] - ruby: [ 2.7 ] + os: [ macos-latest, windows-latest ] + ruby: [ 3.2 ] steps: - name: Checkout source @@ -45,4 +45,4 @@ jobs: - name: Run rake timeout-minutes: 10 - run: bundle exec rake \ No newline at end of file + run: bundle exec rake From 42548f7ca438733436ead8aaccab7e669ca509ad Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Thu, 5 Feb 2026 13:42:41 +0100 Subject: [PATCH 5/6] Remove Bundler dev dependency. --- sketchup-api-stubs.gemspec | 1 - 1 file changed, 1 deletion(-) diff --git a/sketchup-api-stubs.gemspec b/sketchup-api-stubs.gemspec index b287d56..629a2a1 100644 --- a/sketchup-api-stubs.gemspec +++ b/sketchup-api-stubs.gemspec @@ -21,5 +21,4 @@ Gem::Specification.new do |spec| ]) # spec.require_paths = ['Sketchup'] - spec.add_development_dependency 'bundler', '>= 1.15.0', '< 3.0' end From abee1376e8e025bf84810b4a3f4abd3dfbb85175 Mon Sep 17 00:00:00 2001 From: Thomas Thomassen Date: Thu, 5 Feb 2026 13:46:30 +0100 Subject: [PATCH 6/6] Bump version to 0.7.11. --- sketchup-api-stubs.gemspec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sketchup-api-stubs.gemspec b/sketchup-api-stubs.gemspec index 629a2a1..00e8a87 100644 --- a/sketchup-api-stubs.gemspec +++ b/sketchup-api-stubs.gemspec @@ -1,7 +1,7 @@ # coding: utf-8 Gem::Specification.new do |spec| spec.name = 'sketchup-api-stubs' - spec.version = '0.7.10' + spec.version = '0.7.11' spec.authors = ['Trimble Inc, SketchUp Team'] spec.summary = %q{SketchUp Ruby API stubs.}