Dll functions exported by QM

Note that the colored code lines below are not function calling examples. They are copied from declarations and used here to show function name, arguments etc.

Where the return value is not documented, it means that either the return value is not used or the function returns 1 if succeeded, 0 if failed.

Tip: For pointer parameters you can pass variables without operator & (QM 2.4.1).

#StrCompare $s1 $s2 [insens]

QM 2.3.0.

Compares two strings.

#StrCompareN $s1 $s2 n [insens]

QM 2.3.0.

Compares maximum n characters (bytes) of two strings.

#MemCompare $s1 $s2 n [insens]

QM 2.3.0.

Compares n bytes of two memory blocks. Unlike the StrX functions, can compare binary data. The StrX functions never compare memory after the terminating null character.

s1, s2 - strings. Can be str or lpstr variables or string constants. With MemCompare, also can be pointers of any type.

n - number of bytes to compare.

insens - case insensitive if nonzero.

These functions return:

0	s1 and s2 are equal. Null and "" are considered equal.
1	s1 is > s2. It means that s1 would be below s2 in a sorted list.
-1	s1 is < s2. It means that s1 would be above s2 in a sorted list.

These functions should be used instead of similar Windows API and msvcrt.dll functions, because:

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.

To compare strings, you can also use matchw, findrx, sel, SelStr, some str functions and operators. However they cannot be used in sorting.

To compare strings also can be used CompareString, lstrcmp, other Windows API and msvcrt.dll functions, all documented in 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.

#q_stricmp $s1 $s2

#q_strnicmp $s1 $s2 count

#q_memicmp $s1 $s2 count

#StrCompareEx $s1 $s2 compare ;;compare: 0 simple, 1 insens, 2 ling, 3 ling/insens, 4 number/ling/insens, 128 date

QM 2.3.2.

Compares two strings. Same as StrCompare but has more options.

compare:

0	Simple, case sensitive. Uses StrCompare to compare strings.
1	Simple, case insensitive. Uses StrCompare to compare strings.
2	Linguistic, case sensitive. Uses StrCmp to compare strings.
3	Linguistic, case insensitive. Uses StrCmpI to compare strings.
4	Number, linguistic, case insensitive. Uses StrCmpLogicalW to compare strings. It compares numbers in strings as number values, not as strings.
128 (flag)	QM 2.3.3. Date. Converts strings to DATE and compares. If cannot convert both strings, compares like without this flag.

#q_sort !*base num width func [!*param]

QM 2.3.2.

Same as qsort, but allows you to pass some value to the callback function. Read more about qsort in MSDN. The callback function must begin with:

function[c]# param TYPE&a TYPE&b

Here TYPE is type of array elements.

A template is available in menu -> File -> New -> Templates.

See also: ARRAY.sort, sub-functions.

#DetectStringEncoding $s ;;returns: 0 ASCII, 1 UTF8, 2 other

QM 2.3.2.

Scans the string to determine its character encoding.

Returns:

0	all characters are ASCII (character codes <=127).
1	found UTF-8 characters or BOM, and the string can be considered UTF-8.
2	found characters in range 128-255 that are not valid UTF-8 characters.

#isdigit char

QM 2.3.0.

Returns a nonzero value if char is a digit '0' to '9'. This function replaces the msvcrt.dll function because the later also would return nonzero for superscript characters.

#isalnum char

QM 2.3.0.

Returns a nonzero value if char is a digit '0' to '9' or a letter (including non ASCII). This function replaces the msvcrt.dll function because the later also would return nonzero for superscript characters.

The return value consists of flags: C1_DIGIT (4), C1_ALPHA (0x100), C1_UPPER (1), C1_LOWER (2).

#iscsym char ;;ASCII letter, digit or _

QM 2.3.2.

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 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.

!*q_malloc size ;;QM malloc

Allocates size bytes of memory. Returns pointer to the allocated memory block.

!*q_calloc elemcount elemsize ;;QM calloc

Allocates elemcount*elemsize bytes of memory and fills with 0. Returns pointer to the allocated memory block.

!*q_realloc !*mem size ;;QM realloc

Allocates more or less memory. mem can be memory allocated with one of these functions, or 0. Returns pointer to the allocated memory block. It can be different or the same as mem.

q_free !*mem ;;QM free

Frees memory allocated with one of these functions. mem can be 0.

#q_msize !*mem ;;QM _msize

Gets size of memory allocated with one of these functions.

$q_strdup $s ;;QM _strdup

Allocates duplicate string. s can be any string, not necessary allocated with one of these functions. The function allocates memory using q_malloc and copies s there.

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.

#QmKeyCodeToVK $qmkey int&vk ;;Returns number of characters eaten.

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 variable vk, and returns number of parsed characters (eg 3 for F12). If qmkey is invalid, vk receives 0.

QM 2.2.1: Instead can be used key. It converts multiple key codes, variables, etc. However then the QM key codes cannot be a variable string.

QmKeyCodeFromVK virtualkey str&qmkey

Converts virtual-key code to QM key code.

#RealGetKeyState vk ;;Returns 1 if the key is pressed. If vk contains flag 0x100 - if toggled. vk is virtual-key code.

QM 2.2.1.

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.

#GetMod ;;Returns: 1 Shift, 2 Ctrl, 4 Alt, 8 Win.

Checks whether modifier keys are pressed. The return value is combination of the following values: 1 - Shift is pressed, 2 - Ctrl is pressed, 4 - Alt is pressed, 8 Win is pressed. For example, if Ctrl and Alt are pressed, the return value is 6.

Example

if(GetMod&2) out "Ctrl pressed"

