sketchup-api-stubs 0.7.4 → 0.7.8

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 (151) hide show
  1. checksums.yaml +4 -4
  2. data/lib/sketchup-api-stubs/sketchup.rb +148 -145
  3. data/lib/sketchup-api-stubs/stubs/{array.rb → Array.rb} +741 -741
  4. data/lib/sketchup-api-stubs/stubs/Geom/BoundingBox.rb +322 -318
  5. data/lib/sketchup-api-stubs/stubs/Geom/Bounds2d.rb +172 -172
  6. data/lib/sketchup-api-stubs/stubs/Geom/LatLong.rb +126 -126
  7. data/lib/sketchup-api-stubs/stubs/Geom/OrientedBounds2d.rb +102 -102
  8. data/lib/sketchup-api-stubs/stubs/Geom/Point2d.rb +400 -400
  9. data/lib/sketchup-api-stubs/stubs/Geom/Point3d.rb +661 -661
  10. data/lib/sketchup-api-stubs/stubs/Geom/PolygonMesh.rb +523 -492
  11. data/lib/sketchup-api-stubs/stubs/Geom/Transformation.rb +478 -478
  12. data/lib/sketchup-api-stubs/stubs/Geom/Transformation2d.rb +263 -263
  13. data/lib/sketchup-api-stubs/stubs/Geom/UTM.rb +141 -141
  14. data/lib/sketchup-api-stubs/stubs/Geom/Vector2d.rb +522 -522
  15. data/lib/sketchup-api-stubs/stubs/Geom/Vector3d.rb +693 -691
  16. data/lib/sketchup-api-stubs/stubs/{geom.rb → Geom.rb} +351 -348
  17. data/lib/sketchup-api-stubs/stubs/{languagehandler.rb → LanguageHandler.rb} +93 -92
  18. data/lib/sketchup-api-stubs/stubs/Layout/AngularDimension.rb +595 -573
  19. data/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinition.rb +698 -411
  20. data/lib/sketchup-api-stubs/stubs/Layout/AutoTextDefinitions.rb +183 -174
  21. data/lib/sketchup-api-stubs/stubs/Layout/ConnectionPoint.rb +70 -70
  22. data/lib/sketchup-api-stubs/stubs/Layout/Document.rb +516 -514
  23. data/lib/sketchup-api-stubs/stubs/Layout/Ellipse.rb +29 -29
  24. data/lib/sketchup-api-stubs/stubs/Layout/Entities.rb +148 -143
  25. data/lib/sketchup-api-stubs/stubs/Layout/Entity.rb +353 -353
  26. data/lib/sketchup-api-stubs/stubs/Layout/FormattedText.rb +354 -349
  27. data/lib/sketchup-api-stubs/stubs/Layout/Grid.rb +311 -311
  28. data/lib/sketchup-api-stubs/stubs/Layout/Group.rb +261 -261
  29. data/lib/sketchup-api-stubs/stubs/Layout/Image.rb +91 -91
  30. data/lib/sketchup-api-stubs/stubs/Layout/Label.rb +370 -371
  31. data/lib/sketchup-api-stubs/stubs/Layout/Layer.rb +218 -218
  32. data/lib/sketchup-api-stubs/stubs/Layout/LayerInstance.rb +128 -128
  33. data/lib/sketchup-api-stubs/stubs/Layout/Layers.rb +225 -220
  34. data/lib/sketchup-api-stubs/stubs/Layout/LinearDimension.rb +567 -567
  35. data/lib/sketchup-api-stubs/stubs/Layout/LockedEntityError.rb +10 -10
  36. data/lib/sketchup-api-stubs/stubs/Layout/LockedLayerError.rb +11 -11
  37. data/lib/sketchup-api-stubs/stubs/Layout/Page.rb +183 -183
  38. data/lib/sketchup-api-stubs/stubs/Layout/PageInfo.rb +387 -387
  39. data/lib/sketchup-api-stubs/stubs/Layout/Pages.rb +209 -204
  40. data/lib/sketchup-api-stubs/stubs/Layout/Path.rb +344 -344
  41. data/lib/sketchup-api-stubs/stubs/Layout/Rectangle.rb +174 -174
  42. data/lib/sketchup-api-stubs/stubs/Layout/SketchUpModel.rb +692 -694
  43. data/lib/sketchup-api-stubs/stubs/Layout/Style.rb +1519 -1519
  44. data/lib/sketchup-api-stubs/stubs/Layout/Table.rb +290 -290
  45. data/lib/sketchup-api-stubs/stubs/Layout/TableCell.rb +149 -149
  46. data/lib/sketchup-api-stubs/stubs/Layout/TableColumn.rb +139 -139
  47. data/lib/sketchup-api-stubs/stubs/Layout/TableRow.rb +135 -135
  48. data/lib/sketchup-api-stubs/stubs/Layout.rb +25 -25
  49. data/lib/sketchup-api-stubs/stubs/{length.rb → Length.rb} +278 -278
  50. data/lib/sketchup-api-stubs/stubs/{numeric.rb → Numeric.rb} +249 -249
  51. data/lib/sketchup-api-stubs/stubs/Sketchup/Animation.rb +144 -140
  52. data/lib/sketchup-api-stubs/stubs/Sketchup/AppObserver.rb +169 -157
  53. data/lib/sketchup-api-stubs/stubs/Sketchup/ArcCurve.rb +209 -209
  54. data/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionaries.rb +152 -152
  55. data/lib/sketchup-api-stubs/stubs/Sketchup/AttributeDictionary.rb +286 -281
  56. data/lib/sketchup-api-stubs/stubs/Sketchup/Axes.rb +149 -149
  57. data/lib/sketchup-api-stubs/stubs/Sketchup/Behavior.rb +302 -328
  58. data/lib/sketchup-api-stubs/stubs/Sketchup/Camera.rb +478 -577
  59. data/lib/sketchup-api-stubs/stubs/Sketchup/ClassificationSchema.rb +63 -63
  60. data/lib/sketchup-api-stubs/stubs/Sketchup/Classifications.rb +122 -122
  61. data/lib/sketchup-api-stubs/stubs/Sketchup/Color.rb +294 -281
  62. data/lib/sketchup-api-stubs/stubs/Sketchup/ComponentDefinition.rb +619 -562
  63. data/lib/sketchup-api-stubs/stubs/Sketchup/ComponentInstance.rb +593 -593
  64. data/lib/sketchup-api-stubs/stubs/Sketchup/Console.rb +76 -76
  65. data/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionLine.rb +257 -257
  66. data/lib/sketchup-api-stubs/stubs/Sketchup/ConstructionPoint.rb +32 -32
  67. data/lib/sketchup-api-stubs/stubs/Sketchup/Curve.rb +201 -194
  68. data/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionList.rb +426 -329
  69. data/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionObserver.rb +74 -72
  70. data/lib/sketchup-api-stubs/stubs/Sketchup/DefinitionsObserver.rb +104 -102
  71. data/lib/sketchup-api-stubs/stubs/Sketchup/Dimension.rb +165 -165
  72. data/lib/sketchup-api-stubs/stubs/Sketchup/DimensionLinear.rb +306 -312
  73. data/lib/sketchup-api-stubs/stubs/Sketchup/DimensionObserver.rb +42 -38
  74. data/lib/sketchup-api-stubs/stubs/Sketchup/DimensionRadial.rb +87 -87
  75. data/lib/sketchup-api-stubs/stubs/Sketchup/Drawingelement.rb +396 -390
  76. data/lib/sketchup-api-stubs/stubs/Sketchup/Edge.rb +502 -508
  77. data/lib/sketchup-api-stubs/stubs/Sketchup/EdgeUse.rb +211 -211
  78. data/lib/sketchup-api-stubs/stubs/Sketchup/Entities.rb +1205 -1119
  79. data/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesBuilder.rb +272 -0
  80. data/lib/sketchup-api-stubs/stubs/Sketchup/EntitiesObserver.rb +127 -125
  81. data/lib/sketchup-api-stubs/stubs/Sketchup/Entity.rb +545 -544
  82. data/lib/sketchup-api-stubs/stubs/Sketchup/EntityObserver.rb +60 -59
  83. data/lib/sketchup-api-stubs/stubs/Sketchup/ExtensionsManager.rb +126 -125
  84. data/lib/sketchup-api-stubs/stubs/Sketchup/Face.rb +937 -750
  85. data/lib/sketchup-api-stubs/stubs/Sketchup/FrameChangeObserver.rb +104 -104
  86. data/lib/sketchup-api-stubs/stubs/Sketchup/Group.rb +750 -697
  87. data/lib/sketchup-api-stubs/stubs/Sketchup/Http/Request.rb +292 -285
  88. data/lib/sketchup-api-stubs/stubs/Sketchup/Http/Response.rb +62 -62
  89. data/lib/sketchup-api-stubs/stubs/Sketchup/Http.rb +27 -27
  90. data/lib/sketchup-api-stubs/stubs/Sketchup/Image.rb +468 -409
  91. data/lib/sketchup-api-stubs/stubs/Sketchup/ImageRep.rb +266 -226
  92. data/lib/sketchup-api-stubs/stubs/Sketchup/Importer.rb +189 -190
  93. data/lib/sketchup-api-stubs/stubs/Sketchup/InputPoint.rb +407 -393
  94. data/lib/sketchup-api-stubs/stubs/Sketchup/InstanceObserver.rb +84 -82
  95. data/lib/sketchup-api-stubs/stubs/Sketchup/InstancePath.rb +306 -303
  96. data/lib/sketchup-api-stubs/stubs/Sketchup/Layer.rb +326 -285
  97. data/lib/sketchup-api-stubs/stubs/Sketchup/LayerFolder.rb +422 -0
  98. data/lib/sketchup-api-stubs/stubs/Sketchup/Layers.rb +427 -244
  99. data/lib/sketchup-api-stubs/stubs/Sketchup/LayersObserver.rb +249 -136
  100. data/lib/sketchup-api-stubs/stubs/Sketchup/Licensing/ExtensionLicense.rb +86 -86
  101. data/lib/sketchup-api-stubs/stubs/Sketchup/Licensing.rb +48 -48
  102. data/lib/sketchup-api-stubs/stubs/Sketchup/LineStyle.rb +24 -24
  103. data/lib/sketchup-api-stubs/stubs/Sketchup/LineStyles.rb +112 -112
  104. data/lib/sketchup-api-stubs/stubs/Sketchup/Loop.rb +137 -137
  105. data/lib/sketchup-api-stubs/stubs/Sketchup/Material.rb +414 -416
  106. data/lib/sketchup-api-stubs/stubs/Sketchup/Materials.rb +318 -311
  107. data/lib/sketchup-api-stubs/stubs/Sketchup/MaterialsObserver.rb +142 -141
  108. data/lib/sketchup-api-stubs/stubs/Sketchup/Menu.rb +93 -95
  109. data/lib/sketchup-api-stubs/stubs/Sketchup/Model.rb +1651 -1638
  110. data/lib/sketchup-api-stubs/stubs/Sketchup/ModelObserver.rb +357 -356
  111. data/lib/sketchup-api-stubs/stubs/Sketchup/OptionsManager.rb +131 -132
  112. data/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProvider.rb +284 -284
  113. data/lib/sketchup-api-stubs/stubs/Sketchup/OptionsProviderObserver.rb +58 -58
  114. data/lib/sketchup-api-stubs/stubs/Sketchup/Page.rb +797 -770
  115. data/lib/sketchup-api-stubs/stubs/Sketchup/Pages.rb +363 -353
  116. data/lib/sketchup-api-stubs/stubs/Sketchup/PagesObserver.rb +77 -76
  117. data/lib/sketchup-api-stubs/stubs/Sketchup/PickHelper.rb +477 -456
  118. data/lib/sketchup-api-stubs/stubs/Sketchup/RegionalSettings.rb +43 -43
  119. data/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptions.rb +364 -364
  120. data/lib/sketchup-api-stubs/stubs/Sketchup/RenderingOptionsObserver.rb +45 -44
  121. data/lib/sketchup-api-stubs/stubs/Sketchup/SectionPlane.rb +150 -150
  122. data/lib/sketchup-api-stubs/stubs/Sketchup/Selection.rb +459 -454
  123. data/lib/sketchup-api-stubs/stubs/Sketchup/SelectionObserver.rb +115 -115
  124. data/lib/sketchup-api-stubs/stubs/Sketchup/Set.rb +212 -212
  125. data/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfo.rb +260 -257
  126. data/lib/sketchup-api-stubs/stubs/Sketchup/ShadowInfoObserver.rb +59 -57
  127. data/lib/sketchup-api-stubs/stubs/Sketchup/Skp.rb +40 -0
  128. data/lib/sketchup-api-stubs/stubs/Sketchup/Style.rb +69 -69
  129. data/lib/sketchup-api-stubs/stubs/Sketchup/Styles.rb +217 -211
  130. data/lib/sketchup-api-stubs/stubs/Sketchup/Text.rb +262 -262
  131. data/lib/sketchup-api-stubs/stubs/Sketchup/Texture.rb +217 -225
  132. data/lib/sketchup-api-stubs/stubs/Sketchup/TextureWriter.rb +237 -237
  133. data/lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb +837 -829
  134. data/lib/sketchup-api-stubs/stubs/Sketchup/Tools.rb +132 -132
  135. data/lib/sketchup-api-stubs/stubs/Sketchup/ToolsObserver.rb +156 -154
  136. data/lib/sketchup-api-stubs/stubs/Sketchup/UVHelper.rb +75 -61
  137. data/lib/sketchup-api-stubs/stubs/Sketchup/Vertex.rb +142 -142
  138. data/lib/sketchup-api-stubs/stubs/Sketchup/View.rb +1317 -1301
  139. data/lib/sketchup-api-stubs/stubs/Sketchup/ViewObserver.rb +45 -43
  140. data/lib/sketchup-api-stubs/stubs/{sketchup.rb → Sketchup.rb} +1360 -1310
  141. data/lib/sketchup-api-stubs/stubs/{sketchupextension.rb → SketchupExtension.rb} +353 -353
  142. data/lib/sketchup-api-stubs/stubs/{string.rb → String.rb} +24 -24
  143. data/lib/sketchup-api-stubs/stubs/UI/Command.rb +389 -310
  144. data/lib/sketchup-api-stubs/stubs/UI/HtmlDialog.rb +496 -356
  145. data/lib/sketchup-api-stubs/stubs/UI/Notification.rb +269 -229
  146. data/lib/sketchup-api-stubs/stubs/UI/Toolbar.rb +240 -240
  147. data/lib/sketchup-api-stubs/stubs/UI/WebDialog.rb +635 -633
  148. data/lib/sketchup-api-stubs/stubs/{ui.rb → UI.rb} +683 -667
  149. data/lib/sketchup-api-stubs/stubs/_top_level.rb +311 -311
  150. data/lib/sketchup-api-stubs.rb +1 -1
  151. metadata +15 -12
