Function PostAppEvent() Foundation
Places an event in the event queue.
PostAppEvent( <nEvent>, [<mp1>], [<mp2>], [<oXbp>] ) --> lSuccess
The return value of PostAppEvent() is .T. (true) when the event could be written into the event queue, otherwise it is .F. (false).
The function PostAppEvent() allows intervening with the message stream of an event driven application and sending events directly to a specific addressee. PostAppEvent() places events in the event queue, along with the attached message parameters. These events can then be processed by the addressee of the message.
Symbolic constants from the file Appevent.ch are generally used for the event code <nEvent>, but user-defined events can also be used. A user-defined event code is created using the base value (the constant xbeP_User) added to an integer. The message parameter <mp1> and <mp2> may contain any values and are used along with the event code to create the message sent to the addressee <oXbp>. The send occurs using the event queue, meaning it is an asynchronized message transfer when the message containing the event code <nEvent> is placed into the event queue. The addressee of the message only receives the message when it is read from the event queue by the function AppEvent().
If an addressee is specified, the addressee of the message must be an XBase Part. Note that Xbase Parts "understand" only a limited number of messages. If #define constants from the file Appevent.ch are used for the event code <nEvent>, a constant should be selected which is known to be an event processed by the addressee of the message. Otherwise, the addressee does not react or the event is sent on to the window. The event codes recognized by the various Xbase Parts are described in the section on each Xbase Part.
Multithreading issues and GUI
In a GUI application, events are collected in an event queue and retrieved from this queue by the AppEvent() function. If a GUI program is split into multiple threads, it must be emphasized that an event queue has thread-local scope and each thread maintains its own event queue. When an event is posted to a particular Xbase Part (4th parameter <oXbp>), PostAppEvent() places this event in the event queue of the thread the Xbase Part was created in. For example, if thread B executes PostAppEvent() and posts an event to an Xbase Part created in thread A, the event arrives in the event queue of thread A and can only be retrieved from this queue when AppEvent() is executed in thread A. As a result, the event posted in thread B will be processed in thread A, not in thread B.
If a program is not linked with the linker switch /PM:PM, it is a text mode application which has only one event queue. When a text mode application uses multiple threads, they share this queue.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.