sketchup-api-stubs 0.7.2 → 0.7.7

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

@@ -0,0 +1,422 @@
+# Copyright:: Copyright 2021 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# Allows layers to be organized in folders. Folders may have duplicate names.
+#
+# @api TagFolder
+#
+# @note As of SketchUp 2020 "Layers" were renamed to "Tags" in the UI.
+#   The API retains the use of "Layer" for compatibility and is synonymous with
+#   "Tag".
+#
+# @version SketchUp 2021.0
+class Sketchup::LayerFolder < Sketchup::Entity
+
+  # Includes
+
+  include Comparable
+
+  # Instance Methods
+
+  # The {#<=>} method is used to compare two layer folders based on their names.
+  # You could use this for sorting if you're building a list of folder names.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder1 = layers.add('Folder1')
+  #   folder2 = layers.add('Folder2')
+  #   comparison = folder1 <=> folder2 # Returns: -1
+  #   comparison = folder1 <=> folder1 # Returns: 0
+  #   comparison = folder2 <=> folder1 # Returns: 1
+  #
+  # @param [Object] other
+  #
+  # @return [Integer, nil] +-1+ if the receiver should appear before +other+.
+  #   +1+ if the receiver should appear after +other+.
+  #   +0+ if the receiver and +other+ are equal.
+  #   +nil+ if +other+ is not comparable with the receiver.
+  #
+  # @version SketchUp 2021.0
+  def <=>(other)
+  end
+
+  # The {#==} method is used to determine if two layer folders are the same.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder1 = layers.add('Folder1')
+  #   folder2 = layers.add('Folder2')
+  #   equal = folder1 == folder2
+  #
+  # @param [Object] other
+  #
+  # @return [Boolean]
+  #
+  # @version SketchUp 2021.0
+  def ==(other)
+  end
+
+  # The {#add_folder} method adds or moves a layer folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder1 = manager.add_folder('Doors')
+  #   folder2 = folder1.add_folder('Outer Doors')
+  #
+  # @overload add_folder(name)
+  #
+  #   Adds a new folder with the given name. Unlike layers, folders do not
+  #   need to have a unique name.
+  #   @param [String] name
+  #
+  # @overload add_folder(folder)
+  #
+  #   Moves an existing {Sketchup::LayerFolder} to the receiver. This will
+  #   include any children in the given folder.
+  #   @param [Sketchup::LayerFolder] folder
+  #   @see Sketchup::LayerFolder#folder= Information on how which notifications
+  #     trigger when reparenting an existing folder.
+  #
+  # @return [Sketchup::LayerFolder]
+  #
+  # @see #count_layers
+  #
+  # @version SketchUp 2021.0
+  def add_folder(arg)
+  end
+
+  # The {#add_layer} method adds a layer to a folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   layer = manager.add_layer('Inner Doors')
+  #   folder = manager.add_folder('Doors')
+  #
+  #   folder.add_layer(layer)
+  #
+  # @param [Sketchup::Layer] layer
+  #
+  # @return [nil]
+  #
+  # @see Sketchup::Layer#folder=
+  #   Information on how which notifications
+  #   trigger when reparenting a layer.
+  #
+  # @version SketchUp 2021.0
+  def add_layer(layer)
+  end
+
+  # The {#count_folders} method retrieves the number of child folders in the
+  # folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   layers = Sketchup.active_model.layers
+  #   folder1 = layers.add_folder('Hello')
+  #   folder2 = folder1.add_folder('World')
+  #   number = folder1.folder_count # Returns: 1
+  #
+  # @return [Integer]
+  #
+  # @version SketchUp 2021.0
+  def count_folders
+  end
+
+  # The {#count_layers} method retrieves the number of layers in the folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   layers = Sketchup.active_model.layers
+  #   layer = layers.add_layer('World')
+  #   folder = layers.add_folder('Hello')
+  #   folder.add_layer(layer)
+  #   number = folder.layer_count # Returns: 1
+  #
+  # @return [Integer]
+  #
+  # @see #size
+  #
+  # @see #length
+  #
+  # @version SketchUp 2021.0
+  def count_layers
+  end
+  alias_method :length, :count_layers
+  alias_method :size, :count_layers
+
+  # The {#each_folder} method is used to iterate through the folders that are
+  # direct children to the folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder1 = layers.add_folder('Hello')
+  #   folder1.add_folder('World')
+  #   folder1.each_folder { | folder | puts folder.name }
+  #
+  # @version SketchUp 2021.0
+  #
+  # @yield [folder]
+  #
+  # @yieldparam [Sketchup::LayerFolder] folder
+  def each_folder
+  end
+
+  # The {#each_layer} method is used to iterate through the layers that are
+  # direct children to the folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   layer = layers.add_layer('World')
+  #   folder = layers.add_folder('Hello')
+  #   folder.add_layer(layer)
+  #   folder.each_layer { | layer | puts layer.name }
+  #
+  # @version SketchUp 2021.0
+  #
+  # @yield [layer]
+  #
+  # @yieldparam [Sketchup::Layer] layer
+  def each_layer
+  end
+  alias_method :each, :each_layer
+
+  # The {#folder} method is used to return the parent layer folder of a layer
+  # folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder1 = layers.add('Folder1')
+  #   parent_folder = folder1.folder # Returns: nil
+  #
+  #   folder2 = folder1.add('Folder2')
+  #   parent_folder = folder2.folder # Returns: folder1
+  #
+  # @return [Sketchup::LayerFolder, nil] +nil+ if the folder is a direct child to
+  #   the layer manager.
+  #
+  # @version SketchUp 2021.0
+  def folder
+  end
+
+  # The {#folder=} method is used to set the parent layer folder of a layer
+  # folder.
+  #
+  # This will trigger +onLayerFolderRemoved+ followed by +onLayerFolderAdded+.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder1 = layers.add('Folder1')
+  #   folder2 = layers.add('Folder2')
+  #
+  #   folder2.folder = folder1
+  #
+  # @param [Sketchup::LayerFolder, nil] parent
+  #   +nil+ will make the the folder a
+  #   direct child to the layer manager.
+  #
+  # @version SketchUp 2021.0
+  def folder=(parent)
+  end
+
+  # The {#folders} returns the direct child-folders of the folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder1 = manager.add_folder('Doors')
+  #   folder2 = folder1.add_folder('Windows')
+  #   folders = folder1.folders
+  #
+  # @return [Array<Sketchup::LayerFolder>]
+  #
+  # @version SketchUp 2021.0
+  def folders
+  end
+
+  # The {#layers} method retrieves the child layers of a folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Hello')
+  #   folder.add_layer(manager.add_layer('World'))
+  #   folder.add_layer(manager.add_layer('Universe'))
+  #
+  #   layers = folder.layers
+  #
+  # @return [Array<Sketchup::Layer>]
+  #
+  # @version SketchUp 2021.0
+  def layers
+  end
+
+  # The {#name} method gets the name of the folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Doors')
+  #   name = folder.name
+  #
+  # @return [String]
+  #
+  # @version SketchUp 2021.0
+  def name
+  end
+  alias_method :display_name, :name
+
+  # The {#name=} method sets the name of the folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Doors')
+  #   folder.name = 'Windows'
+  #
+  # @param [String] name
+  #
+  # @raise [ArgumentError] if +name+ is empty.
+  #
+  # @version SketchUp 2021.0
+  def name=(name)
+  end
+
+  # The {#remove_folder} method removes the folder from the model. All children
+  # are preserved, but move up one level.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder1 = manager.add_folder('Doors')
+  #   folder2 = manager.add_folder('Outer Doors')
+  #   folder1.remove_folder(folder2)
+  #
+  # @param [Sketchup::LayerFolder] folder
+  #
+  # @raise [ArgumentError] if the +folder+ is not a direct child of the receiver.
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def remove_folder(folder)
+  end
+
+  # The {#remove_layer} method removes a layer from a folder. The layer will be
+  # parent to the layer manager.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   layer = manager.add_layer('Inner Doors')
+  #   folder = manager.add_folder('Doors')
+  #   folder.add_layer(layer)
+  #
+  #   folder.remove_layer(layer)
+  #
+  # @param [Sketchup::Layer] layer
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def remove_layer(layer)
+  end
+
+  # The {#visible=} method is used to set if the layer folder is visible.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder = layers.add('Hello')
+  #   folder.visible = false
+  #
+  # @param [Boolean] visible
+  #
+  # @version SketchUp 2021.0
+  def visible=(visible)
+  end
+
+  # The {#visible?} method is used to determine if the layer folder is visible.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder = layers.add('Hello')
+  #   folder.visible? # Returns: true
+  #
+  # @return [Boolean]
+  #
+  # @version SketchUp 2021.0
+  def visible?
+  end
+
+  # The {#visible_on_new_pages=} method is used to set if the layer folder is by
+  # default visible on new pages.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder = layers.add_folder('Hello')
+  #   folder.visible_on_new_pages = false
+  #   page = model.pages.add('My Page')
+  #   model.pages.select_page = page # `folder` will now be hidden.
+  #
+  # @param [Boolean] visible
+  #
+  # @version SketchUp 2021.0
+  def visible_on_new_pages=(visible)
+  end
+
+  # The {#visible_on_new_pages?} method is used to determine if the layer folder
+  # is by default visible on new pages.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   folder = layers.add_folder('Hello')
+  #   folder.visible_on_new_pages? # Returns: true
+  #
+  # @return [Boolean]
+  #
+  # @version SketchUp 2021.0
+  def visible_on_new_pages?
+  end
+
+end

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

