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
@@ -32,13 +32,12 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
32
32
  # sorting. The comparison is done based on the component name.
33
33
  #
34
34
  # @example
35
- # c1=Sketchup.find_support_file "Bed.skp",
36
- # "Components/Components Sampler/"
37
- # c2=Sketchup.find_support_file "Fence.skp",
38
- # "Components/Components Sampler/"
39
- # if c1 <=> c2
40
- # puts "c1 sorts before c2"
41
- # end
35
+ # definitions = Sketchup.active_model.definitions
36
+ # # Sort the definitions by name using the <=> operator.
37
+ # sorted_list = definitions.sort { |a, b| a <=> b }
38
+ # # This is the same as using sort_by:
39
+ # sorted_list = definitions.sort_by(&:name)
40
+ # sorted_list.each { |definition| puts definition.name }
42
41
  #
43
42
  # @param [Sketchup::ComponentDefinition] compdef2
44
43
  # The second component definition in the comparison.
@@ -106,6 +105,66 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
106
105
  def add_observer(observer)
107
106
  end
108
107
 
108
+ # Attaches a procedure to this component definition, making it a procedural component if the
109
+ # procedure is valid for the component's input geometry.
110
+ #
111
+ # The definition must not already be procedural. Make it non-procedural with
112
+ # {Sketchup::ComponentDefinition#make_non_procedural} before attaching a different procedure.
113
+ #
114
+ # @example
115
+ # definition = Sketchup.active_model.definitions[0]
116
+ # my_proc = MyModule::MyProcedure.new
117
+ # Sketchup.register_procedure(my_proc)
118
+ # definition.attach_procedure(my_proc, { count: 5, spacing: 10.0 })
119
+ #
120
+ # @example Attaching a native procedure by ID
121
+ # definition = Sketchup.active_model.definitions[0]
122
+ # definition.attach_procedure(Sketchup::PROCEDURE_ID_FOLLOW_ME, {})
123
+ #
124
+ # @overload attach_procedure(procedure, parameters)
125
+ #
126
+ # @param [Sketchup::Procedure] procedure Procedure to be attached.
127
+ # @param [Hash{Symbol, String => Integer, Float, String, Boolean}] parameters
128
+ # A hash of parameter identifier symbols/strings to values. Pass in an empty hash if the
129
+ # procedure does not need any parameters. The parameter identifiers (hash keys) must match
130
+ # those declared in the procedure's {Sketchup::Procedure#declare_params_and_ui} method.
131
+ #
132
+ # @overload attach_procedure(procedure_id, parameters)
133
+ #
134
+ # @param [String] procedure_id The ID of a registered procedure. Use one of the
135
+ # +Sketchup::PROCEDURE_ID_*+ constants to target a native procedure (for example
136
+ # {Sketchup::PROCEDURE_ID_FOLLOW_ME}).
137
+ # @param [Hash{Symbol, String => Integer, Float, String, Boolean}] parameters
138
+ #
139
+ # @raise [TypeError] If this is a group or image definition.
140
+ #
141
+ # @raise [TypeError] If this definition is already procedural.
142
+ #
143
+ # @raise [TypeError] If parameters is not a Hash.
144
+ #
145
+ # @raise [TypeError] If a parameter value has an unsupported type.
146
+ #
147
+ # @raise [TypeError] If the first argument is neither a {Sketchup::Procedure} nor a String.
148
+ #
149
+ # @raise [ArgumentError] If a String procedure ID is given but no procedure with that ID is
150
+ # registered.
151
+ #
152
+ # @raise [ArgumentError] If the procedure cannot be attached to this definition most likely due to
153
+ # input geometry being invalid for the procedure.
154
+ #
155
+ # @return [nil]
156
+ #
157
+ # @see Sketchup::ComponentDefinition#make_non_procedural
158
+ #
159
+ # @see Sketchup::Procedure#declare_params_and_ui
160
+ #
161
+ # @see file:pages/native_procedures.md
162
+ # Native Procedure Parameters
163
+ #
164
+ # @version SketchUp 2027.0
165
+ def attach_procedure(procedure, parameters)
166
+ end
167
+
109
168
  # The behavior method is used to retrieve the Behavior object associated with
110
169
  # a component definition.
111
170
  #
@@ -123,6 +182,20 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
123
182
  def behavior