FormatKeyString !vk !mod str&s ;;mod:   1 Shift, 2 Ctrl, 4 Alt, 8 Win.

Gets key name for a key and/or modifiers. The text will be like "Ctrl+Page Up".

vk - virtual-key code.

mod - modifiers. See GetMod.

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

#SilentImport $_file [flags] ;;_file: qml file to import; flags: 1 add shared, 2 at bottom. Returns 1 if successful.

Imports a QM file. Same as menu File -> Import, but without the File Viewer.

_file - full path of .qml file.

flags - see above.

Not available in exe.

#SilentExport $item $_file [flags] ;;item: qm item or folder name or +id; _file: folder or qml file; flags: 1 no import, 2 no open, 4 no shared, 8 no partial/renamed, 16 read-only, 0x100 make zip. Returns 1 if successful.

Exports a QM item or folder to a QM file. Same as menu File -> Export, but without the Export dialog.

item - QM item or folder. Can be name, path, GUID or +id.

QM 2.4.3.8: can be a list of QM items or/and folders, like "Func1[]Func2[]\Functions\Public".

_file - full path of .qml file to create. If does not end with ".qml" - folder where to create .qml file.

flags - see above. The same as the checkboxes in the Export dialog.

Not available in exe.

#GetQmItemsInFolder $folder ARRAY(QMITEMIDLEVEL)&a [flags] ;;1 only direct children

QM 2.4.1.

Gets array of QM items in a folder in the list of QM items.

Returns 0 if folder not found. Else returns 1.

folder - folder name, path or +id. Gets all if folder is "".

a - variable that receives id and level of QM items that are in folder and its subfolders. The order will be the same as in the list of QM items. Levels are 0-based, relative to folder. To get item properties, use qmitem or str.getmacro.

Not available in exe.

Example

out
ARRAY(QMITEMIDLEVEL) a; int i
if(!GetQmItemsInFolder("\System\Functions" &a)) end "failed"
for i 0 a.len
	out "%.*m%s" a[i].level 9 _s.getmacro(a[i].id 1)

#IsThreadRunning $threadName ;;Returns number of threads.  name can be QM item name or +id.

Returns the number of threads (running instances) of the function or macro.

threadName - QM item name or id. If sub-function, can be like "ParentName:SubName".

To get the number of threads of current function, instead use getopt nthreads, it's faster and don't need to specify name.

Example

mac "FunctionX" ;;run function "FunctionX" in separate thread
wait 5
if(IsThreadRunning("FunctionX"))
	out "FunctionX is running"

#EnumQmThreads [QMTHREAD*arr] [nelem] [flags] [$threadName] ;;flags: must be 0

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 or id. Use 0 or "" if need all threads. If sub-function, can be lik "ParentName:SubName".

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"

#GetQmThreadInfo handle QMTHREAD&qt ;;Returns 1 on success, 0 on failure. handle=0 - current thread.

QM 2.2.0.

Gets information about a QM thread. 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.

qt - variable of type QMTHREAD (described above) that receives the info.

#GetToolbarOwner hwndTb ;;Returns handle of a QM toolbar's owner window

QM 2.2.0.

Returns handle of the window to which the toolbar is attached. Returns 0 if the toolbar is not attached to a window. Use this function instead of GetWindow or other Windows API, because QM toolbars are not owned as Windows interprets it.

hwndTb - toolbar window handle. Note that it is handle of toolbar, not of its owner window.

Example (in a toolbar)

out my owner :int w=GetToolbarOwner(TriggerWindow); outw w

GetLastSelectedMenuItem str&label [str&command] [flags] ;;flags: 1 get pidl always

QM 2.2.0.

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

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

command - variable that 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

MenuSetString hMenu item $s ;;item: > 0 id, <=0 -position

QM 2.3.0.

Changes menu item text.

#MenuGetString hMenu item str&s ;;item: > 0 id, <=0 -position. Returns 1 on success, 0 on failure.

QM 2.3.0.

Gets menu item text.

hMenu - menu handle.

item - menu item id or negative position.

s - sets or receives menu item text.

The menu cannot be a QM user-defined popup menu.

#SubclassWindow hwnd newWndProc

QM 2.3.0.

Replaces window procedure. Returns address of old procedure. Read more about subclassing in MSDN Library.

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

newproc - address of new window procedure (a user-defined function).

The function must begin with function hWnd message wParam lParam.
The function must end with ret CallWindowProcW(oldproc hWnd message wParam lParam).

Note: If the window is Unicode (IsWindowUnicode returns 1), the new window procedure receives Unicode UTF-16 strings in standard text messages such as WM_SETTEXT. Most window classes are Unicode. If you instead use SetWindowLong/CallWindowProc (ANSI versions), Windows automatically converts Unicode/ANSI, however it is not recommended.

QM 2.3.5. You should instead use SetWindowSubclass. It is safer and easier to use. It is a Windows API, documented in MSDN. A template window procedure is available in menu File -> New.

SetWinStyle hwnd style [flags] ;;flags: 0 set, 1 add, 2 remove, 4 exstyle, 8 update nonclient, 16 update client

Changes window style or extended style.

hwnd - window handle. Can be top-level or child window.

style - style or extended style.

Window styles are documented in 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).

See also: GetWinStyle

Example

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

#IsWindow64Bit hwnd [flags] ;;flags: 1 hwnd is process id

QM 2.2.0.

Returns 1 if the window belongs to a 64-bit process.

Before QM 2.4.3 this function returned -1 if failed. Now returns 0.

hwnd - window handle. If flags includes 1 - process id.

See also: _win64

#WinTest hwnd $cls

QM 2.4.3.

