sketchup-api-stubs 0.7.11 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. checksums.yaml +4 -4
  2. data/lib/sketchup-api-stubs/sketchup.rb +6 -0
  3. data/lib/sketchup-api-stubs/stubs/Array.rb +4 -0
  4. data/lib/sketchup-api-stubs/stubs/Geom/BoundingBox.rb +35 -11
  5. data/lib/sketchup-api-stubs/stubs/Geom/Point2d.rb +1 -1
  6. data/lib/sketchup-api-stubs/stubs/Geom/Point3d.rb +9 -5
  7. data/lib/sketchup-api-stubs/stubs/Geom/Transformation.rb +5 -0
  8. data/lib/sketchup-api-stubs/stubs/Geom/Transformation2d.rb +10 -0
  9. data/lib/sketchup-api-stubs/stubs/Geom/Vector3d.rb +5 -2
  10. data/lib/sketchup-api-stubs/stubs/Geom.rb +2 -0
  11. data/lib/sketchup-api-stubs/stubs/LanguageHandler.rb +4 -4
  12. data/lib/sketchup-api-stubs/stubs/Layout/AngularDimension.rb +53 -51
  13. data/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinition.rb +2 -1
  14. data/lib/sketchup-api-stubs/stubs/Layout/Document.rb +1 -1
  15. data/lib/sketchup-api-stubs/stubs/Layout/FormattedText.rb +6 -8
  16. data/lib/sketchup-api-stubs/stubs/Layout/Group.rb +50 -0
  17. data/lib/sketchup-api-stubs/stubs/Layout/Image.rb +8 -10
  18. data/lib/sketchup-api-stubs/stubs/Layout/Path.rb +1 -1
  19. data/lib/sketchup-api-stubs/stubs/Layout/ReferenceEntity.rb +8 -10
  20. data/lib/sketchup-api-stubs/stubs/Layout/SketchUpModel.rb +6 -9
  21. data/lib/sketchup-api-stubs/stubs/Layout/Style.rb +1 -1
  22. data/lib/sketchup-api-stubs/stubs/Layout/Table.rb +17 -0
  23. data/lib/sketchup-api-stubs/stubs/Sketchup/AppObserver.rb +109 -21
  24. data/lib/sketchup-api-stubs/stubs/Sketchup/ArcCurve.rb +17 -11
  25. data/lib/sketchup-api-stubs/stubs/Sketchup/CRSLocation.rb +402 -0
  26. data/lib/sketchup-api-stubs/stubs/Sketchup/CRSMapUnit.rb +83 -0
  27. data/lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb +220 -8
  28. data/lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb +85 -16
  29. data/lib/sketchup-api-stubs/stubs/Sketchup/Curve.rb +11 -9
  30. data/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionList.rb +5 -1
  31. data/lib/sketchup-api-stubs/stubs/Sketchup/Dimension.rb +6 -6
  32. data/lib/sketchup-api-stubs/stubs/Sketchup/DimensionLinear.rb +19 -11
  33. data/lib/sketchup-api-stubs/stubs/Sketchup/DimensionRadial.rb +8 -9
  34. data/lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb +181 -33
  35. data/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.rb +0 -5
  36. data/lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb +8 -1
  37. data/lib/sketchup-api-stubs/stubs/Sketchup/EntityObserver.rb +0 -5
  38. data/lib/sketchup-api-stubs/stubs/Sketchup/Face.rb +14 -12
  39. data/lib/sketchup-api-stubs/stubs/Sketchup/Group.rb +100 -19
  40. data/lib/sketchup-api-stubs/stubs/Sketchup/HatchPattern.rb +277 -0
  41. data/lib/sketchup-api-stubs/stubs/Sketchup/HatchPatternData.rb +245 -0
  42. data/lib/sketchup-api-stubs/stubs/Sketchup/HatchPatterns.rb +155 -0
  43. data/lib/sketchup-api-stubs/stubs/Sketchup/Image.rb +2 -2
  44. data/lib/sketchup-api-stubs/stubs/Sketchup/InstancePath.rb +144 -0
  45. data/lib/sketchup-api-stubs/stubs/Sketchup/Layer.rb +6 -0
  46. data/lib/sketchup-api-stubs/stubs/Sketchup/LayerFolder.rb +13 -1
  47. data/lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb +2 -4
  48. data/lib/sketchup-api-stubs/stubs/Sketchup/Material.rb +66 -3
  49. data/lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb +4 -4
  50. data/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb +112 -25
  51. data/lib/sketchup-api-stubs/stubs/Sketchup/ModelObserver.rb +130 -4
  52. data/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProviderObserver.rb +0 -1
  53. data/lib/sketchup-api-stubs/stubs/Sketchup/Page.rb +95 -83
  54. data/lib/sketchup-api-stubs/stubs/Sketchup/Pages.rb +11 -11
  55. data/lib/sketchup-api-stubs/stubs/Sketchup/Procedure.rb +452 -0
  56. data/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptions.rb +29 -3
  57. data/lib/sketchup-api-stubs/stubs/Sketchup/SectionPlane.rb +30 -0
  58. data/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb +15 -13
  59. data/lib/sketchup-api-stubs/stubs/Sketchup/Style.rb +16 -0
  60. data/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb +74 -0
  61. data/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb +49 -8
  62. data/lib/sketchup-api-stubs/stubs/Sketchup/ToolsObserver.rb +25 -12
  63. data/lib/sketchup-api-stubs/stubs/Sketchup/View.rb +78 -22
  64. data/lib/sketchup-api-stubs/stubs/Sketchup.rb +55 -4
  65. data/lib/sketchup-api-stubs/stubs/SketchupExtension.rb +73 -59
  66. data/lib/sketchup-api-stubs/stubs/UI/Command.rb +119 -164
  67. data/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb +50 -9
  68. data/lib/sketchup-api-stubs/stubs/UI/WebDialog.rb +4 -1
  69. data/lib/sketchup-api-stubs/stubs/UI.rb +15 -8
  70. data/lib/sketchup-api-stubs/stubs/_top_level.rb +8 -0
  71. metadata +9 -7