124
183
  end
125
184
 
185
+ # For a Procedural Component, retrieves a collection of control (input) elements.
186
+ #
187
+ # @example
188
+ # definition = Sketchup.active_model.definitions[0]
189
+ # entities = definition.control_entities if definition.procedural?
190
+ #
191
+ # @raise [TypeError] if this definition is not procedural.
192
+ #
193
+ # @return [Sketchup::Entities]
194
+ #
195
+ # @version SketchUp 2027.0
196
+ def control_entities
197
+ end
198
+
126
199
  # The count_instances method is used to count the number of unique component
127
200
  # instances in a model using this component definition. This does not represent
128
201
  # the total number of instances placed in the model as it doesn't take into
@@ -194,7 +267,11 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
194
267
  end
195
268
 
196
269
  # The entities method retrieves a collection of all the entities in the
197
- # component definition
270
+ # component definition.
271
+ #
272
+ # SketchUp 2027.0 and later: For a Procedural Component, this will return the output entities.
273
+ # Extension code should not directly modify these entities as they are managed by the procedure.
274
+ # Use {#control_entities} to access the control (input) entities of a Procedural Component.
198
275
  #
199
276
  # @example
200
277
  # componentdefinition = Sketchup.active_model.definitions[0]
@@ -225,6 +302,27 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
225
302
  def get_classification_value(path)
226
303
  end
227
304
 
305
+ # Returns the parameters of the procedure attached to this procedural component definition.
306
+ #
307
+ # @example
308
+ # definition = Sketchup.active_model.definitions[0]
309
+ # # Assuming the definition is procedural and has a procedure attached
310
+ # parameters = definition.get_procedure_parameters
311
+ # # => { count: 5, spacing: 10.0 }
312
+ #
313
+ # @raise [TypeError] If this definition is not procedural.
314
+ #
315
+ # @return [Hash{Symbol => Integer, Float, String, Boolean}] A hash of parameter identifier symbols to their current values. Returns an empty hash if the
316
+ # procedure declares no parameters or is not registered in the current session.
317
+ #
318
+ # @see Sketchup::ComponentDefinition#set_procedure_parameters
319
+ #
320
+ # @see Sketchup::Procedure#declare_params_and_ui
321
+ #
322
+ # @version SketchUp 2027.0
323
+ def get_procedure_parameters
324
+ end
325
+
228
326
  # The group? method is used to determine if this component definition is used
229
327
  # to hold the elements of a group.
230
328
  #
@@ -422,6 +520,56 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
422
520
  def load_time
423
521
  end
424
522
 
523
+ # Makes this procedural component definition a regular, non-procedural definition. The procedure
524
+ # is detached and the definition keeps either the procedural output geometry or the control
525
+ # (input) geometry, as specified by +retained_geometry+.
526
+ #
527
+ # If +:keep_output+ is requested but the procedural output is empty (for example because the
528
+ # procedure errored), the control (input) geometry is retained instead.
529
+ #
530
+ # @example Detach a component whose procedure's extension is not installed
531
+ # definition = Sketchup.active_model.definitions[0]
532
+ # definition.make_non_procedural(:keep_output) if definition.procedural?
533
+ #
534
+ # @example Keep the control (input) geometry
535
+ # definition.make_non_procedural(:keep_input)
536
+ #
537
+ # @param [Symbol] retained_geometry
538
+ # Either +:keep_output+ to keep the procedural output geometry,
539
+ # or +:keep_input+ to keep the control (input) geometry.
540
+ #
541
+ # @raise [TypeError] If this definition is not procedural.
542
+ #
543
+ # @raise [TypeError] If +retained_geometry+ is not a Symbol.
544
+ #
545
+ # @raise [ArgumentError] If +retained_geometry+ is not +:keep_output+ or +:keep_input+.
546
+ #
547
+ # @return [nil]
548
+ #
549
+ # @see Sketchup::ComponentDefinition#attach_procedure
550
+ #
551
+ # @version SketchUp 2027.0
552
+ def make_non_procedural(retained_geometry)
553
+ end
554
+
555
+ # The manifold? method is used to determine if a component definition is manifold.
556
+ #
557
+ # A manifold definition is one where all edges are shared by exactly two faces,
558
+ # and there are no holes or singularities. This allows checking if a definition
559
+ # represents a closed solid without needing to create an instance.
560
+ #
561
+ # @example
562
+ # definition = Sketchup.active_model.definitions.add("Box")
563
+ # face = definition.entities.add_face([0,0,0], [10,0,0], [10,10,0], [0,10,0])
564
+ # face.pushpull(-10)
565
+ # status = definition.manifold?
566
+ #
567
+ # @return [Boolean]
568
+ #
569
+ # @version SketchUp 2026.2
570
+ def manifold?
571
+ end
572
+
425
573
  # The name method retrieves the name of the component definition.
