187 | | |
188 | | == Translating MFC Messages into Events == |
189 | | |
190 | | The messages are aggregated into events using a set of rules defined in XML. The order of the rules in the XML file defines their priority. |
191 | | |
192 | | === Single Messages and Sequences === |
193 | | |
194 | | There is a distinction between single messages and whole sequences of messages of the same type. The former may be used for, e.g., {{{WM_LBUTTONDOWN}}} and {{{WM_LBUTTONUP}}}: |
195 | | {{{ |
196 | | <msg type="&WM_LBUTTONDOWN;"/> |
197 | | <msg type="&WM_LBUTTONUP;"/> |
198 | | }}} |
199 | | |
200 | | Sequences of the same message occur, e.g., when scrolling: |
201 | | {{{ |
202 | | <msg type="&WM_LBUTTONDOWN;"/> |
203 | | <msg type="&WM_HSCROLL;" multiple=true/> |
204 | | <msg type="&WM_LBUTTONUP;"/> |
205 | | }}} |
206 | | |
207 | | The distinction is using the {{{multiple}}} attribute of the {{{msg}}} node, |
208 | | which is per default false. If it is true, it means ``at least one'', similar to |
209 | | ``+'' in regular expressions. |
210 | | |
211 | | === Storage of messages === |
212 | | |
213 | | Each message or message sequence can be stored for later use, e.g., comparisons |
214 | | with other messages or generating replays. This is done using the {{{store}}} |
215 | | and {{{storeSeq}}} nodes: |
216 | | {{{ |
217 | | <msg type="&WM_LBUTTONDOWN;"> |
218 | | <store var="clicked"/> |
219 | | </msg> |
220 | | <msg type=&WM_HSCROLL;" multiple=true> |
221 | | <storeSeq varSeq="scrolls/> |
222 | | </msg> |
223 | | }}} |
224 | | |
225 | | When storing a message, the {{{window.hwnd}}} is automatically resolved and its |
226 | | target string is stored as an attribute of the message ({{{winParamType}}}). If |
227 | | other parameters contain HWNDs that need to be later on to address a target, |
228 | | they can be resolved manually and stored as a further parameter: |
229 | | {{{ |
230 | | <msg type=&WM_HSCROLL;" multiple=true> |
231 | | <storeSeq varSeq="scrolls> |
232 | | <resolveHwnd param="scrollBarHandle" storeParam="scrollBarTarget"/> |
233 | | </storeSeq> |
234 | | </msg> |
235 | | }}} |
236 | | |
237 | | === Checking equalities === |
238 | | |
239 | | Only matching messages by their type is insufficient. Comparisons between their |
240 | | parameters are also required. This can be done using {{{equals}}} nodes: |
241 | | {{{ |
242 | | <msg type="&WM_LBUTTONDOWN;"> |
243 | | <store var="clicked"/> |
244 | | </msg> |
245 | | <msg type="&WM_LBUTTONUP;"> |
246 | | <equals> |
247 | | <paramValue obj="this" param="window.hwnd"/> |
248 | | <paramvalue obj="clicked" param="window.hwnd/> |
249 | | </equals> |
250 | | </msg> |
251 | | }}} |
252 | | In the example above, the {{{equals}}} node compares whether the value of the |
253 | | parameter ``window.hwnd'' is equal for the stored variable ``clicked'' and the |
254 | | current message itself, i.e., ``this''. |
255 | | |
256 | | In general, each {{{equals}}} node has the same structure: |
257 | | {{{ |
258 | | <equals> |
259 | | termNode1 |
260 | | termNode2 |
261 | | </equals> |
262 | | }}} |
263 | | There are four types of term nodes: |
264 | | 1. {{{paramValue}}}: of the messages (example above) |
265 | | 1. {{{constValue}}}: constant value, e.g., {{{<constValue value="Button"/>}}} |
266 | | 1. {{{winInfoValue}}}: information about the target of the message. |
267 | | - {{{<winInfoValue obj="this" winParam="class"/>}}} for the class of the target |
268 | | - {{{<winInfoValue obj="this" winParam="hwnd"/>}}} for the HWND |
269 | | - {{{<winInfoValue obj="this" winParam="resourceId"/>}}} for the resource Id. |
270 | | - {{{<winInfoValue obj="this" winParam="parentTarget"/>}}} for the target of the GUI objects parent |
271 | | 1. {{{msgInfoValue}}}: information about the type and target of the message. |
272 | | - {{{<msgInfoValue obj="this" msgParam="type"/>}}} for the type of the message (its integer) |
273 | | - {{{<msgInfoValue obj="this" msgParam="target"/>}}} for the target of the message (its string representation) |
274 | | |
275 | | The comparison of sequence variables is not yet implemented! |
276 | | |
277 | | === Generation of replay sequences === |
278 | | If a message sequence has been successfully matched to a rule, a replay sequence |
279 | | is generated. This is done using {{{genMsg}}} and {{{genMsgSeq}}} nodes. |
280 | | |
281 | | The first way to generate a replay message is to directly replay a message that |
282 | | has been stored during the matching phase: |
283 | | {{{ |
284 | | <genMsg delay="100"> |
285 | | <storedVar obj=clicked"/> |
286 | | </genMsg> |
287 | | }}} |
288 | | The delay attribute signifies that the replaying tool pauses for 100 ms after |
289 | | sending the message stored in the variable ``clicked''. |
290 | | |
291 | | The second way is to ``construct'' it: |
292 | | {{{ |
293 | | <genMsg delay="100"> |
294 | | <type> |
295 | | <msgInfoValue obj="cmd" msgParam="type"/> |
296 | | </type> |
297 | | <target> |
298 | | <msgInfoValue obj="cmd" msgParam="target"/> |
299 | | </target> |
300 | | <LPARAM> |
301 | | <paramValue obj="cmd" param="sourceDesc"/> |
302 | | </LPARAM> |
303 | | <WPARAM> |
304 | | <paramValue obj="cmd" param="WPARAM"/> |
305 | | </WPARAM> |
306 | | </genMsg> |
307 | | }}} |
308 | | The type needs to be an integer. The target needs to be a target string. |
309 | | The LPARAM and WPARAM are both optional, their default values are 0. They can be |
310 | | either numerical or target strings. Furthermore, it is possible to define the |
311 | | HI and LO word of them separatly: |
312 | | {{{ |
313 | | <LPARAM> |
314 | | <LOWORD> |
315 | | value |
316 | | </LOWORD> |
317 | | <HIWORD> |
318 | | value |
319 | | </HIWORD> |
320 | | </LPARAM> |
321 | | }}} |
322 | | |
323 | | The value types are the same that can be used as terms for {{{equals}}} nodes. |
324 | | |
325 | | To generate message sequences, the {{{genMsgSeq}}} node is used: |
326 | | {{{ |
327 | | <genMsgSeq delay="20"> |
328 | | <type> |
329 | | <constValue value="&TBM_SETPOS;"/> |
330 | | </type> |
331 | | <target> |
332 | | <seqValue seqObj="scrolls" param="scrollBarTarget"/> |
333 | | </target> |
334 | | <LPARAM> |
335 | | <constValue value="1"/> |
336 | | </LPARAM> |
337 | | <WPARAM> |
338 | | <seqValue seqObj="scrolls" param="scrollPos"/> |
339 | | </WPARAM> |
340 | | </genMsgSeq> |
341 | | }}} |
342 | | The three value types used for equals are allowed. However, either the |
343 | | type or the target must be of a {{{seqValue}}}, otherwise the |
344 | | creation will fail. In case more than one {{{seqValue}}} variable is used, |
345 | | e.g., a different one for the LPARAM than for the target, both sequences must |
346 | | have the same length. |
347 | | |