Dll functions exported by QM

These dll functions and interfaces are provided by qm.exe. Declared in QmDll.

In some function descriptions is specified QM version when the function has been added. If not specified, the function has been added before QM 2.1.9. Some functions are not available in exe. It is specified in function descriptions. Almost all functions support Unicode. If a function does not support Unicode, it is specified in its description. All file functions support special folders.

Interfaces

IStringMap, CreateStringMap

QM 2.2.0.

String map object. A string map is an array of string pairs.

ICsv, CreateCsv

QM 2.3.0.

CSV object. CSV is a file format used to save tables.

IXml, IXmlNode, CreateXml

QM 2.3.0.

XML object. XML is a file format used to save tables and hierarchical data structures.

Functions

Compare: StrCompare, StrCompareN, MemCompare, q_stricmp, q_strnicmp, q_memicmp

Character type: isdigit, isalnum, __iscsym

Memory: q_malloc, q_calloc, q_realloc, q_free, q_msize, q_strdup

QM key codes: QmKeyCodeToVK, QmKeyCodeFromVK

Key state: RealGetKeyState, GetMod

QM items and folders: SilentImport, SilentExport

QM threads: EnumQmThreads, GetQmThreadInfo

QM menus and toolbars: GetToolbarOwner, GetLastSelectedMenuItem

Standard menu: MenuSetString, MenuGetString

Window: IsHungWindow, RealGetNextWindow, SubclassWindow, SetWinStyle, IsWindow64Bit

Multiple monitors: MonitorFromIndex, MonitorIndex, AdjustWindowPos

Rich edit: RichEditLoad, RichEditSave

Performance: GetCPU, GetDiskUsage

Security: SetPrivilege

Session: IsLoggedOn, EnsureLoggedOn

System/user info: IsUserAdmin, GetUserInfo

Process info: GetProcessUacInfo, GetProcessIntegrityLevel, EnumProcessesEx, ProcessNameToId, GetProcessExename

Run program: StartProcess, AllowActivateWindows

File system, PIDL: GetFileOrFolderSize, GetFullPath, PidlToStr, PidlFromStr

Shortcut: CreateShortcutEx, GetShortcutInfoEx

Icon, image: GetFileIcon, GetWindowIcon, SaveBitmap, LoadPictureFile

Setup: RegisterComComponent

Drag and drop: QmRegisterDropTarget, QmUnregisterDropTarget

Exe: GetExeResHandle, ExeExtractFile, ExeGetResourceData

Math: Crc32, Round, RandomNumber, RandomInt

Tools: GetQmCodeEditor, InsertStatement, HtmlHelp, SpecFoldersMenu, CreateRegExpMenu, RecGetWindowName, OnScreenRect, CompileAllItems, FormatKeyString, EditReplaceSel

1. Support Unicode (when QM is running in Unicode mode).

2. Case insensitive comparison is much faster, especially when the strings are ASCII.

3. Don't afraid null strings. Null and "" are considered equal.

4. The return value is strictly 0 or 1 or -1.

You can also use matchw, findrx, some str functions and operators. However they cannot be used in sorting.

To compare strings also can be used CompareString, lstrcmp, orther Windows API and msvcrt.dll functions, all documented in the MSDN Library. Note that the case insensitive ANSI versions cannot compare UTF-8 text containing non ASCII characters. In QM, text normally is UTF-8 in Unicode mode.

The following 3 functions exist for backward compatibility. Use the above functions instead.

Returns 1 if char is a valid character for a QM or C++ identifier, or 0 if not. This function replaces the msvcrt.dll function because the later also would return nonzero for some non ASCII characters.

For other character types, can be used similar msvcrt.dll functions, for example isalpha, isprint. Also can be used Windows API functions, for example IsCharAlpha, GetStringType. All documented in the MSDN Library.

These functions don't support Unicode. To get Unicode UTF-16 character type, use W versions of Windows API functions, for example IsCharAlphaW.

These functions also can be used with memory that is allocated or will be freed by str variables. For this purpose don't use malloc and other functions from msvcrt.dll, because QM uses other memory allocation functions.