@@ -15,7 +15,7 @@ class Sketchup::DimensionRadial < Sketchup::Dimension
15
15
  # @example
16
16
  # arc = dim.arc_curve
17
17
  #
18
- # @return The ArcCurve object to which the dimension is attached.
18
+ # @return [Sketchup::ArcCurve] The ArcCurve object to which the dimension is attached.
19
19
  #
20
20
  # @version SketchUp 2014
21
21
  def arc_curve
@@ -27,9 +27,8 @@ class Sketchup::DimensionRadial < Sketchup::Dimension
27
27
  # @example
28
28
  # dim.arc_curve = arc
29
29
  #
30
- # @param arc_curve
31
- # The ArcCurve object to which the dimension is to be
32
- # attached.
30
+ # @param [Sketchup::ArcCurve] arc_curve
31
+ #
33
32
  #
34
33
  # @return The ArcCurve object to which the dimension was attached.
35
34
  #
@@ -44,7 +43,7 @@ class Sketchup::DimensionRadial < Sketchup::Dimension
44
43
  # pt = dim.leader_break_point
45
44
  # puts "Break point is #{pt}"
46
45
  #
47
- # @return the leader break point
46
+ # @return [Geom::Point3d] the leader break point
48
47
  #
49
48
  # @version SketchUp 2014
50
49
  def leader_break_point
@@ -56,7 +55,7 @@ class Sketchup::DimensionRadial < Sketchup::Dimension
56
55
  # @example
57
56
  # dim.leader_break_point = [10, 0, 0]
58
57
  #
59
- # @param point
58
+ # @param [Geom::Point3d] point
60
59
  # the point to be set
61
60
  #
62
61
  # @return the point that was set
@@ -65,7 +64,7 @@ class Sketchup::DimensionRadial < Sketchup::Dimension
65
64
  def leader_break_point=(point)
66
65
  end
67
66
 
68
- # The leader_points method returns the 3 significant points along the dimension
67
+ # The {#leader_points} method returns the 3 significant points along the dimension
69
68
  # line in world coordinates.
70
69
  #
71
70
  # @example
@@ -74,8 +73,8 @@ class Sketchup::DimensionRadial < Sketchup::Dimension
74
73
  # puts "Attach point is #{pts[1]}"
75
74
  # puts "Opposite point is #{pts[2]}"
76
75
  #
77
- # @return Array of 3 Point3d objects. Point 0: leader break point,
78
- # where the text extension attaches. Point 1: attach point,
76
+ # @return [Array(Geom::Point3d, Geom::Point3d, Geom::Point3d)] Array of 3 Point3d
77
+ # objects. Point 0: leader break point, where the text extension attaches. Point 1: attach point,
79
78
  # where leader touches the arc/circle. Point 2: opposite
80
79
  # point, where the diameter leader touches the circle on
81
80
  # the opposite side.
@@ -137,7 +137,9 @@ class Sketchup::Entities
137
137
  # @param [Numeric] radius The radius of the arc.
138
138
  # @param [Numeric] start_angle Start angle for the arc, in radians.
139
139
  # @param [Numeric] end_angle End angle for the arc, in radians.
140
+ #
140
141
  # @return [Array<Sketchup::Edge>] an array of Edge objects that define the arc.