426
574
  #
427
575
  # @example
@@ -477,6 +625,18 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
477
625
  def path
478
626
  end
479
627
 
628
+ # Returns whether this component definition is procedural.
629
+ #
630
+ # @example
631
+ # definition = Sketchup.active_model.definitions[0]
632
+ # is_procedural = definition.procedural?
633
+ #
634
+ # @return [Boolean]
635
+ #
636
+ # @version SketchUp 2027.0
637
+ def procedural?
638
+ end
639
+
480
640
  # The refresh_thumbnail method is used to force SketchUp to regenerate the
481
641
  # thumbnail image that appears in the component browser. This is useful if
482
642
  # you've used the API to change the geometry of your component and would
@@ -531,6 +691,31 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
531
691
  def remove_observer(observer)
532
692
  end
533
693
 
694
+ # Runs the procedures attached to this procedural component definition, regenerating
695
+ # its output geometry.
696
+ #
697
+ # By default, procedures run only if the component has been marked as modified (its
698
+ # control geometry changed or its procedures/parameters were updated). Pass +:force+
699
+ # to run the procedures unconditionally.
700
+ #
701
+ # @example
702
+ # definition = Sketchup.active_model.definitions[0]
703
+ # definition.run_procedures # run only if needed
704
+ # definition.run_procedures(:force) # always run
705
+ #
706
+ # @param [Symbol] mode
707
+ # Either +:if_modified+ (default) or +:force+.
708
+ #
709
+ # @raise [TypeError] If this definition is not procedural.
710
+ #
711
+ # @raise [ArgumentError] If +mode+ is not +:if_modified+ or +:force+.
712
+ #
713
+ # @return nil
714
+ #
715
+ # @version SketchUp 2027.0
716
+ def run_procedures(mode)
717
+ end
718
+
534
719
  # The {#save_as} method is used to save your definition as a SketchUp file at the
535
720
  # specified file destination.
536
721
  #
@@ -538,6 +723,8 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
538
723
  # out the definition, without changing the path it is associated with, use
539
724
  # {#save_copy} instead.
540
725
  #
726
+ # @bug Prior to SketchUp 2027.0, saving a copy changed the definition {#guid}.
727
+ #
541
728
  # @example
542
729
  # my_definition = Sketchup.active_model.definitions[0]
543
730
  # my_definition.save_as("c:\\myComponent.skp")
@@ -635,6 +822,31 @@ class Sketchup::ComponentDefinition < Sketchup::Drawingelement
635
822
  def set_classification_value(path, value)
636
823
  end
637
824
 
825
+ # Sets the parameters for the procedure attached to this procedural component definition.
826
+ # The component's output geometry will be regenerated with the new parameters.
827
+ #
828
+ # @example
829
+ # definition = Sketchup.active_model.definitions[0]
830
+ # # Assuming the definition is procedural and has a procedure attached
831
+ # definition.set_procedure_parameters(count: 5, spacing: 10.0)
832
+ #
833
+ # @param [Hash{Symbol, String => Integer, Float, String, Boolean}] parameters
834
+ # A hash of parameter identifier symbols/strings to values. The parameter identifiers (hash
835
+ # keys) must match those declared in the procedure's {Sketchup::Procedure#declare_params_and_ui}
836
+ # method.
837
+ #
838
+ # @raise [TypeError] If this definition is not procedural.
839
+ #
840
+ # @raise [ArgumentError] If the parameters are invalid for the attached procedure.
841
+ #
842
+ # @see Sketchup::Procedure#declare_params_and_ui
843
+ #
844
+ # @see Sketchup::ComponentDefinition#attach_procedure
845
+ #
846
+ # @version SketchUp 2027.0
847
+ def set_procedure_parameters(parameters)
848
+ end
849
+
638
850
  # The {#thumbnail_camera} method is used to retrieve a camera representing