Converts from QM key code (string) to Windows virtual-key code (integer). qmkey may contain more than one QM key code. The function stores virtual-key code of the first QM key code into the int variable whose address is vk, and returns number of parsed characters (eg 3 for F12). vk will be 0 if qmkey is invalid.

QM 2.2.1: Instead can be used key. It converts multiple key codes, variables, etc.

Checks if the specified key or mouse button is pressed or toggled. Can be used instead of ifk. More reliable than GetKeyState and GetAsyncKeyState.

Returns 1 if the key is pressed, 0 if not. If vk contains flag 0x100 (eg VK_CAPITAL|0x100), returns 1 if the key is toggled, 0 if not.

vk - virtual-key code 1 to 255. Add flag 0x100 to check toggled state.

Gets information about currently running QM threads, except special threads. Returns the number of threads.

arr - caller-allocated array of nelem elements of QMTHREAD type. Can be 0. See example.

nelem - number of elements in arr.

flags - currently not used and must be 0.

threadname (2.2.0) - QM item name (in quotes, or string variable) or id. If 0 or "", enumerates all threads.

This type is used with EnumQmThreads and GetQmThreadInfo:

type QMTHREAD qmitemid threadid threadhandle flags tuid

qmitemid - QM item id. Can be used to display item name (str.getmacro or qmitem) or end thread (shutdown).

threadid - thread id. Can be used with shutdown -6 (end thread) and with Windows API functions.

threadhandle - thread handle. Can be used with wait (wait until thread exits), shutdown -6, and with Windows API functions.

flags - currently is not used.

tuid (QM 2.2.0) - unique thread id. Can be used with shutdown -6. Cannot be used with Windows API functions. Unlike thread id and handle, the same unique id value is not reused for new threads.

Examples

 Display all threads
int i n=EnumQmThreads(0 0 0 0)
ARRAY(QMTHREAD) a.create(n)
for i 0 EnumQmThreads(&a[0] n 0 0)
	out _s.getmacro(a[i].qmitemid 1)

 Is Function55 running?
if(EnumQmThreads(0 0 0 "Function55")) out "running"

Gets information about a QM thread. Fills variable of type QMTHREAD (described above). It must not be a special thread.

handle - thread handle. For example, mac returns thread handle when you use it to run a function. If 0 - current thread.

Yo can call this function after showing a popup menu to get clicked item string. To show the menu, use mac as function. If mac returns a nonzero value, call this function. See example.

label - receives selected menu item label string. Can be 0.

command - receives selected menu item code string. With an expand-folder menu - selected file path or ITEMIDLIST string. Can be 0.

Not available in exe.

Example

 Show menu "Drives" and get selected item info
if(mac("Drives"))
	str s
	GetLastSelectedMenuItem 0 &s 0
	mes s

Returns handle of next window in Z order, skipping invisible and other windows that would be skipped by Alt+Tab.

hwndFrom - handle of window behind which in Z order to search. If 0, starts from the top of the Z order.
flags:
1 - if hwndFrom is not 0 and there is no matching windows behind it, retry from the top of the Z order (like Alt+Tab).
2 - skip minimized windows.

Replaces window procedure. Returns address of old procedure. If the window is ANSI, calls SetWindowLongA. If Unicode, calls SetWindowLongW. Read more about subclassing in the MSDN Library.

hwnd - window handle. The window must belong to qm/exe process.

newproc - address of new window procedure. The function must begin with function hWnd message wParam lParam and end with ret CallWindowProc(oldproc hWnd message wParam lParam).

hwnd - window handle. Can be top-level or child window.
style - style or extended style. Window styles are documented in the MSDN Library. To view available styles and extended styles, type .WS_ .

flags: 0 set, 1 add, 2 remove, 4 style is extended style, 8 update nonclient area, 16 update client area (QM 2.2.1).

Example:

 remove Notepad's title bar:
int h=win("Notepad")
SetWinStyle h WS_CAPTION 2|8

See also: _win64

monitor - requested monitor. Like with _monitor, it can be monitor index 1-30, or 0 (primary), -1 (mouse), -2 (active window), -3 (primary), or window handle.

flags:

1 - get work area coordinates.

32 - monitor is monitor handle.

r - address of a RECT variable that receives monitor coordinates, relative to the primary monitor. Can be 0 if not needed.

