From c46f9e8a4c5ee6f331a8b89481063d73759bdbef Mon Sep 17 00:00:00 2001 From: jrand Date: Fri, 26 Jul 2002 03:06:04 +0000 Subject: [PATCH] Adding BMessageFilter docs to CVS git-svn-id: file:///srv/svn/repos/haiku/trunk/current@449 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- .../app/usecases/BMessageFilterUseCases.html | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/develop/app/usecases/BMessageFilterUseCases.html diff --git a/docs/develop/app/usecases/BMessageFilterUseCases.html b/docs/develop/app/usecases/BMessageFilterUseCases.html new file mode 100644 index 0000000000..41ecfc9a2a --- /dev/null +++ b/docs/develop/app/usecases/BMessageFilterUseCases.html @@ -0,0 +1,123 @@ + + + +BMessageFilter Use Cases and Implementation Details + + + + + + +

BMessageFilter Use Cases and Implementation Details:

+ +

This document describes the BMessageFilter interface and some basics of how it is implemented. +The document has the following sections:

+ +
    +
  1. BMessageFilter Interface
    2. +
  2. BMessageFilter Use Cases
    3. +
  3. BMessageFilter Implementation
    4. +
+ +

BMessageFilter Interface:

+ +

The BMessageFilter class is a simple class for processing incoming BMessage's before +they are dispatched to a BLooper. The best source of information for the BMessageFilter interface +can be found +here in the Be Book. +

+ +

BMessageFilter Use Cases:

+ +

The following use cases cover the BMessageFilter functionality:

+ +
    + +

  1. Construction 1: A BMessageFilter can be created by specifying a message_delivery +option, a message_source option, a command code and an optional filter function. These +options are used to determine the messages on which the filter will act and the filter itself +(see the "Filter" use cases).

    2. + +

  2. Construction 2: A BMessageFilter can be created by specifying a message_delivery +option, a message_source option and an optional filter function. These options are used to +determine the messages on which the filter will act and the filter itself (see the "Filter" use +cases).

    3. + +

  3. Construction 3: A BMessageFilter can be created by specifying a command code +and an optional filter function. These options are used to determine the messages on which the +filter will act and the filter itself (see the "Filter" use cases).

    4. + +

  4. Construction 4: A BMessageFilter can be constructed by use of a copy constructor +which can take a reference to or a pointer to another BMessageFilter. The new BMessageFilter +will have all the options of the source BMessageFilter when that source filter was constructed. +Any other state of the source BMessageFilter that it has accumulated after construction is not +copied to the new filter.

    5. + +

  5. Assignment: A BMessageFilter can be assigned the attributes of a source +BMessageFilter by the use of the assignment operator. The target BMessageFilter will have all +the options of the source BMessageFilter when that source filter was constructed. Any other +state of the source BMessageFilter that it has accumulated after construction is not copied +to the new filter.

    6. + +

  6. Destruction: When a BMessageFilter is deconstructed, the BMessageFilter releases +any shared resources it may have allocated.

    7. + +

  7. Command: When Command() is used on a BMessageFilter, the command code specified +at construction time for this filter is returned. If a BMessageFilter was not constructed +with a specific command code, this member function does not return a valid result.

    8. + +

  8. FiltersAnyCommand: When FiltersAnyCommand() is called on a BMessageFilter, it +returns true if a command code was not specified at construction time for this filter. It +returns false if a command code was specified at construction time. The Command() member +function (see above use case) is only valid when FiltersAnyCommand() returns false.

    9. + +

  9. Looper: The Looper() member function returns a pointer to the BLooper (or BHandler) +to which this filter has been added. If the filter has not been added to a BLooper, NULL is +returned. The member functions BLooper::AddCommonFilter() or BHandler::AddFilter() can be +used to add the filter to a looper (see use cases for BLooper and BHandler for details about +adding a filter).

    10. + +

  10. MessageDelivery: The MessageDelivery() member function returns the message delivery +value that was specified at construction time for this filter. The possible values are +B_DROPPED_DELIVERY, B_PROGRAMMED_DELIVERY and B_ANY_DELIVERY. If no message delivery value +was specified at construction time, B_ANY_DELIVERY is returned.

    11. + +

  11. MessageSource: The MessageSource() member function returns the message source +value that was specified at construction time for this filter. The possible values are +B_LOCAL_SOURCE, B_REMOTE_SOURCE and B_ANY_SOURCE. If no message source value +was specified at construction time, B_ANY_SOURCE is returned.

    12. + +

  12. Filter 1: The filter can be applied for a message by passing the message and the +target BHandler which has received that message to the Filter() member function. This member +function returns B_DISPATCH_MESSAGE or B_SKIP_MESSAGE to the caller. The actual impact +of these filter results is dependent on the BLooper and BHandler behaviour (see the use cases for +these classes for more details).

    13. + + +

  13. Filter 2: If a filter function was not supplied on construction of the +BMessageFilter, then the Filter() member function determines the result of the filter. If the +Filter() member has been overridden in a derived class, the result depends on the behaviour of +this derived class. If the class has not been overridden and no filter function was provided +on construction, the B_DISPATCH_MESSAGE is returned. If a filter function was provided on +construction, then the filter function will be called and the Filter() member will return what +this filter function returns.

    14. + +
+ +

BMessageFilter Implementation:

+ +

The implementation of the BMessageFilter is pretty simple. It is mainly a container for +properties of the filter itself and a few simple methods for getting and setting these +properties.

+ +

The actual act of dispatching or skipping the message as dictated by the filter is implemented +in BLooper or BHandler. The BMessageFilter just provides a mechanism for these classes to +determine which to do. Also the BLooper or BHandler decide whether to pass the message through +the filter on their own. The filter does not look at every message to see whether the source +and delivery of this message is such that it should pass through the filter. Instead, BLooper or +BHandler look at the filter, check the source and delivery options of the filter against the +message itself and call the filter if appropriate. So, the filter is really just a container for +these options and doesn't take action based on them.

+ + +