Gets window class name and compares with the specified string. Returns 1 if matches, 0 if not. Returns 0 if hwnd is 0 or invalid.

hwnd - window handle. Can be any window (top-level or child).

cls - a string to compare with window class name.

Can contain wildcard characters *?.
Can be a list, like "Class1[]Class2". Then returns 1-based index of matching string.

In programming often need just to compare window class name. Then WinTest is easier to use than wintest, which has more parameters and throws error when the handle is invalid.

AdjustWindowPos hwnd RECT&r [flags] [monitor] ;;flags: 1 work area, 2 actually move, 4 raw x y, 8 only move into screen, 16 can resize, 32 monitor is hmonitor. monitor: 0 primary, 1-30 index, -1 mouse, -2 active window, -3 primary, or window handle

QM 2.2.1.

Adjusts window or rectangle coordinates like mes and other QM functions do. If negative, adjusts so that the window would be at the right or bottom of the screen. If 0, adjusts so that the window would be at the center of the screen. Ensures that whole window is in the screen. Ensures that the window will be in the specified monitor.

If the window is minimized, does not restore it but ensures that the window will be in correct position when restored. If the window is maximized, does not change its position and size, except when need to move to another monitor, but ensures that the window will be in correct position when restored to normal. All this is if hwnd is nonzero and flag 2 used. If hwnd is nonzero, the function always returns rectangle of normal (not minimized or maximized) window, regardless of its current state.

hwnd - window handle. Can be 0 if you only need to adjust r.

r - a RECT variable or 0.

On input, the variable must contain requested window coordinates in r.left and r.top. If hwnd is 0, r.right and r.bottom also must be specified, else they are not used. The coordinates are relative to the monitor, except when flag 8 used.
On output, the variable will contain normal coordinates, ie relative to the primary monitor.
Can be 0 if flag 8 used or to use r.left= 0 and r.top=0.

flags:

1	when calculating new coordinates, use work area instead of whole screen.
2	actually move the window. By default, only modifies r.
4	use raw x y relative to the monitor. Negative and 0 x y don't have special meaning.
8	only move the window or rectangle to the nearest position in the work area, if it is not completely there. If hwnd is not 0, r is not used and can be 0. Else r must contain normal coordinates. If monitor is 0, uses the monitor that contains the biggest part of the window or rectangle, or is nearest.
16	resize if needed. By default the function can only move. Should be used only with flag 8.
32	monitor is monitor handle.

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

#MonitorFromIndex [monitor] [flags] [RECT&r] ;;flags: 1 work area, 32 monitor is hmonitor. monitor: 0 primary, 1-30 index, -1 mouse, -2 active window, -3 primary, or window handle

QM 2.2.1.

Returns handle of monitor that is specified by index or some other property. Also can get monitor coordinates.

monitor - 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 - variable that receives monitor coordinates, relative to the primary monitor. Can be 0 if don't need.

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

#MonitorIndex hmonitor ;;Returns 1-based monitor index.

QM 2.2.1.

Returns 1-based monitor index. Returns 0 if the handle is invalid.

hmonitor - monitor handle.

#RichEditLoad hwndRE $_file ;;Returns 1 if successful.

Loads a file to a rich edit control.

#RichEditSave hwndRE $_file ;;Returns 1 if successful.

Saves rich edit control text to a file.

hwndRE - control handle.

_file - file. If ends with .rtf, uses RTF format, else text format.

Rich edit control's class usually is RichEdit20A or RichEdit20W. The control must belong to qm/exe process.

Supports macro resources (QM 2.4.1) and exe resources.

#GetCPU ;;Returns % CPU usage, 0 to 100.

Returns % of processor usage since last call. When calling first time in thread, result is undefined.

#GetDiskUsage ;;Returns % disk usage, 0 to 100.

Returns % of disk usage (all physical disks) since last call. That is, % of time spent in disk read/write mode. When calling first time in thread, result is undefined. Should not be called too frequently (with < 100 ms period), or results may be incorrect.

This function should work only for administrators and users in the Performance Log Users group. In my tests it was true on Windows Vista, but the function always works on Windows 7 and 8.

PerfFirst

PerfNext

PerfOut [flags] [str&sOut] ;;flags: 1 begin collect, 2 collect, 3 out collected

QM 2.3.5.

Measures and shows time spent executing parts of macro code. Unit - microseconds.

PerfFirst and PerfNext get current time and store in internal global variables.

PerfOut displays times between PerfFirst and max 10 following PerfNext.

flags: 1 - 3 can be used to measure time spent in parts of repeatedly executed code. Instead of displaying time in each loop, PerfOut 2 collects times, and finally PerfOut 3 displays sums. Insert PerfOut 1 at the very beginning.

sOut - variable that receives string containing times. If omitted or 0, the function displays the string in QM output.

See also: perf

Examples

 simple
PerfFirst
rep 1000
	find("one two three four" "four")
PerfNext
rep 1000
	findrx("one two three four" "four")
PerfNext
PerfOut

 with collecting times
PerfOut 1 ;;start collecting
rep 10
	PerfFirst
	win("" "Shell_TrayWnd")
	PerfNext
	win("not found")
	PerfNext
	PerfOut 2 ;;collect. Does not show times now.
	0.001 ;;can be more code, its time will not be included
PerfOut 3 ;;show collected

#IsLoggedOn ;;Returns: 0 not logged on, 1 normal, 2 locked, 3 switched off, 4 custom desktop.

Checks whether QM is running on interactive desktop. Returns 0 if not logged on, 1 if normal (runs on interactive desktop), 2 if locked (directly or by a secure screen saver), 3 if switched off, 4 custom desktop.

