Dll functions exported by QM

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

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. On Windows 2000 uses flag 3 instead.

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

See also: ARRAY.sort.

#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 leass 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*virtualkey ;;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 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.

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.

QM 2.1.9.

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 - address of a str variable that receives the text. If s initially is not empty, appends to the end.

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

Imports qml file. Any dialogs or error messages are not displayed. Not available in exe.

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

Exports qm item or folder. Any dialogs or error messages are not displayed. Not available in exe.

#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 (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"

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

#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 necessarily owned as Windows interprets it.

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

QM 2.2.0.9. Also available in exe.

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

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 popup menu. It must be a menu created using Windows API functions, such as CreatePopupMenu. It must belong to qm/exe process.

#IsHungWindow hwnd ;;Returns: 1 hung, 0 not, -1 invalid hwnd

Returns 1 if the window is hung. A window is hung if it does not respond for certain time, eg 10 s. Windows XP hides a hung window and replaces it with a ghost window.

hwnd - window handle.

#RealGetNextWindow hwndFrom [flags] ;;Gets next window, skipping invisible and other windows that would be skipped by Alt+Tab. flags: 1 retry from top, 2 skip minimized

QM 2.2.1.

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.

#SubclassWindow hwnd newWndProc

QM 2.3.0.

Replaces window procedure. Returns address of old procedure. If the window is ANSI, calls SetWindowLongA. If Unicode, calls SetWindowLongW. Read more about subclassing in 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).

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

Example

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

#IsWindow64Bit hwnd [flags] ;;flags: 1 hwnd is pid; returns: 0 32-bit, 1 64-bit, -1 error

QM 2.2.0.

Lets you to know if a process is 64-bit. Always returns 0 on 32-bit Windows.

Return values:

0	not 64-bit.
1	64-bit.
-1	error.

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 (qm or exe).

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 - address of a str 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 not Vista or failed, 1 UAC off or non-admin account, 2 admin, 3 uiAccess, 4 user; flags: 1 hwnd is pid (pid 0 = current process)

QM 2.2.0.

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

Return values:

0	not Vista/7, 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.

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.

QM 2.2.0. Added parameter flags.

exename - program name or full path.

allpids - address of array that receives process ids of all matching processes. Can be 0 if not needed.

flags:

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

#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 - address of a str 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] [*hProcess] ;;flags: 0 as QM, 1 medium, 2 high, 3 high with consent, 4 low, 5 as QM -uiAccess, 16 get pid, hibyte showcmd

QM 2.2.0.

Runs an executable file with specified privileges (administrator, user, etc). Mostly useful on Vista, but can be used on all OS.

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.

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

%GetFileOrFolderSize $file

QM 2.2.0.

Returns size of a file, folder or drive. Calculating folder size may took several seconds because enumerates all files. For drives, returns the used size (total-available). To get drive sizes, uses 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 - 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 pidl string

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

ITEMIDLIST*PidlFromStr $s

Converts path or ":: XXXX..." string to ITEMIDLIST. Use CoTaskMemFree to free it.

#CreateShortcutEx $shortcut SHORTCUTINFO*si ;;Returns 1 if successful.

Creates shortcut. All si members except target are optional. You can also use simpler function CreateShortcut.

#GetShortcutInfoEx $shortcut SHORTCUTINFO*si ;;Returns 1 if successful.

Gets shortcut's parameters (target path, icon, etc).

shortcut - shortcut file (.lnk) path.

si - address of a variable that contains or receives shortcut properties. The variable must be of type SHORTCUTINFO which is described below.

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

Some members:

target - file/folder path, or ITEMIDLIST string.

hotkey - hot key.

The low-order byte is virtual-key code.
The high-order byte is combination of flags 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)

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

Extracts icon from an icon file, or gets icon for a file that itself does not contain icons. Returns icon handle. When it is no longer needed, destroy it using DestroyIcon.

_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 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. Without this flag would get cursor file's icon that cannot be used as cursor. Returns cursor handle. When it is no longer needed, destroy it using DestroyCursor.

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

If _file is like ".txt", gets icon associated with that file type.

Supports ":resourceid filepath" syntax to add the icon to exe resources. Adds 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 or fails to get it, gets icon of nearest available size.

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

#GetWindowIcon hwnd ;;Returns icon handle if successful. Later call DestroyIcon.

Gets icon that is displayed in top-left corner of window hwnd.

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

Supports ":resourceid filepath" syntax to add the file to exe resources. Example: ":2 file.bmp".

#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. WM_DROPFILES does not work on Vista under UAC, because Vista 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 on Vista 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 decribed 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

QM 2.1.9.

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

#ExeExtractFile resid $dest [flags] ;;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 (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 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$\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
if(!ExeExtractFile(1 "$temp$\testexe\test.txt")) ret
run "$temp$\testexe\test.txt"

#else

run "$desktop$\test.txt"

#endif

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

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

QM 2.2.0.

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

#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 of a string or binary data.

flags (QM 2.3.2):

1	src is file. Calculates CRC of whole file.

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

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 QM code into the QM editor. Inserts at current position. Inserts as separate line, 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.

Not available in exe.

#HtmlHelp hwndCaller $pszFile uCommand dwData ;;Same as WinAPI function HtmlHelp, but supports UTF-8. For reference, search for HtmlHelp in MSDN Library.

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

#SpecFoldersMenu hwnd str*s ;;returns 1 if selected

Shows menu of special folders and gets selected string.

hwnd - menu owner window handle.

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

#CreateRegExpMenu [flags] ;;flags must be 0

QM 2.1.9.

Creates menu for regular expressions to use with TrackPopupMenuEx.

#RecGetWindowName hwnd str*s [flags] ;;flags: must be 0

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.

OnScreenRect action RECT*r ;;action: 1 begin, 0 move, 2 end, 3 temporarily hide

QM 2.2.0.

Draws on-screen rectangle.

r - address of a RECT variable that contains rectangle coordinates.

Not available in exe.

EditReplaceSel hDlg cid $s [flags] ;;flags: 1 replace all, 2 set focus

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, does not disable Undo. 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 - input string.
sOut - output string.
itemId: 0 macro/function, -1 menu/toolbar, -2 TS menu. 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 $startfrom [flags] ;;flags: must be 0

Compiles multiple macros and functions. Purpose - quickly check for errors multiple macros and functions. startfrom can be either item name or id (<0x10000). If startfrom is 0, compiles all. If startfrom is folder, compiles all in that folder. If startfrom is not folder, compiles all starting from startfrom. Should be called soon after QM startup. Does not compile menus and toolbars.

Not available in exe.

$OutWinMsg message wParam lParam [str*sout]

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 - if used and not 0, receives the string. Else the function displays the string in QM output.

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] [*itemId] [flags] ;;flags: 1 include indirect callers

QM 2.3.1.

Gets current 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 - receives the statement. Can be 0 if not needed (faster).

itemId - receives QM item id. Can be 0 if not needed.

flags:

1	include indirect callers. Direct caller is macro or function that 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 you changed code after compiling it.

The caller's statement not necessary begins with current function's name. For example, it may be "var=CurFunc(1)" or "ret CurFunc(1)" or "AnotherFunc CurFunc(1) 2".

Not available in exe.

q_printf $format ...

QM 2.3.2.

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

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

#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 other or reopen current macro list 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.

Not available in exe.

Controls

Grid.

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.

0	not Vista, or failed.
1	Low.
2	Medium.
3	Administrator or uiAccess.
4	System.