Module: AMS::Window

Defined in:
docs/ams/window.rb

Overview

Note:

Windows only!

The Window namespace contains functions that are associated with Windows window.

Since:

  • 2.0.0

Class Method Summary collapse

Class Method Details

.adjust_rect(rect, style, style_ex, b_menu) ⇒ Array<Integer>

Adjust window rect.

Parameters:

  • rect (Array<Integer>)
  • style (Integer)
  • style_ex (Integer)
  • b_menu (Boolean) —

    Whether window contains a menu.

Returns:

  • (Array<Integer>) —

    New rect: [x1,y1, x2,y2].

See Also:

Since:

  • 2.0.0

.bring_to_top(handle) ⇒ Boolean

Bring window to the top of Z order. If window is a top-level window, it is activated. If window is a child window, the top-level parent window associated with the child window is activated.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 3.0.0

.client_to_screen(handle, x, y) ⇒ Array<Integer>

Convert client coordinates to screen coordinates.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • x (Integer)
  • y (Integer)

Returns:

  • (Array<Integer>) —

    Converted point: [x,y]

See Also:

Since:

  • 3.0.0

.close(handle) ⇒ Boolean

Note:

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

Close window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.draw_menu_bar(handle) ⇒ Boolean

Update menu bar of a specific window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.enable_input(handle, b_state) ⇒ Boolean

Enable/Disable keyboard and mouse input to a specific window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • b_state (Boolean)

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

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

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?

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?

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?

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

Get active window.

Returns:

  • (Integer) —

    A handle to an active window.

See Also:

Since:

  • 2.0.0

.get_ancestor(handle, flag) ⇒ Integer?

Get window ancestor.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • flag (Integer) —

    An ancestor:

    1. parent window
    2. root window
    3. root owner window

Returns:

  • (Integer, nil) —

    A handle to the ancestor window if any.

See Also:

Since:

  • 3.0.0

.get_caption(handle) ⇒ String

Get window text.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (String)

See Also:

Since:

  • 3.0.0

.get_child_windows(parent_handle, include_sub_childs = false, include_hidden = true) ⇒ Array<Integer>

Get all child windows belonging to a parent window.

Parameters:

  • parent_handle (Integer) —

    Handle to a valid parent window.

  • include_sub_childs (Boolean) (defaults to: false) —

    Whether to include child window descendants.

  • include_hidden (Boolean) (defaults to: true) —

    Whether to include hidden windows.

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 3.0.0

.get_class_long(handle, index) ⇒ Integer

Get class long.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • index (Integer)

Returns:

  • (Integer) —

    Window long.

See Also:

Since:

  • 3.6.0

.get_class_name(handle) ⇒ String

Get class name of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (String)

See Also:

Since:

  • 2.0.0

.get_client_rect(handle) ⇒ Array<Integer>

Get upper-left and lower-right coordinates of the window's client area in client coordinates, relative to the upper-left corner of the window's client area. Because coordinates are relative to the upper-left corner of the client area, the coordinates of the upper-left corner are (0,0).

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Array<Integer>) —

    An array of four numeric values, representing upper-left and lower-right coordinates: [x1,y1, x2,y2].

See Also:

Since:

  • 2.0.0

.get_executable_name(handle) ⇒ String?

Get executable name of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (String, nil)

Since:

  • 3.1.0

.get_executable_path(handle) ⇒ String?

Get full executable path of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (String, nil)

Since:

  • 3.1.0

.get_keyboard_focus ⇒ Integer?

Get window containing keyboard focus.

Returns:

  • (Integer, nil) —

    A handle to a window with keyboard focus.

See Also:

Since:

  • 3.6.0

.get_layered_attributes(handle) ⇒ Array<(Array<Integer>, Integer, Integer)>

Get layered attributes of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Array<(Array<Integer>, Integer, Integer)>) —

    An array of three values: [rgb_color, opacity, flags]

Since:

  • 3.0.0

.get_long(handle, index) ⇒ Integer

Get window long.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • index (Integer)

Returns:

  • (Integer) —

    Window long.

See Also:

Since:

  • 2.0.0