@@ -1,4 +1,4 @@
-# Copyright:: Copyright 2020 Trimble Inc.
+# Copyright:: Copyright 2021 Trimble Inc.
 # License:: The MIT License (MIT)
 
 # The Layers collection allows you to see and manage all of the layers in a
@@ -8,6 +8,10 @@
 #   model = Sketchup.active_model
 #   layers = model.layers
 #
+# @note As of SketchUp 2020 "Layers" were renamed to "Tags" in the UI.
+#   The API retains the use of "Layer" for compatibility and is synonymous with
+#   "Tag".
+#
 # @version SketchUp 6.0
 class Sketchup::Layers < Sketchup::Entity
 
@@ -38,7 +42,7 @@ class Sketchup::Layers < Sketchup::Entity
   def [](index_or_name)
   end
 
-  # The add method is used to add a new layer.
+  # The {#add} method is used to add a new layer.
   #
   # If you give the name of a Layer that is already defined, it will return the
   # existing Layer rather than adding a new one.
@@ -47,25 +51,56 @@ class Sketchup::Layers < Sketchup::Entity
   #   layers = Sketchup.active_model.layers
   #   layer = layers.add("Test Layer")
   #
-  # @param layer_name
+  # @param [String] layer_name
   #   The name of the added layer.
   #
