sketchup-api-stubs 0.1.0

data/SketchUp/Sketchup/Materials.rb

@@ -0,0 +1,283 @@
+# Copyright:: Copyright 2017 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# A collection of Materials objects. Each model contains a Materials collection
+# that can be accessed via Model.materials.
+#
+# @example
+#   # Get a handle to all the materials in the current model.
+#   model = Sketchup.active_model
+#   materials = model.materials
+#
+# @version SketchUp 6.0
+class Sketchup::Materials < Sketchup::Entity
+
+  # Includes
+
+  include Enumerable
+
+  # Instance Methods
+
+  # The {#[]} method is used to retrieve a material by index or name.
+  #
+  # The {#at} method is an alias of {#[]}
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   materials = model.materials
+  #   material = materials[0]
+  #
+  # @overload [](index)
+  #
+  #   @param index         A number representing the material's index in an array
+  #                        of Material objects.
+  #   @return              material - a Material object on success, Nil on failure
+  #
+  # @overload [](name)
+  #
+  #   @param name          The name of the material.
+  #   @return              material - a Material object on success, Nil on failure
+  #
+  # @version SketchUp 6.0
+  def [](arg)
+  end
+
+  # Add a new Material.  When called with no arguments, this will generate a
+  # new unique name for the new Material.  If a name is given, it will check
+  # to see if there is already a material with that name.  If there is already
+  # a material with the given name, then a new unique name is generated using
+  # the given name as a base.
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   materials = model.materials
+  #   material = materials.add('Joe')
+  #
+  # @param name
+  #   The name of the new material.
+  #
+  # @return material - a Material object
+  #
+  # @version SketchUp 6.0
+  def add(name)
+  end
+
+  # The add_observer method is used to add an observer to the materials
+  # collection.
+  #
+  # @example
+  #   materials = Sketchup.active_model.materials
+  #   status = materials.add_observer(observer)
+  #
+  # @param observer
+  #   An observer.
+  #
+  # @return success - true if successful, false if unsuccessful.
+  #
+  # @version SketchUp 6.0
+  def add_observer(observer)
+  end
+
+  # The {#[]} method is used to retrieve a material by index or name.
+  #
+  # The {#at} method is an alias of {#[]}
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   materials = model.materials
+  #   material = materials[0]
+  #
+  # @overload [](index)
+  #
+  #   @param index         A number representing the material's index in an array
+  #                        of Material objects.
+  #   @return              material - a Material object on success, Nil on failure
+  #
+  # @overload [](name)
+  #
+  #   @param name          The name of the material.
+  #   @return              material - a Material object on success, Nil on failure
+  #
+  # @version SketchUp 6.0
+  def at(arg)
+  end
+
+  #
+  # @example
+  #   materials = Sketchup.active_model.materials
+  #   count = materials.count
+  #
+  # @note Since SketchUp 2014 the count method is inherited from Ruby's
+  #   +Enumable+ mix-in module. Prior to that the {#count} method is an alias
+  #   for {#length}.
+  #
+  # @return integer - number of materials in the collection.
+  #
+  # @see #length
+  #
+  # @version SketchUp 6.0
+  def count
+  end
+
+  # The current method is used to get the current material, i.e. the material
+  # that the user has selected in the Materials dialog.
+  #
+  # @example
+  #   current = Sketchup.active_model.materials.current
+  #
+  # @return material - a Material object.
+  #
+  # @version SketchUp 6.0
+  def current
+  end
+
+  # The current= method is used to set the current material.
+  #
+  # @example
+  #   # Make the first material in the model "current"
+  #   materials = Sketchup.active_model.materials
+  #   materials.current = materials[0]
+  #
+  # @param material
+  #   A Material object.
+  #
+  # @return true if successful, false if unsuccessful.
+  #
+  # @version SketchUp 6.0
+  def current=(material)
+  end
+
+  # The each method is used to iterate through all of the materials.
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   model.materials.each { |material|
+  #     puts material.display_name
+  #   }
+  #
+  # @return material - a Material object
+  #
+  # @version SketchUp 6.0
+  #
+  # @yield [material] A variable that will hold each Material object as they
+  #   are found.
+  def each
+  end
+
+  # The number of materials in the collection.
+  #
+  # The {#size} method is an alias for {#length} added in SketchUp 2014.
+  #
+  # @example
+  #   materials = Sketchup.active_model.materials
+  #   number = materials.length
+  #
+  # @return integer - number of materials in the collection.
+  #
+  # @version SketchUp 6.0
+  def length
+  end
+
+  # The {#load} method is used to load a material from file into the model.
+  #
+  # If a matching material exist in the model that will be returned instead.
+  #
+  # @example
+  #   # Load a material from the shipped SketchUp library. (SketchUp 2016)
+  #   filename = 'Materials/Brick, Cladding and Siding/Cinder Block.skm'
+  #   path = Sketchup.find_support_file(filename)
+  #   materials = Sketchup.active_model.materials
+  #   material = materials.load(path)
+  #
+  # @param [String] filename
+  #   the path to the SKM file to load.
+  #
+  # @raise [RuntimeError] if the material failed to load.
+  #
+  # @return [Sketchup::Material] the new loaded material, or existing material.
+  #
+  # @version SketchUp 2017
+  def load(filename)
+  end
+
+  # The purge_unused method is used to remove unused materials.
+  #
+  # @example
+  #   materials = Sketchup.active_model.materials
+  #   materials.purge_unused
+  #
+  # @return materials - The Materials object.
+  #
+  # @version SketchUp 6.0
+  def purge_unused
+  end
+
+  # Remove a given material.
+  #
+  # NOTE: On SketchUp versions prior to 2014 there is a bug in this method that
+  # could potentially lead to file corruption. If you call Materials.remove on a
+  # material that is painted onto any entity in the active model (e.g. faces,
+  # edges, groups, ...), then calling this method will not successfully unpaint
+  # the entity and remove the material from the model.
+  # You must first unpaint all of the entities that respond to .material
+  # and .back_material before calling Materials.remove.
+  #
+  # @example
+  #   if entity.respond_to?(:material) do
+  #     if entity.material.equal?(material_to_remove) do
+  #       entity.material = nil
+  #     end
+  #   end
+  #   # for entities that have a back material
+  #   if entity.respond_to?(:back_material) do
+  #     if entity.back_material.equal?(material_to_remove) do
+  #       entity.back_material = nil
+  #     end
+  #   end
+  #
+  # @example
+  #   model = Sketchup.active_model
+  #   materials = model.materials
+  #   material = materials.add('Joe')
+  #   materials.remove(material)
+  #
+  # @param material
+  #   The material to remove.
+  #
+  # @return status - true if successful, false if unsuccessful.
+  #
+  # @version SketchUp 8.0 M1
+  def remove(material)
+  end
+
+  # The remove_observer method is used to remove an observer from the materials
+  # collection.
+  #
+  # @example
+  #   materials = Sketchup.active_model.materials
+  #   status = materials.remove_observer(observer)
+  #
+  # @param observer
+  #   An observer.
+  #
+  # @return success - true if successful, false if unsuccessful.
+  #
+  # @version SketchUp 6.0
+  def remove_observer(observer)
+  end
+
+  # The number of materials in the collection.
+  #
+  # The {#size} method is an alias for {#length} added in SketchUp 2014.
+  #
+  # @example
+  #   materials = Sketchup.active_model.materials
+  #   number = materials.length
+  #
+  # @return integer - number of materials in the collection.
+  #
+  # @version SketchUp 6.0
+  def size
+  end
+
+end

data/SketchUp/Sketchup/MaterialsObserver.rb

@@ -0,0 +1,141 @@
+# Copyright:: Copyright 2017 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# This observer interface is implemented to react to materials 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.
+#
+# @example
+#   class MyMaterialsObserver < Sketchup::MaterialsObserver
+#     def onMaterialAdd(materials, material)
+#       puts "onMaterialAdd: #{material}"
+#     end
+#   end
+#
+#   Sketchup.active_model.materials.add_observer(MyMaterialsObserver.new)
+#
+# @note The callback +onMaterialRemoveAll+ has been deprecated, we recommend using
+#   {#onMaterialRemove} instead.
+#
+# @version SketchUp 6.0
+class Sketchup::MaterialsObserver
+
+  # Instance Methods
+
+  # The {#onMaterialAdd} method is invoked whenever a new material is added.
+  #
+  # @example
+  #   def onMaterialAdd(materials, material)
+  #     puts "onMaterialAdd: #{material}"
+  #   end
+  #
+  # @param [Sketchup::Materials] materials
+  #
+  # @param [Sketchup::Material] material
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 6.0
+  def onMaterialAdd(materials, material)
+  end
+
+  # The {#onMaterialChange} method is invoked whenever a material's texture image
+  # is altered.
+  #
+  # @example
+  #   def onMaterialChange(materials, material)
+  #     puts "onMaterialChange: #{material}"
+  #   end
+  #
+  # @param [Sketchup::Materials] materials
+  #
+  # @param [Sketchup::Material] material
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 6.0
+  def onMaterialChange(materials, material)
+  end
+
+  # The {#onMaterialRefChange} method is invoked whenever the number of entities
+  # that a material is painted on changes. This could be due to the user
+  # manually painting something, but it could also be when faces are split,
+  # pasted, push-pulled, deleted, etc.
+  #
+  # @example
+  #   def onMaterialRefChange(materials, material)
+  #     puts "onMaterialRefChange: #{material}"
+  #   end
+  #
+  # @param [Sketchup::Materials] materials
+  #
+  # @param [Sketchup::Material] material
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 6.0
+  def onMaterialRefChange(materials, material)
+  end
+
+  # The {#onMaterialRemove} method is invoked whenever a material is deleted.
+  #
+  # @example
+  #   def onMaterialRemove(materials, material)
+  #     puts "onMaterialRemove: #{material}"
+  #   end
+  #
+  # @param [Sketchup::Materials] materials
+  #
+  # @param [Sketchup::Material] material
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 6.0
+  def onMaterialRemove(materials, material)
+  end
+
+  # The {#onMaterialSetCurrent} method is invoked whenever a different material
+  # is selected in the Materials dialog.
+  #
+  # The materials parameter might be Nil when the material is picked from the
+  # materials libraries and not yet added to the model.
+  #
+  # @example
+  #   def onMaterialSetCurrent(materials, material)
+  #     puts "onMaterialSetCurrent: #{material}"
+  #   end
+  #
+  # @param [Sketchup::Materials] materials
+  #
+  # @param [Sketchup::Material] material
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 6.0
+  def onMaterialSetCurrent(materials, material)
+  end
+
+  # The {#onMaterialUndoRedo} method is invoked whenever a material is altered
+  # and then those changes are undone or redone.
+  #
+  # @example
+  #   def onMaterialUndoRedo(materials, material)
+  #     puts "onMaterialUndoRedo: #{material}"
+  #   end
+  #
+  # @note Due to a bug, this callback does not fire in SU6 or SU7. You can use
+  #   the {Sketchup::ModelObserver#onTransactionStart} to capture all undo
+  #   events.
+  #
+  # @param [Sketchup::Material] material
+  #
+  # @param [Sketchup::Materials] materials
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 6.0
+  def onMaterialUndoRedo(materials, material)
+  end
+
+end

data/SketchUp/Sketchup/Menu.rb

@@ -0,0 +1,97 @@
+# Copyright:: Copyright 2017 Trimble Inc.
+# License:: The MIT License (MIT)
+
+# An interface to a menu.
+#
+# @version SketchUp 6.0
+class Sketchup::Menu
+
+  # Instance Methods
+
+  # The add_item menu item is used to add a menu item to the specified menu.
+  #
+  # This method takes a block that defines the action to perform when the menu
+  # item is selected.
+  #
+  # The item id that is returned can be used when adding an optional
+  # validation procedure for the menu item.
+  #
+  # @example
+  #   plugins_menu = UI.menu("Plugins")
+  #   item = plugins_menu.add_item("Test") { test }
+  #   if (item)
+  #     UI.messagebox item
+  #   else
+  #     UI.messagebox "Failure"
+  #   end
+  #
+  # @param menu
+  #   A string name of the menu to add.
+  #
+  # @return item_id - a unique integer id for the added menu item.
+  #
+  # @version SketchUp 6.0
+  #
+  # @yield A method that will be invoked when the menu item is
+  #   selected.
+  def add_item(menu, &block)
+  end
+
+  # The add_separator method is used to add a menu separator to a menu.
+  #
+  # @example
+  #   plugins_menu = UI.menu("Plugins")
+  #   plugins_menu.add_separator
+  #
+  # @return nil
+  #
+  # @version SketchUp 6.0
+  def add_separator
+  end
+
+  # The add_submenu method is used to add a sub-menu to a menu.
+  #
+  # @example
+  #   plugins_menu = UI.menu("Plugins")
+  #   submenu = plugins_menu.add_submenu("Test")
+  #   submenu.add_item("Hello World") {
+  #     UI.messagebox("Hi there!")
+  #   }
+  #
+  # @param [String] title
+  #   The title of the sub menu.
+  #
+  # @return submenu - a Menu object
+  #
+  # @version SketchUp 6.0
+  def add_submenu(title)
+  end
+
+  # The set_validation_proc method is used to identify the menu validation
+  # procedure. Your procedure should return either MF_ENABLED, MF_DISABLED,
+  # MF_CHECKED, MF_UNCHECKED, or MF_GRAYED.
+  #
+  # @example
+  #   plugins_menu = UI.menu("Plugins")
+  #   item = plugins_menu.add_item("Test") { UI.messagebox "My Test Item"}
+  #   status = plugins_menu.set_validation_proc(item)  {
+  #     if Sketchup.is_pro?
+  #       MF_ENABLED
+  #     else
+  #       MF_GRAYED
+  #     end
+  #   }
+  #
+  # @param menu
+  #   A string name of the menu to add.
+  #
+  # @return item_id - a unique numerical item id for the menu
+  #
+  # @version SketchUp 6.0
+  #
+  # @yield A method that will be invoked when the menu item is
+  #   selected.
+  def set_validation_proc(menu, &block)
+  end
+
+end