Module: AMS::Sketchup

Defined in:
docs/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

.activate_scenes_bar_tab(tab_index) ⇒ Boolean

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

Parameters:

  • tab_index (Integer)

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 have a public access.

Note:

An observer is not required to utilize all of the callback methods from the observers list. Feel free to include/exlude those as you wish.

Note:

A unique suffix 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 monitor window messages, but SWP events additionally permit you to make decisions to the messages, whether or not to allow a message to interact with the SketchUp window. If the return value for an SWP callback method is 1, the message associated with the event will not interact with the SketchUp window. For example, utilizing the swp_on_key_down callback and returning 1 for a particular key, prevents the key from interacting with the SketchUp window procedure, which means any keyboard shortcut associated with the key will not be triggered. SWP events come in handy for extensions requiring greater 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

.bring_to_top ⇒ Boolean

Set main window active.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.close ⇒ Boolean

Note:

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

Close current SketchUp application.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.close_dialogs ⇒ Integer

Note:

Dialogs ignored via ignore_dialog are not included in this operation.

Close all dialogs and trays.

Returns:

  • (Integer) —

    Number of dialogs closed.

See Also:

Since:

  • 2.0.0

.close_toolbars ⇒ Integer

Close all floating toolbars.

Returns:

  • (Integer) —

    Number of floating toolbars closed.

Since:

  • 2.0.0

.close_trays ⇒ Integer

Close all trays.

Returns:

  • (Integer) —

    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) ⇒ Integer?

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 (Integer) —

    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:

  • (Integer, 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) ⇒ Integer?

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 (Integer) —

    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:

  • (Integer, nil) —

    Handle to the first found window if any.

Since:

  • 3.0.0

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

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:

  • (Integer, 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) ⇒ Integer?

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:

  • (Integer, nil) —

    Handle to the first found window if any.

Since:

  • 3.0.0

.get_active_dialogs ⇒ Array<Integer>

Note:

Ignored dialogs are not included in this list.

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

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 2.0.0

.get_active_toolbars ⇒ Array<Integer>

Note:

Ignored toolbars are not included in this list.

Get all used floating toolbars.

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 2.0.0

.get_caption ⇒ String

Get main window title text.

Returns:

  • (String)

Since:

  • 2.0.0

.get_dialogs ⇒ Array<Integer>

Note:

Ignored dialogs are not included in this list.

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

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 2.0.0

.get_executable_path ⇒ String

Get full path to SketchUp.exe.

Returns:

  • (String)

Since:

  • 2.0.0

.get_executalbe_name ⇒ String

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

Returns:

  • (String)

Since:

  • 3.1.0

.get_main_window ⇒ Integer

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

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_menu_bar ⇒ Integer

Get handle to the menu bar of the main window.

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_module_handle ⇒ Integer

Get module handle to the current SketchUp application.

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_other_main_windows ⇒ Array<Integer>

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

Returns:

  • (Array<Integer>)

Since:

  • 3.1.0

.get_process_id ⇒ Integer

Get process id of the current SketchUp application.

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_registry_path ⇒ String

Get registry path of the current SketchUp application.

Returns:

  • (String)

Since:

  • 2.0.0

.get_scenes_bar ⇒ Integer

Get handle to the scenes bar of the main window.

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_status_bar ⇒ Integer

Get handle to the status bar of the main window.

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_thread_id ⇒ Integer

Get thread id of the current SketchUp application.

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_toolbar_containers ⇒ Array<Integer>

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

Returns:

  • (Array<Integer>) —

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

Since:

  • 2.0.0

.get_toolbars ⇒ Array<Integer>

Note:

Ignored toolbars are not included in this list.

Get all floating toolbars of the current SketchUp application.

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 2.0.0

.get_viewport ⇒ Integer

Get handle to the view window of the main window.

Returns:

  • (Integer)

Since:

  • 2.0.0

.get_viewport_center ⇒ Array<Integer>

Get viewport center in screen coordinates.

Returns:

  • (Array<Integer>) —

    [x,y]

Since:

  • 2.0.0

.get_viewport_origin ⇒ Array<Integer>

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

Returns:

  • (Array<Integer>) —

    [x,y]

Since:

  • 2.0.0

.get_viewport_rect ⇒ Array<Integer>

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<Integer>) —

    [x1,y1, x2,y2]

Since:

  • 2.0.0

.get_viewport_size ⇒ Array<Integer>

Note:

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

Get width and height of the view window in pixels.

Returns:

  • (Array<Integer>) —

    [width, height]

Since:

  • 2.0.0

.get_visible_dialogs ⇒ Array<Integer>

Note:

Ignored dialogs are not included in this list.

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

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 2.0.0