-  # @return layer - the new Layer object
+  # @return [Sketchup::Layer]
   #
   # @version SketchUp 6.0
   def add(layer_name)
   end
+  alias_method :add_layer, :add
 
-  # The add_observer method is used to add an observer to the layers collection.
+  # The {#add_folder} method adds or moves a layer folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Doors')
+  #
+  # @overload add_folder(name)
+  #
+  #   Adds a new folder with the given name. Unlike layers, folders do not
+  #   need to have a unique name. But the name does have to be non-empty.
+  #   @param [String] name
+  #
+  # @overload add_folder(folder)
+  #
+  #   Moves an existing {Sketchup::LayerFolder} to the receiver. This will
+  #   include any children in the given folder.
+  #   @param [Sketchup::LayerFolder] folder
+  #   @see Sketchup::LayerFolder#folder= Information on how which notifications
+  #     trigger when reparenting an existing folder.
+  #
+  # @return [Sketchup::LayerFolder]
+  #
+  # @see #count_layers
+  #
+  # @version SketchUp 2021.0
+  def add_folder(arg)
+  end
+
+  # The {#add_observer} method is used to add an observer to the layers
+  # collection.
   #
   # @example
   #   layers = Sketchup.active_model.layers
   #   status = layers.add_observer observer
   #
