sketchup-api-stubs 0.7.0 → 0.7.5

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

@@ -2,9 +2,11 @@
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to events on a definitions
-# collection. To implement this observer, create a Ruby class of this type,
-# override the desired methods, and add an instance of the observer to the
-# collection of interest.
+# collection.
+#
+# @abstract To implement this observer, create a Ruby class of this type,
+#   override the desired methods, and add an instance of the observer to the
+#   collection of interest.
 #
 # @example
 #   class MyDefinitionsObserver < Sketchup::DefinitionsObserver

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

@@ -168,17 +168,11 @@ class Sketchup::DimensionLinear < Sketchup::Dimension
   #
   # @example
   #   dim.offset_vector = Geom::Vector3d.new(0, 0, 10)
-  #   # or
-  #   dim.offset_vector = [0, 0, 10]
   #
-  # @param vec
-  #   the offset vector to be set, either a Vector3d or in
-  #   array form.
-  #
-  # @return the offset vector that was set
+  # @param [Geom::Vector3d] offset_vector
   #
   # @version SketchUp 2014
-  def offset_vector=(vec)
+  def offset_vector=(offset_vector)
   end
 
   # The start method returns the point or entity the dimension is referencing at

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

@@ -3,6 +3,10 @@
 
 # This observer interface is implemented to react to changes in dimension text.
 #
+# @abstract To implement this observer, create a Ruby class of this type,
+#   override the desired methods, and add an instance of the observer to the
+#   dimensions of interest.
+#
 # @example
 #   # This is an example of a DimensionObserver
 #   class MyDimensionObserver < Sketchup::DimensionObserver

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

@@ -11,8 +11,14 @@ class Sketchup::Drawingelement < Sketchup::Entity
 
   # Instance Methods
 
-  # The bounds method is used to retrieve the BoundingBox for an drawing
-  # element.
+  # The {#bounds} method is used to retrieve the {Geom::BoundingBox} bounding a
+  # {Sketchup::Drawingelement}.
+  #
+  # For a {Sketchup::Edge}, {Sketchup::ComponentInstance} and most other
+  # {Sketchup::Drawingelement}s, the boundingbox follows the coordinate system
+  # the drawing element is placed in.
+  # For {Sketchup::ComponentDefinition}, the box bounds the contents of the
+  # component and follows the component's own internal coordinate system.
   #
   # @example
   #   depth = 100
@@ -31,7 +37,7 @@ class Sketchup::Drawingelement < Sketchup::Entity
   #   # is a sub-class of Drawingelement.
   #   boundingbox = face.bounds
   #
-  # @return [Geom::BoundingBox] A BoundingBox object if successful
+  # @return [Geom::BoundingBox]
   #
   # @version SketchUp 6.0
   def bounds

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

@@ -155,20 +155,13 @@ class Sketchup::Edge < Sketchup::Drawingelement
   def explode_curve
   end
 
-  # The faces method is used to retrieve all of the faces common to the edge.
+  # The {#faces} method is used to retrieve all of the faces common to the edge.
   #
   # @example
-  #   edge = Sketchup.active_model.entities.add_line([0,0,0],[100,100,0])
+  #   edge = Sketchup.active_model.entities.add_line([0, 0, 0], [100, 100, 0])
   #   faces = edge.faces
-  #   if (faces)
-  #     # Display the pointer to the first face returned in the array
-  #     UI.messagebox faces[0]
-  #   else
-  #     UI.messagebox "Failure: No Faces Found"
-  #   end
   #
-  # @return [Array<Sketchup::Face>] an array of Face objects if successful, false
-  #   if unsuccessful
+  # @return [Array<Sketchup::Face>]
   #
   # @version SketchUp 6.0
   def faces
@@ -229,8 +222,9 @@ class Sketchup::Edge < Sketchup::Drawingelement
   #
   # @overload length(transform)
   #
