/**
Returns a copy of the event.
- Any event that is posted to the wxWidgets event system for later action (via
- wxEvtHandler::AddPendingEvent or wxPostEvent()) must implement this method.
+ Any event that is posted to the wxWidgets event system for later action
+ (via wxEvtHandler::AddPendingEvent or wxPostEvent()) must implement
+ this method.
All wxWidgets events fully implement this method, but any derived events
implemented by the user should also implement this method just in case they
virtual ~wxEvtHandler();
/**
- This function posts an event to be processed later.
+ Queue event for a later processing.
+
+ This method is similar to ProcessEvent() but while the latter is
+ synchronous, i.e. the event is processed immediately, before the
+ function returns, this one is asynchronous and returns immediately
+ while the event will be processed at some later time (usually during
+ the next event loop iteration).
+
+ Another important difference is that this method takes ownership of the
+ @a event parameter, i.e. it will delete it itself. This implies that
+ the event should be allocated on the heap and that the pointer can't be
+ used any more after the function returns (as it can be deleted at any
+ moment).
+
+ QueueEvent() can be used for inter-thread communication from the worker
+ threads to the main thread, it is safe in the sense that it uses
+ locking internally and avoids the problem mentioned in AddPendingEvent()
+ documentation by ensuring that the @a event object is not used by the
+ calling thread any more. Care should still be taken to avoid that some
+ fields of this object are used by it, notably any wxString members of
+ the event object must not be shallow copies of another wxString object
+ as this would result in them still using the same string buffer behind
+ the scenes. For example
+ @code
+ void FunctionInAWorkerThread(const wxString& str)
+ {
+ wxCommandEvent* evt = new wxCommandEvent;
+
+ // NOT evt->SetString(str) as this would be a shallow copy
+ evt->SetString(str.c_str()); // make a deep copy
+
+ wxTheApp->QueueEvent( evt );
+ }
+ @endcode
+
+ Finally notice that this method automatically wakes up the event loop
+ if it is currently idle by calling ::wxWakeUpIdle() so there is no need
+ to do it manually when using it.
+
+ @since 2.9.0
- The difference between sending an event (using the ProcessEvent
- method) and posting it is that in the first case the event is
- processed before the function returns, while in the second case,
- the function returns immediately and the event will be processed
- sometime later (usually during the next event loop iteration).
+ @param event
+ A heap-allocated event to be queued, QueueEvent() takes ownership
+ of it. This parameter shouldn't be @c NULL.
+ */
+ virtual void QueueEvent(wxEvent *event);
- A copy of event is made by the function, so the original can be deleted as
- soon as function returns (it is common that the original is created on the
- stack). This requires that the wxEvent::Clone method be implemented by event
- so that it can be duplicated and stored until it gets processed.
+ /**
+ Post an event to be processed later.
- This is also the method to call for inter-thread communication - it will post
- events safely between different threads which means that this method is
- thread-safe by using critical sections where needed. In a multi-threaded program,
- you often need to inform the main GUI thread about the status of other working
- threads and such notification should be done using this method.
+ This function is similar to QueueEvent() but can't be used to post
+ events from worker threads for the event objects with wxString fields
+ (i.e. in practice most of them) because of an unsafe use of the same
+ wxString object which happens because the wxString field in the
+ original @a event object and its copy made internally by this function
+ share the same string buffer internally. Use QueueEvent() to avoid
+ this.
- This method automatically wakes up idle handling if the underlying window
- system is currently idle and thus would not send any idle events.
- (Waking up idle handling is done calling ::wxWakeUpIdle.)
+ A copy of event is made by the function, so the original can be deleted
+ as soon as function returns (it is common that the original is created
+ on the stack). This requires that the wxEvent::Clone() method be
+ implemented by event so that it can be duplicated and stored until it
+ gets processed.
@param event
- Event to add to process queue.
+ Event to add to the pending events queue.
*/
virtual void AddPendingEvent(const wxEvent& event);
@param event
Event to process.
- @returns @true if a suitable event handler function was found and
+ @return @true if a suitable event handler function was found and
executed, and the function did not call wxEvent::Skip.
@see SearchEventTable()
@param event
Event to process.
- @returns @true if the event was processed, @false if no handler was found
+ @return @true if the event was processed, @false if no handler was found
or an exception was thrown.
@see wxWindow::HandleWindowEvent
@param event
Event to be matched against an event table entry.
- @returns @true if a suitable event handler function was found and
+ @return @true if a suitable event handler function was found and
executed, and the function did not call wxEvent::Skip.
@remarks This function looks through the object's event table and tries
other platforms (you can still distinguish simple clicks from double-clicks as
they generate different kinds of events however).
- @wxsince{2.9.0}
+ @since 2.9.0
*/
int GetClickCount() const;
int GetSelection() const;
/**
- Returns item string for a listbox or choice selection event (not valid for
- a deselection).
+ Returns item string for a listbox or choice selection event. If one
+ or several items have been deselected, returns the index of the first
+ deselected item. If some items have been selected and others deselected
+ at the same time, it will return the index of the first selected item.
*/
wxString GetString() const;
bool IsChecked() const;
/**
- For a listbox or similar event, returns @true if it is a selection, @false if it
- is a deselection.
+ For a listbox or similar event, returns @true if it is a selection, @false
+ if it is a deselection. If some items have been selected and others deselected
+ at the same time, it will return @true.
*/
bool IsSelection() const;
bool IsPopup() const;
};
+/**
+ @class wxShowEvent
+ @wxheader{event.h}
+
+ An event being sent when the window is shown or hidden.
+
+ Currently only wxMSW, wxGTK and wxOS2 generate such events.
+
+ @onlyfor{wxmsw,wxgtk,wxos2}
+
+ @beginEventTable{wxShowEvent}
+ @event{EVT_SHOW(func)}
+ Process a wxEVT_SHOW event.
+ @endEventTable
+
+ @library{wxcore}
+ @category{events}
+
+ @see @ref overview_eventhandling, wxWindow::Show,
+ wxWindow::IsShown
+*/
+
+class wxShowEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ */
+ wxShowEvent(int winid = 0, bool show = false);
+
+ /**
+ Set whether the windows was shown or hidden.
+ */
+ void SetShow(bool show);
+
+ /**
+ Return @true if the window has been shown, @false if it has been
+ hidden.
+ */
+ bool IsShown() const;
+
+ /**
+ @deprecated This function is deprecated in favour of IsShown().
+ */
+ bool GetShow() const;
+};
+
+
/**
@class wxIconizeEvent
Returns @true if the frame has been iconized, @false if it has been
restored.
*/
+ bool IsIconized() const;
+
+ /**
+ @deprecated This function is deprecated in favour of IsIconized().
+ */
bool Iconized() const;
};
Otherwise, it dispatches @a event immediately using
wxEvtHandler::ProcessEvent(). See the respective documentation for details
- (and caveats).
+ (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent()
+ this function is not thread-safe for event objects having wxString fields,
+ use wxQueueEvent() instead.
@header{wx/event.h}
*/
-void wxPostEvent(wxEvtHandler* dest, wxEvent& event);
+void wxPostEvent(wxEvtHandler* dest, const wxEvent& event);
+
+/**
+ Queue an event for processing on the given object.
+
+ This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation
+ for more details.
+
+ @header{wx/event.h}
+
+ @param dest
+ The object to queue the event on, can't be @c NULL.
+ @param event
+ The heap-allocated and non-@c NULL event to queue, the function takes
+ ownership of it.
+ */
+void wxQueueEvent(wxEvtHandler* dest, wxEvent *event);
//@}
projects / wxWidgets.git / blobdiff