142
+ # Returns an empty array if +radius+ is +0+.
141
143
  #
142
144
  # @overload add_arc(center, xaxis, normal, radius, start_angle, end_angle, num_segments)
143
145
  #
@@ -148,7 +150,9 @@ class Sketchup::Entities
148
150
  # @param [Numeric] start_angle Start angle for the arc, in radians.
149
151
  # @param [Numeric] end_angle End angle for the arc, in radians.
150
152
  # @param [Integer] num_segments How many segments to draw.
153
+ #
151
154
  # @return [Array<Sketchup::Edge>] an array of Edge objects that define the arc.
155
+ # Returns an empty array if +radius+ is +0+.
152
156
  #
153
157
  # @version SketchUp 6.0
154
158
  def add_arc(*args)
@@ -162,7 +166,7 @@ class Sketchup::Entities
162
166
  # center_point = Geom::Point3d.new
163
167
  # # Create a circle perpendicular to the provided vector.
164
168
  # normal = Z_AXIS
165
- # edges = entities.add_circle(center_point, vector, 10)
169
+ # edges = entities.add_circle(center_point, normal, 10)
166
170
  #
167
171
  # @param [Geom::Point3d] center
168
172
  # A Point3d object representing the center.
@@ -176,7 +180,8 @@ class Sketchup::Entities
176
180
  # @param [Integer] numsegs
177
181
  # The number of segments.
178
182
  #
179
- # @return [Array<Sketchup::Edge>] an Array object containing edges if successful
183
+ # @return [Array<Sketchup::Edge>] an Array object containing edges if successful.
184
+ # Returns an empty array if +radius+ is +0+.
180
185
  #
181
186
  # @version SketchUp 6.0
182
187
  def add_circle(center, normal, radius, numsegs = 24)
@@ -214,6 +219,48 @@ class Sketchup::Entities
214
219
  def add_cline(*args)
215
220
  end
216
221
 
222
+ # The {#add_copy} method copies a set of drawing elements into this {Sketchup::Entities}
223
+ # collection.
224
+ #
225
+ # Source elements' geometric coordinates from within their parent components are preserved, and
226
+ # they are applied to the copies in this component's local coordinate frame. The transformation
227
+ # is also interpreted to be in the local coordinates of this (target) component.
228
+ #
229
+ # The drawing elements being copied may already belong to this collection or to a different one,
230
+ # but they must all share the same parent, and belong to the same model as this collection.
231
+ # Dependent geometry needed to reproduce the originals (e.g. the edges bounding a copied face)
232
+ # are copied automatically and included in the result.
233
+ #
234
+ # @example
235
+ # model = Sketchup.active_model
236
+ # entities = model.active_entities
237
+ # face = entities.add_face([0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0])
238
+ # transformation = Geom::Transformation.new([20, 0, 0])
239
+ # copies = entities.add_copy(face, transform: transformation)
240
+ #
241
+ # @param [Array<Sketchup::Drawingelement>, Sketchup::Drawingelement, Sketchup::Selection] entities
242
+ # The drawing elements to copy.
243
+ #
244
+ # @param [Geom::Transformation] transform
245
+ # A transformation applied to the copies within the local axes of this component.
246
+ #
247
+ # @raise [TypeError] if any of the given entities is not a {Sketchup::Drawingelement}.
248
+ #
249
+ # @raise [ArgumentError] if the entities do not share a common parent.
250
+ #
251
+ # @raise [ArgumentError] if the entities do not belong to the same model as this collection.
252
+ #
253
+ # @raise [ArgumentError] if the transformation is not invertible.
254
+ #
255
+ # @raise [ArgumentError] if the copy would create a recursive component definition.
256
+ #
257
+ # @return [Array<Sketchup::Drawingelement>] the copied drawing elements. If the elements are
258
+ # split by intersecting geometry, more elements can be returned than were originally passed in.
259
+ #
260
+ # @version SketchUp 2027.0
261
+ def add_copy(entities, transform: IDENTITY)
262
+ end
263
+
217
264
  # The add_cpoint method is used to create a construction point.
218
265
  #
219
266
  # @example
@@ -256,6 +303,9 @@ class Sketchup::Entities
256
303
 
257
304
  # The {#add_dimension_linear} method adds a linear dimension to the entities.
258
305
  #
306
+ # @bug Prior to SketchUp 2026.2 could move the {Sketchup::ConstructionPoint}
307
+ # if passing an {Sketchup::InstancePath} containing a construction point.
308
+ #
259
309
  # @example
260
310
  # entities = Sketchup.active_model.entities
261
311
  # # From point to point
@@ -359,8 +409,8 @@ class Sketchup::Entities
359
409
  # entities = Sketchup.active_model.entities