Other functions that can be used to get monitor handle: MonitorFromWindow, MonitorFromPoint, MonitorFromRect. Documented in the MSDN Library.

monitor - requested monitor. The same as with MonitorFromIndex and _monitor.

Checks whether QM is running on interactive desktop. If computer is locked, and unlock is nonzero, attempts to unlock. Returns 0 if cannot ensure interactive desktop, 1 if normal, 2 if successfully unlocked. The unlock method and settings are the same as specified in the Temporarily Unlock Computer dialog.

Unlocking is not available in exe (unlock value is ignored).

Some triggers (scheduler, event log, etc) may launch the macro while QM is not running on interactive desktop (e.g., while computer is locked). Then the macro runs in the background. However, many commands (keyboard, mouse, etc) then don't work, because background users cannot access keyboard, mouse and monitor. To ensure that the macro will not run in the background, you can check the checkboxes in Properties -> Macro properties or use EnsureLoggedOn or IsLoggedOn in the macro.

Example

 If QM is not running on interactive desktop, try to unlock computer; if it fails, exit
if(!EnsureLoggedOn(1)) ret

Returns some Vista UAC info of a process (running program):

Return values:

0 - not Vista, or failed.

1 - UAC turned off, or the process is running as standard user on standard user account.

2 - The process is running as administrator.

3 - The process is running not as administrator but has uiAccess privileges.

4 - The process is running on administrator account but not as administrator.

hwnd - handle of a window that belongs to the process. If flags includes 1, then hwnd must be process id. You can use process id 0 to specify current process.

See also: IsUserAdmin (see above)

Returns the Vista integrity level of a process:

0 - not Vista, or failed.

1 - Low.

2 - Medium.

3 - Administrator or uiAccess.

4 - System.

hwnd - handle of a window that belongs to the process. If flags includes 1, then hwnd must be process id. You can use process id 0 to specify current process.

ARRAY(str) a
EnumProcessesEx 0 &a 0
for(_i 0 a.len) out a[_i]

The process here must be identified using process id. To use window instead, can be used str.getwinexe.

flags - privileges that you need. Available values are described in the Make Exe topic. Search for StartProcess.

path - executable file path.

cl - command line.

defdir - default directory.

hProcess - address of an int variable that receives process handle. Later you must close it using CloseHandle. If you use flag 16, the function retrieves process id instead of handle, and you must not close it.

QM 2.2.1. The highest byte of flags can contain suggested window state (maximized, hidden, etc), like with run. To store a value to the highest byte, use value<<24. For example, to run the program hidden, use flags|(16<<24).

Not available in exe.

Converts ITEMIDLIST to file system path or string in QM format (":: XXXX..."). Read more.

type SHORTCUTINFO ~target ~param ~initdir ~descr ~iconfile iconindex showstate @hotkey

target - file/folder path, or ITEMIDLIST string.

hotkey - hot key. Low-order byte is virtual-key code. High-order byte is combination of HOTKEYF_ALT, HOTKEYF_CONTROL, HOTKEYF_SHIFT, HOTKEYF_EXT.

Example

 Create shortcut with all possible attributes
SHORTCUTINFO si.target="$system$\notepad.exe"
si.iconfile="shell32.dll"
si.iconindex=4
si.descr="test descr"
si.hotkey=HOTKEYF_CONTROL<<8|VK_F6
si.initdir="$my qm$"
si.param="-p"
si.showstate=SW_MAXIMIZE
CreateShortcutEx("$desktop$\test.lnk" &si)

_file - any file or folder. Can be path or ITEMIDLIST string. Can be only filename.

index - 0, or icon index (0-based). If negative, index is interpreted as negative resource id. Alternatively, icon index can be appended to _file. Example: "shell32.dll,3".

flags:

1 - get large icon (32x32). By default, gets small icon (16x16).

2 - don't use shell icon. Read more below.

For ico files, always extracts icon from the file. For other files, extracts icon from the file if index is nonzero, or icon index is appended to _file, or flag 2 is used. Otherwise, gets icon shell icon (icon that would be displayed in Windows Explorer).

If _file begins with dot and does not contain more dots, gets icon associated with that file type. Example: ".txt".