#EnsureLoggedOn [unlock] ;;Returns: 0 cannot ensure, 1 normal, 2 successfully unlocked.

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 Unlock Computer dialog.

Unlocking is unavailable in exe and in portable QM. Then 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

#GetUserInfo str&s [flags] ;;flags: 0 user name, 1 computer name

QM 2.3.0.

Gets user name or computer name.

s - variable that receives it.

#IsUserAdmin ;;Returns 1 if QM (or exe) is running as administrator

QM 2.2.0.

Returns 1 if current process (QM or exe) is running as administrator.

#GetProcessUacInfo hwnd [flags] ;;returns: 0 XP or failed, 1 UAC off or non-admin account, 2 admin, 3 uiAccess, 4 user; flags: 1 hwnd is process id (0 = current process)

QM 2.2.0.

Returns some UAC (Vista/7/8/10) info of a process (running program):

Return values:

0	Older OS (not Vista/7/8/10), 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)

#GetProcessIntegrityLevel hwnd [flags] ;;returns: 0 XP or failed, 1 Low, 2 Medium, 3 High, 4 System; flags: 1 hwnd is process id (0 = current process)

QM 2.2.0.

Returns integrity level of a process:

0	Older OS (not Vista/7/8/10), 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.

EnumProcessesEx ARRAY(int)&pids [ARRAY(str)&names] [flags] ;;flags: 1 full path, 2 current user session only

Gets names and/or process ids of all processes (running programs).

pids - variable that receives process ids. Can be 0 if don't need.

names - variable that receives process names. Can be 0 if don't need.

flags:

get full paths.

Note: cannot get full paths of processes running in other user sessions if QM is running not as administrator.

2 (QM 2.2.0)

enumerate only processes running in current user session (fast user switching).

Example

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

#ProcessNameToId $exename [ARRAY(int)&allPids] [flags] ;;allpids can be 0; flags: 1 current user session only

Returns process id.

Returns 0 if the process does not exist (the program is not running).

QM 2.2.0. Added parameter flags.

exename - program name or full path.

allPids - variable that receives process ids of all matching processes. Can be 0 if don't need.

flags:

1	find only processes running in current user session.

#ProcessHandleToId hProcess

QM 2.4.2.

Gets process id from process handle.

Example

__Handle hp=run("notepad.exe")
int pid=ProcessHandleToId(hp)

#GetProcessExename pid str&exename flags ;;flags: 1 full path. Returns: 1 success, 0 failed.

QM 2.2.1.

Gets name or full path of the executable file that started specified process (running program).

pid - process id.

exename - variable that receives the name.

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

See also: _qmdir

#StartProcess flags $path [$cl] [$defDir] [int&hProcess] ;;flags: 0 as QM, 1 medium, 2 high, 3 high with consent, 4 low, 5 as QM -uiAccess, 16 get process id, hibyte showcmd

QM 2.2.0.

Runs a program with specified privileges (administrator, user, etc). Mostly useful on Vista and later, but can be used on all OS.

flags - integrity level (IL) that you need, and other flags, see above. The IL values are described in the Make Exe topic.

path - executable file path.

cl - command line.

defDir - default directory.

hProcess - variable that receives process handle. Later close it with CloseHandle. With flag 16, gets process id instead; don't 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.

There are some limitations in portable QM.

#AllowActivateWindows ;;Returns 1 if successful

By default, Windows does not allow background programs to activate windows. QM is usually running in the background. Use this function to temporarily allow QM to activate windows.

Tip: After calling this function, you also can call AllowSetForegroundWindow -1 to allow other processes activate windows.

#FileExists $_file [flags] ;;flags: 0 file, 1 folder, 2 file or folder.   Returns: 0 not found, 1 file, 2 folder.

QM 2.4.0.

Checks if the specified file, folder or drive exists.

0	Does not exist, or failed.
1	Exists, and is file.
2	Exists, and is folder or drive.

_file - full or relative path of a file, folder or drive.

flags:

0 (default)	Must be file. Return 0 if exists but is folder or drive.
1	Must be folder or drive. Return 0 if exists but is file.
2	Can be file, folder or drive.

Internally uses Windows API function GetFileAttributes. Returns 0 if it fails for any reason, eg when the file exists but cannot be accessed because of security settings. Does not support wildcard characters, use Dir class instead (dialog "Get file info").

%GetFileOrFolderSize $file

QM 2.2.0.

Returns size of the specified file, folder or drive.

If folder, calculates sum of sizes of all files in the folder and subfolders. It is slow.

If drive, gets used size. It is fast. Uses Windows API function GetDiskFreeSpaceEx, except for network drives.

GetFullPath $sAny str&sFull

QM 2.3.0.

Gets full path of a file or folder. Expands special folders, replaces "..", etc. Does not check whether the file or folder exists.

sAny - full or relative path. If it is relative path, prepends current directory. Can contain ".." (parent folder), "." (same folder). If it is a drive letter without "\", appends "\". Read more: File names and paths.

sFull - variable that receives full path.

This function can be used to create full path from user-entered file name. For example, if user entered "..\f3\file.txt", and your default folder is "c:\f1\f2\", join them ("c:\f1\f2\..\f3\file.txt") and pass to GetFullPath. Result will be "c:\f1\f3\file.txt".

To know whether a file path is full or relative, can be used function PathIsRelative.

#PidlToStr ITEMIDLIST*pidl str&s flags ;;Returns 1 if successful.  flags: 1 must be path, 2 must be ":: ITEMIDLIST", 4 path can be URL, 8 path can be "::{CLSID}", 16 path must be display name

Converts ITEMIDLIST to string - file system path, ":: ITEMIDLIST", URL, "::{CLSID}" or display name. Variable s receives the string.

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)

