123456789_123456789_123456789_123456789_123456789_

Class: Sketchup::DefinitionList

Relationships
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Entity
Instance Chain:
self, Enumerable, Entity
Inherits: Sketchup::Entity

Overview

A DefinitionList object holds a list of all of the ComponentDefinition objects in a model. This class contains methods for adding and retrieving definitions from the list.

Version:

  • SketchUp 6.0

Instance Attribute Summary

Entity - Inherited

#deleted?

The deleted? method is used to determine if your entity is still valid (not deleted by another script, for example.).
#valid?

The #valid? method is used to determine if your entity is still valid (not deleted by another script, for example).

Instance Method Summary

Entity - Inherited

#add_observer

The add_observer method is used to add an observer to the current object.
#attribute_dictionaries

The attribute_dictionaries method is used to retrieve the AttributeDictionaries collection attached to the entity.
#attribute_dictionary

The attribute_dictionary method is used to retrieve an attribute dictionary with a given name that is attached to an Entity.
#delete_attribute

The #delete_attribute method is used to delete an attribute from an entity.
#entityID

The entityID method is used to retrieve a unique ID assigned to an entity.
#get_attribute

The #get_attribute method is used to retrieve the value of an attribute in the entity's attribute dictionary.
#inspect

The #inspect method is used to retrieve the string representation of the entity.
#model

The model method is used to retrieve the model for the entity.
#parent

The parent method is used to retrieve the parent of the entity.
#persistent_id

The #persistent_id method is used to retrieve a unique persistent id assigned to an entity.
#remove_observer

The remove_observer method is used to remove an observer from the current object.
#set_attribute

The set attribute is used to set the value of an attribute in an attribute dictionary with the given name.
#to_s

The #to_s method is used to retrieve the string representation of the entity.
#typename

The typename method retrieves the type of the entity, which will be a string such as "Face", "Edge", or "Group".

Instance Method Details

#[](index) ⇒ Sketchup::ComponentDefinition? #[](name) ⇒ Sketchup::ComponentDefinition? #[](guid) ⇒ Sketchup::ComponentDefinition?

The [] method is used to retrieve a component definition from the list. You can give an integer index in the range 0 to length, a string which represents the GUID (a unique internal identifier), or a string that is the name of the definition.

Examples:

path=Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.load path
component = definitions[0]

Overloads:

Version:

  • SketchUp 6.0

#add(def_name) ⇒ Sketchup::ComponentDefinition

The add method is used to add a new component definition to the definition list with the given name.

Examples:

model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.add "BedTraditional"
component = definitions[0]

Parameters:

  • def_name (String) —

    The new component definition to add to the definition list.

Returns:

Version:

  • SketchUp 6.0

#add_observer(observer) ⇒ Boolean

The add_observer method is used to add an observer to the current object.

Examples:

definitions = Sketchup.active_model.definitions
status = definitions.add_observer observer

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#[](index) ⇒ Sketchup::ComponentDefinition? #[](name) ⇒ Sketchup::ComponentDefinition? #[](guid) ⇒ Sketchup::ComponentDefinition?

The [] method is used to retrieve a component definition from the list. You can give an integer index in the range 0 to length, a string which represents the GUID (a unique internal identifier), or a string that is the name of the definition.

Examples:

path=Sketchup.find_support_file "Bed.skp",
  "Components/Components Sampler/"
model = Sketchup.active_model
definitions = model.definitions
componentdefinition = definitions.load path
component = definitions[0]

Overloads:

Version:

  • SketchUp 6.0

#count ⇒ Integer

Note:

Since SketchUp 2014 the count method is inherited from Ruby's Enumerable mix-in module. Prior to that the #count method is an alias for #length.

Examples:

model = Sketchup.active_model
definitions = model.definitions
number = definitions.count

See Also:

Version:

  • SketchUp 6.0

#each {|definition| ... } ⇒ Sketchup::ComponentDefinition

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.

The #each method is used to iterate through all of the component definitions in the definition list.

Examples:

model = Sketchup.active_model
definitions = model.definitions
definitions.add("BedTraditional")
number = definitions.each { |definition| puts definition.name }

Yield Parameters:

Version:

  • SketchUp 6.0

#import(path, options = {}) ⇒ Sketchup::ComponentDefinition

The #import method is used to import a (non-SketchUp) 3d model file as a definition.

Importers using the C API SketchUpModelImporterInterface interface are supported (those in the Importers/ directory).

See the {Sketchup::Importer Options} file for information on creating a valid hash for the various importers.

For SketchUp models, instead use #load.

Examples:

path = "C:/circle.dwg"
definition = Sketchup.active_model.definitions.import(path)

Parameters:

  • path (String)
  • options (Hash) (defaults to: {})

Raises:

  • (IOError) —

    if the file is missing.

  • (ArgumentError) —

    if no suitable importer could be found.

Version:

  • SketchUp 2021.1

#length ⇒ Integer

The #length method is used to retrieve number of component definitions in the list.

Examples:

model = Sketchup.active_model
definitions = model.definitions
number = definitions.length

See Also:

Version:

  • SketchUp 6.0

#load(path) ⇒ Sketchup::ComponentDefinition #load(path, allow_newer: false) ⇒ Sketchup::ComponentDefinition

The #load method is used to load a component from a file.

Examples:

path = Sketchup.find_support_file("Bed.skp",
  "Components/Components Sampler/")
model = Sketchup.active_model
definitions = model.definitions
definition = definitions.load(path)

