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