#GetFileIcon _file [index] [flags] ;;Returns icon handle if successful. Later call DestroyIcon. flags: 1 large, 2 don't use shell icon, 4 cursor, 8 create empty if fails

Extracts icon from an icon file, or gets icon for a file that itself does not contain icons. Returns icon handle. Later destroy it using DestroyIcon. Or assign to a __Hicon variable.

_file - any file or folder.

Can be full path, filename or ITEMIDLIST string.
Can be just file type extension, like ".txt". Gets icon of that file type.

index - 0, or icon index (0-based).

If negative, index is interpreted as negative resource id.
Alternatively, icon index or -id 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.
4 (QM 2.3.0)	Get cursor. Returns cursor handle. Later destroy it with DestroyCursor.
8 (QM 2.4.3)	Create empty/transparent icon if failed or if _file string is "".

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 used. Otherwise, gets shell icon (icon that would be displayed in Windows Explorer).

Supports macro resources (QM 2.4.1) and exe resources. Adds (to exe) images of all sizes and colors that are in the icon file or resource, not only of the specified size.

QM 2.3.0. You can specify custom size in high-order word of flags. Flag 1 then is ignored. If icon of that size is unavailable, gets icon of nearest available size.

See also: GetWindowIcon.

Example

int hi=GetFileIcon("shell32.dll,3" 0 1)
int dc=GetDC(GetQmCodeEditor)
DrawIconEx dc 100 100 hi 0 0 0 0 DI_NORMAL
ReleaseDC 0 dc
DestroyIcon hi

#SaveBitmap hbitmap $_file [flags] ;;Returns 1 if successful. flags: 1 _file is IStream.

Saves bitmap to a file.

hbitmap - bitmap handle.

_file - .bmp file.

#LoadPictureFile _file [flags] ;;Returns bitmap handle. flags: 1 return IPicture

Loads bitmap from a bmp, jpg or gif file. QM 2.3.4: also can be png.

Supports macro resources (QM 2.4.1) and exe resources.

#QmRegisterDropTarget hwndTarget hwndNotify flags ;;flags: 1 notify on enter, 2 notify on over, 4 notify on leave, 16 need only files, 32 need .lnk

QM 2.2.0.

Registers a window as an OLE drag and drop target. Returns 1 on success, 0 on failure.

Can be used to receive paths of dropped files, other shell objects (ITEMIDLIST) and Internet links. Also can be used to receive dropped data of other formats (text, HTML, etc).

Unlike WM_DROPFILES, this method works well on Windows Vista and later. WM_DROPFILES does not work under UAC, because it does not allow to drag and drop files between processes of different integrity level (IL). QM normally has high IL, but Windows Explorer has medium IL. However in exe running with high IL this method does not work too.

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 parameters:

hwndTarget - 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 - 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 use hDlg for hwndNotify. Can be 0 if it is the same window as hwndTarget.

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. The message is sent with the following info:

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

lParam - address of variable of QMDRAGDROPINFO type.

type QMDRAGDROPINFO hwndTarget IDataObject'dataObj ARRAY(FORMATETC)formats keyState POINT'pt effect str'files

hwndTarget - target window handle.

dataObj - IDataObject interface pointer. Available on drag enter and drop. Can be used to extract data of various formats. In QM, only GetData function is valid, and can retrieve only data described as TYMED_HGLOBAL. In exe, dataObj is fully valid.

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

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

#QmUnregisterDropTarget hwndTarget

QM 2.2.0.

Unregisters drop target. Optional. Returns 1 on success, 0 on failure.

#GetExeResHandle

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

When the macro runs as separate exe file, gets exe module handle, which is the same as _hinst.
When the macro runs in separate process and uses .qmm file, gets .qmm file handle.
When the macro runs in QM and there is associated .exe or .qmm file, gets .exe or .qmm module handle.
Else returns 0.

#ExeExtractFile resId $dest [flags] [resType] ;;Returns: 1 success, 0 failed. flags: must be 0

QM 2.2.0.

Extracts a file added to exe. The file can be added to exe using syntax ":resourceid filepath" (QM 2.3.0), or #exe addfile, or using a resource editor. 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 or in ":resourceid filepath".

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 qm$\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:

1	QM 2.3.4. Load dll and return handle.

resType (QM 2.3.4) - resource type. If omitted or 0, uses RT_RCDATA (10).

resType and/or resId can be integer 1 to 0xFFFF or string (eg "WAVE").

Example

#if EXE=1 ;;EXE is 1 if compiling exe, 2 if qmm, 0 if the macro runs in QM

#exe addfile "$desktop$\test.txt" 1
if(!ExeExtractFile(1 "$temp qm$\testexe\test.txt")) ret
run "$temp qm$\testexe\test.txt"

#else

run "$desktop$\test.txt"

#endif

See also code in function ExeQmGridDll. It adds a dll to exe, and extracts/loads at run time.

#ExeGetResourceData resType resId str&data int*size ;;Returns: 1 success, 0 failed. resType: if 0, uses RT_RCDATA

QM 2.2.0.

Loads exe resource data. 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 - variable that receives data.

Can be 0. Then the function returns pointer to resource data in memory. It is read-only.

size (QM 2.3.4) - variable that receives resource size. Use when you need resource size when data is 0.

resType and/or resId can be integer 1 to 0xFFFF or string (eg "WAVE").

Example

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

#Crc32 !*data nbytes [flags] ;;Returns CRC of data. If data is string, nbytes can be string length or -1.  flags: 1 data is file (nbytes not used).

Calculates CRC checksum (hash) of a string or binary data.

flags (QM 2.3.2):

