Resources (macro resources)
In macros you sometimes use images or other binary (non-text) data. There are several ways to store such data:
- External files. For example, .ico files for icons.
- Convert to text (hex or base64) and store in macro.
- Macro resources. Added in QM 2.4.1, partially in QM 2.4.0.
Each macro (or other QM item) can have any number of resources. They are stored in the same QM file. They are deleted when you delete the macro; copied when you clone or export the macro. You can think about macro resources like about email message attachments.
Resources have names. Case-sensitive. Some names are recognized by QM as images:
- Names that begin with "image:" are LZO-compressed bitmap (.bmp file) images.
- Names that end with ".bmp", ".png", ".jpg", ".gif", ".ico", ".cur" and ".ani" are images, icons and cursors. The data format is the same as in files.
In macros use resource name with "resource:" prefix. Example: "resource:email.ico".
- The prefix is optional if name begins with "image:". Example: "image:button1".
- If the resource is in another macro, use prefix "resource:<macro name>". Examples: "resource:<macro1>image:button1", "resource:<icons>email.ico". In some cases need this even if in same macro. For macro name also can be used GUID.
- If macro name not specified, in most cases QM also can find the resource in a caller function in the function call stack.
- Resources that are not attached to a macro are called file resources. To manage file resources, select <file> in the Resources dialog. In macros use prefix "resource:<>". Example: "resource:<>email.ico". Don't use file resources in shared files, because QM looks for the resource only in the current main file.
Functions that support resources:
- scan - "image:", ".bmp", ".png" and ".ico" resources.
- GetFileIcon - ".ico", ".cur", ".ani".
- LoadPictureFile - "image:", ".bmp", ".png", ".jpg", ".gif".
- __ImageListLoad - "image:", ".bmp".
- ShowDialog (images, background, icon) - all image resources.
- str.getfile - all resources. Also IXml.FromFile, ICsv.FromFile, RichEditLoad and some other.
- bee - ".wav".
- Functions that use the above functions. For example AddTrayIcon, __ImageList.Load.
- #exe addfile.
- Icons in menus and toolbars - ".ico".
- QM item icon, exe icon - ".ico".
In the code editor QM displays images below lines with image resource name and file path strings. Even if the strings are in comments, if enclosed in ". To show/hide images, use toolbar button 'Images in code editor'. You also can display images in output and function help.
In Options you can set to record screenshots when recording mouse clicks or using the Mouse dialog. QM saves the recorded images in macro resources with names that begin with "~:", and inserts the names in macro text as comments. Auto-deletes unused screenshot resources, for example when you delete macro text containing "~:..." and then close the macro.
When creating exe, QM looks for strings that begin with "resource:" or "image:" and adds the macro resources to exe resources (it's a different thing, although similar). Then in exe QM functions get data from these exe resources. Supports multiline strings. Use #exe addfile if QM does not auto-add a resource, eg if if its full name string is not used in macro.
Exe resource type and name (or id) of auto-added macro resources depends on macro resource name. If it contains colon, eg "A:B", in exe A will be resource type, and B name. Else exe resource name will be the same as macro resource name, and type depends on macro resource name: if it ends with ".bmp", ".ico", ".cur" or ".ani", type will be RT_BITMAP, RT_GROUP_ICON, RT_GROUP_CURSOR or RT_ANICURSOR, else RT_RCDATA. If type or name string begins with an integer number 1-65535, in exe resources it will be numeric (id), else string. For example, if macro resource name is "10 info.ico", in exe it will be RT_GROUP_ICON resource with id 10. Note that if exe has icon resources with string names, Windows Explorer displays wrong icon; to avoid it, all icon resources added to exe should have numeric names.
Sub-functions cannot have resources, but can use resources of parent QM item.
To manage macro resources, you can use:
The 'Resources' dialog
You can find the dialog in the Tools menu or toolbar.
At the left are listed all QM items (macros etc) that have resources. At the right are displayed resources of the selected item.
Special items at the left:
- <this> - the macro that is currently open in the code editor. When you open another macro, the dialog is updated to show its resources. If the macro does not have resources, there will be only an Add link.
- <all> - resources of all macros in single view.
- <duplicate> - resources that have identical data but are in different macros or have different names.
- <unused> - resources whose names are not found in text (or as icon) of any macro.
- <size> - resources of all macros sorted by size.
- <file> - resources that are not attached to any QM item (file resources).
At the right side you can manage resources of the selected item:
- Click the Add link to add a resource from a file or another macro. Or drag and drop files from Windows Explorer.
- Click a resource name link to delete, rename, export, etc.
- When exporting an "image:..." resource, QM uncompresses it and saves as .bmp file. When importing a .bmp file, if the 'Compress' checkbox is checked, imports as "image:..." resource. Other files/resources are imported/exported unchanged.
- When importing a .ico file, the suggested resource name begins with a number to be used for exe resource id.
- To move or copy one or more resources from macro A to macro B:
- Open resources of macro A (or <all> etc). Optionally select text with the resource names (links).
- Drag the line or selected text with the right mouse button, and drop to macro B in the list. To copy, use Ctrl.
- Or copy selected text to the clipboard, open resources of macro B, click the Add link.
- Or click a resource name and select 'Move...', then click Add in B resources.
- If need several selections, at first make one as usually, then make more selections with Ctrl.
- To open a macro from the dialog, click its name (link) in the right. Or double click at the left, or Enter.
- If you want to see only resources of some types or containing certain string in name, use the Filter field. Will be displayed only resources with names matching the filter. Use wildcard characters as with SQLite GLOB. Supports operator NOT at the beginning.
- To find a resource by name in all resources, select <all> and enter resource name in the Filter field. Use wildcard characters to find partial, eg *partOfName*. Must match case.