-  #   @param transform [Geom::Transformation] A Transformation object or array
-  #                       that can be interpreted as a Transformation object.
+  #   @param [Geom::Transformation] transform
+  #     A Transformation object or array that can be interpreted as a
+  #     Transformation object.
   #   @return [Length] the length of the edge
   #
   # @version SketchUp 6.0
@@ -416,7 +410,7 @@ class Sketchup::Edge < Sketchup::Drawingelement
   def soft?
   end
 
-  # The split method is used to  to split an edge into to or more distinct
+  # The split method is used to  to split an edge into two or more distinct
   # edges. If a Point3d is given, it must be a point that is on the Edge.
   #
   # If a Float is given, it is a number between 0 and 1 that gives the

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

@@ -1,8 +1,9 @@
 # Copyright:: Copyright 2020 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# The Entities class is a container class for all entities in a model (it is a
-# collection of Entity objects).
+# The {Sketchup::Entities} class is a collection of Entity objects, either in a
+# {Sketchup::ComponentDefinition} or directly in the {Sketchup::Model}. A
+# {Sketchup::Entities} object corresponds to a drawing context in the GUI.
 #
 # @version SketchUp 6.0
 class Sketchup::Entities
@@ -540,8 +541,8 @@ class Sketchup::Entities
   #     UI.messagebox "Failure"
   #   end
   #
-  # @param [String] filename
-  #   A filename for the image file.
+  # @param [String] path
+  #   A path for the image file.
   #
   # @param [Geom::Point3d] point
   #   A Point3d object representing the insertion point of
@@ -558,7 +559,7 @@ class Sketchup::Entities
   # @return [Sketchup::Image, nil] an Image object if successful.
   #
   # @version SketchUp 6.0
-  def add_image(filename, point, width, height = 0.0)
+  def add_image(path, point, width, height = 0.0)
   end
 
   # The add_instance method adds a component instance to the collection of
@@ -806,8 +807,8 @@ class Sketchup::Entities
   def count
   end
 
-  # The each method is used to iterate through the entities in the collection of
-  # entities.
+  # The {#each} method is used to iterate through the entities in the collection
+  # of entities.
   #
   # @example
   #   coordinates = [10, 10, 10]
@@ -815,7 +816,12 @@ class Sketchup::Entities
   #   entities = model.entities
   #   point = Geom::Point3d.new coordinates
   #   text = entities.add_text "This is a Test", point
-  #   entities.each { | entity| UI.messagebox entity }
+  #   entities.each { | entity| puts entity }
+  #
+  # @note Don't remove content from this collection while iterating over it with
+  #   {#each}. This would change the size of the collection and cause elements to
+  #   be skipped as the indices change. Instead copy the current collection to an
+  #   array using +to_a+ and then use +each+ on the array, when removing content.
   #
   # @return [nil]
   #
@@ -1045,8 +1051,15 @@ class Sketchup::Entities
   # sub-entities all at once.
   #
   # @example
-  #   # Need better Ruby example.
-  #   entities = entities.transform_by_vectors sub_entities, vector_array
+  #   # Raise vertices in selection by their distance to the origin.
+  #   model = Sketchup.active_model
+  #   entities = model.active_entities
+  #   with_vertices = entities.select { |entity| entity.respond_to?(:vertices) }
+  #   vertices = with_vertices.flat_map(&:vertices).uniq
+  #   lengths = vertices.map { |vertex| vertex.position.distance(ORIGIN) }
+  #   vectors = lengths.map { |length| Geom::Vector3d.new(0, 0, length) }
+  #
+  #   entities.transform_by_vectors(vertices, vectors)
   #
   # @param [Array<Sketchup::Entity>] sub_entities
   #   An array of entities to transform.
@@ -1063,24 +1076,18 @@ class Sketchup::Entities
   # The transform_entities method is used to apply a transform to several
   # sub-entities all at once.
   #