-  # @param observer
-  #   An observer.
+  # @param [Sketchup::LayersObserver] observer
   #
-  # @return success - true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 6.0
   def add_observer(observer)
@@ -105,20 +140,135 @@ class Sketchup::Layers < Sketchup::Entity
   def count
   end
 
-  # The each method is used to iterate through all of the layers.
+  # The {#count_folders} method counts the number of folders which are direct
+  # children of the layer manager.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Doors')
+  #   num_folders = manager.count_folders
+  #
+  # @return [Integer]
+  #
+  # @version SketchUp 2021.0
+  def count_folders
+  end
+
+  # The {#count_layers} method retrieves the number of layers not in a folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   layers = Sketchup.active_model.layers
+  #   number = layers.count_layers
+  #
+  # @return [Integer]
+  #
+  # @see #size
+  #
+  # @see #length
+  #
+  # @version SketchUp 2021.0
+  def count_layers
+  end
+
+  # The {#each} method is used to iterate through all of the layers in the model.
+  # This include layers that are nested inside folders.
   #
   # @example
   #   model = Sketchup.active_model
   #   layers = model.layers
-  #   layers.add("test layer")
+  #   layers.add("Test layer")
   #   layers.each { | layer | puts layer.name }
   #
+  # @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.
+  #
   # @version SketchUp 6.0
   #
-  # @yield [layer] - a variable that will hold each Layer object as they are found.
+  # @yield [layer]
+  #
+  # @yieldparam [Sketchup::Layer] layer
   def each
   end
 
+  # The {#each_folder} method is used to iterate through the folders that are
+  # direct children to the layer manager.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Doors')
+  #   folder = manager.add_folder('Windows')
+  #   manager.each_folder { |folder|
+  #     puts folder.name
+  #   }
+  #
+  # @version SketchUp 2021.0
+  #
+  # @yield [folder]
+  #
+  # @yieldparam [Sketchup::LayerFolder] folder
+  def each_folder
+  end
+
+  # The {#each_layer} method is used to iterate through the layers that are not
+  # inside a layer folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   layers = model.layers
+  #   layers.add('Test layer')
+  #   layers.each_layer { | layer | puts layer.name }
+  #
+  # @version SketchUp 2021.0
+  #
+  # @yield [layer]
+  #
+  # @yieldparam [Sketchup::Layer] layer
+  def each_layer
+  end
+
+  # The {#folders} method returns the folders of the layer manager.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   manager.add_folder('Doors')
+  #   manager.add_folder('Windows')
+  #   folders = manager.folders
+  #
+  # @note This does not return all the folders in the model, only those that are
+  #   direct children of the layer manager.
+  #
+  # @return [Array<Sketchup::LayerFolder>]
+  #
+  # @version SketchUp 2021.0
+  def folders
+  end
+
+  # The {#layers} method retrieves the layers not in a folder.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   layers = manager.layers
+  #
+  # @return [Array<Sketchup::Layer>]
+  #
+  # @version SketchUp 2021.0
+  def layers
+  end
+
   # The {#length} method retrieves the number of layers.
   #
   # @example
@@ -133,17 +283,39 @@ class Sketchup::Layers < Sketchup::Entity
   def length
   end
 
-  # The purged_unused method is used to remove unused layers.
+  # The {#purge_unused} method is used to remove unused layers.
   #
   # @example
   #   layers = Sketchup.active_model.layers
