sketchup-api-stubs 0.1.2 → 0.2.0

data/SketchUp/{SketchupExtension.rb → sketchupextension.rb}

@@ -51,7 +51,7 @@ class SketchupExtension
   #   # And this will load the extension.
   #   ext_c.check
   #
-  # @return boolean - whether the load succeeded
+  # @return [Boolean] whether the load succeeded
   #
   # @version SketchUp 8.0 M2
   def check
@@ -67,7 +67,7 @@ class SketchupExtension
   #   extension.copyright = '2008'
   #   copyright = extension.copyright
   #
-  # @return copyright - the Extension copyright
+  # @return [String] the Extension copyright
   #
   # @version SketchUp 6.0
   def copyright
@@ -83,10 +83,10 @@ class SketchupExtension
   #   extension.copyright = '2008'
   #   copyright = extension.copyright
   #
-  # @param copyright
+  # @param [String] copyright
   #   The copyright to set
   #
-  # @return copyright - the new copyright
+  # @return [String] the new copyright
   #
   # @version SketchUp 6.0
   def copyright=(copyright)
@@ -102,7 +102,7 @@ class SketchupExtension
   #   extension.creator = 'Trimble Navigation, Inc.'
   #   creator = extension.creator
   #
-  # @return creator - the Extension creator
+  # @return [String] the Extension creator
   #
   # @version SketchUp 6.0
   def creator
@@ -118,10 +118,10 @@ class SketchupExtension
   #   extension.creator = 'Trimble Navigation, Inc.'
   #   creator = extension.creator
   #
-  # @param creator
+  # @param [String] creator
   #   The creator to set
   #
-  # @return creator - the new creator
+  # @return [String] the new creator
   #
   # @version SketchUp 6.0
   def creator=(creator)
@@ -137,7 +137,7 @@ class SketchupExtension
   #   extension.description = 'My description.'
   #   description = extension.description
   #
-  # @return description - the Extension description
+  # @return [String] the Extension description
   #
   # @version SketchUp 6.0
   def description
@@ -153,10 +153,10 @@ class SketchupExtension
   #   extension.description = 'My description.'
   #   description = extension.description
   #
-  # @param description
+  # @param [String] description
   #   The description string to set.
   #
-  # @return description - the Extension description
+  # @return [String] the Extension description
   #
   # @version SketchUp 6.0
   def description=(description)
@@ -165,7 +165,7 @@ class SketchupExtension
   # The extension_path method returns the file system path to the extension's
   # outer rb file.
   #
-  # @return extension_path - the file system path to the extension
+  # @return [String] the file system path to the extension
   #
   # @version SketchUp 2013
   def extension_path
@@ -173,7 +173,7 @@ class SketchupExtension
 
   # The id method returns the Extension Warehouse ID string.
   #
-  # @return id - the Extension Warehouse ID
+  # @return [String] the Extension Warehouse ID
   #
   # @version SketchUp 2013
   def id
@@ -193,14 +193,14 @@ class SketchupExtension
   #   # telling SketchUp to load the extension by default.
   #   Sketchup.register_extension(extension, true)
   #
-  # @param title
+  # @param [String] title
   #   The name of the extension
   #
-  # @param path
+  # @param [String] path
   #   The relative path to the script that loads your
   #   plugin.
   #
-  # @return extension - the new Extension object
+  # @return [Sketchup::Extension] the new Extension object
   #
   # @version SketchUp 6.0
   def initialize(title, path)
@@ -214,7 +214,7 @@ class SketchupExtension
   #   Sketchup.register_extension(ext, true)
   #   UI.messagebox("load_on_start? is now true: #{ext.load_on_start?.to_s}")
   #
-  # @return boolean - true if the extension loads on startup.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -228,10 +228,10 @@ class SketchupExtension
   # @example
   #   ext = SketchupExtension.new('Stair Tools', 'StairTools/core.rb')
   #   UI.messagebox("loaded? is false: #{ext.loaded?.to_s}")
-  #   Sketchup.register_extension ext, true
+  #   Sketchup.register_extension(ext, true)
   #   UI.messagebox("loaded? is now true: #{ext.loaded?.to_s}")
   #
