The Filter Manager provides facilities for you to register filters to be used when a specified task calls Wimp_Poll, or when Wimp_Poll is about to return to that task. These are known - respectively - as pre-filters and post-filters:
Filters need not be applied to a specific task; you can also apply filters to all tasks.
Each filter is a routine that has well-defined entry and exit conditions; it is your responsibility to write the routine.
| R1 | = | &87 (reason code) |
| R1 | preserved | |
This service call is issued when the Filter Manager starts up. You may then register new filters using Filter_RegisterPreFilter and Filter_RegisterPostFilter.
| R1 | = | &88 (reason code) |
| R1 | preserved | |
This service call is issued as a broadcast to inform filters that they have been deregistered and that the Filter Manager is about to die.
| R0 | = | pointer to filter name (null terminated) |
| R1 | = | pointer to filter routine (Filter_PreFilter) |
| R2 | = | value to be passed in R12 when filter is called |
| R3 | = | task handle to which to apply filter (or 0 for all tasks) |
| R0 | preserved | |
| R1 | preserved | |
| R2 | preserved | |
| R3 | preserved | |
This call registers a pre-filter routine (pointed to by R1), which will be called whenever the specified task calls Wimp_Poll.
| R0 | = | pointer to filter name (null terminated) |
| R1 | = | pointer to filter routine (Filter_PostFilter) |
| R2 | = | value to be passed in R12 when filter is called |
| R3 | = | task handle to which to apply filter (or 0 for all tasks) |
| R4 | = | event mask (1 bit masks the event out as for Wimp_Poll) |
| R0 | preserved | |
| R1 | preserved | |
| R2 | preserved | |
| R3 | preserved | |
| R4 | preserved | |
This call registers a post-filter routine (pointed to by R1), which will be called whenever the Wimp is about to return from Wimp_Poll to the specified task.
| R0 | = | pointer to filter name (null terminated) |
| R1 | = | pointer to filter routine (Filter_PreFilter) |
| R2 | = | value to be passed in R12 when filter is called |
| R3 | = | task handle to which to apply filter (or 0 for all tasks) |
| R0 | preserved | |
| R1 | preserved | |
| R2 | preserved | |
| R3 | preserved | |
| R4 | preserved | |
This call removes a pre-filter from the list of pre-filters. All values on entry must be the same as those used to originally register the filter (ie those that were passed to Filter_RegisterPreFilter).
| R0 | = | pointer to filter name (null terminated) |
| R1 | = | pointer to filter routine (Filter_PostFilter) |
| R2 | = | value to be passed in R12 when filter is called |
| R3 | = | task handle to which to apply filter (or 0 for all tasks) |
| R4 | = | event mask (1 bit masks the event out as for Wimp_Poll) |
| R0 | preserved | |
| R1 | preserved | |
| R2 | preserved | |
| R3 | preserved | |
| R4 | preserved | |
This call removes a post-filter from the list of post-filters. All values on entry must be the same as those used to originally register the filter (ie those that were passed to Filter_RegisterPostFilter).
| R0 | = | event mask, as passed to Wimp_Poll |
| R1 | = | pointer to event block, as passed to Wimp_Poll |
| R2 | = | task handle of task that called Wimp_Poll |
| R12 | = | value of R2 on entry to Filter_RegisterPreFilter |
| R0 | = | may have bits cleared to provide a new event mask. |
| R1-12 | preserved | |
This entry point is called by FilterManager when Wimp_Poll is called by a task. It allows the the call to be modified to support the behaviour of other filters.
Task is paged in, so the filter can access its memory. The routine should exit using the instruction:
MOVS pc, r14
| R0 | = | event reason code, as returned from Wimp_Poll |
| R1 | = | pointer to event block, as returned from Wimp_Poll |
| R2 | = | task handle of task that is being returned to |
| R12 | = | value of R2 on entry to Filter_RegisterPostFilter |
| R0 | = | may be modified to a new reason code, or may be set to -1 to claim the event, and prevent it from being passed to the task. |
| R1 | = | must be preserved, but the contents of the buffer may be modified. |
| R2-12 | preserved | |
This entry point is called by FilterManager when Wimp_Poll is about to return to a task. It allows the the message being returned to be processed to augment the behaviour of the task.
Task is paged in, so the filter can access its memory. The routine should exit using the instruction:
MOVS pc, r14
Note: Under RISC OS 3, if a filter routine sets R0 to -1 to claim an event and prevent it being passed to its task, then that event is not passed on to any further post filters. From RISC OS 3.5 onwards, claiming an event does not prevent other post filters from being called, but does still prevent the event being passed to the task.
*Filters
*Filters lists all currently active pre- and post-Wimp_Poll filters.
*Filters
Filters called on entry to Wimp_Poll:
Filter Task
------ ----
Llama All tasks
Filters called on exit from Wimp_Poll:
Filter Task Mask
------ ---- ----
Llama All tasks 00000000
| Maintainer(s): | RISCOS Ltd <developer@riscos.com> | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| History: |
| ||||||||
| Disclaimer: |
Copyright © Pace Micro Technolgy plc, 2002. |