-  # Important note: If you apply a transformation to entities that are
-  # not in the current edit context (i.e. faces that are inside a group),
-  # SketchUp will apply the transformation incorrectly, since the geometry
-  # has one origin and the current edit context has another. You can correct
-  # for this by watching the Model.edit_transform and Model.active_path. See
-  # ModelObserver.onActivePathChanged for more information.
+  # If you are transforming entities in the active drawing context or any of its
+  # parent drawing contexts, the transformation will be interpreted as relative
+  # to the global coordinate system. Otherwise the transformation will be
+  # interpreted as being on the local coordinate system.
   #
   # @example
   #   entities = Sketchup.active_model.entities
-  #   entities.add_line([0,0,0],[100,100,100])
-  #   entities.add_line([0,0,0],[200,-10,-10])
-  #
-  #   entities_to_transform = []
-  #   entities_to_transform.push(entities[0])
-  #   entities_to_transform.push(entities[1])
+  #   entity1 = entities.add_line([0,0,0],[100,100,100])
+  #   entity2 = entities.add_line([0,0,0],[200,-10,-10])
   #
-  #   transform = Geom::Transformation.new([100,0,0])
-  #   entities.transform_entities(transform, ent1, ent2, ent3)
+  #   transformation = Geom::Transformation.new([100,0,0])
+  #   entities.transform_entities(transformation, [entity1, entity2])
   #
   # @param [Geom::Transformation] transform
   #   The Transformation to apply.
@@ -1088,10 +1095,32 @@ class Sketchup::Entities
   # @param [Array<Sketchup::Entity>] entities
   #   An array or series of entities to transform.
   #
-  # @return [Boolean] results of the transform.
+  # @return [Boolean] +false+ if the entities array was empty.
   #
   # @version SketchUp 6.0
   def transform_entities(transform, entities)
   end
 
+  # The {#weld} method takes a set of edges and find all possible chains of edges
+  # and connect them with a {Sketchup::Curve}.
+  #
+  # A curve will not cross another curve. They will split where multiple curves
+  # meet.
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   edges = model.selection.grep(Sketchup::Edge)
+  #   curves = model.active_entities.weld(edges)
+  #
+  # @param [Array<Sketchup::Edge>] edges
+  #
+  # @raise [ArgumentError] if the given entities are not part of the same
+  #   {Sketchup::Entities} collection.
+  #
+  # @return [Array<Sketchup::Curve>]
+  #
+  # @version SketchUp 2020.1
+  def weld(edges)
+  end
+
 end

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

@@ -2,9 +2,11 @@
 # License:: The MIT License (MIT)
 
 # This observer interface is implemented to react to {Sketchup::Entities}
-# collection events. To implement this observer, create a Ruby class of this
-# type, override the desired methods, and add an instance of the observer to
-# the objects of interests.
+# collection events.
+#
+# @abstract To implement this observer, create a Ruby class of this
+#   type, override the desired methods, and add an instance of the observer to
+#   the objects of interests.
 #
 # @example
 #   # This is an example of an observer that watches the entities collection

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

@@ -73,12 +73,11 @@ class Sketchup::Entity
   #   status = entity1.set_attribute "testdictionary", "test", 115
   #   attrdicts = entity1.attribute_dictionaries
   #
-  # @return [Sketchup::AttributeDictionaries, nil] the AttributeDictionaries
-  #   object associated with the entity, or nil if there are
-  #   no attribute_dictionary objects associated with the
-  #   model. Care must be taken if nil is returned, for
-  #   example: invoking attribute_dictionaries.length will
-  #   throw a NoMethodError exception, not return 0.
+  # @note The return value may be either +nil+ or an empty
+  #   {Sketchup::AttributeDictionaries} collection if this entity has no
+  #   {Sketchup::AttributeDictionary}s.
+  #
+  # @return [Sketchup::AttributeDictionaries, nil]
   #
   # @version SketchUp 6.0
   def attribute_dictionaries