360
410
  # # Create a circle
361
411
  # center_point = Geom::Point3d.new(10, 10, 0)
362
- # vector = Geom::Vector3d.new(0, 0, 1)
363
- # edges = entities.add_circle(center_point, vector, 10)
412
+ # normal = Geom::Vector3d.new(0, 0, 1)
413
+ # edges = entities.add_circle(center_point, normal, 10)
364
414
  # circle = edges[0].curve
365
415
  # dim = entities.add_dimension_radial(circle, [30, 30, 0])
366
416
  #
@@ -425,6 +475,9 @@ class Sketchup::Entities
425
475
  # For the last form that takes a Curve, the curve must be closed - like a
426
476
  # circle.
427
477
  #
478
+ # @bug Prior to SketchUp 2027.0 calls to {#add_face} with an array of edges would silently fail
479
+ # and abort any open operation if an existing face was found.
480
+ #
428
481
  # @example
429
482
  # model = Sketchup.active_model
430
483
  # entities = model.active_entities
@@ -439,6 +492,12 @@ class Sketchup::Entities
439
492
  # @note A special case exists for any face created on the ground plane, in
440
493
  # which case the vertex order is ignored and the face is always facing down.
441
494
  #
495
+ # @note When using the edge array or curve overload this method will return +nil+ and abort any
496
+ # open operation if:
497
+ # - The edges do not form a closed loop
498
+ # - The edges are not planar
499
+ # In these cases use +$!+ to check for an error message if the face creation fails.
500
+ #
442
501
  # @overload add_face(entities)
443
502
  #
444
503
  # @param [Array<Sketchup::Edge>, Array<Geom::Point3d>, Sketchup::Curve] entities
@@ -840,6 +899,31 @@ class Sketchup::Entities
840
899
  def at(entity_index)
841
900
  end
842
901
 
902
+ # The {#bounds} method is used to retrieve the {Geom::BoundingBox} bounding
903
+ # the collection of entities.
904
+ #
905
+ # For a Procedural Component, {Sketchup::ComponentDefinition#entities} and
906
+ # {Sketchup::ComponentDefinition#control_entities} have different bounds.
907
+ # For non-procedural components this has the same effect as
908
+ # {Sketchup::ComponentDefinition#bounds}.
909
+ #
910
+ # @example
911
+ # definition = Sketchup.active_model.definitions.first
912
+ # bounds = definition.entities.bounds
913
+ #
914
+ # @example Get separate bounds for control and output entities of a procedural component
915
+ # definition = Sketchup.active_model.definitions.first
916
+ # if definition.procedural?
917
+ # control_bounds = definition.control_entities.bounds
918
+ # output_bounds = definition.entities.bounds
919
+ # end
920
+ #
921
+ # @return [Geom::BoundingBox]
922
+ #
923
+ # @version SketchUp 2027.0
924
+ def bounds
925
+ end
926
+
843
927
  # Creates an {Sketchup::EntitiesBuilder} that can be used to generate bulk
844
928
  # geometry with performance in mind. This is particularly useful for importers
845
929
  # where the geometry is already well defined and one wants to recreate it
@@ -1039,56 +1123,120 @@ class Sketchup::Entities
1039
1123
  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)
1040
1124
  end
1041
1125
 
1042
- # The {#intersect_with} method is used to intersect a Sketchup::Entities, Sketchup::Component,
1043
- # or Sketchup::Group object with a entities object.
1126
+ # The {#intersect_with} method computes the intersections between two sets of
1127
+ # entities in different 3D contexts and creates the resulting intersection
1128
+ # edges in a third context.
1044
1129
  #
1045
- # empty if no intersection(s) were found.
1130
+ # This powerful method operates on three distinct sets of entities:
1046
1131
  #
1047
- # @example
1048
- # model = Sketchup.active_model
1049
- # entities = model.active_entities
1132
+ # 1. The Receiver (+self+): The {Sketchup::Entities} collection the
1133
+ # method is called on.
1050
1134
  #
1051
- # # Create a group to intersect with the model
1052
- # group1 = entities.add_group
1053
- # face1 = group1.entities.add_face([0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0])
1054
- # face1.pushpull(-40)
1135
+ # 2. The Cutting Entities (+entities2+): The entities that intersect
1136
+ # with the receiver.
1055
1137
  #
1056
- # # Add geometry into the model
1057
- # face2 = entities.add_face([50, 50, 0], [200, 50, 0], [200, 200, 0], [50, 200, 0])
1058
- # face2.pushpull(-100)
1138
+ # 3. The Result Container (+entities1+): The {Sketchup::Entities} collection
1139
+ # where the new intersection edges are placed.
1059
1140
  #
