Class: Sketchup::Overlay

Inherits:
Object
  • Object
show all
Defined in:
lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb

Overview

An Overlay provides contextual model information directly in the viewport. This can be presented in 2D and 3D.

Examples can be annotations or analytical model information such as geometry analysis, energy analysis, etc.

The overlay feature is not intended as a mechanism to provide custom entities to SketchUp. Whatever overlays draw is not pickable nor exportable.

It is also not allowed to perform model changes from overlay events. Doing so will result in a RuntimeError being thrown.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def draw(view)
    rectangle = [
      [100, 100, 0], [300, 100, 0], [300, 200, 0], [100, 200, 0]
    ]
    view.drawing_color = 'blue'
    view.draw2d(GL_QUADS, rectangle)
    point = Geom::Point3d.new(120, 120, 0)
    view.draw_text(point, "Hello Overlay", size: 20, bold: true, color: 'white')
  end

end

# Using an observer to create a new overlay per model.
class ExampleAppObserver < Sketchup::AppObserver

  def expectsStartupModelNotifications
    true
  end

  def register_overlay(model)
    overlay = ExampleOverlay.new
    model.overlays.add(overlay)
  end
  alias_method :onNewModel, :register_overlay
  alias_method :onOpenModel, :register_overlay

end

observer = ExampleAppObserver.new
Sketchup.add_observer(observer)

# The following line is needed if you copy+paste in the Ruby Console or
# at the moment the extension is installed:
observer.register_overlay(Sketchup.active_model)

Version:

  • SketchUp 2023.0

Instance Method Summary collapse

Constructor Details

#initialize(id, name, description: "") ⇒ Overlay

Returns a new instance of Overlay.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    description = "A short sentence describing the overlay."
    super('example_inc.my_overlay', 'Example Overlay', description: description)
  end

end

overlay = ExampleOverlay.new

Parameters:

  • id (String) —

    The string should be unique per overlay subclass. A good pattern would be something like: “company_name.extension_name.overlay_name”.

  • name (String) —

    This is a user facing display name that will appear in the UI. Make it short and representative for what the overlay does.

  • description (String) (defaults to: "") —

    This is a user facing description that will appear in the UI. Make it short and representative for what the overlay does.

Raises:

  • (ArgumentError) —

    if id or name is an empty string

Version:

  • SketchUp 2023.0



254
255
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 254

def initialize(id, name, description: "")
end

Instance Method Details

#description ⇒ String

This is a short user facing description of the overlay that will appear in the UI.

Examples:

Sketchup.active_model.overlays.each { |overlay|
  puts "#{overlay.name}: #{overlay.description}"
}

Returns:

Version:

  • SketchUp 2023.0



77
78
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 77

def description
end

#description=(description) ⇒ String

Sets a short user facing description of the overlay that will appear in the UI. Set this before adding to the Sketchup::OverlaysManager.

Examples:

Sketchup.active_model.overlays.each { |overlay|
  puts "#{overlay.name}: #{overlay.description}"
}

Returns:

Version:

  • SketchUp 2023.0



93
94
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 93

def description=(description)
end

#draw(view) ⇒ Object

This method is abstract.

It is called whenever the view updates.

Note:

This is called very often. Perform minimal amount of computation in this event. Cache the data needed to draw what the overlay needs whenever possible.

Note:

If you draw outside the model bounds you need to implement #getExtents which return a bounding box large enough to include the points you draw. Otherwise your drawing will be clipped.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def draw(view)
    # Draw a square.
    points = [
      Geom::Point3d.new(0, 0, 0),
      Geom::Point3d.new(9, 0, 0),
      Geom::Point3d.new(9, 9, 0),
      Geom::Point3d.new(0, 9, 0)
    ]
    # Fill
    view.drawing_color = Sketchup::Color.new(255, 128, 128)
    view.draw(GL_QUADS, points)
    # Outline
    view.line_stipple = '' # Solid line
    view.drawing_color = Sketchup::Color.new(64, 0, 0)
    view.draw(GL_LINE_LOOP, points)
  end

end

Parameters:

  • view (Sketchup::View) —

    A View object where the method was invoked.

See Also:

Version:

  • SketchUp 2023.0



143
144
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 143

def draw(view)
end

#enabled=(enabled) ⇒ Object

Note:

In most cases, extensions doesn’t need to expose any new UI for enabling them. This can be done from the Overlays panel. However, in some cases the extension might have additional UI related to the overlays and might want to offer a way to toggle its overlays along with the rest of the UI.

Parameters:

  • enabled (Boolean)

Raises:

  • (RuntimeError) —

    if the overlay is not added to a model.

Version:

  • SketchUp 2023.0



160
161
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 160

def enabled=(enabled)
end

#enabled? ⇒ Boolean

Examples:

Sketchup.active_model.overlays.each { |overlay|
  puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
}

Returns:

  • (Boolean)

Version:

  • SketchUp 2023.0



174
175
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 174

def enabled?
end

#getExtents ⇒ Geom::BoundingBox

This method is abstract.