@@ -1,311 +1,318 @@
1
- # Copyright:: Copyright 2020 Trimble Inc.
2
- # License:: The MIT License (MIT)
3
-
4
- # A collection of Materials objects. Each model contains a Materials collection
5
- # that can be accessed via Model.materials.
6
- #
7
- # @example
8
- # # Get a handle to all the materials in the current model.
9
- # model = Sketchup.active_model
10
- # materials = model.materials
11
- #
12
- # @version SketchUp 6.0
13
- class Sketchup::Materials < Sketchup::Entity
14
-
15
- # Includes
16
-
17
- include Enumerable
18
-
19
- # Instance Methods
20
-
21
- # The {#[]} method is used to retrieve a material by index or name.
22
- #
23
- # The {#at} method is an alias of {#[]}
24
- #
25
- # @example
26
- # model = Sketchup.active_model
27
- # materials = model.materials
28
- # material = materials[0]
29
- #
30
- # @overload [](index)
31
- #
32
- # @param index [Integer] A number representing the material's index in an array
33
- # of Material objects.
34
- # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
35
- #
36
- # @overload [](name)
37
- #
38
- # @param name [String] The name of the material.
39
- # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
40
- #
41
- # @version SketchUp 6.0
42
- def [](arg)
43
- end
44
-
45
- # Add a new Material. When called with no arguments, this will generate a
46
- # new unique name for the new Material. If a name is given, it will check
47
- # to see if there is already a material with that name. If there is already
48
- # a material with the given name, then a new unique name is generated using
49
- # the given name as a base.
50
- #
51
- # @example
52
- # model = Sketchup.active_model
53
- # materials = model.materials
54
- # material = materials.add('Joe')
55
- #
56
- # @param [String] name
57
- # The name of the new material.
58
- #
59
- # @return [Sketchup::Material] a Material object
60
- #
61
- # @version SketchUp 6.0
62
- def add(name)
63
- end
64
-
65
- # The add_observer method is used to add an observer to the materials
66
- # collection.
67
- #
68
- # @example
69
- # materials = Sketchup.active_model.materials
70
- # status = materials.add_observer(observer)
71
- #
72
- # @param [Object] observer
73
- # An observer.
74
- #
75
- # @return [Boolean] true if successful, false if unsuccessful.
76
- #
77
- # @version SketchUp 6.0
78
- def add_observer(observer)
79
- end
80
-
81
- # The {#[]} method is used to retrieve a material by index or name.
82
- #
83
- # The {#at} method is an alias of {#[]}
84
- #
85
- # @example
86
- # model = Sketchup.active_model
87
- # materials = model.materials
88
- # material = materials[0]
89
- #
90
- # @overload [](index)
91
- #
92
- # @param index [Integer] A number representing the material's index in an array
93
- # of Material objects.
94
- # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
95
- #
96
- # @overload [](name)
97
- #
98
- # @param name [String] The name of the material.
99
- # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
100
- #
101
- # @version SketchUp 6.0
102
- def at(arg)
103
- end
104
-
105
- #
106
- # @example
107
- # materials = Sketchup.active_model.materials
108
- # count = materials.count
109
- #
110
- # @note Since SketchUp 2014 the count method is inherited from Ruby's
111
- # +Enumable+ mix-in module. Prior to that the {#count} method is an alias
112
- # for {#length}.
113
- #
114
- # @return [Integer]
115
- #
116
- # @see #length
117
- #
118
- # @version SketchUp 6.0
119
- def count
120
- end
121
-
122
- # The current method is used to get the current material, i.e. the material
123
- # that the user has selected in the Materials dialog.
124
- #
125
- # @example
126
- # current = Sketchup.active_model.materials.current
127
- #
128
- # @return [Sketchup::Material] a Material object.
129
- #
130
- # @version SketchUp 6.0
131
- def current
132
- end
133
-
134
- # The current= method is used to set the current material.
135
- #
136
- # @example
137
- # # Make the first material in the model "current"
138
- # materials = Sketchup.active_model.materials
139
- # materials.current = materials[0]
140
- #
141
- # @param [Sketchup::Material] material
142
- # A Material object.
143
- #
144
- # @return [Sketchup::Material]
145
- #
146
- # @version SketchUp 6.0
147
- def current=(material)
148
- end
149
-
150
- # The each method is used to iterate through all of the materials.
151
- #
152
- # @example
153
- # model = Sketchup.active_model
154
- # model.materials.each { |material|
155
- # puts material.display_name
156
- # }
157
- #
158
- # @return [nil]
159
- #
160
- # @version SketchUp 6.0
161
- #
162
- # @yield [Sketchup::Material] A variable that will hold each Material object as they
163
- # are found.
164
- def each
165
- end
166
-
167
- # The number of materials in the collection.
168
- #
169
- # @example
170
- # materials = Sketchup.active_model.materials
171
- # number = materials.length
172
- #
173
- # @note The returned number includes {Sketchup::Image} materials as well.
174
- # It will not reflect the number of materials yielded by {#each}. To get
175
- # the number of non-image materials use {#count} or +materials.to_a.size+.
176
- #
177
- # @return [Integer]
178
- #
179
- # @see #size
180
- #
181
- # @version SketchUp 6.0
182
- def length
183
- end
184
-
185
- # The {#load} method is used to load a material from file into the model.
186
- #
187
- # If a matching material exist in the model that will be returned instead.
188
- #
189
- # @example
190
- # # Load a material from the shipped SketchUp library. (SketchUp 2016)
191
- # filename = 'Materials/Brick, Cladding and Siding/Cinder Block.skm'
192
- # path = Sketchup.find_support_file(filename)
193
- # materials = Sketchup.active_model.materials
194
- # material = materials.load(path)
195
- #
196
- # @param [String] filename
197
- # the path to the SKM file to load.
198
- #
199
- # @raise [RuntimeError] if the material failed to load.
200
- #
201
- # @return [Sketchup::Material] the new loaded material, or existing material.
202
- #
203
- # @version SketchUp 2017
204
- def load(filename)
205
- end
206
-
207
- # The purge_unused method is used to remove unused materials.
208
- #
209
- # @example
210
- # materials = Sketchup.active_model.materials
211
- # materials.purge_unused
212
- #
213
- # @return [Sketchup::Materials] The Materials object.
214
- #
215
- # @version SketchUp 6.0
216
- def purge_unused
217
- end
218
-
219
- # Remove a given material.
220
- #
221
- # NOTE: On SketchUp versions prior to 2014 there is a bug in this method that
222
- # could potentially lead to file corruption. If you call Materials.remove on a
223
- # material that is painted onto any entity in the active model (e.g. faces,
224
- # edges, groups, ...), then calling this method will not successfully unpaint
225
- # the entity and remove the material from the model.
226
- # You must first unpaint all of the entities that respond to .material
227
- # and .back_material before calling Materials.remove.
228
- #
229
- # @example
230
- # if entity.respond_to?(:material) do
231
- # if entity.material.equal?(material_to_remove) do
232
- # entity.material = nil
233
- # end
234
- # end
235
- # # for entities that have a back material
236
- # if entity.respond_to?(:back_material) do
237
- # if entity.back_material.equal?(material_to_remove) do
238
- # entity.back_material = nil
239
- # end
240
- # end
241
- #
242
- # @example
243
- # model = Sketchup.active_model
244
- # materials = model.materials
245
- # material = materials.add('Joe')
246
- # materials.remove(material)
247
- #
248
- # @param [Sketchup::Material] material
249
- # The material to remove.
250
- #
251
- # @return [Boolean] true if successful, false if unsuccessful.
252
- #
253
- # @version SketchUp 8.0 M1
254
- def remove(material)
255
- end
256
-
257
- # The remove_observer method is used to remove an observer from the materials
258
- # collection.
259
- #
260
- # @example
261
- # materials = Sketchup.active_model.materials
262
- # status = materials.remove_observer(observer)
263
- #
264
- # @param [Object] observer
265
- # An observer.
266
- #
267
- # @return [Boolean] true if successful, false if unsuccessful.
268
- #
269
- # @version SketchUp 6.0
270
- def remove_observer(observer)
271
- end
272
-
273
- # The number of materials in the collection.
274
- #
275
- # The {#size} method is an alias for {#length}.
276
- #
277
- # @example
278
- # materials = Sketchup.active_model.materials
279
- # number = materials.size
280
- #
281
- # @note The returned number includes {Sketchup::Image} materials as well.
282
- # It will not reflect the number of materials yielded by {#each}. To get
283
- # the number of non-image materials use {#count} or +materials.to_a.size+.
284
- #
285
- # @return [Integer]
286
- #
287
- # @see #length
288
- #
289
- # @version SketchUp 2014
290
- def size
291
- end
292
-
293
- # The {#unique_name} method is used to retrieve a unique name from the
294
- # materials collection that is based on the provided one. If provided name is
295
- # unique it will be returned, otherwise any trailing indices will be replaced
296
- # by a new index.
297
- #
298
- # @example
299
- # materials = Sketchup.active_model.materials
300
- # unique_name = materials.unique_name("test_name")
301
- #
302
- # @param [String] name
303
- # the suggested name.
304
- #
305
- # @return [String] a unique name.
306
- #
307
- # @version SketchUp 2018
308
- def unique_name(name)
309
- end
310
-
311
- end
1
+ # Copyright:: Copyright 2022 Trimble Inc.
2
+ # License:: The MIT License (MIT)
3
+
4
+ # A collection of Materials objects. Each model contains a Materials collection
5
+ # that can be accessed via Model.materials.
6
+ #
7
+ # @example
8
+ # # Get a handle to all the materials in the current model.
9
+ # model = Sketchup.active_model
10
+ # materials = model.materials
11
+ #
12
+ # @version SketchUp 6.0
13
+ class Sketchup::Materials < Sketchup::Entity
14
+
15
+ # Includes
16
+
17
+ include Enumerable
18
+
19
+ # Instance Methods
20
+
21
+ # The {#[]} method is used to retrieve a material by index or name.
22
+ #
23
+ # The {#at} method is an alias of {#[]}
24
+ #
25
+ # @example
26
+ # model = Sketchup.active_model
27
+ # materials = model.materials
28
+ # material = materials[0]
29
+ #
30
+ # @overload [](index)
31
+ #
32
+ # @param [Integer] index
33
+ # A number representing the material's index in an array of Material
34
+ # objects.
35
+ # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
36
+ #
37
+ # @overload [](name)
38
+ #
39
+ # @param [String] name The name of the material.
40
+ # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
41
+ #
42
+ # @version SketchUp 6.0
43
+ def [](arg)
44
+ end
45
+
46
+ # Add a new Material. When called with no arguments, this will generate a
47
+ # new unique name for the new Material. If a name is given, it will check
48
+ # to see if there is already a material with that name. If there is already
49
+ # a material with the given name, then a new unique name is generated using
50
+ # the given name as a base.
51
+ #
52
+ # @example
53
+ # model = Sketchup.active_model
54
+ # materials = model.materials
55
+ # material = materials.add('Joe')
56
+ #
57
+ # @param [String] name
58
+ # The name of the new material.
59
+ #
60
+ # @return [Sketchup::Material] a Material object
61
+ #
62
+ # @version SketchUp 6.0
63
+ def add(name)
64
+ end
65
+
66
+ # The add_observer method is used to add an observer to the materials
67
+ # collection.
68
+ #
69
+ # @example
70
+ # materials = Sketchup.active_model.materials
71
+ # status = materials.add_observer(observer)
72
+ #
73
+ # @param [Object] observer
74
+ # An observer.
75
+ #
76
+ # @return [Boolean] true if successful, false if unsuccessful.
77
+ #
78
+ # @version SketchUp 6.0
79
+ def add_observer(observer)
80
+ end
81
+
82
+ # The {#[]} method is used to retrieve a material by index or name.
83
+ #
84
+ # The {#at} method is an alias of {#[]}
85
+ #
86
+ # @example
87
+ # model = Sketchup.active_model
88
+ # materials = model.materials
89
+ # material = materials[0]
90
+ #
91
+ # @overload [](index)
92
+ #
93
+ # @param [Integer] index
94
+ # A number representing the material's index in an array of Material
95
+ # objects.
96
+ # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
97
+ #
98
+ # @overload [](name)
99
+ #
100
+ # @param [String] name The name of the material.
101
+ # @return [Sketchup::Material, nil] a Material object on success, Nil on failure
102
+ #
103
+ # @version SketchUp 6.0
104
+ def at(arg)
105
+ end
106
+
107
+ #
108
+ # @example
109
+ # materials = Sketchup.active_model.materials
110
+ # count = materials.count
111
+ #
112
+ # @note Since SketchUp 2014 the count method is inherited from Ruby's
113
+ # +Enumerable+ mix-in module. Prior to that the {#count} method is an alias
114
+ # for {#length}.
115
+ #
116
+ # @return [Integer]
117
+ #
118
+ # @see #length
119
+ #
120
+ # @version SketchUp 6.0
121
+ def count
122
+ end
123
+
124
+ # The current method is used to get the current material, i.e. the material
125
+ # that the user has selected in the Materials dialog.
126
+ #
127
+ # @example
128
+ # current = Sketchup.active_model.materials.current
129
+ #
130
+ # @return [Sketchup::Material] a Material object.
131
+ #
132
+ # @version SketchUp 6.0
133
+ def current
134
+ end
135
+
136
+ # The current= method is used to set the current material.
137
+ #
138
+ # @example
139
+ # # Make the first material in the model "current"
140
+ # materials = Sketchup.active_model.materials
141
+ # materials.current = materials[0]
142
+ #
143
+ # @param [Sketchup::Material] material
144
+ # A Material object.
145
+ #
146
+ # @return [Sketchup::Material]
147
+ #
148
+ # @version SketchUp 6.0
149
+ def current=(material)
150
+ end
151
+
152
+ # The {#each} method is used to iterate through all of the materials.
153
+ #
154
+ # @example
155
+ # model = Sketchup.active_model
156
+ # model.materials.each { |material|
157
+ # puts material.display_name
158
+ # }
159
+ #
160
+ # @note Don't remove content from this collection while iterating over it with
161
+ # {#each}. This would change the size of the collection and cause elements to
162
+ # be skipped as the indices change. Instead copy the current collection to an
163
+ # array using +to_a+ and then use +each+ on the array, when removing content.
164
+ #
165
+ # @return [nil]
166
+ #
167
+ # @version SketchUp 6.0
168
+ #
169
+ # @yield [Sketchup::Material] A variable that will hold each Material object as they
170
+ # are found.
171
+ def each
172
+ end
173
+
174
+ # The number of materials in the collection.
175
+ #
176
+ # @example
177
+ # materials = Sketchup.active_model.materials
178
+ # number = materials.length
179
+ #
180
+ # @note The returned number includes {Sketchup::Image} materials as well.
181
+ # It will not reflect the number of materials yielded by {#each}. To get
182
+ # the number of non-image materials use {#count} or +materials.to_a.size+.
183
+ #
184
+ # @return [Integer]
185
+ #
186
+ # @see #size
187
+ #
188
+ # @version SketchUp 6.0
189
+ def length
190
+ end
191
+
192
+ # The {#load} method is used to load a material from file into the model.
193
+ #
194
+ # If a matching material exist in the model it will be returned instead.
195
+ #
196
+ # @example
197
+ # # Load a material from the shipped SketchUp library. (SketchUp 2016)
198
+ # filename = 'Materials/Brick, Cladding and Siding/Cinder Block.skm'
199
+ # path = Sketchup.find_support_file(filename)
200
+ # materials = Sketchup.active_model.materials
201
+ # material = materials.load(path)
202
+ #
203
+ # @param [String] filename
204
+ # the path to the SKM file to load.
205
+ #
206
+ # @raise [RuntimeError] if the material failed to load.
207
+ #
208
+ # @return [Sketchup::Material] the new loaded material, or existing material.
209
+ #
210
+ # @version SketchUp 2017
211
+ def load(filename)
212
+ end
213
+
214
+ # The purge_unused method is used to remove unused materials.
215
+ #
216
+ # @example
217
+ # materials = Sketchup.active_model.materials
218
+ # materials.purge_unused
219
+ #
220
+ # @return [Sketchup::Materials] The Materials object.
221
+ #
222
+ # @version SketchUp 6.0
223
+ def purge_unused
224
+ end
225
+
226
+ # Remove a given material.
227
+ #
228
+ # NOTE: On SketchUp versions prior to 2014 there is a bug in this method that
229
+ # could potentially lead to file corruption. If you call Materials.remove on a
230
+ # material that is painted onto any entity in the active model (e.g. faces,
231
+ # edges, groups, ...), then calling this method will not successfully unpaint
232
+ # the entity and remove the material from the model.
233
+ # You must first unpaint all of the entities that respond to .material
234
+ # and .back_material before calling Materials.remove.
235
+ #
236
+ # @example
237
+ # if entity.respond_to?(:material) do
238
+ # if entity.material.equal?(material_to_remove) do
239
+ # entity.material = nil
240
+ # end
241
+ # end
242
+ # # for entities that have a back material
243
+ # if entity.respond_to?(:back_material) do
244
+ # if entity.back_material.equal?(material_to_remove) do
245
+ # entity.back_material = nil
246
+ # end
247
+ # end
248
+ #
249
+ # @example
250
+ # model = Sketchup.active_model
251
+ # materials = model.materials
252
+ # material = materials.add('Joe')
253
+ # materials.remove(material)
254
+ #
255
+ # @param [Sketchup::Material] material
256
+ # The material to remove.
257
+ #
258
+ # @return [Boolean] true if successful, false if unsuccessful.
259
+ #
260
+ # @version SketchUp 8.0 M1
261
+ def remove(material)
262
+ end
263
+
264
+ # The remove_observer method is used to remove an observer from the materials
265
+ # collection.
266
+ #
267
+ # @example
268
+ # materials = Sketchup.active_model.materials
269
+ # status = materials.remove_observer(observer)
270
+ #
271
+ # @param [Object] observer
272
+ # An observer.
273
+ #
274
+ # @return [Boolean] true if successful, false if unsuccessful.
275
+ #
276
+ # @version SketchUp 6.0
277
+ def remove_observer(observer)
278
+ end
279
+
280
+ # The number of materials in the collection.
281
+ #
282
+ # The {#size} method is an alias for {#length}.
283
+ #
284
+ # @example
285
+ # materials = Sketchup.active_model.materials
286
+ # number = materials.size
287
+ #
288
+ # @note The returned number includes {Sketchup::Image} materials as well.
289
+ # It will not reflect the number of materials yielded by {#each}. To get
290
+ # the number of non-image materials use {#count} or +materials.to_a.size+.
291
+ #
292
+ # @return [Integer]
293
+ #
294
+ # @see #length
295
+ #
296
+ # @version SketchUp 2014
297
+ def size
298
+ end
299
+
300
+ # The {#unique_name} method is used to retrieve a unique name from the
301
+ # materials collection that is based on the provided one. If provided name is
302
+ # unique it will be returned, otherwise any trailing indices will be replaced
303
+ # by a new index.
304
+ #
305
+ # @example
306
+ # materials = Sketchup.active_model.materials
307
+ # unique_name = materials.unique_name("test_name")
308
+ #
309
+ # @param [String] name
310
+ # the suggested name.
311
+ #
312
+ # @return [String] a unique name.
313
+ #
314
+ # @version SketchUp 2018
315
+ def unique_name(name)
316
+ end
317
+
318
+ end