1060
- # entities1 = group1.entities
1061
- # entities2 = entities.to_a
1141
+ # The transformations +transform1+ and +transform2+ are used to relate these
1142
+ # three different contexts to each other, allowing for intersections to be
1143
+ # calculated between objects anywhere in the model hierarchy. The intersection
1144
+ # calculation occurs in a common coordinate space, and the transformations
1145
+ # are used to bring the geometry into that space.
1146
+ #
1147
+ # @example
1148
+ # # --- Setup ---
1149
+ # model = Sketchup.active_model
1150
+ # entities = model.entities
1151
+ # model.start_operation('Intersect Example', true)
1152
+ #
1153
+ # # Clear any existing geometry to prevent conflicts
1154
+ # entities.clear!
1155
+ #
1156
+ # # Create a "cutter" group - a cube shifted in space
1157
+ # cutter_group = entities.add_group
1158
+ # cutter_face = cutter_group.entities.add_face(
1159
+ # [0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]
1160
+ # )
1161
+ # cutter_face.pushpull(-50)
1162
+ # # Move the cutter cube to create an interesting intersection
1163
+ # cutter_group.transform!(Geom::Transformation.new([25, 25, 25]))
1164
+ #
1165
+ # # Create a "mesh" group - a larger box that overlaps the cutter
1166
+ # mesh_group = entities.add_group
1167
+ # mesh_face = mesh_group.entities.add_face(
1168
+ # [0, 0, 0], [200, 0, 0], [200, 200, 0], [0, 200, 0]
1169
+ # )
1170
+ # mesh_face.pushpull(-100)
1171
+ # # Move the mesh_group so it partially overlaps the cutter_group
1172
+ # mesh_group.transform!(Geom::Transformation.new([50, 50, 0]))
1173
+ #
1174
+ # # Create an empty group to hold the intersection results
1175
+ # result_group = entities.add_group
1176
+ #
1177
+ # # --- Intersection ---
1178
+ # # Define transformations to relate the three groups. We use the
1179
+ # # cutter_group's coordinate space as the common ground.
1180
+ #
1181
+ # # Transformation from the mesh_group's space to the cutter_group's space.
1182
+ # tr_mesh_to_cutter = cutter_group.transformation.inverse * mesh_group.transformation
1183
+ #
1184
+ # # Transformation from the result_group's space to the cutter_group's space.
1185
+ # tr_result_to_cutter = cutter_group.transformation.inverse * result_group.transformation
1186
+ #
1187
+ # # Perform the intersection
1188
+ # intersecting_edges = mesh_group.entities.intersect_with(
1189
+ # false, # recurse
1190
+ # tr_mesh_to_cutter, # transform1 for the receiver (mesh_group)
1191
+ # result_group.entities, # entities1 (result container)
1192
+ # tr_result_to_cutter, # transform2 for the result container
1193
+ # true, # hidden
1194
+ # cutter_group.entities.to_a # entities2 (cutting entities)
1195
+ # )
1196
+ #
1197
+ # # Verify the results
1198
+ # puts "Intersection created #{intersecting_edges.length} edges"
1199
+ #
1200
+ # # Change the color of the result edges to make them visible
1201
+ # if intersecting_edges.length > 0
1202
+ # result_group.material = Sketchup::Color.new(255, 0, 0) # Red
1203
+ # end
1062
1204
  #
1063
- # transformation1 = Geom::Transformation.new
1064
- # transformation2 = group1.transformation
1205
+ # model.commit_operation
1065
1206
  #
1066
- # # Intersect the group and model geometry
1067
- # entities.intersect_with(true, transformation1, entities1, transformation2, true, entities2)
1207
+ # # Zoom to see the entire model
1208
+ # model.active_view.zoom_extents
1068
1209
  #
1069
1210
  # @param [Boolean] recurse
1070
- # true if you want this entities object to be recursed
1071
- # (intersection lines will be put inside of groups and
1072
- # components within this entities object).
1211
+ # If `true`, the intersection will recurse through any nested
1212
+ # Groups or Components within the **receiver** (`self`).
1073
1213
  #
1074
1214
  # @param [Geom::Transformation] transform1
1075
- # The transformation for this entities object.
1215
+ # The transformation applied to the **receiver** entities (`self`)
1216
+ # to position them in the common coordinate space where the
1217
+ # intersection will be calculated.
1076
1218
  #
1077
1219
  # @param [Sketchup::Entities] entities1
1078
- # The entities object where you want the intersection
1079
- # lines to appear.
1220
+ # The **result** entities collection. This is the drawing context
1221
+ # where the new intersection edges will be created.
1080
1222
  #
1081
1223
  # @param [Geom::Transformation] transform2
