ref

refname - some name that will be used to identify the reference file.

file - file or QM item (macro etc) that contains declarations.

1	Load on demand. Will be loaded only when actually needed.
2	Global scope. Identifiers from this file can be used anywhere without specifying refname.
4	Low priority. QM searches for declarations in low-priority refs after it does it in other refs.
8	Always show members in the main popup list. Also, members are always declared automatically when they are first time used or viewed in editor. This flag is used together with flag 2. Flag 1 would not have effect.

Remarks

Syntax1

Declare file or macro where QM will look for declarations. Can be anywhere, not necessary in the same macro where used.

Syntax2

Makes identifiers from a somewhere declared reference file or macro available in current macro without specifying refname. Also, if the file is still not loaded, loads.

Reference files/macros can contain declarations of types (type, class, category), constants (def), dll functions (dll), COM interfaces (interface) and type libraries (typelib). The declarations are in QM format. Each declaration starts from the beginning of a line.

The purpose is the same as of type libraries (typelib) or #compile: declare various identifiers (constants, dll functions, types, etc) so that you don't have to do it when you want to use them. Unlike type libraries, reference files can be used only in QM. Unlike #compile, ref does not compile whole file/macro. For example, if you compile a macro that contains declarations of dll functions, dll files are immediately loaded into memory. With ref, dll is loaded only when (if) it is needed.

QM 2.2.0. A reference file/macro (lets call it file1) also can contain references to other reference files/macros (file2). In file2 QM will look for declarations of identifiers that are used in declarations in file1 but not declared in file1. To add such a reference, add ref refname line in file1. Also declare file2 somewhere in macros, using syntax1, before or after of file1 declaration.

A declaration in a reference file/macro can be followed by comments in the next line. Comments will be displayed in QM status bar. The line must begin with single space and two semicolons. Declarations should not have comments in the same line.

Accessing identifiers declared in a reference file

If a reference file is declared with global scope (flag 2), identifiers from it can be used anywhere, without any special syntax. Otherwise use syntax refname.identifier, unless the reference file is declared in the same macro/function. Also, when using refname.identifier syntax, identifier is automatically declared and colored when typing or opening macro.

Existing reference files

Quick Macros comes with several reference files containing Windows API and other declarations:

WINAPI - mostly used Windows XP API declarations. It is declared with flag 2 (global scope) and therefore you can use Windows API simply, without prepending WINAPI.. That is why you can use Windows API without declaring them. That is why when you type or click an identifier (type, function, etc), its declaration is displayed in QM status bar.

The file has been updated in QM 2.3.0. To create it was used Vista SDK v6.0 headers/libraries and preproccessor definitions for Windows 2003 and Internet Explorer 6 (WINVER 0x0502, _WIN32_IE 0x0603). The old file (QM 2.2.0-2.2.1) was created from older header files and therefore there are some changes. If you upgraded QM from an older version, you can still find the old file in QM folder. The old file is named winapiqm.txt. The new file is winapi.txt.

WINAPIV - declarations specific to Windows Vista. To avoid conflicts, it is declared not as global, and therefore functions and other identifiers can be accessed only like WINAPIV.Function. The file has been added in QM 2.3.0. To create it was used Vista SDK v6.0 headers/libraries and preproccessor definitions for Windows Vista and Internet Explorer 7 (WINVER 0x0600, _WIN32_IE 0x0700).

WINAPI7 - declarations specific to Windows 7. To avoid conflicts, it is declared not as global, and therefore functions and other identifiers can be accessed only like WINAPIV.Function. The file has been added in QM 2.3.1. To create it was used Windows 7 SDK v7.0 headers/libraries and preproccessor definitions for Windows 7 and Internet Explorer 8 (WINVER 0x0601, _WIN32_IE 0x0800).

#define NOCRYPT //don't add cryptography, 218 KB
#include "crt.h" //most header files for msvcrt.dll
#include <windows.h>
#include <winternl.h>
#include <winioctl.h> //QM 2.3.0
#include <shlobj.h> //#includes <commctrl.h>
#include <shlwapi.h>
#include <richedit.h>
#include <olectl.h>
#include <oleacc.h>
#include <htmlhelp.h>
#include <pdh.h>
#include <tlhelp32.h>
#include <winsock2.h>
#include <wtsapi32.h> //QM 2.2.0.3
#include <mstask.h>
#include <msterr.h>
#include <dbt.h>
#include <psapi.h>
#include <uxtheme.h>
#include <wininet.h> //QM 2.3.0

Using with distributed macros

If you create macros for distributing, in them you should not use identifiers from reference files, unless you are sure that others have the same reference files. For example, WINAPI has been updated in QM 2.2.0 and in QM 2.3.0. If you use identifiers from it in your macros, other people that use other QM versions may get "unknown identifier" errors. You should rather extract these declarations from the reference file and place them in the macros. All this is not actual if the macros are compiled to exe.

Extracting and logging declarations

To extract a single declaration from a reference file or macro, type or click the identifier (e.g. function name) in the editor and do one of the following: 1. Ctrl+click the identifier and copy declaration from output. 2. Copy declaration from status bar, or press Alt+F8 to transfer it from status bar to output. 3. Press F2 and copy declaration from file. Also, to extract multiple declarations (except from macros), you can use menu Run -> Compile Options-> Show declarations from ref files. Then used declarations that are found in reference files are displayed in the output. A declaration is displayed when the identifier is first time used in a macro that you run or compile, or first time displayed in code when you use syntax refname.identifier.

Errors in declarations

Sometimes may happen that some declaration in reference file fails, for example, due to a missing dll or type library. In such case, file is opened, and statement highlighted. If you want that on error would be executed some user-defined function, place #err function in reference file, immediately after declaration. If function returns nonzero value, error is not shown, and compilation stops. If returns negative value, "unknown identifier" error also is not shown.

Declare reference file or macro

Syntax1 - declare a reference file

Syntax2 - use previously declared file

Parameters