The method should be implementing sub-classes ensure what is drawn in 3D space doesn’t appear clipped. If the overlay only draws in 2D this isn’t needed.

Note:

This is called very often. Perform minimal amount of computation in this event. Cache the data needed to compute the bounds of what the overlay draws whenever possible.

In order to accurately draw things, SketchUp needs to know the extents of what it is drawing. If the overlay is doing its own drawing, it may need to implement this method to tell SketchUp the extents of what it will be drawing. If you don’t implement this method, you may find that part of what the overlay is drawing gets clipped to the extents of the rest of the model.

This must return a Geom::BoundingBox. In a typical implementation, you will create a new Geom::BoundingBox, add points to set the extents of the drawing that the overlay will do and then return it.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
    @points = [ [0, 0, 0], [9, 0, 0], [9, 9, 0], [0, 9, 0] ]
  end

  def getExtents
    bb = Sketchup.active_model.bounds
    bb.add(@points)
    return bb
  end

  def draw(view)
    view.draw(GL_QUADS, @points)
  end

end

Returns:

Version:

  • SketchUp 2023.0



221
222
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 221

def getExtents
end

#name ⇒ String

This is a user facing display name that will appear in the UI.

Examples:

Sketchup.active_model.overlays.each { |overlay|
  puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
}

Returns:

Version:

  • SketchUp 2023.0



269
270
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 269

def name
end

#onMouseEnter(flags, x, y, view) ⇒ Object

This method is abstract.

It can be used by implementing sub-classes to react to mouse movement in the viewport.

The #onMouseEnter method is called by SketchUp when the mouse enters the viewport.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def onMouseEnter(flags, x, y, view)
    puts "onMouseEnter: flags = #{flags}"
    puts "                  x = #{x}"
    puts "                  y = #{y}"
    puts "               view = #{view}"
  end

end

Parameters:

  • flags (Integer) —

    A bit mask that tells the state of the modifier keys and other mouse buttons at the time.

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 2023.0



309
310
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 309

def onMouseEnter(flags, x, y, view)
end

#onMouseLeave(view) ⇒ Object

This method is abstract.

It can be used by implementing sub-classes to react to mouse movement in the viewport.

The #onMouseLeave method is called by SketchUp when the mouse enters the viewport.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def onMouseLeave(view)
    puts "onMouseLeave"
  end

end

Parameters:

Version:

  • SketchUp 2023.0



336
337
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 336

def onMouseLeave(view)
end

#onMouseMove(flags, x, y, view) ⇒ Object

This method is abstract.

It can be used by implementing sub-classes to react to mouse movement in the viewport.

Try to make this method as efficient as possible because this method is called often.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def onMouseMove(flags, x, y, view)
    puts "onMouseMove: flags = #{flags}"
    puts "                  x = #{x}"
    puts "                  y = #{y}"
    puts "               view = #{view}"
  end

end

Parameters:

  • flags (Integer) —

    A bit mask that tells the state of the modifier keys and other mouse buttons at the time.

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 2023.0



376
377
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 376

def onMouseMove(flags, x, y, view)
end

#overlay_id ⇒ String

Examples:

Implementing

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

end

Accessing

Sketchup.active_model.overlays.each { |overlay|
  puts "#{overlay.name} (#{overlay.overlay_id}) Enabled: #{overlay.enabled?}"
}

Returns:

Version:

  • SketchUp 2023.0



399
400
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 399

def overlay_id
end

#source ⇒ String

Describes the source associated with the overlay. This is automatically inferred when the overlay instance is initialized.

Examples:

Sketchup.active_model.overlays.each { |overlay|
  puts "#{overlay.name} (Extension: #{overlay.source})"
}

Returns:

Version:

  • SketchUp 2023.0



415
416
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 415

def source
end

#start ⇒ Object

This method is abstract.

It can be used by implementing sub-classes to react when the overlay becomes active, for instance when the user turns it on.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def start
    puts "Overlay #{self} started"
  end

end

Version:

  • SketchUp 2023.0



438
439
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 438

def start
end

#stop ⇒ Object

This method is abstract.

It can be used by implementing sub-classes to react when the overlay becomes inactive, for instance when the user turns it off.

Examples:

class ExampleOverlay < Sketchup::Overlay

  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end

  def stop(view)
    puts "Overlay #{self} stopped"
  end

end

Version:

  • SketchUp 2023.0



461
462
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 461

def stop
end

#valid? ⇒ Boolean

Indicates whether the overlay is valid. An overlay becomes invalid after being removed from the model and cannot be reused.

Examples:

class ExampleOverlay < Sketchup::Overlay
  def initialize
    super('example_inc.my_overlay', 'Example Overlay')
  end
end

overlay = ExampleOverlay.new
p overlay.valid? # => true
Sketchup.active_model.overlays.add(overlay)
p overlay.valid? # => true

Sketchup.active_model.overlays.remove(overlay)
p overlay.valid? # => false

Returns:

  • (Boolean)

Version:

  • SketchUp 2023.0



487
488
 
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Overlay.rb', line 487

def valid?
end