1082
- # The transformation for entities1.
1224
+ # The transformation applied to the **result** entities collection
1225
+ # (`entities1`) to correctly position it relative to the
1226
+ # intersection calculation space.
1083
1227
  #
1084
1228
  # @param [Boolean] hidden
1085
- # true if you want hidden geometry in this entities
1086
- # object to be used in the intersection.
1229
+ # If +true+, hidden geometry in the **receiver** entities will be
1230
+ # considered for the intersection. This parameter only affects hidden
1231
+ # geometry in the receiver, not in the cutting entities.
1087
1232
  #
1088
1233
  # @param [Sketchup::Entity, Array<Sketchup::Entity>] entities2
1089
- # A single entity, or an array of entities.
1234
+ # The **cutting** entities. These are the entities that will be
1235
+ # intersected with the receiver. This can be a single entity or an
1236
+ # array of entities.
1090
1237
  #
1091
1238
  # @return [Array<Sketchup::Edge>] The intersecting edges created. This array may be
1239
+ # empty if no intersection(s) were found.
1092
1240
  #
1093
1241
  # @version SketchUp 6.0
1094
1242
  def intersect_with(recurse, transform1, entities1, transform2, hidden, entities2)
@@ -20,11 +20,6 @@
20
20
  # # Attach the observer
21
21
  # Sketchup.active_model.entities.add_observer(MyEntitiesObserver.new)
22
22
  #
23
- # @note The methods of this observer fire in such a way that making changes
24
- # to the model while inside of them is dangerous. If you experience sudden
25
- # crashes, it could be because of this observer. A potential workaround is to
26
- # use a {Sketchup::ToolsObserver} to watch what the user is doing instead.
27
- #
28
23
  # @version SketchUp 6.0
29
24
  class Sketchup::EntitiesObserver
30
25
 
@@ -26,7 +26,7 @@
26
26
  # end
27
27
  # }
28
28
  #
29
- # "There are #{face_count} faces selected."
29
+ # puts "There are #{face_count} faces selected."
30
30
  #
31
31
  # @version SketchUp 6.0
32
32
  class Sketchup::Entity
@@ -331,6 +331,8 @@ class Sketchup::Entity
331
331
  #
332
332
  # The persistent id persistent between sessions.
333
333
  #
334
+ # [Sketchup 2025.0]
335
+ # - {Sketchup::Environment}
334
336
  # [SketchUp 2020.1]
335
337
  # - {Sketchup::ComponentDefinition}
336
338
  # - {Sketchup::Material}
@@ -430,6 +432,11 @@ class Sketchup::Entity
430
432
  # entity1 = entities[1]
431
433
  # status = entity1.set_attribute "testdictionary", "test", 115
432
434
  #
435
+ # @note {Geom::Point3d} or {Geom::Vector3d} array values stored as vertex
436
+ # attributes are automatically transformed when the vertex is moved.
437
+ # In case you want to preserve the coordinates, you can transform them
438
+ # to an array.
439
+ #
433
440
  # @param [String] dict_name
434
441
  # The name of an attribute dictionary.
435
442
  #
@@ -17,11 +17,6 @@
17
17
  # # Attach the observer. (Assumes there is an entity in the model.)
18
18
  # Sketchup.active_model.entities[0].add_observer(MyEntityObserver.new)
19
19
  #
20
- # @note The methods of this observer fire in such a way that making changes
21
- # to the model while inside of them is dangerous. If you experience sudden
22
- # crashes, it could be because of this observer. A potential workaround is to
23
- # use a {Sketchup::ToolsObserver} to watch what the user is doing instead.
24
- #
25
20
  # @version SketchUp 6.0
26
21
  class Sketchup::EntityObserver
27
22
 
@@ -71,8 +71,8 @@ class Sketchup::Face < Sketchup::Drawingelement
71
71
  # @overload area(transform)
72
72
  #
73
73
  # @param [Geom::Transformation] transform
74
- # A Transformation object or array that can be interpreted as a
75
- # Transformation object.
74
+ # A Transformation object or array that can be interpreted as a
75
+ # Transformation object.
76
76
  # @return [Float] the area of the face in square inches.
77
77
  #
78
78
  # @version SketchUp 6.0
@@ -329,25 +329,25 @@ class Sketchup::Face < Sketchup::Drawingelement
329
329
  # @overload get_UVHelper(front = true, back = true)
330
330
  #
331
331
  # @param [Boolean] front
332
- # True if you want the texture coordinates for the front
333
- # face, false if not.
332
+ # True if you want the texture coordinates for the front
333
+ # face, false if not.
334
334
  #
335
335
  # @param [Boolean] back
