Module: AMS::Sketchup

Defined in:
Documentation/ams/sketchup.rb

Overview

Note:

Windows only!

The Sketchup namespace contains functions that allow user to get various information on SketchUp window and its child windows.

Since:

  • 2.0.0

Class Method Summary collapse

Class Method Details

.activateBoolean Also known as: bring_to_top

Set main window active.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.activate_scenes_bar_tab(tab_index) ⇒ Boolean

Activate (highlight) scene tab without activating the associated page.

Parameters:

  • tab_index (Fixnum)

Returns:

  • (Boolean)

    success

Since:

  • 3.5.0

.add_observer(object) ⇒ Boolean

Note:

An observer can be a class, module, or a class instance. Your observer will work as long as the callback methods are public.

Note:

Your observer is not supposed to contain every callback method from the observers list. You may include/elude those as you wish.

Note:

A unique extension swp or swo is added in front of each observer method. SWP stands for Sketchup Window Procedure, and SWO stands for Sketchup Window Observer. Both SWP and SWO events are capable to monitor window messages, but SWP events are also capable to make decisions to the message, whether or not the message should interact with SketchUp window. If the return value for the SWP callback method is 1, the message associated with the event will not interact with SketchUp window. For example, returning 1 in the swp_on_key_down event will prevent the key from interacting with SketchUp window, which means any shortcut associated with such key will not be triggered. SWP events may come in handy for extensions that want more control over SketchUp.

Add object to the observers list.

Examples:

Adding observer from a class instance:

class MySketchupObserver
  def swo_on_switch_full_screen(state)
    puts 'Main window was set full screen!' if state
  end
end # module MySketchupObserver
AMS::Sketchup.add_observer(MySketchupObserver.new)

Adding observer from a module:

module MySketchupObserver
  def self.swo_on_switch_full_screen(state)
    puts 'Main window was set full screen!' if state
  end
end # module MySketchupObserver
AMS::Sketchup.add_observer(MySketchupObserver)

Another way to add observer from a module:

module MySketchupObserver
  class << self
    def swo_on_switch_full_screen(state)
      puts 'Main window was set full screen!' if state
    end
  end # class << self
end # module MySketchupObserver
AMS::Sketchup.add_observer(MySketchupObserver)

Parameters:

  • object (Object)

Returns:

  • (Boolean)

    success

See Also:

Since:

  • 2.0.0

.closeBoolean

Note:

This behaves the same way as clicking the 'X' button.

Close current SketchUp application.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.close_dialogsFixnum

Note:

Ignored dialogs won't be included in this operation.

Close all dialogs and trays.

Returns:

  • (Fixnum)

    Number of dialogs closed.

Since:

  • 2.0.0

.close_toolbarsFixnum

Close all floating toolbars.

Returns:

  • (Fixnum)

    Number of floating toolbars closed.

Since:

  • 2.0.0

.close_traysFixnum

Close all trays.

Returns:

  • (Fixnum)

    Number of trays closed.

Since:

  • 3.5.0

.find_child_window_by_caption(parent_handle, caption, include_sub_childs = false, full_match = true, case_sensitive = true) ⇒ Fixnum?

Note:

This function will iterate through windows belonging to the current SketchUp process only. All windows belonging to a different process or a different SketchUp application will not be searched.

Find handle to a child window with a specific caption.

Parameters:

  • parent_handle (Fixnum)

    Handle to a valid parent window.

  • caption (String)

    Text to match.

  • include_sub_childs (Boolean) (defaults to: false)

    Whether to include windows descending from the child windows.

  • full_match (Boolean) (defaults to: true)

    Whether to match full (true) or part (false) of the window text.

  • case_sensitive (Boolean) (defaults to: true)

    Whether to consider uppercased/lowercased letters.

Returns:

  • (Fixnum, nil)

    Handle to the first found window if any.

Since:

  • 3.0.0

.find_child_window_by_class_name(parent_handle, class_name, include_sub_childs = false, full_match = true, case_sensitive = true) ⇒ Fixnum?

Note:

This function will iterate through windows belonging to the current SketchUp process only. All windows belonging to a different process or a different SketchUp application will not be searched.

Find handle to a child window with a specific class name.

Parameters:

  • parent_handle (Fixnum)

    Handle to a valid parent window.

  • class_name (String)

    Text to match.

  • include_sub_childs (Boolean) (defaults to: false)

    Whether to include windows descending from the child windows.

  • full_match (Boolean) (defaults to: true)

    Whether to match full (true) or part (false) of the window class name.

  • case_sensitive (Boolean) (defaults to: true)

    Whether to consider uppercased/lowercased letters.

Returns:

  • (Fixnum, nil)

    Handle to the first found window if any.

Since:

  • 3.0.0

.find_window_by_caption(caption, full_match = true, case_sensitive = true) ⇒ Fixnum?

Note:

This function will iterate through windows belonging to the current SketchUp process only. All windows belonging to a different process or a different SketchUp application will not be searched.

Find handle to a window with a specific caption.

Parameters:

  • caption (String)

    Text to match.

  • full_match (Boolean) (defaults to: true)

    Whether to match full (true) or part (false) of the window text.

  • case_sensitive (Boolean) (defaults to: true)

    Whether to consider uppercased/lowercased letters.

Returns:

  • (Fixnum, nil)

    Handle to the first found window if any.

Since:

  • 3.0.0

.find_window_by_class_name(class_name, full_match = true, case_sensitive = true) ⇒ Fixnum?

Note:

This function will iterate through windows belonging to the current SketchUp process only. All windows belonging to a different process or a different SketchUp application will not be searched.

Find handle to a window with a specific class name.

Parameters:

  • class_name (String)

    Text to match.

  • full_match (Boolean) (defaults to: true)

    Whether to match full (true) or part (false) of the window class name.

  • case_sensitive (Boolean) (defaults to: true)

    Whether to consider uppercased/lowercased letters.

Returns:

  • (Fixnum, nil)

    Handle to the first found window if any.

Since:

  • 3.0.0

.get_active_dialogsArray<Fixnum>

Note:

Ignored dialogs are not included in this list.

Get all used pop-up windows of the current SketchUp application.

Returns:

  • (Array<Fixnum>)

    An array of window handles.

Since:

  • 2.0.0

.get_active_toolbarsArray<Fixnum>

Note:

Ignored toolbars are not included in this list.

Get all used floating toolbars.

Returns:

  • (Array<Fixnum>)

    An array of window handles.

Since:

  • 2.0.0

.get_captionString

Get main window title text.

Returns:

  • (String)

Since:

  • 2.0.0

.get_dialogsArray<Fixnum>

Note:

Ignored dialogs are not included in this list.

Get all pop-up windows of the current SketchUp application.

Returns:

  • (Array<Fixnum>)

    An array of window handles.

Since:

  • 2.0.0

.get_executable_pathString

Get full path to SketchUp.exe.

Returns:

  • (String)

Since:

  • 2.0.0

.get_executalbe_nameString

Get executable name of this application. In most cases it would be “SketchUp.exe”.

Returns:

  • (String)

Since:

  • 3.1.0

.get_main_windowFixnum

Get handle to the main window of the current SketchUp application.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_menu_barFixnum

Get handle to the menu bar of the main window.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_module_handleFixnum

Get module handle to the current SketchUp application.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_other_main_windowsArray<Fixnum>

Get handles to all SketchUp main windows, except for the current one.

Returns:

  • (Array<Fixnum>)

Since:

  • 3.1.0

.get_process_idFixnum

Get process id of the current SketchUp application.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_registry_pathString

Get registry path of the current SketchUp application.

Returns:

  • (String)

Since:

  • 2.0.0

.get_scenes_barFixnum

Get handle to the scenes bar of the main window.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_status_barFixnum

Get handle to the status bar of the main window.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_thread_idFixnum

Get thread id of the current SketchUp application.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_toolbar_containersArray<Fixnum>

Get handles to the four toolbar containers of the main window.

Returns:

  • (Array<Fixnum>)

    [top toolbar, bottom toolbar, left toolbar, right toolbar]