639
851
  # the thumbnail associated with the component definition.
640
852
  #
@@ -194,6 +194,35 @@ class Sketchup::ComponentInstance < Sketchup::Drawingelement
194
194
  def guid
195
195
  end
196
196
 
197
+ # Retrieves the hatch pattern assigned to the component instance.
198
+ #
199
+ # @example
200
+ # instance = Sketchup.active_model.entities[0]
201
+ # puts instance.hatch_pattern.name
202
+ #
203
+ # @return [Sketchup::HatchPattern, nil]
204
+ #
205
+ # @version SketchUp 2027.0
206
+ def hatch_pattern
207
+ end
208
+
209
+ # Assigns a hatch pattern to the component instance.
210
+ #
211
+ # @example
212
+ # model = Sketchup.active_model
213
+ # hatch_patterns = model.hatch_patterns
214
+ # instance = model.entities[0]
215
+ # instance.hatch_pattern = hatch_patterns['Pattern1']
216
+ #
217
+ # @param [Sketchup::HatchPattern, nil] pattern
218
+ # the pattern to assign, or +nil+ to clear the assignment.
219
+ #
220
+ # @raise [ArgumentError] if the pattern does not belong to the component instance's model.
221
+ #
222
+ # @version SketchUp 2027.0
223
+ def hatch_pattern=(pattern)
224
+ end
225
+
197
226
  # The intersect method is used to compute the boolean intersection of two
198
227
  # instances representing manifold solid volumes (this - arg). If the specified
199
228
  # objects (this and arg) do not represent manifold volumes, this method fails.
@@ -276,6 +305,9 @@ class Sketchup::ComponentInstance < Sketchup::Drawingelement
276
305
 
277
306
  # The manifold? method is used to determine if an instance is manifold.
278
307
  #
308
+ # @deprecated Use {Sketchup::ComponentDefinition#manifold?} instead. This method
309
+ # checks the definition, not the instance.
310
+ #
279
311
  # @example
280
312
  # entities = Sketchup.active_model.entities
281
313
  # definition = Sketchup.active_model.definitions[0]
@@ -285,6 +317,8 @@ class Sketchup::ComponentInstance < Sketchup::Drawingelement
285
317
  #
286
318
  # @return [Boolean]
287
319
  #
320
+ # @see Sketchup::ComponentDefinition#manifold?
321
+ #
288
322
  # @version SketchUp 8.0
289
323
  def manifold?
290
324
  end
@@ -420,30 +454,65 @@ class Sketchup::ComponentInstance < Sketchup::Drawingelement
420
454
  def show_differences(instance, verbose)
421
455
  end
422
456
 
423
- # The split method is used to compute the boolean split (map overlay)of the two
424
- # instances representing manifold solid volumes (this - arg). If the specified
425
- # objects (this and arg) do not represent manifold volumes, this method fails.
457
+ # The {#split} method performs a boolean "split" (map overlay) between this
458
+ # component instance (the receiver) and another manifold solid (group or
459
+ # component instance). The operation partitions the combined volumes into:
460
+ #
461
+ # - Difference2: (other - self)
462
+ # - Difference1: (self - other)
463
+ # - Intersection: (self ∩ other)
426
464
  #
427
- # resultant groups if the two objects (this and arg) represent manifold solids and the operation
428
- # succeeds otherwise nil is returned. The 3 groups are as follows: The intersection of volume 1 &
429
- # volume 2, the difference of volume 1 minus volume 2, and the reverse difference of volume 2 minus
430
- # volume 1.
465
+ # The originals (self and other) are ERASED and replaced by three newly created
466
+ # groups representing these volumes.
431
467
  #
432
468
  # @example
433
- # entities = Sketchup.active_model.entities
434
- # instance1 = entities[0]
435
- # instance2 = entities[1]
436
- # result = instance1.split(instance2)
469
+ # model = Sketchup.active_model
470
+ # g1 = model.entities.add_group
471
+ # g1.entities.add_face([0, 0, 0], [100, 0, 0], [100, 100, 0], [0, 100, 0]).pushpull(50)
472
+ # g2 = model.entities.add_group
473
+ # g2.entities.add_face([50, -25, 0], [150, -25, 0], [150, 75, 0], [50, 75, 0]).pushpull(50)
474
+ # diff2, diff1, inter = g1.to_component.split(g2) # Order: Difference2, Difference1, Intersection
475
+ # puts [diff2.name, diff1.name, inter.name] # => ["Difference2","Difference1","Intersection"]
437
476
  #