@@ -155,14 +154,14 @@ class Sketchup::Entity
   #
   # @overload delete_attribute(dictionary_name)
   #
-  #   @param dictionary_name [String] The name of an attribute dictionary.
-  #   @return                [Boolean]
+  #   @param [String] dictionary_name The name of an attribute dictionary.
+  #   @return [Boolean]
   #
   # @overload delete_attribute(dictionary_name, key)
   #
-  #   @param dictionary_name [String] The name of an attribute dictionary.
-  #   @param key             [String] An attribute key.
-  #   @return                [Boolean]
+  #   @param [String] dictionary_name The name of an attribute dictionary.
+  #   @param [String] key An attribute key.
+  #   @return [Boolean]
   #
   # @version SketchUp 6.0
   def delete_attribute(*args)
@@ -344,6 +343,10 @@ class Sketchup::Entity
   #
   # The persistent id persistent between sessions.
   #
+  # [SketchUp 2020.1]
+  #   - {Sketchup::ComponentDefinition}
+  #   - {Sketchup::Material}
+  #   - {Sketchup::Style}
   # [SketchUp 2020.0]
   #   - {Sketchup::Layer}
   #   - {Sketchup::LineStyle}
@@ -504,16 +507,18 @@ class Sketchup::Entity
   #   entity1 = entities[1]
   #   type = entity1.typename
   #
+  # @note Prefer +is_a?+ over +typename+ when possible as it is faster.
+  #
   # @return [String] the type of the entity
   #
   # @version SketchUp 6.0
   def typename
   end
 
-  # The valid? method is used to determine if your entity is still valid (not
-  # deleted by another script, for example.)
+  # The {#valid?} method is used to determine if your entity is still valid (not
+  # deleted by another script, for example).
   #
-  # This method is functionally identical to the deleted? method.
+  # This method is functionally the inverse to the {#deleted?} method.
   #
   # @example
   #   depth = 100

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

@@ -1,10 +1,11 @@
 # Copyright:: Copyright 2020 Trimble Inc.
 # License:: The MIT License (MIT)
 
-# This observer interface is implemented to react to entity events. To
-# implement this observer, create a Ruby class of this type, override the
-# desired methods, and add an instance of the observer to the entity of
-# interests.
+# This observer interface is implemented to react to entity events.
+#
+# @abstract To  implement this observer, create a Ruby class of this type, override the
+#   desired methods, and add an instance of the observer to the entity of
+#   interests.
 #
 # @example
 #   class MyEntityObserver < Sketchup::EntityObserver

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

@@ -21,11 +21,11 @@ class Sketchup::ExtensionsManager
   #
   # @example
   #   manager = Sketchup.extensions
-  #   extension = manager[0]
+  #   extension = manager[1]
   #   if (extension)
-  #     UI.messagebox extension.name
+  #     puts extension.name
   #   else
-  #     UI.messagebox "Failure"
+  #     puts "No Extensions installed"
   #   end
   #
   #   # You can also get extensions by name.
@@ -34,11 +34,12 @@ class Sketchup::ExtensionsManager
   #   # You can also get extensions by ID.
   #   my_extension = manager['2475A758-6503-46D5-AC5E-16AEA0A3162A']
   #
-  # @param index_or_name
+  # @note Index starts at 1.
+  #
+  # @param [Integer, String] index_or_name
   #   The index, name or ID of the SketchupExtension object.
   #
-  # @return extension - an SketchupExtension object if
-  #   successful, otherwise nil.
+  # @return [SketchupExtension, nil]
   #
   # @version SketchUp 8.0 M2
   def [](index_or_name)
@@ -66,7 +67,7 @@ class Sketchup::ExtensionsManager
   # @example
   #   manager = Sketchup.extensions
   #   # Retrieves each extension
-  #   manager.each { |extension| UI.messagebox extension.name }
+  #   manager.each { |extension| puts extension.name }
   #
   # @return nil
   #

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

