docs/user/app/MessageFilter.dox

   1 /*
   2  * Copyright 2007-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   7  *              John Scipione, jscipione@gmail.com
   8  *
   9  * Corresponds to:
  10  *              headers/os/app/MessageFilter.h  hrev47355
  11  *              src/kits/app/MessageFilter.cpp  hrev47355
  12  */
  13
  14
  15 /*!
  16         \file MessageFilter.h
  17         \ingroup app
  18         \ingroup libbe
  19         \brief Provides BMessageFilter class.
  20 */
  21
  22
  23 /*!
  24         \enum filter_result
  25         \brief Return Codes and Protocol of the #filter_hook.
  26
  27         These return codes should be used in your own filter_hook function, or by
  28         your overridden BMessageFilter::Filter() method.
  29
  30         \since BeOS R3
  31 */
  32
  33
  34 /*!
  35         \var B_SKIP_MESSAGE
  36         \brief The message does not pass the filter criteria and should not be
  37                handled.
  38
  39         \since BeOS R3
  40 */
  41
  42
  43 /*!
  44         \var B_DISPATCH_MESSAGE
  45         \brief The message passes the filter criteria and should be dispatched to
  46                a BHandler.
  47
  48         \since BeOS R3
  49 */
  50
  51
  52 /*!
  53         \typedef filter_result (*filter_hook) (BMessage* message,
  54                  BHandler** target, BMessageFilter* filter)
  55         \brief Prototype for a custom \c filter_hook for use in the BMessageFilter
  56                class.
  57
  58         This hook can be used when you are constructing a new BMessageFilter
  59         object. It is a custom filter function you can use.
  60
  61         This hook should handle the following parameters:
  62
  63         \param[in] message The message that needs to be verified.
  64         \param[out] target If your filter hook is conscious about the available
  65                     handlers, you can set a specific BHandler based on your filters
  66                     requirements. You do not have to change this field, because
  67                     there will always be a working default.
  68         \param[in] filter A pointer to the filter from which this hook is called.
  69
  70         \return You should return #B_SKIP_MESSAGE in case the message does not
  71                 conform to the filter criteria, or #B_DISPATCH_MESSAGE if the
  72                 message passes these criteria.
  73
  74         \see BMessageFilter(uint32, filter_hook)
  75         \see BMessageFilter(message_delivery, message_source, filter_hook)
  76         \see BMessageFilter(message_delivery, message_source, uint32, filter_hook)
  77
  78         \since BeOS R3
  79 */
  80
  81
  82 /*!
  83         \enum message_delivery
  84         \brief BMessageFilter filter criteria on how a message was delivered.
  85
  86         Two constructors of the BMessageFilter class allow you to specify that it
  87         should filter based on how the message was delivered. There are two ways in
  88         which messages can be delivered within the Haiku API: by direct delivery
  89         using the BLooper::PostMessage() function, and by drag and drop in the GUI.
  90         With this filter you can, for example, specify that your handler only
  91         handles deliveries that were programmed by you, and not any random drag and
  92         drop actions initiated by the user.
  93
  94         \since BeOS R3
  95 */
  96
  97
  98 /*!
  99         \var B_ANY_DELIVERY
 100         \brief Accept both delivery methods.
 101
 102         \since BeOS R3
 103 */
 104
 105
 106 /*!
 107         \var B_DROPPED_DELIVERY
 108         \brief Only accept messages that were dropped by the user in the GUI.
 109
 110         \since BeOS R3
 111 */
 112
 113
 114 /*!
 115         \var B_PROGRAMMED_DELIVERY
 116         \brief Only accept messages that were delivered using the
 117                BLooper::PostMessage() method.
 118
 119         \since BeOS R3
 120 */
 121
 122
 123 /*!
 124         \enum message_source
 125         \brief BMessageFilter filter criteria on the source of a message.
 126
 127         One of the key features of the messaging system of Haiku, is the ability
 128         to send messages between applications. However, your handler or looper
 129         might have been written in such a way that it would make no sense to try
 130         to process messages from an external source. Use these filter criteria to
 131         filter the unwanted messages out.
 132
 133         You use these constants in the constructors of the BMessageFilter class.
 134
 135         \warning System messages, for example from the \c app_server, are
 136                  considered remote messages. Keep this in mind when you want
 137                  to set up criteria for your window and application loopers.
 138
 139         \since BeOS R3
 140 */
 141
 142
 143 /*!
 144         \var B_ANY_SOURCE
 145         \brief Accept both local and remote messages.
 146
 147         \since BeOS R3
 148 */
 149
 150
 151 /*!
 152         \var B_REMOTE_SOURCE
 153         \brief Only accept messages from a remote source, so from other
 154                applications.
 155
 156         \since BeOS R3
 157 */
 158
 159
 160 /*!
 161         \var B_LOCAL_SOURCE
 162         \brief Only accept messages from your own local application.
 163
 164         \since BeOS R3
 165 */
 166
 167
 168 /*!
 169         \class BMessageFilter
 170         \ingroup app
 171         \ingroup libbe
 172         \brief Describes a message filter for BLooper and BHandler.
 173
 174         Objects of this class serve as a description of properties that incoming
 175         messages should have in order to be processed by a handler or a looper.
 176         BMessageFilter provides three default filter criteria, the \c what
 177         constant, the #message_source and the type of message_delivery,
 178         and an extendible #filter_hook.
 179
 180         BMessageFilter's standard filter criteria can be extended in two ways:
 181         -# Specify a #filter_hook. This is a static function that takes a message
 182            and a pointer to a BHandler as arguments, and allows you to accept or
 183            reject the message, and even redirect it to a specific BHandler.
 184         -# Subclass the BMessageFilter class and override the Filter() function.
 185            This has the same capabilities as using a #filter_hook, but it allows
 186            cleaner code (in some cases).
 187         Both methods have their merits, but please remember that you have to choose
 188         which one you want to use, since you can't use both. The order of
 189         processing the criteria is in this order: the source, the delivery method,
 190         the filter hook and then the overrided Filter() method. Additionally, if a
 191         #filter_hook is registered, the Filter() method will not be called.
 192
 193         The BMessageFilter objects are used in two different classes. They can be
 194         associated with specific BHandlers. Using the BHandler::AddFilter()
 195         and the BHandler::SetFilterList() methods, you can add filters to the
 196         filter list. It is also possible to associate filters with BLoopers. In
 197         that case, all incoming messages of that looper are checked against the
 198         criteria. To perform filtering in loopers, have a look at the
 199         BLooper::AddCommonFilter() and the BLooper::SetCommonFilterList() methods.
 200
 201         An example of a filter that selects on the default criteria:
 202 \code
 203 // Our window does not handle drop events.
 204 BMessageFilter *filter = new BMessageFilter(B_PROGRAMMED_DELIVERY, B_ANY_SOURCE);
 205 window->AddCommonFilter(filter);
 206 \endcode
 207
 208         An example of a filter that only allows one type of message:
 209 \code
 210 BMessageFilter *filter = new BMessageFilter(kHappyMessages);
 211 handler->AddFilter(filter);
 212 \endcode
 213
 214         An example of a #filter_hook:
 215 \code
 216 // The handler depends on the what code of a message
 217 filter_result
 218 ScreenMessage(BMessage* message, BHandler** target, BMessageFilter* filter)
 219 {
 220         switch (message->what) {
 221                 case kTcpEvent:
 222                         target = &fTcpHandler;
 223                         return B_DISPATCH_MESSAGE;
 224                 case kUdpEvent:
 225                         target = &fUdpHandler;
 226                         return B_DISPATCH_MESSAGE;
 227         }
 228
 229         return B_SKIP_MESSAGE;
 230 }
 231
 232 BMessageFilter *filter = new BMessageFilter(B_ANY_DELIVERY, B_ANY_SOURCE, ScreenMessage);
 233 looper->AddCommonFilter(filter);
 234 \endcode
 235
 236         The two classes that use BMessageFilter are BLooper and BHandler. In the
 237         general messaging introduction, there is also a section on
 238         \ref app-messaging-receiving "handling messages".
 239
 240         \since BeOS R3
 241 */
 242
 243
 244
 245 /*!
 246         \fn BMessageFilter::BMessageFilter(uint32 inWhat, filter_hook func)
 247         \brief Construct a new object that filters on a message constant.
 248
 249         You can also specify a #filter_hook, if you want apply custom filter
 250         criteria.
 251
 252         \see BMessageFilter(message_delivery, message_source, filter_hook)
 253         \see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)
 254
 255         \since BeOS R3
 256 */
 257
 258
 259 /*!
 260         \fn BMessageFilter::BMessageFilter(message_delivery delivery,
 261                  message_source source, filter_hook func)
 262         \brief Construct a new object that filters on delivery method and message
 263                 source.
 264
 265         You can also specify a #filter_hook, if you want to apply custom filter
 266         criteria.
 267
 268         \see BMessageFilter(uint32 what,filter_hook)
 269         \see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)
 270
 271         \since BeOS R3
 272 */
 273
 274
 275 /*!
 276         \fn BMessageFilter::BMessageFilter(message_delivery delivery,
 277                 message_source source, uint32 inWhat, filter_hook func)
 278         \brief Construct a new object that filters on delivery method, message
 279                 source and specific message constants.
 280
 281         You can also specify a #filter_hook, if you want to apply custom filter
 282         criteria.
 283
 284         \see BMessageFilter(uint32 what,filter_hook)
 285         \see BMessageFilter(message_delivery, message_source, filter_hook)
 286
 287         \since BeOS R3
 288 */
 289
 290
 291 /*!
 292         \fn BMessageFilter::BMessageFilter(const BMessageFilter& filter)
 293         \brief Copy constructor. Copy the criteria from another object.
 294
 295         \since BeOS R3
 296 */
 297
 298
 299 /*!
 300         \fn BMessageFilter::BMessageFilter(const BMessageFilter* filter)
 301         \brief Create a new object based on criteria of another object.
 302
 303         \since BeOS R3
 304 */
 305
 306
 307 /*!
 308         \fn BMessageFilter::~BMessageFilter()
 309         \brief Destructor. Does nothing.
 310
 311         \since BeOS R3
 312 */
 313
 314
 315 /*!
 316         \fn BMessageFilter& BMessageFilter::operator=(const BMessageFilter& from)
 317         \brief Assignment operator. Copies criteria from another filter.
 318
 319         \since BeOS R3
 320 */
 321
 322
 323 /*!
 324         \fn filter_result BMessageFilter::Filter(BMessage* message,
 325                  BHandler** target)
 326         \brief Filter the message according to custom criteria.
 327
 328         The default implementation of this method always returns
 329         \c B_DISPATCH_MESSAGE. You can override this method in subclasses to
 330         suit your own criteria. You receive two arguments.
 331
 332         \param message The message that needs to be filtered.
 333         \param target If you want to, you can specify a handler that should handle
 334                this message. Note that you do have to pass a handler that is
 335                associated with the looper that received the message.
 336
 337         \return You should return \c B_DISPATCH_MESSAGE in case the message passes
 338                 the tests, or \c B_SKIP_MESSAGE in case the message does not pass.
 339
 340         \since BeOS R3
 341 */
 342
 343
 344 /*!
 345         \fn message_delivery BMessageFilter::MessageDelivery() const
 346         \brief Return the message_delivery criterium of this filter.
 347
 348         \since BeOS R3
 349 */
 350
 351
 352 /*!
 353         \fn message_source BMessageFilter::MessageSource() const
 354         \brief Return the message_source criterium of this filter.
 355
 356         \since BeOS R3
 357 */
 358
 359
 360 /*!
 361         \fn uint32 BMessageFilter::Command() const
 362         \brief Return the accepted message constant.
 363
 364         This method returns zero (0) in case this filter does not filter based on
 365         the message constant.
 366
 367         \see FiltersAnyCommand() const
 368
 369         \since BeOS R3
 370 */
 371
 372
 373 /*!
 374         \fn bool BMessageFilter::FiltersAnyCommand() const
 375         \brief Return whether or not this filter has a message command criterium.
 376
 377         \see Command() const
 378
 379         \since BeOS R3
 380 */
 381
 382
 383 /*!
 384         \fn BLooper* BMessageFilter::Looper() const
 385         \brief Return the looper this filter is associated with.
 386
 387         \since BeOS R3
 388 */