.get_menu(handle) ⇒ Integer?

Get window menu.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Integer, nil) —

    A handle to the menu. If the specified window has no menu, the return value is nil.

See Also:

Since:

  • 2.0.0

.get_module_hanlde(handle) ⇒ Integer?

Get module instance handle of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Integer, nil)

Since:

  • 3.1.0

.get_origin(handle) ⇒ Array<Integer>

Get coordinates of the upper-left corner of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Array<Integer>) —

    [x,y]

Since:

  • 2.0.0

.get_parent(handle) ⇒ Integer?

Get parent window of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Integer, nil) —

    If the window is a child window, the return value is a handle to the parent window. If the window is a top-level window with the WS_POPUP style, the return value is a handle to the owner window. Otherwise, the return value is nil.

See Also:

Since:

  • 2.0.0

.get_placement(handle) ⇒ Array<(Integer, Integer, Integer, Array<Integer>, Array<Integer>, Array<Integer>)>

Get window placement.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Array<(Integer, Integer, Integer, Array<Integer>, Array<Integer>, Array<Integer>)>) —

    An array of six objects representing window placement: [length, flags, show_cmd, min_pt, max_pt, rect].

See Also:

Since:

  • 2.0.0

.get_process_id(handle) ⇒ Integer

Get process identifier of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Integer)

See Also:

Since:

  • 2.0.0

.get_process_windows(process_id, include_hidden = true) ⇒ Array<Integer>

Get all windows belonging to a process.

Parameters:

  • process_id (Integer)
  • include_hidden (Boolean) (defaults to: true) —

    Whether to include hidden windows.

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 3.0.0

.get_rect(handle) ⇒ Array<Integer>

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

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Array<Integer>) —

    An array of four numeric values, representing upper-left and lower-right coordinates: [x1,y1, x2,y2].

See Also:

Since:

  • 2.0.0

.get_related(handle, command) ⇒ Integer?

Get related window of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • command (Integer) —

    See link below for existing commands.

Returns:

  • (Integer, nil) —

    A handle to a related window if any.

See Also:

Since:

  • 3.0.0

.get_size(handle) ⇒ Array<Integer>

Get size of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Array<Integer>) —

    [width, height]

Since:

  • 2.0.0

.get_thread_id(handle) ⇒ Integer

Get thread identifier of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Integer)

See Also:

Since:

  • 2.0.0

.get_thread_windows(thread_id, include_hidden = true) ⇒ Array<Integer>

Get all windows belonging to a thread.

Parameters:

  • thread_id (Integer)
  • include_hidden (Boolean) (defaults to: true) —

    Whether to include hidden windows.

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 3.0.0

.get_windows(include_hidden = true) ⇒ Array<Integer>

Get all windows.

Parameters:

  • include_hidden (Boolean) (defaults to: true) —

    Whether to include hidden windows.

Returns:

  • (Array<Integer>) —

    An array of window handles.

Since:

  • 3.0.0

.is_active?(handle) ⇒ Boolean

Determine whether window is active.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_child?(handle, parent_handle) ⇒ Boolean

Determine whether window is a child window of a specific parent window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • parent_handle (Integer) —

    Handle to a valid parent window.

Returns:

  • (Boolean)

See Also:

Since:

  • 3.0.0

.is_input_enabled?(handle) ⇒ Boolean

Determine whether keyboard and mouse input is enabled in a specific window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

See Also:

Since:

  • 2.0.0

.is_maximized?(handle) ⇒ Boolean

Determine whether window is maximized.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

See Also:

Since:

  • 2.0.0

.is_minimized?(handle) ⇒ Boolean

Determine whether window is minimized.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

See Also:

Since:

  • 2.0.0

.is_resizeable?(handle) ⇒ Boolean

Determine whether window is resizeable.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_restored?(handle) ⇒ Boolean

Determine whether window is restored; not maximized nor minimized.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

Since:

  • 2.0.0

.is_unicode?(handle) ⇒ Boolean

Determine whether window is unicode.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

See Also:

Since:

  • 3.0.0

.is_valid?(handle) ⇒ Boolean