1	data is file path. Calculates CRC of file data. nbytes not used and can be 0.

See also: str.encrypt (MD5).

^Round ^number [cDec] ;;Returns number rounded to cDec digits after decimal point

QM 2.2.1.

Returns number rounded to cDec digits after decimal point. Can be used to convert a floating-point (double) value to nearest int value.

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

^RandomNumber ;;Returns random number between 0.0 and 1.0, not including them

QM 2.2.1.

Random number generator. Returns a random value between 0 and 1, not including them. The value can be multiplied to get a random double number in any range.

#RandomInt bound1 bound2 ;;Returns random number between bound1 and bound2, including them

QM 2.2.1.

Returns a random integer value between bound1 and bound2, including them.

%ConvertSignedUnsigned int'value [valueType] ;;valueType: 0 unsigned int, 1 signed byte (char), 2 signed word (short)

QM 2.3.2.

Converts from an integer type unavailable in QM to long (64-bit integer).

QM does not have these integer types:

32-bit unsigned. In C++ it is DWORD, UINT, unsigned int, WPARAM, etc. The matching QM type is int, but it is signed.
8-bit signed. In C++ it is char. The matching QM type is byte, but it is unsigned.
16-bit signed. In C++ it is short. The matching QM type is word, but it is unsigned.

Values of these types can be returned by dll functions. Variables of the matching QM types can store them. However, when assigning to a bigger type using operator =, possible incorrect conversion. This function converts correctly.

valueType:

0	value is unsigned 32-bit integer. The return value must be stored into a long variable.
1	value is signed 8-bit integer. The return value must be stored into a int or long variable.
2	value is signed 16-bit integer. The return value must be stored into a int or long variable.

Examples

int i; long lo
i=0xffffffff
lo=i; out lo ;;-1
lo=ConvertSignedUnsigned(i); out lo ;;4294967295

word w; int j
w=0xffff
j=w; out j ;;65535
j=ConvertSignedUnsigned(w 2); out j ;;-1

byte c; int k
c=0xff
k=c; out k ;;255
k=ConvertSignedUnsigned(c 1); out k ;;-1

#GetQmCodeEditor

QM 2.3.0.

Returns QM code editor control handle. If there are two controls, returns one that is currently active, ie has focus or had focus more recently. Use this function instead of id(2210 _hwndqm).

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 control created by Neil Hodgson. QM currently uses Scintilla version 3.3.9, upgraded from 2.23 in QM 2.4.1.

Not available in exe.

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

InsertStatement $s [label] [icon] [flags] ;;flags: 1 simple, 2 set focus, 4 don't indent

QM 2.3.0.

Inserts one or more lines of QM code in the QM editor, at current position. Inserts as separate line(s), properly indents, etc.

s - one or more QM statements (commands).

label - label of menu item or toolbar button. Default: "Label". With other item types, it is appended as comments.

icon - icon file.

flags:

1	simply insert the string in current position, not necessary as separate line.
2	set focus.
4	don't indent.

When inserting multiline text in menu/toolbar/autotext, creates new sub-function with m attribute.

QM uses this function to insert code created by the code toolbar dialogs, recorded code, etc.

Not available in exe.

#HtmlHelp hwndCaller $pszFile uCommand dwData ;;HtmlHelp that supports UTF-8. For reference, search for HtmlHelp in MSDN Library.

Controls HTML help. For reference, search for HtmlHelp in MSDN Library.

#RecGetWindowName hwnd str&s [flags] [str&sParent] [str&sComments] [str&sComments2]

Gets window or child window expression as it would be recorded. Can be win, child or id function. Returns 1, or 0 if failed.

hwnd - window handle.

s - variable that receives the string.

flags - not used, must be 0.

sParent (QM 2.3.4) - if used, for child windows receives "win(...)" string (parent window), and s will be like "id(5 {window})"; for top-level windows will be empty.

sComments (QM 2.3.4) - if used, receives child window description.

sComments2 (QM 2.3.4) - if used, receives description of child accessible object from mouse.

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

Not available in exe.

EditReplaceSel hDlg cid $s [flags] ;;flags: 1 replace all, 2 set focus, 4 move caret to end

QM 2.3.0.

Inserts or replaces text in an Edit control. Unlike str.setwintext, can replace only selection, or just insert if there is no selection. Also, Undo will work. The function is intended to use in QM dialogs, but also works with edit controls in other threads and processes, except flag 2.

hDlg, cid - can be one of:

Edit control handle and 0.
Parent window handle and Edit control id.

s - text.

QmCodeToHtml $sIn str&sOut itemId bbcode flags

QM 2.3.2.

Formats HTML or BBCode or QM forum code from string containing QM code, like menu -> Edit -> Other Formats.

sIn - string containing QM code.

sOut - variable that receives the formatted string.

itemId: 0 macro/function, -1 menu/toolbar, -2 autotext list. Or QM item id.

bbcode: 0 HTML, 1 qm forum code, 2 standard bbcode.

flags:

1	with css.
2	with <pre>.
4	don't escape tabs/spaces.
8	<span> instead of <div>.

All flags used only with HTML.

Not available in exe.

CompileAllItems $folder [$excludeList]

Compiles multiple macros and functions. Purpose - quickly check for errors multiple macros and functions.

folder - name or id (<0x10000) of folder to compile. If 0, compiles all. If it is not folder, compiles all starting from item with this name/id.

excludeList (QM 2.3.4) - multiline list of names of functions and macros that the function must not compile.

Compiles only macros, functions and member functions. Not menus, toolbars, autotexts. Does not recompile if already compiled. Should be called soon after QM startup.

See also: #compile

Not available in exe.