If _file begins with semicolon, it is interpreted as resource id in exe. Examples: ":150", "&:150", ":151 file.ico".

To get window icon, use GetWindowIcon.

Example

int hi=GetFileIcon("shell32.dll" 3 1)
int dc=GetDC(0)
DrawIconEx dc 300 200 hi 32 32 0 0 DI_NORMAL
ReleaseDC 0 dc
DestroyIcon hi

If _file begins with semicolon , it is interpreted as bitmap resource id in exe. Examples: ":1", ":2 file.bmp".

The most important advantage over WS_EX_ACCEPTFILES/WM_DROPFILES is that this method works well on Windows Vista. WM_DROPFILES does not work on Vista under UAC, because Vista does not allow to drag and drop files from Medium integrity level (IL) processes (like Windows Explorer) to windows of higher IL processes (like QM). Other advantages - you can receive not only file system paths, but also ITEMIDLIST strings of other shell objects, URLs of dropped Internet links, and data of other formats.

The information below may be hard to understand. Also, most of it is not useful in most cases. You can start from the example. Also, you can ask about it in the QM forum.

QmRegisterDropTarget arguments:

hwndTarget - the handle of the target window. It can be a top level window (e.g. a custom dialog) or a child window (e.g. an edit control in a dialog).

hwndNotify - the handle of the window that will receive notifications. For example, if the target is a control in a dialog, you'll probably want to receive notifications in the dialog procedure, and therefore set hwndNotify to the dialog handle (hDlg). Can be 0 if it is the same window.

