AMS Library

Documentation: https://antonsynytsia.github.io/manuals/ams-lib/v3.7.1/doc/

Description

AMS Library is a collection of functions and utilities for interacting with SketchUp window and its input procedures via the Microsoft Windows API. Features include switching SketchUp full screen, monitoring window state changes, monitoring keyboard and mouse events, and preventing the interference of SketchUp keyboard and mouse shortcut accelerators. Such features provide extension developers with additional control over their tool. In addition to utilizing Sketchup::Tool events, a developer can utilize AMS Library's keyboard and mouse callback functions to receive input of all the messages, including the mouse wheel. AMS Library's callback events are registered in form of observers (although they are also modifiers), meaning a tool does not necessarily have to be an active tool in order to receive input events. This allows for operating extensions while other extensions are operating. In addition to the observer and modifier procedures, AMS Library provides Windows API functionality for tweaking dialogs to a next level, including removing the surrounding window frame and applying window transparency. Furthermore, AMS Library comes with various geometry and entity hierarchy manipulation functions. In a way, AMS Library provides developers with functionality not achievable with SketchUp Ruby API.

Purpose

To provide extension developers with more control over their tool via an additional API.

Usage

AMS Library is intended to be a dependency extension for other extensions. Extensions planning to use AMS Library need to verify AMS Library, of a specific version, is installed, shown in the following sample:

# FILE: main_entry.rb

tload_me = true

# Load and verify AMS Library
begin
  # Attempt to load
  require 'ams_Lib/main'

  # Verify version
  tload_me = false if AMS::Lib::VERSION.to_f < 3.6

rescue LoadError
  tload_me = false

end

if tload_me
  # Load the main file
  cfpath = __FILE__.dup
  cfpath.force_encoding('UTF-8') if cfpath.respond_to?(:force_encoding)
  dir = ::File.expand_path(::File.dirname(cfpath))
  require ::File.join(dir, "main")

else
  msg = "[MY_EXTENSION_NAME] requires AMS Library, version 3.6.0 or later! "
  msg << "This extension will not be loaded with the library not installed or outdated. "
  msg << "Would you like to navigate to the library's download page?"
  tload_me = false
  if ::UI.messagebox(msg, MB_YESNO) == IDYES
    ::UI.openURL('http://sketchucation.com/forums/viewtopic.php?f=323&t=55067#p499835')
  end

end

When registering your extension (e.g. from my_Plugin.rb), have it load the main_entry.rb file:

module MyPlugin

  MY_EXTENSION_NAME = 'MY Plugin'

  cfpath = __FILE__.dup
  cfpath.force_encoding('UTF-8') if cfpath.respond_to?(:force_encoding)
  efpath = ::File.expand_path('../my_Plugin/main_entry', cfpath)
  extension = ::SketchupExtension.new(MY_EXTENSION_NAME, efpath)

  # ...

end

The presented plugin structure is as follows:

  • my_Plugin - folder

    • main_entry.rb - loaded by my_Plugin.rb
    • main.rb - loaded by main_entry.rb
    • other files... - loaded by main.rb

  • my_Plugin.rb - file that calls my_Plugin/main_entry.rb

Next section shows a few examples of what could be utilized in the main.rb file, which is conditionally loaded in the main_entry.rb file.

Examples

The following sections show a few examples regarding the use of AMS Library. All functions and utilities are available in the documentation.

Using Observers and Modifiers

# FILE: main.rb

require 'ams_Lib/main'

# Monitoring and processing SketchUp window events.
class MySketchupObserver

  def swo_on_switch_full_screen(state)
    if state
      puts 'Main window switched full screen!'
    else
      puts 'Main window switched to original placement.'
    end
  end

  # @see AMS::SketchupObserver.#swp_on_mouse_wheel_rotate
  def swp_on_mouse_wheel_rotate(x, y, dir)
    puts "mouse wheel rotated - pos : (#{x}, #{y}), dir : #{dir}"
    # Prevent mouse wheel from interacting with SU window. Returning 1 means
    # mouse wheel zoom in/out operation would be blocked, which might be
    # handy for those seeking more control over SketchUp window. Returning
    # any other value won't block the event.
    return 1
  end

end # class MySketchupObserver

unless file_loaded?(__FILE__)
  file_loaded(__FILE__)

  # Register the observer
  AMS::Sketchup.add_observer(MySketchupObserver.new)
end

Switching Full Screen on Single Monitor

# Setting SketchUp full screen on the monitor SU window is associated to.
AMS::Sketchup.switch_full_screen(true)

Switching Full Screen on Multiple Monitors

# Setting SketchUp full screen on all monitors.
AMS::Sketchup.switch_full_screen(true, 2, 2)

Obtaining Handle to Main Window

# Get handle to SketchUp window.
AMS::Sketchup.get_main_window

Requirements

  • Microsoft Windows XP or later
  • Mac OS X 10.8 or later, 64bit only
  • SketchUp 6 or later

Installation Instructions

AMS Library releases are available at Extension Warehouse or SketchUcation PluginStore.

To download from the repository, do the following:

  1. Compile binaries. See compile_instructions.md for details.
  2. Copy ams_Lib folder and ams_Lib.rb from ./ext-ruby/, to your plugins folder.