438
- # @note This method is not available in SketchUp Make.
477
+ # @note Both operands must be manifold solids (see {#manifold?}). Non‑manifold
478
+ # geometry returns +nil+.
479
+ #
480
+ # @note The returned groups are always new objects; any prior references to the
481
+ # original receiver or argument are invalid after this call.
482
+ #
483
+ # @note All three result groups are placed on Layer0, regardless of original
484
+ # layer assignments.
485
+ #
486
+ # @note Materials and attribute dictionaries are not fully preserved. Faces
487
+ # with default materials may inherit what was previously a container
488
+ # material; new faces get the default material.
489
+ #
490
+ # @note The Intersection group can be empty (contain no geometry) when volumes
491
+ # only touch or one lies entirely within the other without producing new
492
+ # partitioning geometry.
493
+ #
494
+ # @note Undo will restore pre‑split objects but object references you held
495
+ # beforehand become stale; reacquire them if needed.
496
+ #
497
+ # @note Not available in SketchUp Make.
498
+ #
499
+ # @param [Sketchup::ComponentInstance, Sketchup::Group] other
500
+ # The other solid to split with.
501
+ #
502
+ # @return [Array(Sketchup::Group, Sketchup::Group, Sketchup::Group), nil] Returns an Array of three new groups [Difference2, Difference1, Intersection]
503
+ # on success, or +nil+ if either operand is not a manifold solid or the
504
+ # operation fails.
505
+ #
506
+ # @see #union
507
+ #
508
+ # @see #intersect
439
509
  #
440
- # @param [Sketchup::ComponentInstance, nil] instance
441
- # The instance to split this instance with.
510
+ # @see #subtract
442
511
  #
443
- # @return [Array(Sketchup::Group, Sketchup::Group, Sketchup::Group)] A vector (array) of the three
512
+ # @see #trim
444
513
  #
445
514
  # @version SketchUp 8.0
446
- def split(instance)
515
+ def split(other)
447
516
  end
448
517
 
449
518
  # The subtract method is used to compute the boolean difference of the two
@@ -31,7 +31,7 @@ class Sketchup::Curve < Sketchup::Entity
31
31
  # curve = edge.curve
32
32
  # number = curve.count_edges
33
33
  #
34
- # @return num_edges - the number of edges in the curve
34
+ # @return [Integer]
35
35
  #
36
36
  # @version SketchUp 6.0
37
37
  def count_edges
@@ -52,10 +52,13 @@ class Sketchup::Curve < Sketchup::Entity
52
52
  # curve = edge.curve
53
53
  # curve.each_edge {|edge| puts "Edge {edge.entityID}: {edge.length}" }
54
54
  #
55
- # @return edge - a variable that will hold each Edge object as
56
- # they are found.
55
+ # @return [nil]
57
56
  #
58
57
  # @version SketchUp 6.0
58
+ #
59
+ # @yield [edge] Each edge associated with this curve.
60
+ #
61
+ # @yieldparam [Sketchup::Edge] edge
59
62
  def each_edge
60
63
  end
61
64
 
@@ -74,7 +77,7 @@ class Sketchup::Curve < Sketchup::Entity
74
77
  # curve = edge.curve
75
78
  # edges = curve.edges
76
79
  #
77
- # @return edges - an array of Edge objects if successful
80
+ # @return [Array<Sketchup::Edge>]
78
81
  #
79
82
  # @version SketchUp 6.0
80
83
  def edges
@@ -94,7 +97,7 @@ class Sketchup::Curve < Sketchup::Entity
94
97
  # curve = edge.curve
95
98
  # firstedge = curve.first_edge
96
99
  #
97
- # @return edge - the first Edge object in the curve if successful
100
+ # @return [Sketchup::Edge]
98
101
  #
99
102
  # @version SketchUp 6.0
100
103
  def first_edge
@@ -109,8 +112,7 @@ class Sketchup::Curve < Sketchup::Entity
109
112
  # ents.each { |e| curve = e.curve if e.is_a? Sketchup::Edge }