Workaround for loading from the same path twice

path = "some/location/on/your/computer.skp"
definition1 = Sketchup.active_model.definitions.load(path)

# Now open the external file and make some changes to it.

# HACK: Prior to version 2023.0 SketchUp wouldn't load components from the same path twice.
# Instead it silently returned the existing, outdated component.
# Making an arbitrary change to the existing component allows a new one to be loaded.
definition1.entities.add_cpoint(ORIGIN) if Sketchup.version.to_i < 23

definition2 = Sketchup.active_model.definitions.load(path)

Overloads:

  • #load(path) ⇒ Sketchup::ComponentDefinition

    Parameters:

    • path (String) —

      The path where the component definition file is located.

  • #load(path, allow_newer: false) ⇒ Sketchup::ComponentDefinition

    Starting with SketchUp 2021.0 SketchUp attempts to load newer SketchUp models. If a newer model is loaded some information might have been skipped and extensions should be careful to not save over the file they loaded from as information might be lost.

    Parameters:

    • path (String) —

      The path where the component definition file is located.

    • allow_newer (Boolean) —

      Indicate that it is ok to load a model with of a newer version.

    Version:

    • SketchUp 2021.0

Returns:

Raises:

  • IOError If the file is not a valid SketchUp model.

  • RuntimeError If the file is the same as the model being loaded into.

  • IOError If the file is an empty component.

  • RuntimeError If the file contains only screen text.

  • RuntimeError If the file is of a newer file version that the executing SketchUp version cannot open.

Version:

  • SketchUp 6.0

#load_from_url(url) ⇒ Sketchup::ComponentDefinition #load_from_url(url, load_handler) ⇒ Sketchup::ComponentDefinition

The #load_from_url method loads a component from a location specified by string url.

This method throws an exception if an url string is not given, or an error occurs during retrieval from URL and a load_handler was not given.

Examples:

Download a component using a LoadHandler

class LoadHandler
  attr_accessor :error

  # @param [Float] percent
  def onPercentChange(percent)
    Sketchup::set_status_text("loading: #{percent.round}%")
  end

  def cancelled?
    # You could, for example, show a messagebox after X seconds asking if the
    # user wants to cancel the download. If this method returns true, then
    # the download cancels.
    return false
  end

  def onSuccess
    Sketchup::set_status_text('')
  end

  # @param [String] error_message
  def onFailure(error_message)
    self.error = error_message
    Sketchup::set_status_text('')
  end
end

# Replace this with a real URL...
url = 'https://www.sketchup.com/model.skp'
model = Sketchup.active_model
load_handler = LoadHandler.new
definition = model.definitions.load_from_url(url, load_handler)

if definition.nil?
  puts "Error: #{load_handler.error}"
end

Workaround for macOS bug related to HtmlDialog action callbacks

module Example

  def self.open_dialog
    @dialog = UI::HtmlDialog.new
    @dialog.add_action_callback("say") { |action_context, url|
      self.load_component_deferred(url)
    }
    @dialog.set_file("path/to/file.html")
    @dialog.show
  end

  def load_component_deferred
    # The timer delay is enough to avoid .load_from_url from deadlocking.
    UI.start_timer(0, false) do
      self.load_component(url)
    end
  end

  def self.load_component(url)
    model = Sketchup.active_model
    definition = model.definitions.load_from_url(url)
    # ...
  end

end

Overloads:

  • #load_from_url(url) ⇒ Sketchup::ComponentDefinition

    Parameters:

    • url (String) —

      URL to load a .skp file from.

  • #load_from_url(url, load_handler) ⇒ Sketchup::ComponentDefinition

    Parameters:

    • url (String) —

      URL to load a .skp file from.

    • load_handler (Object) —

      Ruby object that has methods defined as described in the load_from_url details above.

Version:

  • SketchUp 7.0

#purge_unused ⇒ DefinitionList

Note:

Silently purging can cause data loss. The user may have deleted the last instance but intend to place new ones later. Don't purge without the user's knowledge and approval.

The #purge_unused method is used to remove the unused component definitions.

Examples:

definitions = Sketchup.active_model.definitions
definitions.purge_unused

Version:

  • SketchUp 6.0

#remove(definition) ⇒ Boolean

The #remove method is used to remove a component definition from the definition list with the given component definition. This will remove all instances of the definition.

Examples:

model = Sketchup.active_model
definitions = model.definitions
definition = definitions[0]
definitions.remove(definition)

Parameters:

Raises:

Version:

  • SketchUp 2018

#remove_observer(observer) ⇒ Boolean

The remove_observer method is used to remove an observer from the current object.

Examples:

definitions = Sketchup.active_model.definitions
status = definitions.remove_observer observer

Parameters:

  • observer (Object) —

    An observer.

Returns:

  • (Boolean) —

    true if successful, false if unsuccessful.

Version:

  • SketchUp 6.0

#size ⇒ Integer

The #size method is an alias for #length.

Examples:

model = Sketchup.active_model
definitions = model.definitions
number = definitions.size

See Also:

Version:

  • SketchUp 2014

#unique_name(base_name) ⇒ String

The unique_name is used to generate a unique name for a definition based on a base_name string. For example, a base_name of "Joe" might return "Joe #2"

Examples:

model = Sketchup.active_model
definitions = model.definitions
new_name = definitions.unique_name "My Base Name"

Parameters:

Returns:

  • (String) —

    the unique name.

Version:

  • SketchUp 6.0