int qmitem([name|iid] [flags] [pi] [mask])
name - QM item name. Full, case insensitive. Default: "" (item that is currently open in editor).
iid - QM item id. Integer.
flags - search filter. Combination of values listed below. Default: 0.
| 1 | Skip folders. |
| 2 | Skip shared items. |
| 4 | Skip encrypted items. |
| 8 | Skip disabled items. |
| 16 | Skip items with no trigger. |
| 32 | Skip member functions. |
| 64 | QM 2.3.0. Skip file links. |
pi - variable of type QMITEM (see Remarks). Function fills it with information about found item.
mask - defines which members of QMITEM structure must be retrieved. It can be combination of values listed below. Other members are always retrieved. Default: 0.
| 1 | Name. |
| 2 | Trigger (without programs). |
| 4 | Programs. Begins with / (only) or \ (not). |
| 8 | Text. |
| 16 | Parent folder id. |
| 32 | Filter function. |
| 64 | Trigger description (short). |
| 128 | Date modified. |
| 256 | QM 2.3.0. File link target (file path). |
Each QM item, including folders, has integer identifier (id). Item id can be used with QM-items related functions and commands (mac, dis, str.getmacro, qmitem and other). Item id may change when reloading or auto-reloading file. QM item identifiers are positive nonzero integers.
This function can be used for 3 purposes:
1. Get item id when you know its name. If such item does not exist, qmitem returns 0. If name begins with \, it is interpreted as QM item path. For example, to find macro "Next" that is in "Mouse" folder, you can use "\Mouse\Next". Second argument (flags) can be used to filter results (e.g., skip folders).
2. Enumerate QM items. If first argument is numeric (iid), and it is 0 or negative, qmitem returns next matching item. It starts to search from item that has id one more than absolute value of iid. For example, if iid is -2, qmitem returns item that has id 3 or more (it can skip items that match flags). If you want to enumerate all items, at first call qmitem with iid=0. Then repeatedly call it and use negative form of iid that was returned in previous call. Stop enumeration when qmitem returns 0.
3. Get item properties. Third argument (pi) must be variable of type QMITEM. Function always fills first 9 members of that variable. To fill other members, use fourth argument (mask). First argument can be either name, or iid (or <=0 when enumerating).
QMITEM definition:
type QMITEM !itype !ttype !tkey !tmod !tkey2 []!tmon []!tht flags htvi ~name ~trigger ~triggerdescr ~programs ~filter ~text ~linktarget folderid DATE'datemod
| itype | item type: 0 macro, 1 function, 2 pop-up menu, 3 toolbar, 4 T.S. menu, 5 folder, 6 member function, 7 link to a file. |
| ttype | trigger type: 0 none, 1 keyboard, 2 mouse, 3 window, 4 user-defined, 5 QM events, 6 file, 7 event log, 8 process, 9 accessible object. |
| tkey | trigger key. For keyboard triggers it is virtual-key code. For mouse triggers: 1 wheel forward, 2 wheel backward, 4 X1 button, 5 X2 button, 6 left button, 7 right button, 8 middle button, 9-20 screen edges, 21-32 other movements. For other triggers - undocumented. |
| tmod | modifier-keys (keyboard and mouse triggers). Combination of the following values: 1 Shift, 2 Ctrl, 4 Alt, 8 Win. |
| tkey2 | next key (keyboard triggers). |
| tmon | monitor (mouse movement triggers). 0 primary, 31 all. |
| tht | hit test value (mouse click and wheel triggers). 0 any. |
| flags | item properties. Combination of the following values: 2 shared, 4 encrypted, 8 disabled, 16 is in read-only folder. |
| name | item name. |
| trigger | encoded trigger string (without programs and filter function). |
| triggerdescr | trigger description (e.g., Ctrl+E instead of Ce). |
| programs | trigger scope (programs). Starts with / (Only) or \ (Not). |
| filter | filter function |
| text | item text. |
| linktarget | QM 2.3.0. If the item is file link, contains file path. |
| folderid | parent folder id. |
| htvi | handle of item in TreeView control. |
| datemod | date modified. Precision: 1 s. Time zone: local. This member is 0 for items modified before QM 2.1.5. Modification date is updated when applying changes in text. |
For programmers familiar with TreeView controls: You can use TVM_GETNEXTITEM message to recursively get all hierarchy of QM folders and items. Use TVM_GETITEM message to get QM item id, which is lParam of TVITEM structure.
See also: str.getmacro, EnumQmFolder
Find item "LED": int i=qmitem("LED" 1) if(i) out i; else out "item not found" Find item "LED" and display properties: QMITEM q int i=qmitem("LED" 1 &q 31) if(i) out "i=%i itype=%i ttype=%i tkey=%i tshift=%i flags=%i name=%s trigger=%s programs=%s folder=%s text=[]%s" i q.itype q.ttype q.tkey q.tmod q.flags q.name q.trigger q.programs iif(q.folderid _s.getmacro(q.folderid 1) "") q.text List all items that have triggers: QMITEM q; int i rep i=qmitem(-i 1|16 &q 1|2|4) if(i=0) break out "%-30s %-30s %s" q.name q.trigger q.programs