336
- # True if you want the texture coordinates for the back
337
- # face, false if not.
336
+ # True if you want the texture coordinates for the back
337
+ # face, false if not.
338
338
  #
339
339
  # @overload get_UVHelper(front = true, back = true, texturewriter)
340
340
  #
341
341
  # @param [Boolean] front
342
- # True if you want the texture coordinates for the front
343
- # face, false if not.
342
+ # True if you want the texture coordinates for the front
343
+ # face, false if not.
344
344
  #
345
345
  # @param [Boolean] back
346
- # True if you want the texture coordinates for the back
347
- # face, false if not.
346
+ # True if you want the texture coordinates for the back
347
+ # face, false if not.
348
348
  #
349
349
  # @param [Sketchup::TextureWriter] texturewriter
350
- # An optional TextureWriter object.
350
+ # An optional TextureWriter object.
351
351
  #
352
352
  # @return [Sketchup::UVHelper]
353
353
  #
@@ -723,7 +723,7 @@ class Sketchup::Face < Sketchup::Drawingelement
723
723
  #
724
724
  # @overload position_material(material, points, on_front, projection)
725
725
  #
726
- # @version SketchUp 6.0
726
+ # @version SketchUp 2021.1
727
727
  #
728
728
  # This variant positions a material on the face's plane with projection.
729
729
  #
@@ -756,6 +756,8 @@ class Sketchup::Face < Sketchup::Drawingelement
756
756
  # @see #get_texture_projection
757
757
  #
758
758
  # @see #clear_texture_projection
759
+ #
760
+ # @version SketchUp 6.0
759
761
  def position_material(*args)
760
762
  end
761
763
 
@@ -54,6 +54,23 @@ class Sketchup::Group < Sketchup::Drawingelement
54
54
  # group = Sketchup.active_model.entities.add_group
55
55
  # definition = group.definition
56
56
  #
57
+ # # When editing {Sketchup::Entities} through {#definition}, you need to make the group
58
+ # # unique first if working with multiple instances sharing the same definition so you do
59
+ # # not affect all the groups.
60
+ # entities = Sketchup.active_model.entities
61
+ #
62
+ # group1 = entities.add_group
63
+ # group2 = entities.add_instance(group1.definition, IDENTITY)
64
+ #
65
+ # # Make the first group unique so that we don't also affect
66
+ # # the second group with the first group.
67
+ # group1.make_unique
68
+ # group1.definition.entities.add_cpoint(ORIGIN)
69
+ #
70
+ # @note When editing {Sketchup::Entities} through {#definition} beware that all
71
+ # instances sharing the same definition will be affected by the changes. To only
72
+ # affect the current group instance, call {#make_unique} before accessing its {#definition}.
73
+ #
57
74
  # @return [Sketchup::ComponentDefinition] a ComponentDefinition object if
58
75
  # successful
59
76
  #
@@ -146,6 +163,12 @@ class Sketchup::Group < Sketchup::Drawingelement
146
163
  # face = entities2.add_face pts
147
164
  # entities = group.entities
148
165
  #
166
+ # @note Editing the returned {Sketchup::Entities} will automatically make the
167
+ # group unique, similarly to when you open it for editing in the GUI. This
168
+ # differs from the behavior when editing {Sketchup::Entities} through
169
+ # {#definition}, which does not make the group unique when edited. For said
170
+ # method you need to call {#make_unique} first.
171
+ #
149
172
  # @return [Sketchup::Entities] an Entities object if successful
150
173
  #
151
174
  # @version SketchUp 6.0
@@ -252,6 +275,35 @@ class Sketchup::Group < Sketchup::Drawingelement
252
275
  def guid
253
276
  end
254
277
 
278
+ # Retrieves the hatch pattern assigned to the group.
279
+ #
280
+ # @example
281
+ # group = Sketchup.active_model.entities[0]
282
+ # puts group.hatch_pattern.name
283
+ #
284
+ # @return [Sketchup::HatchPattern, nil]
285
+ #
286
+ # @version SketchUp 2027.0
287
+ def hatch_pattern
288
+ end
289
+
290
+ # Assigns a hatch pattern to the group.
291
+ #
292
+ # @example
293
+ # model = Sketchup.active_model
294
+ # hatch_patterns = model.hatch_patterns
295
+ # group = model.entities[0]
296
+ # group.hatch_pattern = hatch_patterns['Pattern1']
297
+ #
298
+ # @param [Sketchup::HatchPattern, nil] pattern
299
+ # the pattern to assign, or +nil+ to clear the assignment.
300
+ #
301
+ # @raise [ArgumentError] if the pattern does not belong to the group's model.
302
+ #
303
+ # @version SketchUp 2027.0
304
+ def hatch_pattern=(pattern)
305
+ end
306
+
255
307
  # The intersect method is used to compute the boolean intersection of two