@@ -41,7 +41,7 @@ class Sketchup::Face < Sketchup::Drawingelement
   def all_connected
   end
 
-  # The area method is used to retrieve the area of a face in current units.
+  # The area method is used to retrieve the area of a face.
   #
   # You can pass in an optional Transformation (or an array that can represent a
   # transformation), to correct for a parent group's transformation. For example,
@@ -66,13 +66,14 @@ class Sketchup::Face < Sketchup::Drawingelement
   #
   # @overload area
   #
-  #   @return [Float] the area of the face in current units (if successful)
+  #   @return [Float] the area of the face in square inches.
   #
   # @overload area(transform)
   #
-  #   @param transform [Geom::Transformation] A Transformation object or array
-  #                      that can be interpreted as a Transformation object.
-  #   @return [Float] the area of the face in current units (if successful)
+  #   @param [Geom::Transformation] transform
+  #    A Transformation object or array that can be interpreted as a
+  #    Transformation object.
+  #   @return [Float] the area of the face in square inches.
   #
   # @version SketchUp 6.0
   def area(*args)
@@ -639,8 +640,8 @@ class Sketchup::Face < Sketchup::Drawingelement
   #   face = entities.add_face(pts)
   #   status = face.pushpull(100, true)
   #
-  # @param [Numeric] distance
-  #   The distance, in current units, to push/pull the face.
+  # @param [Length] distance
+  #   The distance to push/pull the face.
   #
   # @param [Boolean] copy
   #   Create a new push/pull starting face if true (equivalent

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

@@ -3,13 +3,11 @@
 
 # A Group class contains methods for manipulating groups of entities.
 #
-# Groups in SketchUp are very similar to Components, except that there is no
-# instancing of groups. That means that you always will have one and only one
-# of each of your groups. (In the actual implementation, SketchUp keeps track
-# of groups as a special kind of Component that combines properties of
-# definitions and instances, which is why you will see deprecated methods
-# like Group.make_unique, and the class of observer you attach to Groups are
-# ComponentInstance observers.)
+# Groups in SketchUp are very similar to components, but can from a user point
+# of view be thought of as unique objects. Groups can be instanced when copied
+# but are silently made unique when edited through the GUI. To honor this
+# behavior, make sure to call {#make_unique} before modifying a group through
+# the API.
 #
 # @version SketchUp 6.0
 class Sketchup::Group < Sketchup::Drawingelement
