AMS Library

Documentation: https://www.rubydoc.info/github/AntonSynytsia/ams_lib/index

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 fullscreen, 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.

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
  dir = ::File.expand_path(::File.dirname(__FILE__))
  dir.force_encoding('UTF-8') if RUBY_VERSION !~ /^1.8/
  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, have it load the main_entry file:

dir = ::File.expand_path(::File.dirname(__FILE__))
dir.force_encoding('UTF-8') if RUBY_VERSION !~ /^1.8/
fpath = ::File.join(dir, "MY_EXTENSION_NAME/main_entry")
extension = ::SketchupExtension.new(MY_EXTENSION_NAME, fpath)

Next section shows a few examples of what could be utilized in the main 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

  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 obsever
  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 Extension Store.

To download from the repository, do the following:

1. Compile binaries. See CompileInstructions.md for details.
2. Copy ams_Lib folder and ams_Lib.rb, located at RubyExtension/, to your plugins folder.