Determine whether handle is a reference to a valid window.

Parameters:

  • handle (Integer) —

    A handle to be tested.

Returns:

  • (Boolean)

See Also:

Since:

  • 2.0.0

.is_visible?(handle) ⇒ Boolean

Determine whether window is visible.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean)

See Also:

Since:

  • 2.0.0

.lock_update(handle) ⇒ Boolean

Note:

This method is usually called before and after setting window styles, followed by set_pos to update setting.

Lock window update.

Examples:

Removing caption from an active window.

handle = AMS::Window.get_active
long = AMS::Window.get_long(handle, -16)
AMS::Window.lock_update(handle)
AMS::Window.set_long(handle, -16, long & ~0x00C00000)
AMS::Window.lock_update(nil)
AMS::Window.set_pos(handle, 0, 0, 0, 0, 0, 0x0277)

Adding caption to an active window.

handle = AMS::Window.get_active
long = AMS::Window.get_long(handle, -16)
AMS::Window.lock_update(handle)
AMS::Window.set_long(handle, -16, long | 0x00C00000)
AMS::Window.lock_update(nil)
AMS::Window.set_pos(handle, 0, 0, 0, 0, 0, 0x0277)

Parameters:

  • handle (Integer, nil) —

    Handle to a valid window to be locked. If this parameter is nil, current locked window is unlocked.

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.map_point(handle_from, handle_to, x, y) ⇒ Array<Integer>

Convert (map) a point from a coordinate space relative to one window to a coordinate space relative to another window.

Parameters:

  • handle_from (Integer) —

    Handle to a valid window from which point is converted.

  • handle_to (Integer) —

    Handle to a valid window to which point is converted.

  • x (Integer)
  • y (Integer)

Returns:

  • (Array<Integer>) —

    Converted point: [x,y]

See Also:

Since:

  • 3.0.0

.move(handle, x, y, width, height, b_repaint = true) ⇒ Boolean

Move window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • x (Integer)
  • y (Integer)
  • width (Integer)
  • height (Integer)
  • b_repaint (Boolean) (defaults to: true) —

    Whether to repaint the window.

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.peek_message(handle, msg_filter_min, msg_filter_max, remove_flag) ⇒ Array?

Peek message of a specific window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • msg_filter_min (Integer, Bignum)
  • msg_filter_max (Integer, Bignum)
  • remove_flag (Integer, Bignum)

Returns:

  • (Array, nil) —

    An array containing peeked message data or nil if no messages are available.

See Also:

Since:

  • 3.5.0

.peek_message2(handle, msg_filter_min, msg_filter_max, remove_flag) ⇒ Boolean

Peek message of a specific window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • msg_filter_min (Integer, Bignum)
  • msg_filter_max (Integer, Bignum)
  • remove_flag (Integer, Bignum)

Returns:

  • (Boolean) —

    True if a message is available; false if not.

See Also:

Since:

  • 3.5.0

.post_message(handle, message, wParam, lParam) ⇒ Boolean

Post message to a specific window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • message (Integer, Bignum)
  • wParam (Integer, Bignum)
  • lParam (Integer, Bignum)

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 3.0.0

.refresh(handle) ⇒ Boolean

Refresh window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.screen_to_client(handle, x, y) ⇒ Array<Integer>

Convert screen coordinates to client coordinates.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • x (Integer)
  • y (Integer)

Returns:

  • (Array<Integer>) —

    Converted point: [x,y]

See Also:

Since:

  • 3.0.0

.send_message(handle, message, wParam, lParam) ⇒ Integer

Send message to a specific window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • message (Integer, Bignum)
  • wParam (Integer, Bignum)
  • lParam (Integer, Bignum)

Returns:

  • (Integer) —

    Message processing result.

See Also:

Since:

  • 2.0.0

.set_active(handle) ⇒ Integer

Set active window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Integer) —

    A handle to an original active window.

See Also:

Since:

  • 2.0.0

.set_background_color(handle, color, b_activate = true) ⇒ Boolean

Set window background color.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • color (Sketchup::Color) —

    Background color

  • b_activate (Boolean) (defaults to: true) —

    Whether to activate the window.