110
113
  # is_poly = curve.is_polygon?
111
114
  #
112
- # @return [Boolean] True if this edge was originally created by the polygon
113
- # tool, otherwise false.
115
+ # @return [Boolean]
114
116
  #
115
117
  # @version SketchUp 7.1 M1
116
118
  def is_polygon?
@@ -130,7 +132,7 @@ class Sketchup::Curve < Sketchup::Entity
130
132
  # curve = edge.curve
131
133
  # lastedge = curve.last_edge
132
134
  #
133
- # @return edge - the last Edge object in the curve if successful
135
+ # @return [Sketchup::Edge]
134
136
  #
135
137
  # @version SketchUp 6.0
136
138
  def last_edge
@@ -192,7 +194,7 @@ class Sketchup::Curve < Sketchup::Entity
192
194
  # curve = edge.curve
193
195
  # vertices = curve.vertices
194
196
  #
195
- # @return vertices - a collection of the vertices
197
+ # @return [Array<Sketchup::Vertex>] - a collection of the vertices
196
198
  #
197
199
  # @version SketchUp 6.0
198
200
  def vertices
@@ -358,12 +358,16 @@ class Sketchup::DefinitionList < Sketchup::Entity
358
358
  def load_from_url(*args)
359
359
  end
360
360
 
361
- # The purge_unused method is used to remove the unused component definitions.
361
+ # The {#purge_unused} method is used to remove the unused component definitions.
362
362
  #
363
363
  # @example
364
364
  # definitions = Sketchup.active_model.definitions
365
365
  # definitions.purge_unused
366
366
  #
367
+ # @note Silently purging can cause data loss.
368
+ # The user may have deleted the last instance but intend to place new ones later.
369
+ # Don't purge without the user's knowledge and approval.
370
+ #
367
371
  # @return [Sketchup::DefinitionList]
368
372
  #
369
373
  # @version SketchUp 6.0
@@ -32,7 +32,7 @@ class Sketchup::Dimension < Sketchup::Drawingelement
32
32
  # @param observer
33
33
  # A DimensionObserver.
34
34
  #
35
- # @return true if successful, false if unsuccessful.
35
+ # @return [Boolean] true if successful, false if unsuccessful.
36
36
  #
37
37
  # @version SketchUp 2014
38
38
  def add_observer(observer)
@@ -53,7 +53,7 @@ class Sketchup::Dimension < Sketchup::Drawingelement
53
53
  # puts "Arrow type is closed"
54
54
  # end
55
55
  #
56
- # @return a numerical representation of the arrow type
56
+ # @return [Integer] a numerical representation of the arrow type
57
57
  #
58
58
  # @version SketchUp 2014
59
59
  def arrow_type
@@ -100,7 +100,7 @@ class Sketchup::Dimension < Sketchup::Drawingelement
100
100
  # @example
101
101
  # aligned = dim.has_aligned_text?
102
102
  #
103
- # @return [Boolean] status - true if text is aligned to the dimension.
103
+ # @return [Boolean] - true if text is aligned to the dimension.
104
104
  # False if dimension text is aligned to the screen.
105
105
  #
106
106
  # @version SketchUp 2014
@@ -113,7 +113,7 @@ class Sketchup::Dimension < Sketchup::Drawingelement
113
113
  # @example
114
114
  # plane = dim.plane
115
115
  #
116
- # @return the plane of the dimension
116
+ # @return [Float, Float, Float, Float]
117
117
  #
118
118
  # @version SketchUp 2014
119
119
  def plane
@@ -134,7 +134,7 @@ class Sketchup::Dimension < Sketchup::Drawingelement
134
134
  # @param observer
135
135
  # A DimensionObserver.
136
136
  #
137
- # @return true if successful, false if unsuccessful.
137
+ # @return [Boolean] true if successful, false if unsuccessful.
138
138
  #
139
139
  # @version SketchUp 2014
140
140
  def remove_observer(observer)
@@ -145,7 +145,7 @@ class Sketchup::Dimension < Sketchup::Drawingelement
145
145
  # @example
146
146
  # dimtext = dim.text
147
147
  #
148
- # @return the dimension text
148
+ # @return [String] the dimension text
149
149
  #
150
150
  # @version SketchUp 2014