flags - 1 notify on enter, 2 notify on over, 4 notify on leave, 16 need only files, 32 need .lnk (don't extract shortcut target).

On drag and drop events, the hwndNotify window receives WM_QM_DRAGDROP message. By default, the message is sent only on drop, unless flags 1, 2, and/or 4 are used.

wParam - 0 on drag enter, 1 on drag over, 2 on drag leave, 3 on drop.

lParam - address of variable of QMDRAGDROPINFO type. Members:

hwndTarget - target window handle.

dataObj - IDataObject interface pointer. Available on drag enter and drop. Can be used to extract data of various formats. Window Vista: when running under UAC, only GetData function is valid, and can retrieve only data decribed as TYMED_HGLOBAL.

formats - array of available formats. Available on drag enter and drop. A format is described by a FORMATETC type.

keyState - modifier keys and mouse buttons.

pt - mouse pointer position.

effect - combination of available drop effects (copy, move, link, etc). Available on drag enter, over and drop. If you did not use flag 16, you should remove effects you don't accept. To remove, use the & operator.

files - list of dropped files, other shell objects and Internet links. Valid only on drop. In most cases, it is the only member you need.

IDataObject, FORMATETC, keyState, effect are documented in the MSDN Library. Look for IDropTarget and IDataObject interfaces. In most cases you will not need it.

Usually you'll need only files. To register drop target window, call QmRegisterDropTarget with flags 16. Then the message will be sent only on drop, and QM sets proper effect. In the window or dialog procedure, assign lParam to a QMDRAGDROPINFO* variable, get files, and return 0. See example.

If you also need other notifications, set other flags. Also, on WM_QM_DRAGDROP return 1. To return 1 from a dialog procedure, use ret DT_Ret(hDlg 1). Always return 1 if you have modified effect.

Toolbars: By default, the child toolbar control is a drop target. To replace default drag and drop feature, use something like this in hook procedure on WM_INITDIALOG: QmRegisterDropTarget(wParam hWnd 16). Or you can register the toolbar window (QmRegisterDropTarget(hWnd 0 16)) as a drop target. It is covered by the child toolbar control, so you would have to make the control smaller. On WM_INITDIALOG, resize the control (siz), and on WM_SIZE return 1.

Exe: On Vista, drag and drop does not work if the drop source process has lower integrity level.

Example

Function DropTargetExampleDialog

\Dialog_Editor
function# hDlg message wParam lParam
if(hDlg) goto messages

str controls = "3"
str e3
if(!ShowDialog("DropTargetExampleDialog" &DropTargetExampleDialog &controls)) ret

 BEGIN DIALOG
 0 "" 0x90C80A44 0x100 0 0 223 41 "Dialog"
 1 Button 0x54030001 0x4 4 22 46 14 "OK"
 2 Button 0x54030000 0x4 54 22 46 14 "Cancel"
 3 Edit 0x54030080 0x200 4 4 216 14 ""
 END DIALOG
 DIALOG EDITOR: "" 0x2020006 "" ""

ret
 messages
sel message
	case WM_INITDIALOG
	QmRegisterDropTarget(id(3 hDlg) hDlg 16)
	case WM_DESTROY
	case WM_COMMAND goto messages2
	case WM_QM_DRAGDROP
	QMDRAGDROPINFO& di=+lParam
	 set edit box
	str s.getl(di.files 0) ;;get first file
	s.setwintext(id(3 hDlg))
	 to get all dropped files, you can use eg foreach. Example: foreach(s di.files) out s
ret
 messages2
sel wParam
	case IDOK
	case IDCANCEL
ret 1

Returns module handle that can be used with API resource functions. Useful in exe.

Extracts a file added to exe. The file can be added to exe using #exe addfile or using a resource editor (use resource type RT_RCDATA (10)). Returns 1 on success, 0 on failure. This function works only in exe. It should not be used when the macro runs in QM.

resid - resource id. Use the same resid as with #exe addfile.

dest - destination file. To extract to exe's folder, use "$qm$\filename.ext" or just "filename.ext". To extract to temporary folder, use for example "$temp$\myexename\filename.ext". If the folder does not exist, creates. If the file already exists, compares resource data with existing file data, and replaces existing file only if it is different.

flags - currently not used and must be 0.

Example

#if EXE

#exe addfile "$desktop$\test.txt" 1

str fn="$temp$\testexe\test.txt"
if(!ExeExtractFile(1 fn)) ret
run fn

#else

run "$desktop$\test.txt"

#endif

Example of extracting a dll file and calling functions from it.

Stores exe resource data to a str variable. Returns 1 on success, 0 on failure. This function is used in exe. It also works while the macro runs in QM, if the exe is already created.

resType - resource type. If 0, uses RT_RCDATA.

resId - resource id.

data - address of a str variable that will receive the data.

Example

#exe addfile "$desktop$\test.txt" 1
str s
if(!ExeGetResourceData(0 1 &s)) ret
out s

Calculates CRC checksum of a string or binary data. See also: str.encrypt (MD5).

This and other math functions are added to the math category.

Examples

int i
i=1.1 ;;1
i=1.9 ;;1
i=Round(1.1 0) ;;1
i=Round(1.9 0) ;;2
i=Round(1.5 0) ;;2 (.5 rounds to the nearest even number)
i=Round(2.5 0) ;;2 (.5 rounds to the nearest even number)
double d=Round(1.5555 2) ;;1.56

In QM 2.3.0 and later, QM code editor, output and some other controls are based on Scintilla control. In older versions - rich edit control. Therefore, if you have macros created in older QM versions that use rich edit control messages with these controls, they may stop working. Also, str.getwintext and str.setwintext now does not work because the new control does not support WM_GETTEXT and WM_SETTEXT messages. Now use Scintilla messages. The required constants are in SCI reference file. Also, control id 2203 has been changed to 2210 (primary) and 2211 (right/bottom). See also: InsertStatement (below).

Scintilla is a free source code editing component. Copyright 1998-2003 by Neil Hodgson, All Rights Reserved.

Example

str s
int h=GetQmCodeEditor
int lens=SendMessage(h SCI.SCI_GETTEXTLENGTH 0 0)
s.fix(SendMessage(h SCI.SCI_GETTEXT lens+1 s.all(lens)))
out s

Controls HTML help. Same as the Windows API function with same name. For reference, search for HtmlHelp in the MSDN Library.

Gets window name as it would be recorded, with respect to the settings in the Recording Windows dialog. Actually it will not be just window name, because QM records windows as win function. Returns 1 if it is win function, 2 if it is some other expression, 0 if fails.

hwnd - window handle.

s - address of a str variable that receives the string.

QM 2.3.0. Works well with controls too. Formats either id or child function, which is better in that case.

Not available in exe.

vk - virtual-key code.

mod - modifiers. See GetMod.

s - address of a str variable that receives the text. If s initially is not empty, appends to the end.