@@ -228,6 +226,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.intersect(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to intersect this group with.
   #
@@ -239,11 +239,11 @@ class Sketchup::Group < Sketchup::Drawingelement
   def intersect(group)
   end
 
-  # The local_bounds method returns the BoundingBox object that defines the size
-  # of the group in an untransformed state. Useful for determining the original
-  # width, height, and depth of a group regardless of its current position or
-  # scale. For components, you can get a similar result by checking
-  # my_instance.definition.bounds.
+  # The {#local_bounds} method is used to retrieve the {Geom::BoundingBox}
+  # bounding the contents of a {Sketchup::Group}, in the group's own internal
+  # coordinate system.
+  #
+  # @deprecated In favor of `group.definition.bounds`.
   #
   # @example
   #   # Add a group to the model.
@@ -257,7 +257,7 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group.transform! transformation
   #   local_bounds_2 = group.local_bounds
   #
-  # @return [Geom::BoundingBox] a BoundingBox object
+  # @return [Geom::BoundingBox]
   #
   # @version SketchUp 7.0
   def local_bounds
@@ -303,14 +303,14 @@ class Sketchup::Group < Sketchup::Drawingelement
   def locked?
   end
 
-  # The make_unique method is used to force a group to have a unique definition.
+  # The {#make_unique} method is used to force a group to have a unique
+  # definition. If the group is already unique in the model, nothing happens.
   #
-  # Copying a group using the copy tool in SketchUp will create copies of the
-  # group that share a common definition until an instance is edited manually or
-  # this method is used. If multiple copies are made, all copies share a
-  # definition until all copies are edited manually, or all copies have this
-  # method used on them. This method ensures that the group uses a unique
-  # definition entry in the drawing database.
+  # Copying a group in SketchUp will create a group that shares the same
+  # definition. SketchUp implicitly makes group unique when edited from the GUI,
+  # and from a user point of view groups could be thought of as always being
+  # unique. To honor this behavior, call this method before editing a group
+  # through the API.
   #
   # @example
   #   # Assume we have 2 groups, one copied from the other and sharing definitions
@@ -341,15 +341,16 @@ class Sketchup::Group < Sketchup::Drawingelement
   def manifold?
   end
 
-  # The move! method is used to apply a transformation to the group.
+  # The {#move!} method is used to set the transformation of this group
+  # instance, similarly to {#transformation=} but without recording to the undo
+  # stack.
   #
-  # This method is the same as the transform! method except that it does not
-  # record the move in an undo operation. This method is useful for
-  # transparently moving things during an animation.
+  # This method is useful for moving entities inside of an animation or page
+  # transition.
   #
   # @example
   #   point = Geom::Point3d.new 500,500,500
-  #   t = Geom::Transformation.new point
+  #   transformation = Geom::Transformation.new point
   #   depth = 100
   #   width = 100
   #   model = Sketchup.active_model
@@ -369,21 +370,17 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   # Add a face to within the group
   #   face = entities2.add_face pts
   #   UI.messagebox "Group before Move"
-  #   group = group.move! t
-  #   if (group)
-  #     UI.messagebox "Group after move"
-  #     UI.messagebox group
-  #   else
-  #     UI.messagebox "Failure"
-  #   end
+  #   group = group.move!(transformation)
   #
-  # @param [Geom::Transformation] transform
-  #   A Transformation object.
+  # @note Despite the name being similar to {#transform!}, this method closer
+  #   corresponds to {#transformation=}.
+  #
+  # @param [Geom::Transformation] transformation
   #
   # @return [Sketchup::Group] the transformed Group object if successful
   #
   # @version SketchUp 6.0
-  def move!(transform)
+  def move!(transformation)
   end
 
   # The name method is used to retrieve the name of the group.
@@ -503,6 +500,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.split(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to split this group with.
   #
@@ -528,6 +527,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.subtract(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to subtract this group from.
   #
@@ -613,24 +614,21 @@ class Sketchup::Group < Sketchup::Drawingelement
   def transformation
   end
 
-  # The transformation= method is used to set the transformation for the
-  # group.
+  # The {#transformation=} method is used to set the transformation of this
+  # group
   #
   # @example
   #   # Add a group to the model.
   #   group = Sketchup.active_model.entities.add_group
   #   group.entities.add_line([0,0,0],[100,100,100])
   #
-  #   new_transform = Geom::Transformation.new([100,0,0])
-  #   group.transformation = new_transform
+  #   new_transformation = Geom::Transformation.new([100,0,0])
+  #   group.transformation = new_transformation
   #
-  # @param [Geom::Transformation] transform
-  #   The Transformation object to apply
-  #
-  # @return [Geom::Transformation] the applied transformation
+  # @param [Geom::Transformation] transformation
   #
   # @version SketchUp 6.0
-  def transformation=(transform)
+  def transformation=(transformation)
   end
 
   # The trim method is used to compute the (non-destructive) boolean difference
@@ -644,6 +642,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.trim(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to trim this group against.
   #
@@ -665,6 +665,8 @@ class Sketchup::Group < Sketchup::Drawingelement
   #   group2 = entities[1]
   #   result = group1.union(group2)
   #
+  # @note This method is not available in SketchUp Make.
+  #
   # @param [Sketchup::Group, Sketchup::ComponentInstance] group
   #   The group to union this group with.
   #