Window Module
#window.find number window.find(string windowName) number window.find(string windowName, string className)

Finds a window's HWND (handle to window) based on its title (not case-sensitive), and (optionally) its classname (case-sensitive). 'title' and 'classname' can contain wildcards * and ?.

The ? wildcard allows for one of any character and the * wildcard allows any number of any character.

Returns the first match found. If no match was found, returns nil.

Example:
-- Find the 'Edit' sub-window inside of Notepad editWin = window.find("* - Notepad", "Edit");
#window.findList table window.find(string windowName) table window.find(string windowName, string className)

Exactly like window.find() except that it returns a table of results matching the given search parameters.

Returns a table of tables containing: 'hwnd' (number; handle to window), 'name' (string; window title), and 'class' (string; identifier used by its programmer). If no match was found, returns nil.

Example:
-- Find the 'Edit' sub-window inside of Notepad foundResults = window.findList("* - Notepad*"); table.print(foundResults);
Example output:
1: table: 0x00901938 hwnd: 1576636 class: "Notepad++" name: "new 1 - Notepad++" 2: table: 0x009017F8 hwnd: 8784856 class: "Notepad" name: "Untitled - Notepad"
#window.getParent number window.getParent(number hwnd)

Returns a window's parent, or nil on error.

Example:
-- Find the 'Edit' sub-window inside of Notepad editWin = window.find("* - Notepad", "Edit"); editParentWin = window.getParent(editWin); -- editParentWin should now refer to the main Notepad window, not the edit sub-window
#window.getTitle string window.getTitle(number hwnd)

Returns a window's title as a string.

#window.getTitle string window.getTitle(number hwnd)

Returns a window's title as a string or nil on failure.

#window.setTitle window.setTitle(number hwnd, string title)

Change a window's title.

#window.getClassName string window.getClassName(number hwnd)

Returns a window's class name as a string or nil on failure.

#window.valid boolean window.valid(number hwnd)

Returns true if 'hwnd' is still a valid window handle, or false otherwise.

#window.getRect number x, number y, number w, number h number showCmd window.getRect(number hwnd)

Returns the position (x,y), size (w,h), and 'showCmd' (integer describing the show state) of a window.

See window.show() for details on 'showCmd'.

#window.setRect window.setRect(number hwnd, number x, number y, number w, number h)

Change the position and size of a window with handle 'hwnd'.

#window.getClientRect number x, number y, number w, number h number showCmd window.getClientRect(number hwnd)

Exactly like window.getRect() except it returns only the client area.

The "client area" refers to the area of the window without borders or title bars.

#window.setClientRect window.setClientRect(number hwnd, number x, number y, number w, number h)

Change the position and size of a window's client area with handle 'hwnd'.

The "client area" refers to the area of the window without borders or title bars.

#window.show window.show(number hwnd, number cmd)

Show/hide/minimize/maximize/whatever with the window.

For 'cmd', you should specify one of the following constants:

SW_FORCEMINIMIZE SW_HIDE SW_MAXIMIZE
SW_MINIMIZE SW_RESTORE SW_SHOW
SW_SHOWDEFAULT SW_SHOWMAXIMIZED SW_SHOWMINIMIZED
SW_SHOWMINNOACTIVATE SW_SHOWNA SW_SHOWNOACTIVATE
SW_SHOWNORMAL
Example:
win = window.find("* - Notepad"); window.show(win, SW_MINIMIZE); -- Minimize Notepad
#window.flash window.flash(number hwnd, number flashCount)

"Flash" the window to attempt to grab the user's attention. If 'flashCount' is < 0, stop flashing. If 'flashCount' is 0, flash until user focuses the window. If 'flashCount' is > 0, flash this many times and then stop.

When a window is "flashed", this will cause the icon/window to flash a highlighted color on your Windows taskbar before remaining highlighted. This only affects the item in the taskbar, and not the window itself. Once the window has gained focus (ie. clicked on), the flashing/highlight will be removed.

Window flashing must be turned on (default) for this to work. The setting may be modified in Windows 11's Taskbar Personalization under the "Taskbar behaviors" section.

#window.getPixel number r, number g, number b window.getPixel(number hwnd, number x, number y)

Get the color of a pixel at (x,y) inside window 'hwnd', and return the color split into red, green, and blue channels. 'r', 'g', and 'b' results will be between 0 and 255.

For example: 0,0,0 is black, 255,255,255 is white, and 255,0,255 is "Magic" pink.