$OutWinMsg message wParam lParam [str&sOut] [hwnd]

QM 2.3.1.

Formats string from a Windows message. Can be used in window and dialog procedures to display received messages.

message - message.

wParam and lParam - message parameters. The function uses them to get command/notification codes of some special messages, such as WM_COMMAND and WM_NOTIFY.

sOut - variable that receives the string. If omitted or 0, the function displays the string in QM output.

flags (QM 2.4.1) - a window handle. The function will append it and window class and name to the string.

QM 2.3.3. Returns the formatted string. If sOut is +2, does not display it in QM output.

Not available in exe.

#Statement [caller] [statOffset] [str&statement] [int&itemId] [flags] ;;flags: 1 include indirect callers

QM 2.3.1. Added to exe in QM 2.4.3.4.

Gets currently executing statement info.

caller - 0 current function, 1 caller, 2 caller's caller, and so on.

statOffset - 0 current statement, 1 next, -1, previous, etc. If out of range, gets nearest (first or last) statement. Note that some statements, eg declarations, are not used at run time. To see used statements, run the macro in debug mode.

statement - variable that receives statement code (text). Can be 0 if don't need (faster). Not used in exe.

itemId - variable that receives QM item id. Can be 0 if don't need.

flags:

1	include indirect callers. Direct caller is macro or function that explicitly called current function by name.

Returns:

>=0	Offset of the statement in code.
-1	There is no caller at the specified depth.
-2	The QM item is deleted or encrypted. Gets only itemId.

The results may be incorrect if code of the function changed after compiling.

See also: deb, GetCallStack (see below), other debug functions, getopt nargs

GetCallStack [str&cs] [flags] ;;flags: 1 no code, 2 no formatting

QM 2.3.5.

Gets function call stack.

It is a multiline list of function names. The first is current function, then its caller, caller's caller and so on.

cs - variable that receives results. If omitted or 0, displays in QM output.

flags:

1	Get only function names. By default also gets current statement code (text). In exe never gets code.
2	Get plain text. By default the text is formatted for QM output.

The statement code may be incorrect if code of the functions changed after compiling.

Names of sub-functions are full (like "<00001>SubName") with flag 2. Without this flag, names are like "SubName".

See also: deb, Statement (see above), other debug functions, getopt, qmitem, str.getmacro

q_printf $format ...

QM 2.3.2.

Shows formatted text in QM output like out. Use this function where you cannot use out. For example in C compiled code (__Tcc) instead of printf.

#SetPrivilege $privilege ;;Returns 1 if successful.

Some Windows API functions require certain privileges. This function enables a privilege in current process. Note that not all privileges can be enabled, especially when QM is running not as administrator.

#RegisterComComponent $path flags ;;flags: 1 unregister, 2 check extension (must be dll or ocx), 4 run as admin, 8 show error/success message box

QM 2.2.0.

Registers or unregisters a COM component (dll, ocx). Returns 1 if successful, 0 if not.

Requires admin privileges. Use flag 4 to run as admin (possibly with a "run as" or consent dialog, especially in exe).

QM 2.2.1. Internally runs regsvr32.exe. Now can also register 64-bit dlls. Added flag 8.

To register .NET COM components, instead use regasm.exe; it is in .NET runtime folder; more info is on the internet.

#UnloadDll $dllName

QM 2.3.2.

Unloads a delay-loaded dll (declared with dll-).

Returns 1 if successfully unloaded or still not loaded.

Returns 0 if the dll is not declared or is declared as not delay-loaded.

When you declare a dll with dll-, QM loads it on demand: when a delay-loaded function from it is called first time. Unloads when QM exits or when you open another or reopen current QM file. This function allows you to unload the dll at any time. It does not remove the dll declaration. The functions can be loaded on demand again.

This function is not thread-safe. If other threads use functions of this dll at the same time, QM may crash etc. Use it only when debugging a dll, for example a dll created at run time with __Tcc class. Don't need to unload dlls for other purposes.

Not available in exe.

RtOptions mask RTOPTIONS&x ;;mask: 0 get all, 1 flags, 2 spe_for_macros, 4 waitcpu_time, 8 waitcpu_threshold, 16 web_browser_class, 32 net_clr_version, 64 opt_

QM 2.3.4.

Sets or gets global run-time options. You will probably call this function from init2 or other function that runs when QM or your exe starts.

mask - which options to change. One or more flags listed above.

x - variable that contains or receives run-time options. The function uses only members specified in mask. If mask is 0, the variable receives current options.

type __RTO_OPT !keysync !keymark !keychar !hungwindow !clip
type RTOPTIONS
	flags spe_for_macros waitcpu_time waitcpu_threshold
	str'web_browser_class str'net_clr_version
	__RTO_OPT'opt_macro_function __RTO_OPT'opt_menu_toolbar __RTO_OPT'opt_autotext

flags:

0x8000

Prevent activating message box (mes) windows by default.

spe_for_macros - default autodelay for macros and menu/toolbar/autotext items. Not applied to functions. Default 100.

waitcpu_time - additional autodelay, applied only after opt waitcpu 1. Default 1000.

waitcpu_threshold - default CPU threshold, %. Used by opt waitcpu 1 and wait ... P (wait for CPU). Default 20.

web_browser_class - class name of your default web browser window. Used by web and htm, when window not specified. Use only if your default web browser is not Internet Explorer but is IE-based. Don't use for Firefox, Chrome, Opera.