-  # @return boolean - true if the extension has been loaded
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -248,7 +248,7 @@ class SketchupExtension
   #   extension = SketchupExtension.new('Stair Tools', 'StairTools/core.rb')
   #   name = extension.name
   #
-  # @return name - the Extension name
+  # @return [String] the Extension name
   #
   # @version SketchUp 6.0
   def name
@@ -263,10 +263,10 @@ class SketchupExtension
   #   extension = SketchupExtension.new('Stair Tools', 'StairTools/core.rb')
   #   extension.name = 'Renamed Stair Tools'
   #
-  # @param name
+  # @param [String] name
   #   The new name
   #
-  # @return name - the Extension name
+  # @return [String] the Extension name
   #
   # @version SketchUp 6.0
   def name=(name)
@@ -281,7 +281,7 @@ class SketchupExtension
   #   Sketchup.register_extension(ext, true)
   #   UI.messagebox("Now registered? is now true: #{ext.registered?.to_s}")
   #
-  # @return boolean - true if the extension has been registered.
+  # @return [Boolean]
   #
   # @return [Boolean]
   #
@@ -303,7 +303,7 @@ class SketchupExtension
   #     extension.uncheck
   #   }
   #
-  # @return boolean - whether the unload succeeded
+  # @return [Boolean] whether the unload succeeded
   #
   # @version SketchUp 8.0 M2
   def uncheck
@@ -319,7 +319,7 @@ class SketchupExtension
   #   extension.version = '5.0'
   #   version = extension.version
   #
-  # @return version - the Extension version
+  # @return [String] the Extension version
   #
   # @version SketchUp 6.0
   def version
@@ -335,10 +335,10 @@ class SketchupExtension
   #   extension.version = '5.0'
   #   version = extension.version
   #
-  # @param version
+  # @param [String] version
   #   The version string to set.
   #
-  # @return version - the Extension version
+  # @return [String] the Extension version
   #
   # @version SketchUp 6.0
   def version=(version)
@@ -346,7 +346,7 @@ class SketchupExtension
 
   # The version_id method returns the Extension Warehouse Version ID string.
   #
-  # @return version_id - the Extension Warehouse Version ID string
+  # @return [String] the Extension Warehouse Version ID string
   #
   # @version SketchUp 2013
   def version_id

data/SketchUp/{String.rb → string.rb}

@@ -15,7 +15,7 @@ class String
   # @example
   #   length = "5'".to_l
   #
-  # @return length - the length value
+  # @return [Length] the length value
   #
   # @version SketchUp 6.0
   def to_l

data/SketchUp/ui.rb

@@ -29,7 +29,7 @@ module UI
   #     }
   #   end
   #
-  # @return count - the number of context handlers that are
+  # @return [Integer] the number of context handlers that are
   #   registered
   #
   # @version SketchUp 6.0
@@ -46,7 +46,7 @@ module UI
   # @example
   #   UI.beep
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 6.0
   def self.beep
@@ -70,14 +70,10 @@ module UI
   #     UI.set_cursor(cursor_id)
   #   end
   #
-  # @param filename
+  # @param [String] filename
   #   Filename for an image.
   #
-  # @param hot_x
-  #   An x coordinate that is the "hotpoint" for the cursor
-  #   computed from the left edge of your cursor image.
-  #
-  # @param hot_y
+  # @param [Integer] hot_y
   #   A y coordinate that is the "hotpoint" for the cursor
   #   computed from the top edge of the of your cursor image.
   #   For example, a value of (hot_x, hot_y) = (5,10) would
@@ -85,7 +81,11 @@ module UI
   #   the left edge of your cursor image and 10 pixels from
   #   the top edge of your cursor image.
   #
-  # @return ID - ID associated with the cursor
+  # @param [Integer] hot_x
+  #   An x coordinate that is the "hotpoint" for the cursor
+  #   computed from the left edge of your cursor image.
+  #
+  # @return [Integer] ID associated with the cursor
   #
   # @version SketchUp 6.0
   def self.create_cursor(filename, hot_x, hot_y)
@@ -112,30 +112,37 @@ module UI
   #   list = ["", "", "Male|Female"]
   #   input = UI.inputbox(prompts, defaults, list, "Tell me about yourself.")
   #