Since:

  • 2.0.0

.get_toolbarsArray<Fixnum>

Note:

Ignored toolbars are not included in this list.

Get all floating toolbars of the current SketchUp application.

Returns:

  • (Array<Fixnum>)

    An array of window handles.

Since:

  • 2.0.0

.get_viewportFixnum

Get handle to the view window of the main window.

Returns:

  • (Fixnum)

Since:

  • 2.0.0

.get_viewport_centerArray<Fixnum>

Get viewport center in screen coordinates.

Returns:

  • (Array<Fixnum>)

    [x,y]

Since:

  • 2.0.0

.get_viewport_originArray<Fixnum>

Get upper-left corner of the view window in screen coordinates.

Returns:

  • (Array<Fixnum>)

    [x,y]

Since:

  • 2.0.0

.get_viewport_rectArray<Fixnum>

Get upper-left and lower-right corners of the view window in screen coordinates, relative to the upper-left corner of the screen.

Returns:

  • (Array<Fixnum>)

    [x1,y1, x2,y2]

Since:

  • 2.0.0

.get_viewport_sizeArray<Fixnum>

Note:

This is same as view.vp_width and view.vp_height.

Get width and height of the view window in pixels.

Returns:

  • (Array<Fixnum>)

    [width, height]

Since:

  • 2.0.0

.get_visible_dialogsArray<Fixnum>

Note:

Ignored dialogs are not included in this list.

Get all visible pop-up windows of the current SketchUp application.

Returns:

  • (Array<Fixnum>)

    An array of window handles.

Since:

  • 2.0.0

.get_visible_toolbarsArray<Fixnum>

Note:

Ignored toolbars are not included in this list.

Get all visible floating toolbars of the current SketchUp application.

Returns:

  • (Array<Fixnum>)

    An array of window handles.

Since:

  • 2.0.0

.ignore_dialog(handle) ⇒ Boolean

Elude dialog from the show_dialogs and close_dialogs operations.

Parameters:

  • handle (Fixnum)

    A handle to a valid dialog window.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.ignore_toolbar(handle) ⇒ Boolean

Elude toolbar from the show_toolbars and close_toolbars operations.

Parameters:

  • handle (Fixnum)

    A handle to a valid toolbar window.

Returns:

  • (Boolean)

    success

Since:

  • 3.0.0

.include_dialog(handle) ⇒ Boolean

Note:

By default, all dialogs are included in the show/hide/close dialogs operation. This method is used to remove dialog from the ignore list.

Include dialog in the show_dialogs and close_dialogs operations.

Parameters:

  • handle (Fixnum)

    A handle to a dialog window.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.include_toolbar(handle) ⇒ Boolean

Note:

By default, all toolbars are included in the show/hide/close toolbars operation. This method is used to remove toolbar from the ignore list.

Include toolbar in the show_toolbars and close_toolbars operations.

Parameters:

  • handle (Fixnum)

    A handle to a toolbar window.

Returns:

  • (Boolean)

    success

Since:

  • 3.0.0

.is_active?Boolean

Determine whether the current active window belongs to the current SketchUp application.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_full_screen?Boolean

Determine whether main window is full screen.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_main_window_active?Boolean

Determine whether SketchUp main window is active.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_maximized?Boolean

Determine whether main window is maximized.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_menu_bar_set?Boolean

Determine whether menu bar is set.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_minimized?Boolean

Determine whether main window is minimized.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_restored?Boolean

Determine whether main window is restored.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_scenes_bar_empty?Boolean

Determine whether scenes bar is empty. Scenes bar is empty if there are no pages in the model.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_scenes_bar_filled?Boolean

Determine whether scenes bar is filled. Scenes bar is filled if there is at least one page in the model.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_scenes_bar_visible?Boolean

Determine whether scenes bar is visible.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_status_bar_visible?Boolean

Determine whether status bar is visible.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_toolbar_container_empty?(bar) ⇒ Boolean

Determine whether toolbar container(s) is/are empty.