.get_visible_toolbars ⇒ Array<Integer>

Note:

Ignored toolbars are not included in this list.

Get all visible floating toolbars of the current SketchUp application.

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 2.0.0

.ignore_dialog(handle) ⇒ Boolean

Exlude dialog from the show_dialogs and close_dialogs operations.

Parameters:

  • handle (Integer) —

    A handle to a valid dialog window.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.ignore_toolbar(handle) ⇒ Boolean

Exlude toolbar from the show_toolbars and close_toolbars operations.

Parameters:

  • handle (Integer) —

    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 (Integer) —

    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 (Integer) —

    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

Note:

This simply cheks if the the scenes bar window is visible. This can return true even if the scenes bar has none tabs.

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 (Integer) —

    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 (Integer) —

    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_hidden?(bar) ⇒ Boolean

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

Parameters:

  • bar (Integer) —

    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. at least one filled bar
    8. all filled bars; this returns false if none bars are filled

Returns:

  • (Boolean)

Since:

  • 3.7.0

.is_toolbar_container_visible?(bar) ⇒ Boolean

Note:

The "at least one filled bar" option was added in 3.7.0; "all filled bars" was moved to 8.

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

Parameters:

  • bar (Integer) —

    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. at least one filled bar
    8. all filled bars; this returns false if none bars are filled

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_viewport_border_set? ⇒ Boolean

Determine whether viewport border is set.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_viewport_focused? ⇒ Boolean

Check if the viewport window has the keyboard focus.

Returns:

  • (Boolean)

See Also:

Since:

  • 3.7.0

.maximize ⇒ Boolean

Set main window maximized.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.minimize ⇒ Boolean

Set main window minimized.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.refresh ⇒ Boolean

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

.restore ⇒ Boolean

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 (Integer, nil) —

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

  • id (Integer) —

    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, Integer, 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, Integer,Float,Bignum,String,Symbol,Array, andHash` 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) ⇒ Integer

Note:

Dialogs ignored via ignore_dialog are not included in this operation.

Show/hide all dialogs and trays.

Parameters:

  • state (Boolean)

Returns:

  • (Integer) —

    Number of dialogs shown or hidden.

See Also:

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) —
    • true if the requested state differs from the current state;
    • false if the requested state matches the current state;
    • false if the scenes bar has none tabs and the requested state is to show the scenes bar.

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) —
    • true if the requested state is different from the current state;
    • false if the requested state matches the current state.

Since:

  • 2.0.0

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

Show/hide toolbar container(s).

Parameters:

  • bar (Integer) —

    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) —

    true if anything changed; false if not.

Since:

  • 2.0.0

.show_toolbars(state) ⇒ Integer

Show/hide all floating toolbars.

Parameters:

  • state (Boolean)

Returns:

  • (Integer) —

    Number of floating toolbars shown or hidden.

Since:

  • 2.0.0

.show_trays(state) ⇒ Integer

Show/hide all trays.

Parameters:

  • state (Boolean)

Returns:

  • (Integer) —

    Number of trays shown or hidden.

Since:

  • 3.5.0

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

Note:

In 3.7.0, set_mode can now be changed while in the full-screen mode, without having to unset from the full-screen mode beforehand.

Note:

In 3.7.0, the main window is no longer activated when switching full screen. If you intend to also activate the main window, ensure to do it manually; see bring_to_top.

Set/unset the main window to/from the full-screen mode.

Parameters:

  • state (Boolean) —

    true to set full screen; false to unset from the full-screen mode.

  • reset_mode (Integer) (defaults to: 2) —

    This parameter has an effect if and only if when the main window is unset from the 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 (Integer) (defaults to: 1) —

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

    • 0 - Set full screen on the primary monitor.
    • 1 - Set full screen on the monitor the main window is associated to.
    • 2 - Set full screen on all monitors.

Returns:

  • (Boolean) —

    true if client size of the main window is changed; false otherwise. If client size is changed, all child windows of the main window are respositioned and resized - refreshed.

Since:

  • 2.0.0

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

Note:

Any errors occurring in the threaded procedure are outed to console. To handle errors manually, ensure to wrap your procedure with a custom begin-rescue block.

Note:

See MessageBox for type configuration flags and result interpretation.

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)
    puts 'doing'
    # 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 (Integer) (defaults to: 0x00002030) —

    Messagebox configuration flags

  • owner_handle (Integer) (defaults to: nil) —

    Handle to a valid window or nil.

Yields:

  • Triggered when the messagebox is closed.

Yield Parameters:

  • result (Integer) —

    Message result

Returns:

  • (Integer, nil) —

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

See Also:

Since:

  • 3.5.0