#window.pixelSearch number x, number y window.pixelSearch(number hwnd, number r, number g, number b, number x1, number y1, number x2, number y2) number x, number y window.pixelSearch(number hwnd, number r, number g, number b, number x1, number y1, number x2, number y2, number accuracy) number x, number y window.pixelSearch(number hwnd, number r, number g, number b, number x1, number y1, number x2, number y2, number accuracy, number step)

Search the given window for a pixel that matches r,g,b within the rectangle outlined by (x1,y1) -> (x2,y2). The rect may go from left-to-right, right-to-left, top-to-bottom, bottom-to-top, or any combination of those, depending on the orientation of the two points.

'accuracy' is how many units each channel must be within the given color to generate a match. ie. with an accuracy of 20, the red, green, and blue channels must be within 20 of the target color to match. Default: 1

'step' is the step size (distance between pixels to search). You generally have no need for this so long as you aren't scanning a large area, but you may experience faster scan times (with a chance of missing a match) with a higher step size. Default: 1

Returns the first matching pixel's coordinates (x,y). If the pixel is not found, this function returns nil.

#window.saveScreenshot window.saveScreenshot(number hwnd, string filename)

Save a screenshot of window 'hwnd' to 'filename'. If 'hwnd' is 0, this screenshots the whole desktop.

NOTE: You cannot take a screenshot of a minimized window. This is a limitation in Windows.

#window.getAppHwnd number window.getAppHwnd()

Returns the calling process' (MicroMacro) handle to window (HWND). This is what you may use to access or modify the console's properties where an hwnd is required.

#window.getFocusHwnd number window.getFocusHwnd()

Returns the hwnd of whichever window is top-most as of the the start of this logic cycle. This is polled once per frame and should be fairly accurate so long as your script executes each logic cycle quickly. Be aware that as windows are being minimized, maximized, or otherwise, the focused hwnd may temporarily switch to NULL (0).

#window.makeColor number window.makeColor(number red, number green, number blue)

This helper function converts red-green-blue components into a long integer color value for use in other functions. All input values (red, green, and blue) should be integers between 0 and 255. (0, 0, 0) would result in black, (255, 255, 255) would result in white and (0, 255, 0) would result in green.

#window.drawLine boolean window.drawLine(number hwnd, number x1, number y1, number x2, number y2) boolean window.drawLine(number hwnd, number x1, number y1, number x2, number y2, number color) boolean window.drawLine(number hwnd, number x1, number y1, number x2, number y2, number color, number thickness)

Draws a line in the client region of the window specified by hwnd (note: use 0 to draw directly to screen). It is possible to draw outside of the given window with this function. A line will be drawn starting from (x1,y1) to (x2,y2) with the given color and line thickness. By default, color will be black (0, 0, 0) and thickness (in pixels) will be 1.

You should use window.makeColor() to generate the number passed as the color value if you wish to specify a color by RGB. Alternatively, you can pass the value in by hex notation (ie, 0xFF00FF).

Returns true on success and false on failure.

Note: windows redraw themselves (or parts of themselves) regularly. This may be triggered from an event (something changed in this program - so update the display) or happen at regular intervals (games aim to refresh the screen at 60+ frames per second). If the window is redrawn, whatever you have drawn to that window will likely be painted over. You may opt to continually paint to the window to combat this, however that is likely going to result in some flickering. This is unavoidable without hooking the target application; a topic best left for another time. As such, it is recommended that you only use these types of drawing functions during the design process or during debugging, otherwise your project might look a little bit amateurish.

Example:
local win = window.find("Untitled - Notepad"); local frameColor = window.makeColor(80, 180, 80); local crossColor = window.makeColor(200, 48, 225); local thickness = 2; window.drawRect(win, 10, 10, 200, 200, frameColor, thickness); window.drawLine(win, 20, 20, 190, 190, crossColor, thickness); window.drawLine(win, 190, 20, 20, 190, crossColor, thickness);
Drawing to windows example output Drawing to windows example
#window.drawRect boolean window.drawRect(number hwnd, number x1, number y1, number x2, number y2) boolean window.drawRect(number hwnd, number x1, number y1, number x2, number y2, number color) boolean window.drawRect(number hwnd, number x1, number y1, number x2, number y2, number color, number thickness)

This functions exactly like window.drawLine(), except that it draws a rectangle rather than a line.

Returns true on success and false on failure.

Page last updated at 2023-10-25 13:45:33


Copyright 2024