Returns:

  • (Boolean) —

    success

Since:

  • 3.6.0

.set_caption(handle, caption) ⇒ Boolean

Set window text.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • caption (String)

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 3.0.0

.set_class_long(handle, index, long) ⇒ Integer

Set class long.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • index (Integer)
  • long (Integer)

Returns:

  • (Integer) —

    Previous window long.

See Also:

Since:

  • 3.6.0

.set_icon(handle, full_path) ⇒ Boolean

Modify window icon.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • full_path (String) —

    Icon location.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.set_keyboard_focus(handle) ⇒ Integer

Set keyboard focus to a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

Returns:

  • (Integer) —

    A handle to an original window with keyboard focus.

See Also:

Since:

  • 3.6.0

.set_layered_attributes(handle, color, opacity, flags) ⇒ Boolean

Set layered attributes of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • color (Integer, Bignum, Array<Integer>) —

    A number or an array representing color in RGB form. Note: An array is not acceptible in library versions prior to 3.0.0.

  • opacity (Integer) —

    A value between 0 (transparent) and 255 (opaque).

  • flags (Integer)

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.set_long(handle, index, long) ⇒ Integer

Set window long.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • index (Integer)
  • long (Integer)

Returns:

  • (Integer) —

    Previous window long.

See Also:

Since:

  • 2.0.0

.set_menu(handle, menu_handle) ⇒ Boolean

Set window menu.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • menu_handle (Integer, nil) —

    A handle to the new menu. If this parameter is nil, the window's current menu is removed.

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.set_origin(handle, x, y, b_activate = true) ⇒ Boolean

Set coordinates of the upper-left corner of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • x (Integer)
  • y (Integer)
  • b_activate (Boolean) (defaults to: true) —

    Whether to activate the window.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.set_parent(handle, parent_handle) ⇒ Integer?

Set parent window of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • parent_handle (Integer) —

    Handle to a valid parent window.

Returns:

  • (Integer, nil) —

    If the functions succeeds, the return values is a handle to the previous parent window. Otherwise, the return value is nil.

See Also:

Since:

  • 2.0.0

.set_placement(handle, flags, show_cmd, min_pt, max_pt, rect) ⇒ Boolean

Set Window Placement.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • flags (Integer)
  • show_cmd (Integer)
  • min_pt (Array<Integer>) —

    (x,y)

  • max_pt (Array<Integer>) —

    (x,y)

  • rect (Array<Integer>) —

    (x1,y1, x2,y2)

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.set_pos(handle, handle_insert_after, x, y, cx, cy, flags) ⇒ Boolean

Set window position.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • handle_insert_after (Integer)
  • x (Integer)
  • y (Integer)
  • cx (Integer)
  • cy (Integer)
  • flags (Integer)

Returns:

  • (Boolean) —

    success

See Also:

Since:

  • 2.0.0

.set_rect(handle, x1, y1, x2, y2, b_activate = true) ⇒ Boolean

Set upper-left and lower-right coordinates of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • x1 (Integer)
  • y1 (Integer)
  • x2 (Integer)
  • y2 (Integer)
  • b_activate (Boolean) (defaults to: true) —

    Whether to activate the window.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.set_resizeable(handle, b_state, b_activate = true) ⇒ Boolean

Set window resizeable.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • b_state (Boolean)
  • b_activate (Boolean) (defaults to: true) —

    Whether to activate the window.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.set_size(handle, w, h, b_activate = true) ⇒ Boolean

Set size of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • w (Integer) —

    Window width in pixels.

  • h (Integer) —

    Window height in pixels.

  • b_activate (Boolean) (defaults to: true) —

    Whether to activate the window.

Returns:

  • (Boolean) —

    success

Since:

  • 2.0.0

.show(handle, state) ⇒ Boolean

Set show state of a window.

Parameters:

  • handle (Integer) —

    Handle to a valid window.

  • state (Integer)

Returns:

  • (Boolean) —

    True if window was previously visible; false if window was previously hidden.

See Also:

Since:

  • 2.0.0