-  # @param prompts
-  #   An array of prompt names appearing in the input box
-  #   adjacent to input fields.
-  #
-  # @param [optional] defaults
-  #   An array of default values for the input
-  #   fields.
-  #
-  # @param [optional] title
-  #   The title for the input box.
-  #
-  # @param [optional] title_or_list
-  #   If 3 params are passed, then this value is
-  #   a string containing the title of the input box. If
-  #   a total of 4 params are passed, then this is an array
-  #   containing pipe-separated strings of options.
-  #
-  # @return results - An array of returned values if the user did
+  # @overload inputbox(prompts, defaults, title)
+  #
+  #   @param [Array<String>] prompts
+  #     An array of prompt names appearing in the input box
+  #     adjacent to input fields.
+  #   @param [Array<String>] defaults
+  #     An array of default values for the input
+  #     fields.
+  #   @param [String] title
+  #     The title for the input box.
+  #
+  # @overload inputbox(prompts, defaults, list, title)
+  #
+  #   @param [Array<String>] prompts
+  #     An array of prompt names appearing in the input box
+  #     adjacent to input fields.
+  #   @param [Array<String>] defaults
+  #     An array of default values for the input
+  #     fields.
+  #   @param [String, Array<String>] list
+  #     An array containing pipe-separated strings of options.
+  #   @param [String] title
+  #     The title for the input box.
+  #
+  # @return [Array<String>, false] An array of returned values if the user did
   #   not cancel the dialog.  If the user canceled the
   #   dialog, false is returned.  The returned values in the
   #   array will be in the same order as the input fields.
   #
   # @version SketchUp 6.0
-  def self.inputbox(prompts, defaults, title_or_list, title)
+  def self.inputbox(*args)
   end
 
   # The inspector_names method is used to returns the names of all the
@@ -146,37 +153,39 @@ module UI
   # @example
   #   inspectors = UI.inspector_names
   #
-  # @return inspectors - an array of strings containing the names
+  # @return [Array<String>] an array of strings containing the names
   #   of inspectors.
   #
   # @version SketchUp 6.0
   def self.inspector_names
   end
 
-  # The menu method retrieves a SketchUp's menu object with a given name. This
+  # The {#menu} method retrieves a SketchUp's menu object with a given name. This
   # is the first step toward adding your own custom items to the bottom
   # of SketchUp's menus.
   #
   # Valid menu names are: "File", "Edit", "View", "Camera", "Draw", "Tools",
   # "Window", "Extensions" and "Help".
   #
-  # Note that the "Extensions" menu was named "Plugins" prior to SketchUp 2015.
-  # For backward compatibility "Plugins" still works.
-  #
   # @example
   #   tool_menu = UI.menu("Tools")
   #   tool_menu.add_item("Cheese Tool") {
   #     UI.messagebox("Cheese activated.")
   #   }
   #
-  # @param menuname
-  #   Optional. The name of an existing menu. Default menu
-  #   is "Extensions"
+  # @note The "Extensions" menu was named "Plugins" prior to SketchUp 2015.
+  #   For backward compatibility "Plugins" still works.
+  #
+  # @note In versions prior to SketchUp 2018 this would crash if you passed an
+  #   empty string.
+  #
+  # @param menu_name
+  #   The name of an existing top level menu.
   #
-  # @return menu - a menu object.
+  # @return [Sketchup::Menu]
   #
   # @version SketchUp 6.0
-  def self.menu(menuname = "Extensions")
+  def self.menu(menu_name = "Plugins")
   end
 
   # Creates a dialog box containing static text with a series of buttons for
@@ -230,14 +239,14 @@ module UI
   # @example
   #   mypages = UI.model_info_pages
   #
-  # @return mypages - an array of strings containing the names of
+  # @return [Array<String>] an array of strings containing the names of
   #   model info pages.
   #
   # @version SketchUp 6.0
   def self.model_info_pages
   end
 
-  # The {#openURL} method is used to open the default Web browser to a URL.
+  # The {.openURL} method is used to open the default Web browser to a URL.
   #
   # @example
   #   status = UI.openURL("http://www.sketchup.com")
@@ -266,13 +275,10 @@ module UI
   #   chosen_image = UI.openpanel("Open Image File", "c:/", "Image Files|*.jpg;*.png;||")
   #   chosen_image = UI.openpanel("Open CAD File", "c:/", "DXF|*.dxf|DWG|*.dwg||")
   #