net_clr_version (QM 2.4.1) - .NET CLR version to load when/if will need it. Used by CsScript class and related functions (compile/execute C# or VB.NET code).

Can be:
- "v2.0.50727" - use .NET framework version 3.5. This is default if .NET 4.x is unavailable.
- "v4.0.30319" - use .NET framework version 4.x (4.0, 4.5 etc, which is installed). This is default if .NET 4.x is available.
Once a CLR is loaded in current process, it cannot be unloaded or changed. If need, restart QM or run macros in separate process.

opt_macro_function, opt_menu_toolbar, opt_autotext (QM 2.4.2) - initial run-time options for different QM item types, as with opt.

This function changes only options that are specified with non-zero values. To set an option to 0, assign 0x80.
All default initial options are 0, except opt_autotext.keymark.

Example

RTOPTIONS x
x.spe_for_macros=25
x.opt_autotext.keysync=1
x.opt_macro_function.hungwindow=3
x.opt_menu_toolbar.hungwindow=3
x.opt_autotext.hungwindow=3
RtOptions 2|64 x

#QmSetWindowClassFlags $cls flags ;;flags: 0x80000000 get, 1 use dialog variables, 2 use dialog definition text, 4 disable text editing in Dialog Editor, 8 supports "WM_QM_GETDIALOGVARIABLEDATA"

QM 2.3.4.

Sets or gets flags for a window class. The flags are used only with QM functions, not by Windows.

cls - class name.

flags:

1	Dialog Editor adds variables for controls of this class.
2	ShowDialog passes dialog definition text to controls of this class when creating them. Dialog Editor too. By default, does it only for some known classes, eg Button, Static, Group, readonly Edit. For other controls, eg editable Edit, text can be changed only with dialog variables or setwintext. This flag is ignored for some known classes.
4	Disable text editing in Dialog Editor.
8	QM 2.4.3. The control supports "WM_QM_DIALOGCONTROLDATA" message registered with RegisterWindowMessage. Use when you create a custom control that supports dialog variables, and don't want to use WM_SETTEXT and WM_GETTEXT messages to exchange control data with dialog variables. QM functions ShowDialog, DT_SetControl, DT_SetControls, DT_GetControl and DT_GetControls send this message to controls that support it, to set and get control data from/to dialog variables. If your control does not support it, sends WM_SETTEXT and WM_GETTEXT instead. "WM_QM_DIALOGCONTROLDATA" message parameters: lParam - address of dialog variable. wParam: 1 - need to set control data. The variable contains text stored in it before calling ShowDialog etc. 0 - need to get control data. Your window procedure stores control data in the variable and returns 1. The data must be a string in control-defined format. Example window procedure of your control function# hwnd message wParam lParam sel message case WM_NCCREATE int- t_WM_QM_DIALOGCONTROLDATA=RegisterWindowMessage("WM_QM_DIALOGCONTROLDATA") ... case else if message=t_WM_QM_DIALOGCONTROLDATA str& dialogVar=+lParam sel wParam case 0 ret sub.MyGetControlData(dialogVar) case 1 ret sub.MySetControlData(dialogVar) ret DefWindowProcW(hwnd message wParam lParam)
0x80000000	Get. The function returns flags, does not set.

#IsValidCallback addr nBytesParam

QM 2.3.5.

Can be used in functions that want to validate a callback-function-address parameter.

Returns:

0 - invalid memory address, or the user-defined function has incorrect number of parameters.

1 - it is a user-defined function with correct number of parameters.

-1 - valid (readable) memory address, but it is not a user-defined function. It may be a dll function, other valid code, or not a valid code.

addr - function address.

nBytesParam - total size of parameters that the function must have.

Function parameters are aligned at 4 bytes, and size of a single parameter usually is <=4, therefore nBytesParam usually must be the number of parameters multiplied by 4.
Note that callback functions cannot have parameters of str and other composite types. Parameters of such types, as well as of other types of size>4, should be reference or pointer. For example, callback function can begin with: function str&r. To call it: call(addr &strVariable).
Not used when the address is not of a user-defined function.

See also: call

RedirectQmOutput *redirFunc

QM 2.4.1.

Sets callback function to intercept QM output. The callback function will be called when out or QM sends text to QM output. Also when out or ClearOutput clears QM output.

redirFunc - address of callback function, or 0.

The callback function must begin with:

function# str&s reserved

s - text to be displayed in QM output.

The callback function can change it.
&s is 0 when the callback function is called to clear output.

reserved - currently not used.

The callback function can return:

0 - to send the text (possibly changed) to QM output. When clearing - to clear.
1 - to not send. When clearing - not clear.

Usage examples:

Create an output window in exe.
Write output text to a file etc.
Search for certain strings in output text, and run code depending on it.
Add number, date, etc to the output text.

The callback function is called in the same thread that sends text. It can be any thread.

In the callback function out is not redirected.

If the output text begins with "<>", it is with tags. If you modify it, don't insert your text before the "<>". Also be careful to not break tags.

Multiple callback functions are not supported. This function replaces previous callback function. This function is used by ExeOutputWindow and ExeConsoleRedirectQmOutput, therefore only one of these 3 functions can be used in an exe.

Example callback function

function# str&s reserved

if &s
	OutputDebugString s
	 s+" <MODIFIED>"
else
	OutputDebugString "<CLEAR>"

ret 1

#InitWindowsDll what ;;what: 0 winsock, 1 GDI+

QM 2.4.1.

Calls an API function to initialize a Windows dll that requires it. The API will be called once in process; does nothing if already called. On exit process will be called corresponding API function to uninitialize the dll.

what:

0 - call WSAStartup to initialize ws2_32.dll (Windows sockets). Uses version 0x202.
1 - call GdiplusStartup to initialize gdiplus.dll (GDI+). Uses default GdiplusStartupInput (version 1).

Controls

QM Grid control

QM ComboBox and drop-down list controls