Class: UI::Notification

Inherits:
Object
  • Object
show all

Overview

Notification objects allows you to show native notifications in the desktop. Notifications can have a message, icon and accept and/or dismiss buttons with callback blocks.

Examples:

# For consistency, the accept (yes) and the dismiss (no) buttons
# are always displayed in the same order.
message = "A new version of pizza is available. Install now?"
@notification = UI::Notification.new(sketchup_extension, message)
@notification.on_accept("Pizza!") { puts "Pizza" }
@notification.on_dismiss("No thanks") { puts "No pizza" }
@notification.show

# The two options are however not treated differently by SketchUp and can
# also be used for questions with no strict yes/no answer.
message = "Pizza clashes with health. Select which one to keep."
@notification = UI::Notification.new(sketchup_extension, message)
@notification.on_accept("Pizza") { puts "Pizza" }
@notification.on_dismiss("Health") { puts "Salad" }
@notification.show

Version:

  • SketchUp 2017

Instance Method Summary # collapse

Constructor Details

↑ #initialize(sketchup_extension, message = nil, icon_name = nil, icon_tooltip = nil) ⇒ UI::Notification

Note:

In order to insert line breaks into the message you need to use \r\n.

Creates a new UI::Notification object.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon",
    "Icon Tooltip")
@notification.show

Parameters:

  • sketchup_extension (SketchupExtension) —

    SketchupExtension instance used to identify the source of the notification.

  • message (String) (defaults to: nil) —

    Message to display.

  • icon_name (String) (defaults to: nil) —

    Path to an icon to display along with the message.

  • icon_tooltip (String) (defaults to: nil) —

    Tooltip for the icon.

Version:

  • SketchUp 2017

Known Bugs:

  • Prior to SketchUp 2018 messages could only be 3 lines long on Windows and 2 lines on Mac. Now the notification expands to fit its content.

  • Prior to SketchUp 2021.1 SketchUp could crash if the UI::Notification object is garbaged collected while it has notifications displayed on the screen. This could happen if the UI::Notification object was assigned to a local variable. The local variable would go out of scope and the garbage collector might collect it before the callbacks are invoked.

Instance Method Details

↑ #icon_name ⇒ String

Gets the icon name, this is the path that will be used to get the icon from the file system path.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon",
    "Icon Tooltip")
puts "Icon Name: #{@notification.icon_name}"
@notification.show

Returns:

Version:

  • SketchUp 2017

↑ #icon_name=(icon_name) ⇒ Boolean

Sets the icon path, this icon will be loaded from the path give, the path has to be a local filesystem path.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world")
@notification.icon_name = "/path/to/icon"
@notification.show

Parameters:

  • icon_name (String) —

    String providing the icon filesystem path.

Returns:

  • (Boolean)

Version:

  • SketchUp 2017

↑ #icon_tooltip ⇒ String

Gets the icon Tooltip, this is the string that appear when the mouse is over the icon.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world", "/path/to/icon",
    "Icon Tooltip")
puts "Tooltip: #{@notification.icon_tooltip}"
@notification.show

Returns:

Version:

  • SketchUp 2017

↑ #icon_tooltip=(icon_tooltip) ⇒ Boolean

Sets the icon Tooltip, this string will appear when the mouse is over the icon.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world")
@notification.icon_tooltip = "icon Tooltip"
@notification.show

Parameters:

  • icon_tooltip (String) —

    String providing the new icon Tooltip.

Returns:

  • (Boolean)

Version:

  • SketchUp 2017

↑ #message ⇒ String

Gets the message as string.

Examples:

@notification = UI::Notification.new(sketchup_extension)
puts "This is the current message: #{@notification.message}"
@notification.show

Returns:

Version:

  • SketchUp 2017

↑ #message=(message) ⇒ Boolean

Note:

In order to insert line breaks into the message you need to use \r\n.

Sets a new message. Notifications are meant for quick and brief messages. These message disappear automatically after a short while if they are not interacted with.

Examples:

@notification = UI::Notification.new(sketchup_extension)
@notification.message = "Hello world"
@notification.show

Parameters:

  • message (String) —

    String providing the new message.

Returns:

  • (Boolean)

Version:

  • SketchUp 2017

↑ #on_accept(title, block) ⇒ Boolean

Shows a button in the notification with the given title and callback block, both arguments are required.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world")
@notification.on_accept("Accept")  do |notification, title|
   puts "The user pressed [#{title}] with message #{notification.message}"
end
@notification.show

Parameters:

  • title (String) —

    Sets the title of the button.

  • block (Block) —

    Sets the action callback, this will be called when the user clicks on the dismiss button.

Returns:

  • (Boolean)

Raises:

  • (RuntimeError) —

    When calling on_accept when the notification has already been shown.

Version:

  • SketchUp 2017

Known Bugs:

  • Prior to SketchUp 2019 both the accept and dismiss buttons were displayed, even if only one had been implemented.

↑ #on_accept_title ⇒ String

Returns the accept's button title.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world")
@notification.on_accept("Accept")  do |notification, title|
   puts "The user pressed #{notification.on_accept_title}"
end
@notification.show

Returns:

Version:

  • SketchUp 2017

↑ #on_dismiss(title, block) ⇒ Boolean

Shows a button in the notification with the given title and callback block. Both arguments are required. This callback is only called if you press the Dismiss button, not when the time runs out and the notification automatically disappears.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world")
@notification.on_dismiss("Close")  do |notification, title|
   puts "The user pressed [#{title}] with message #{notification.message}"
end
@notification.show

Parameters:

  • title (String) —

    Sets the title of the button.

  • block (Block) —

    Sets the action callback, this will be called when the user clicks on the dismiss button.

Returns:

  • (Boolean)

Raises:

  • (RuntimeError) —

    When calling on_dismiss when the notification has already been shown.

Version:

  • SketchUp 2017

Known Bugs:

  • Prior to SketchUp 2019 both the accept and dismiss buttons were displayed, even if only one had been implemented.

↑ #on_dismiss_title ⇒ String

Returns the dismiss's button title.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world")
@notification.on_dismiss("Close")  do |notification, title|
   puts "The user pressed #{notification.on_dismiss_title}"
end
@notification.show

Returns:

Version:

  • SketchUp 2017

↑ #show ⇒ Boolean

Shows the notification. If not interacted with, the notification will disappear without calling any callbacks.

Examples:

@notification = UI::Notification.new(sketchup_extension, "Hello world")
@notification.show

Returns:

  • (Boolean)

Version:

  • SketchUp 2017

Known Bugs:

  • If assigned to a local variable SketchUp might crash prior to SketchUp 2021.1. See #initialize for more details.