-  # @param title
+  # @param [String] title
   #   The title to apply to the open dialog box.
   #
-  # @param directory
-  #   The default directory for the open panel.
-  #
-  # @param filename
+  # @param [String] filename
   #   The default filename for the open panel. On Windows, you
   #   can alternatively pass a wildcard filter using this
   #   format: UIname|wildcard||. Additional filter dropdown
@@ -283,7 +289,10 @@ module UI
   #   single line using a semicolon-separated list in the
   #   filter field: ui_name|wildcard1;wildcard2||.
   #
-  # @return string - the full path and name of the file selected, or
+  # @param [String] directory
+  #   The default directory for the open panel.
+  #
+  # @return [String] the full path and name of the file selected, or
   #   nil if the dialog was canceled.
   #
   # @version SketchUp 6.0
@@ -296,13 +305,13 @@ module UI
   # @example
   #   UI.play_sound "Plugins/mediadiscussion.wav"
   #
-  # @param filename
+  # @param [String] filename
   #   the relative path to the filename from the SketchUp
   #   install directory, or an absolute path to the file. (See
   #   Sketchup.find_support_file for a way to search for a
   #   specific file.)
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 6.0
   def self.play_sound(filename)
@@ -314,8 +323,8 @@ module UI
   # @example
   #   prefs = UI.preferences_pages
   #
-  # @return prefspages - an array of strings containing the names
-  #   of prefspages.
+  # @return [Array<String>] an array of strings containing the names
+  #   of preference pages.
   #
   # @version SketchUp 6.0
   def self.preferences_pages
@@ -330,12 +339,28 @@ module UI
   # @example
   #   UI.refresh_inspectors
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 7.0
   def self.refresh_inspectors
   end
 
+  # Tells SketchUp to refresh all floating toolbars. This is useful when you need
+  # to manually force a refresh after you've made a change to the document via
+  # Ruby. Generally, SketchUp will keep these in sync for you, but occasionally
+  # it does not, such as when {Sketchup::Model#start_operation} has disabled UI
+  # updates.
+  # This only affects macOS, on Windows the toolbars are always refreshing.
+  #
+  # @example
+  #   UI.refresh_toolbars
+  #
+  # @return [nil]
+  #
+  # @version SketchUp 2018
+  def self.refresh_toolbars
+  end
+
   # The savepanel method is used to display the Save dialog box. The path that
   # is returned can then be used inside code to save out a text or image file.
   # See the standard Ruby class File for examples of reading and writing from
@@ -349,13 +374,10 @@ module UI
   # @example
   #   path_to_save_to = UI.savepanel("Save Image File", "c:\\", "Shapes.jpg")
   #
-  # @param title
+  # @param [String] title
   #   The title to apply to the save dialog box.
   #
-  # @param directory
-  #   The default directory for the save panel.
-  #
-  # @param filename
+  # @param [String] filename
   #   The default filename for the save panel. On Windows, you
   #   can alternatively pass a mask, like "*.txt", to have all
   #   the .txt files display. If you want multiple file types
@@ -363,7 +385,10 @@ module UI
   #   filename and separate them with a semicolon, like this:
   #   "*.txt;*.doc".
   #
-  # @return string - the full path and name of the file
+  # @param [String] directory
+  #   The default directory for the save panel.
+  #
+  # @return [String] the full path and name of the file
   #   selected or nil if the dialog was canceled.
   #
   # @version SketchUp 6.0
@@ -424,12 +449,10 @@ module UI
   #     directory: "C:/images"
   #   )
   #
-  # @param options
-  #   hash (optional)   The dialog can be customized by
-  #   providing a hash or named arguments of
-  #   options.
+  # @param [Hash] options
+  #   The dialog can be customized by providing a hash or named arguments of options.
   #
-  # @return string or array - A string with the full path of the
+  # @return [String, Array<String>] A string with the full path of the
   #   directory selected when
   #   :select_multiple option is set to
   #   false otherwise an array of strings
@@ -452,10 +475,10 @@ module UI
   #     UI.set_cursor(cursor_id)
   #   end
   #
-  # @param cursor_id
+  # @param [Integer] cursor_id
   #   The id of the cursor you want to display.
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 6.0
   def self.set_cursor(cursor_id)