256
308
  # groups representing manifold solid volumes (this & arg). If the specified
257
309
  # objects (this and arg) do not represent manifold volumes, this method fails.
@@ -363,6 +415,9 @@ class Sketchup::Group < Sketchup::Drawingelement
363
415
 
364
416
  # The manifold? method is used to determine if a group is manifold.
365
417
  #
418
+ # @deprecated Use {Sketchup::ComponentDefinition#manifold?} instead. This method
419
+ # checks the definition, not the group instance.
420
+ #
366
421
  # @example
367
422
  # entities = Sketchup.active_model.entities
368
423
  # definition = Sketchup.active_model.definitions[0]
@@ -372,6 +427,8 @@ class Sketchup::Group < Sketchup::Drawingelement
372
427
  #
373
428
  # @return [Boolean]
374
429
  #
430
+ # @see Sketchup::ComponentDefinition#manifold?
431
+ #
375
432
  # @version SketchUp 8.0
376
433
  def manifold?
377
434
  end
@@ -524,32 +581,56 @@ class Sketchup::Group < Sketchup::Drawingelement
524
581
  def show_differences(group, verbose)
525
582
  end
526
583
 
527
- # The split method is used to compute the boolean split (map overlay) of the
528
- # two groups representing manifold solid volumes (this ^ arg). If the
529
- # specified objects (this and arg) do not represent manifold volumes,
530
- # this method fails.
584
+ # The {#split} method performs a boolean "split" (map overlay) between this
585
+ # group (the receiver) and another manifold solid (group or component
586
+ # instance). The operation partitions the combined volumes into:
587
+ #
588
+ # - Difference2: (other - self)
589
+ # - Difference1: (self - other)
590
+ # - Intersection: (self ∩ other)
591
+ #
592
+ # The originals (self and other) are ERASED and replaced by three newly created
593
+ # groups representing these volumes.
531
594
  #
532
595
  # @example
533
- # entities = Sketchup.active_model.entities
534
- # group1 = entities[0]
535
- # group2 = entities[1]
536
- # result = group1.split(group2)
596
+ # model = Sketchup.active_model
597
+ # g1 = model.entities.add_group
598
+ # g1.entities.add_face([0,0,0],[100,0,0],[100,100,0],[0,100,0]).pushpull(50)
599
+ # g2 = model.entities.add_group
600
+ # g2.entities.add_face([50,-25,0],[150,-25,0],[150,75,0],[50,75,0]).pushpull(50)
601
+ # diff2, diff1, inter = g1.split(g2) # Order: Difference2, Difference1, Intersection
602
+ # puts inter.name # "Intersection"
537
603
  #
538
- # @note This method is not available in SketchUp Make.
604
+ # @note Both operands must be manifold solids (see {#manifold?}). Non‑manifold
605
+ # geometry returns +nil+.
539
606
  #
540
- # @param [Sketchup::Group, Sketchup::ComponentInstance] group
541
- # The group to split this group with.
607
+ # The returned groups are new; original group(s)/instance are deleted.
608
+ #
609
+ # All result groups are assigned to the Untagged tag; original tags are not kept.
610
+ #
611
+ # Materials / attributes are not fully preserved (see ComponentInstance#split notes).
612
+ #
613
+ # Intersection can be empty if there is no volumetric overlap (only
614
+ # touching or full containment without new partition).
615
+ #
616
+ # Not available in SketchUp Make.
617
+ #
618
+ # @param [Sketchup::Group, Sketchup::ComponentInstance] other
619
+ # The other solid to split with.
620
+ #
621
+ # @return [Array(Sketchup::Group, Sketchup::Group, Sketchup::Group), nil] Returns [Difference2, Difference1, Intersection] on success, or +nil+ if
622
+ # either operand is not a manifold solid or the operation fails.
623
+ #
624
+ # @see #union
625
+ #
626
+ # @see #intersect
627
+ #
628
+ # @see #subtract
542
629
  #
543
- # @return [Array(Sketchup::Group, Sketchup::Group, Sketchup::Group), nil] A vector (array) of the three resultant groups
544
- # If the two objects (this and arg) represent manifold
545
- # solids and the operation succeeds otherwise nil is
546
- # returned. The 3 groups are as follows:
547
- # The intersection of volume 1 & volume 2,
548
- # the difference of volume 1 minus volume 2,
549
- # and the reverse difference of volume 2 minus volume 1.
630
+ # @see #trim
550
631
  #
551
632
  # @version SketchUp 8.0
552
- def split(group)
633
+ def split(other)
553
634
  end
554
635
 
555
636
  # The subtract method is used to compute the boolean difference of the two