151
151
  def text
@@ -35,7 +35,7 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
35
35
  # puts 'Text is outside'
36
36
  # end
37
37
  #
38
- # @return an integer specifying the text position
38
+ # @return [Integer]
39
39
  #
40
40
  # @version SketchUp 2014
41
41
  def aligned_text_position
@@ -51,8 +51,8 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
51
51
  # @example
52
52
  # dim.aligned_text_position = Sketchup::DimensionLinear::ALIGNED_TEXT_CENTER
53
53
  #
54
- # @param pos
55
- # an integer specifying the text position
54
+ # @param [Integer] pos
55
+ #
56
56
  #
57
57
  # @return the text position that was set.
58
58
  #
@@ -60,7 +60,7 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
60
60
  def aligned_text_position=(pos)
61
61
  end
62
62
 
63
- # The end method returns the point or entity the dimension is referencing at
63
+ # The end method returns the point and optional entity the dimension is referencing at
64
64
  # its end.
65
65
  #
66
66
  # @example
@@ -71,7 +71,8 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
71
71
  # puts "Attached entity: #{arr[0]}, at point #{arr[1]}"
72
72
  # end
73
73
  #
74
- # @return Array - An array of size 2:
74
+ # @return [Array(Sketchup::Entity, Geom::Point3d), Array(nil, Geom::Point3d)] - An
75
+ # array of size 2:
75
76
  # - Entity being referenced or nil if not associated.
76
77
  # - Point3d that contains the referenced location.
77
78
  #
@@ -126,6 +127,9 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
126
127
  # The {#end_attached_to=} method will attach the ending point to the
127
128
  # {Sketchup::InstancePath} and {Geom::Point3d}.
128
129
  #
130
+ # @bug Prior to SketchUp 2026.2 could move the {Sketchup::ConstructionPoint} contained
131
+ # in the instance path.
132
+ #
129
133
  # @example
130
134
  # # Assuming you have a valid dimension selected that is attached to a
131
135
  # # component instance
@@ -156,7 +160,7 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
156
160
  # vec = dim.offset_vector
157
161
  # puts "Offset vector is #{vec.to_s}"
158
162
  #
159
- # @return offset vector as a Vector3d
163
+ # @return [Geom::Vector3d]
160
164
  #
161
165
  # @version SketchUp 2014
162
166
  def offset_vector
@@ -175,7 +179,7 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
175
179
  def offset_vector=(offset_vector)
176
180
  end
177
181
 
178
- # The start method returns the point or entity the dimension is referencing at
182
+ # The start method returns the point and optional entity the dimension is referencing at
179
183
  # its start.
180
184
  #
181
185
  # @example
@@ -186,7 +190,8 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
186
190
  # puts "Attached entity: #{arr[0]}, at point #{arr[1]}"
187
191
  # end
188
192
  #
189
- # @return Array - An array of size 2:
193
+ # @return [Array(Sketchup::Entity, Geom::Point3d), Array(nil, Geom::Point3d)] - An
194
+ # array of size 2:
190
195
  # - Entity being referenced or nil if not associated.
191
196
  # - Point3d that contains the referenced location.
192
197
  #
@@ -241,6 +246,9 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
241
246
  # The {#start_attached_to=} method will attach the starting point to the
242
247
  # {Sketchup::InstancePath} and {Geom::Point3d}.
243
248
  #
249
+ # @bug Prior to SketchUp 2026.2 could move the {Sketchup::ConstructionPoint} contained
250
+ # in the instance path.
251
+ #
244
252
  # @example
245
253
  # # Assuming you have a valid dimension selected that is attached to a
246
254
  # # component instance
@@ -279,7 +287,7 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
279
287
  # puts 'Text position is Outside end'
280
288
  # end
281
289
  #
282
- # @return an integer specifying the text position
290
+ # @return [Integer]
283
291
  #
284
292
  # @version SketchUp 2014
285
293
  def text_position
@@ -294,8 +302,8 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
294
302
  # @example
295
303
  # dim.text_position = Sketchup::DimensionLinear::TEXT_CENTERED
296
304
  #
297
- # @param pos
298
- # an integer specifying the text position
305
+ # @param [Integer] pos
306
+ #
299
307
  #
300
308
  # @return the text position that was set.
301
309
  #