@@ -469,13 +492,13 @@ module UI
   # @example
   #   status = UI.set_toolbar_visible("Camera", true)
   #
-  # @param name
+  # @param [String] name
   #   The name of a Ruby toolbar.
   #
-  # @param visible
+  # @param [Boolean] visible
   #   True to make the toolbar visible, false to hide it.
   #
-  # @return result - true if successful, false if not.
+  # @return [Boolean] true if successful, false if not.
   #
   # @version SketchUp 6.0
   def self.set_toolbar_visible(name, visible)
@@ -497,28 +520,31 @@ module UI
   # name. You can get the list of valid inspectors with UI.inspector_names.
   #
   # @example
-  #   status = UI.show_inspector "Components"
+  #   status = UI.show_inspector("Components")
   #
-  # @param name
+  # @param [String] name
   #   The name of inspector that you want to display.
   #
-  # @return status - true if successful, false if unsuccessful
+  # @return [Boolean] true if successful, false if unsuccessful
   #
   # @version SketchUp 6.0
   def self.show_inspector(name)
   end
 
-  # The show_model_info method is used to display the model info dialog for a
+  # The {.show_model_info} method is used to display the model info dialog for a
   # specific page. You can get the list of valid dialogs with
-  # UI.model_info_pages.
+  # {UI.model_info_pages}.
+  #
+  # [SketchUp 2014] <code>"Classifications"</code> page was added.
+  # [SketchUp 2017] <code>"Extensions"</code> page was removed.
   #
   # @example
-  #   status = UI.show_model_info('Credits')
+  #   UI.show_model_info('Credits')
   #
-  # @param page_name
+  # @param [String] page_name
   #   The name of the model info dialog you want to display.
   #
-  # @return status - true
+  # @return [Boolean]
   #
   # @version SketchUp 6.0
   def self.show_model_info(page_name)
@@ -532,10 +558,10 @@ module UI
   # @example
   #   status = UI.show_preferences('GraphicsCard')
   #
-  # @param page_name
+  # @param [String] page_name
   #   The name of the preferences dialog you want to display.
   #
-  # @return status - true
+  # @return [Boolean] true
   #
   # @version SketchUp 6.0
   def self.show_preferences(page_name)
@@ -554,14 +580,14 @@ module UI
   #   # Beep once after 10 seconds.
   #   id = UI.start_timer(10, false) { UI.beep }
   #
-  # @param [optional] repeat
+  # @param [Boolean] repeat
   #   true if you want the timer to repeat, false
   #   (or omit) if you do not want it to repeat.
   #
-  # @param seconds
+  # @param [Numeric] seconds
   #   The time in seconds before your code should be called.
   #
-  # @return timer - a timer ID
+  # @return [Integer] a timer ID
   #
   # @version SketchUp 6.0
   #
@@ -577,10 +603,10 @@ module UI
   #   id = UI.start_timer(10) { UI.beep }
   #   UI.stop_timer(id)
   #
-  # @param id
+  # @param [Integer] id
   #   The timer id for the timer that you want to stop.
   #
-  # @return nil
+  # @return [nil]
   #
   # @version SketchUp 6.0
   def self.stop_timer(id)
@@ -592,10 +618,10 @@ module UI
   # @example
   #   toolbar = UI.toolbar('Test')
   #
-  # @param name
+  # @param [String] name
   #   The name of the Ruby toolbar.
   #
-  # @return toolbar - a Toolbar object
+  # @return [UI::Toolbar] a Toolbar object
   #
   # @version SketchUp 6.0
   def self.toolbar(name)
@@ -608,7 +634,7 @@ module UI
   # @example
   #   names = UI.toolbar_names
   #
-  # @return names - Array of strings representing toolbar names.
+  # @return [Array<String>] Array of strings representing toolbar names.
   #
   # @version SketchUp 6.0
   def self.toolbar_names
@@ -622,10 +648,10 @@ module UI
   # @example
   #   status = UI.toolbar_visible?("Camera")
   #
-  # @param name
+  # @param [String] name
   #   The name of a native toolbar.
   #
-  # @return status - true if successful, false if unsuccessful
+  # @return [Boolean]
   #
   # @return [Boolean]
   #