Parameters:

  • bar (Fixnum)

    A number representing which bar(s) to check. Use one of the following numbers:

    1. top bar

    2. bottom bar

    3. left bar

    4. right bar

    5. at least one bar

    6. all bars

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_toolbar_container_filled?(bar) ⇒ Boolean

Determine whether toolbar container(s) is/are filled.

Parameters:

  • bar (Fixnum)

    A number representing which bar(s) to check. Use one of the following numbers:

    1. top bar

    2. bottom bar

    3. left bar

    4. right bar

    5. at least one bar

    6. all bars

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_toolbar_container_visible?(bar) ⇒ Boolean

Determine whether toolbar container(s) is/are visible.

Parameters:

  • bar (Fixnum)

    A number representing which bar(s) to check. Use one of the following numbers:

    1. top bar

    2. bottom bar

    3. left bar

    4. right bar

    5. at least one bar

    6. all bars

    7. all filled bars

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_viewport_border_set?Boolean

Determine whether viewport border is set.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.maximizeBoolean

Set main window maximized.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.minimizeBoolean

Set main window minimized.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.refreshBoolean

Refresh the current SketchUp application.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.remove_observer(object) ⇒ Boolean

Remove object from the observers list.

Parameters:

  • object (Object)

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.restoreBoolean

Set main window to normal placement.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.send_user_message(receiver_handle, id, user_data) ⇒ Boolean

Note:

If a destination window that a message is sent to by this function has an active swo_on_user_message observer, in most cases, it will receive the message sent by this function; otherwise, it wont.

Note:

This function waits until the receiving window completes processing a message before returning.

Note:

32-bit SU windows cannot communicate to 64-bit SU windows; However, 64-bit SU windows can communicate to 32-bit SU windows. For example, assume you have two SU windows open, SU2014 (32-bit) and SU2016 (64-bit). Calling send_user_message from the SU2014 window to the SU2016 window, will not succeed in the SU2016 window receiving the message. However, if you call send_user_message from the SU2016 window to the SU2014 window, the message will succeed in being received by the SU2014 window.

Send information to another window.

Examples:

# Open two or more SketchUp windows and paste the following, except the last
# line, into the Ruby consoles of each SketchUp window.
class MyTool

  # Our unique communication id
  PORT = 123

  def communicate_to_others(text)
    others = AMS::Sketchup.get_other_main_windows
    others.each { |handle|
      AMS::Sketchup.send_user_message(handle, PORT, text.to_s)
    }
  end

  def swo_on_user_message(sender, id, data)
    # Don't bother processing the message if ID is not ours.
    return if (id != PORT)
    # Process the message.
    p data
  end

end # class MyTool

my_tool = MyTool.new
# Register our class with SketchUp window observers.
AMS::Sketchup.add_observer(my_tool)

# Paste the following into one of the SU windows. Ensure that Ruby
# consoles are still open in other SU windows.
# As a result of calling the command below, all other SU windows should
# end-up having a hello message displayed in their Ruby consoles.
my_tool.communicate_to_others("Hello! I'm sent from a SketchUp window with a process id of #{Process.pid}")

Parameters:

  • receiver_handle (Fixnum, nil)

    A handle to a destination window. Pass nil to send to all windows.

  • id (Fixnum)

    A unique message identifier to send along with a message, a value between 0 and 4095. The ID feature allows user to easily filter his/her messages from other messages.

  • user_data (nil, Boolean, Fixnum, Bignum, Float, String, Symbol, Array, Hash)

    Information to transfer along with a message. An Array and a Hash can only contain objects of NilClass, TrueClass, FalseClass, +Fixnum, Float, Bignum, String, Symbol, Array, and Hash types. This, as well, applies to sub-arrays and sub-hashes.

Returns:

  • (Boolean)

    success

Raises:

  • (TypeError)

    if given handle to a window is not valid.

  • (RangeError)

    if given ID is not within a range of 0 and 4095.

  • (TypeError)

    if given user-data or sub-user-data type is not supported.

Since:

  • 3.1.0

.set_caption(caption) ⇒ Boolean

Set main window title text.

Parameters:

  • caption (String)

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.set_menu_bar(state) ⇒ Boolean