-  #   status = layers.purge_unused
+  #   num_layers_removed = layers.purge_unused
+  #
+  # @return [Integer] Number of unused layers removed
   #
-  # @return success - true if successful, false if unsuccessful.
+  # @see #purge_unused_folders
   #
   # @version SketchUp 6.0
   def purge_unused
   end
+  alias_method :purge_unused_layers, :purge_unused
+
+  # The {#purge_unused_folders} method is used to remove all layer folder with
+  # no children.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Doors')
+  #   folder = manager.add_folder('Windows')
+  #   manager.purge_unused_folders
+  #
+  # @version SketchUp 2021.0
+  #
+  # @yield [folder]
+  #
+  # @yieldparam [Sketchup::LayerFolder] folder
+  def purge_unused_folders
+  end
 
   # Remove the given layer from the model, optionally removing the geometry.
   #
@@ -164,31 +336,50 @@ class Sketchup::Layers < Sketchup::Entity
   #   edge.layer = Sketchup.active_model.layers.add("MyLayer")
   #   Sketchup.active_model.layers.remove("MyLayer", true)
   #
-  # @param layer
-  #   Integer index, String name or Layer
+  # @param [Sketchup::Layer, Integer, String] layer
   #
-  # @param remove_geometry
-  #   Boolean - If true, geometry in the removed layer will
+  # @param [Boolean] remove_geometry
+  #   If true, geometry in the removed layer will
   #   be removed as well. If false (which is the default),
   #   this geometry will be placed on Layer 0.
   #
-  # @return boolean - true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 2015
   def remove(layer, remove_geometry = false)
   end
+  alias_method :remove_layer, :remove
 
-  # The remove_observer method is used to remove an observer from the current
+  # The {#remove_folder} method removes the folder from the model. All children are
+  # preserved, but moved up one level.
+  #
+  # @api TagFolder
+  #
+  # @example
+  #   manager = Sketchup.active_model.layers
+  #   folder = manager.add_folder('Doors')
+  #   manager.remove_folder(folder)
+  #
+  # @param [Sketchup::LayerFolder] folder
+  #
+  # @raise [ArgumentError] if the +folder+ is not a direct child of the receiver.
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2021.0
+  def remove_folder(folder)
+  end
+
+  # The {#remove_observer} method is used to remove an observer from the current
   # object.
   #
   # @example
   #   layers = Sketchup.active_model.layers
   #   status = layers.remove_observer observer
   #
-  # @param observer
-  #   An observer.
+  # @param [Sketchup::LayersObserver] observer
   #
-  # @return success - true if successful, false if unsuccessful.
+  # @return [Boolean] true if successful, false if unsuccessful.
   #
   # @version SketchUp 6.0
   def remove_observer(observer)
@@ -208,7 +399,7 @@ class Sketchup::Layers < Sketchup::Entity
   def size
   end
 
-  # The unique_name method can be used to get a string that will be a unique
+  # The {#unique_name} method can be used to get a string that will be a unique
   # layer name inside this collection.
   #
   # @example
@@ -217,15 +408,20 @@ class Sketchup::Layers < Sketchup::Entity
   #   # Will return "Joe" since there are probably no other layers named that.
   #   # Or might return something like "Joe #2" if there is already a layer
   #   # named Joe.
-  #   good_name = layers.unique_name "Joe"
+  #   good_name = layers.unique_name("Joe")
+  #
+  # @overload unique_name
+  #
+  #   @return [String]  Will default to using "Layer" (SketchUp2019 and older)
+  #                     or "Tag" as basename for a unique name.
   #
-  # @param [optional] base_name
-  #   The base name to build the unique name from.
+  # @overload unique_name(base_name)
   #
-  # @return name - the unique name
+  #   @param [String] base_name  The base name to build the unique name from.
+  #   @return [String]
   #
   # @version SketchUp 6.0
-  def unique_name(base_name)
+  def unique_name(*args)
   end
 
 end