Set/Remove menu bar.

Parameters:

  • state (Boolean)

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.set_viewport_border(state) ⇒ Boolean

Set/Remove viewport border, a thin edge surrounding the view.

Parameters:

  • state (Boolean)

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.show_dialogs(state) ⇒ Fixnum

Note:

Ignored dialogs won't be included in this operation.

Show/hide all dialogs and trays.

Parameters:

  • state (Boolean)

Returns:

  • (Fixnum)

    Number of dialogs shown or hidden.

Since:

  • 2.0.0

.show_scenes_bar(state, refresh = true) ⇒ Boolean

Show/hide scenes bar.

Parameters:

  • state (Boolean)
  • refresh (Boolean) (defaults to: true)

    Whether to update after changing state.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.show_status_bar(state, refresh = true) ⇒ Boolean

Show/hide status bar.

Parameters:

  • state (Boolean)
  • refresh (Boolean) (defaults to: true)

    Whether to update after changing state.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.show_toolbar_container(bar, state, refresh = true) ⇒ Boolean

Show/hide toolbar container(s).

Parameters:

  • bar (Fixnum)

    A number representing which bar(s) to show/hide. Use one of the following numbers:

    1. top bar

    2. bottom bar

    3. left bar

    4. right bar

    5. all filled bars

    6. all bars

  • state (Boolean)

    true to show; false to hide.

  • refresh (Boolean) (defaults to: true)

    Whether to update after changing state.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.show_toolbars(state) ⇒ Fixnum

Show/hide all floating toolbars.

Parameters:

  • state (Boolean)

Returns:

  • (Fixnum)

    Number of floating toolbars shown or hidden.

Since:

  • 2.0.0

.show_trays(state) ⇒ Fixnum

Show/hide all trays.

Parameters:

  • state (Boolean)

Returns:

  • (Fixnum)

    Number of trays shown or hidden.

Since:

  • 3.5.0

.switch_full_screen(state, reset_mode = 2, set_mode = 1) ⇒ Boolean

Switch main window full screen.

Parameters:

  • state (Boolean)

    true to set full screen; false unset from full screen.

  • reset_mode (Fixnum) (defaults to: 2)

    This parameter has effect only when main window is unset from full screen mode. Use one of the following reset modes:

    • 0 - Set to restored mode.

    • 1 - Set to maximized mode.

    • 2 - Set to original placement.

  • set_mode (Fixnum) (defaults to: 1)

    This parameter was added in 3.1.4 and has an effect only when main window is set to full screen. Use one of the following set modes:

    • 0 - Set full screen on the primary/main monitor.

    • 1 - Set full screen on the monitor SU window is associated to.

    • 2 - Set full screen on all monitors.

Returns:

  • (Boolean)

    success

Since:

  • 2.0.0

.threaded_messagebox(caption, text, type = 0x00002030, owner_handle = nil) {|result| ... } ⇒ Fixnum?

Note:

Any errors occurring in the threaded block will be ignored.

Display a messagebox on a separate thread.

Examples:

Process while loop until a messagebox is closed.

caption = 'Decision'
text = 'Press OK to finish.'
done = false
thread_id = AMS::Sketchup.threaded_messagebox(caption, text) { |result|
  done = true
}
if thread_id
  while (!done)
    # Do something
  end
  puts 'Done'

  # You can also close the messagebox manually, in case you
  # finish doing something before the messagebox is closed.
  hwnd = AMS::Sketchup.find_window_by_caption(caption)
  AMS::Window.close(hwnd) if hwnd
end

Parameters:

  • caption (String)

    Title

  • text (String)

    Message

  • type (Fixnum) (defaults to: 0x00002030)

    Messagebox configuration flags

  • owner_handle (Fixnum) (defaults to: nil)

    Handle to a valid window or nil.

Yields:

  • Triggered when the messagebox is closed.

Yield Parameters:

  • result (Fixnum)

    Message result

Returns:

  • (Fixnum, nil)

    A handle to the thread with the messagebox or nil on failure.

See Also:

Since:

  • 3.5.0