# :stopdoc:
# This file is automatically generated by the WXRuby3 documentation 
# generator. Do not alter this file.
# :startdoc:


module Wx

  # A class that can handle events from the windowing system.
  # {Wx::Window} is (and therefore all window classes are) derived from this class.
  # When events are received, {Wx::EvtHandler} invokes the method listed in the event table using itself as the object. When using multiple inheritance <b>it is imperative that the {Wx::EvtHandler}(-derived) class is the first class inherited</b> such that the this pointer for the overall object will be identical to the this pointer of the {Wx::EvtHandler} portion.
  # === 
  # 
  # Category:  {Wx::Events}
  # @see How Events are Processed
  # @see  Wx::EventBlocker
  # @see  Wx::EventLoopBase 
  # 
  # 
  class EvtHandler < Object
  
    # Queue event for a later processing.
    # This method is similar to {Wx::EvtHandler#process_event} 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 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).
    # {Wx::EvtHandler#queue_event} 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 {Wx::EvtHandler#add_pending_event} documentation by ensuring that the 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 {Wx::String} members of the event object must not be shallow copies of another {Wx::String} object as this would result in them still using the same string buffer behind the scenes. For example: 
    # 
    #   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 );
    #   }
    # 
    # Note that you can use {Wx::ThreadEvent} instead of {Wx::CommandEvent} to avoid this problem: 
    # 
    #   void FunctionInAWorkerThread(const wxString& str)
    #   {
    #       wxThreadEvent evt;
    #       evt.SetString(str);
    #   
    #       // wxThreadEvent::Clone() makes sure that the internal wxString
    #       // member is not shared by other wxString instances:
    #       wxTheApp->QueueEvent( evt.Clone() );
    #   }
    # 
    # Finally notice that this method automatically wakes up the event loop if it is currently idle by calling {wake_up_idle} so there is no need to do it manually when using it.
    # @param event [Wx::Event]  A heap-allocated event to be queued, {Wx::EvtHandler#queue_event} takes ownership of it. This parameter shouldn't be NULL.
    # @return [void]
    def queue_event(event) end
    
    # Post an event to be processed later.
    # This function is similar to {Wx::EvtHandler#queue_event} but can't be used to post events from worker threads for the event objects with {Wx::String} fields (i.e. in practice most of them) because of an unsafe use of the same {Wx::String} object which happens because the {Wx::String} field in the original event object and its copy made internally by this function share the same string buffer internally. Use {Wx::EvtHandler#queue_event} to avoid this.
    # 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 {Wx::Event#clone} method be implemented by event so that it can be duplicated and stored until it gets processed.
    # @param event [Wx::Event]  Event to add to the pending events queue.
    # @return [void]
    def add_pending_event(event) end
    
    # Try to process the event in this handler and all those chained to it.
    # As explained in {Wx::EvtHandler#process_event} documentation, the event handlers may be chained in a doubly-linked list. This function tries to process the event in this handler (including performing any pre-processing done in {Wx::EvtHandler#try_before}, e.g. applying validators) and all those following it in the chain until the event is processed or the chain is exhausted.
    # This function is called from {Wx::EvtHandler#process_event} and, in turn, calls {Wx::EvtHandler#try_before} and {Wx::EvtHandler#try_after}. It is not virtual and so cannot be overridden but can, and should, be called to forward an event to another handler instead of {Wx::EvtHandler#process_event} which would result in a duplicate call to {Wx::EvtHandler#try_after}, e.g. resulting in all unprocessed events being sent to the application object multiple times.
    # 
    # true if this handler of one of those chained to it processed the event.
    # @param event [Wx::Event]  Event to process.
    # @return [true,false]
    def process_event_locally(event) end
    
    # Processes an event by calling {Wx::EvtHandler#process_event} and handles any exceptions that occur in the process.
    # If an exception is thrown in event handler, {Wx::App::OnExceptionInMainLoop} is called.
    # 
    # true if the event was processed, false if no handler was found or an exception was thrown.
    # @see Wx::Window#handle_window_event 
    # @param event [Wx::Event]  Event to process.
    # @return [true,false]
    def safely_process_event(event) end
    
    # Processes the pending events previously queued using {Wx::EvtHandler#queue_event} or {Wx::EvtHandler#add_pending_event}; you must call this function only if you are sure there are pending events for this handler, otherwise a {Wx::CHECK} will fail.
    # The real processing still happens in {Wx::EvtHandler#process_event} which is called by this function.
    # Note that this function needs a valid application object (see Wx::AppConsole#get_instance) because {Wx::App} holds the list of the event handlers with pending events and this function manipulates that list.
    # @return [void]
    def process_pending_events; end
    
    # Deletes all events queued on this event handler using {Wx::EvtHandler#queue_event} or {Wx::EvtHandler#add_pending_event}.
    # Use with care because the events which are deleted are (obviously) not processed and this may have unwanted consequences (e.g. user actions events will be lost).
    # @return [void]
    def delete_pending_events; end
    
    # Returns true if the event handler is enabled, false otherwise.
    # 
    # @see Wx::EvtHandler#set_evt_handler_enabled 
    # @return [true,false]
    def get_evt_handler_enabled; end
    alias_method :evt_handler_enabled, :get_evt_handler_enabled
    
    # Returns the pointer to the next handler in the chain.
    # 
    # @see Wx::EvtHandler#set_next_handler
    # @see  Wx::EvtHandler#get_previous_handler
    # @see  Wx::EvtHandler#set_previous_handler
    # @see  Wx::Window#push_event_handler
    # @see  Wx::Window#pop_event_handler 
    # @return [Wx::EvtHandler]
    def get_next_handler; end
    alias_method :next_handler, :get_next_handler
    
    # Returns the pointer to the previous handler in the chain.
    # 
    # @see Wx::EvtHandler#set_previous_handler
    # @see  Wx::EvtHandler#get_next_handler
    # @see  Wx::EvtHandler#set_next_handler
    # @see  Wx::Window#push_event_handler
    # @see  Wx::Window#pop_event_handler 
    # @return [Wx::EvtHandler]
    def get_previous_handler; end
    alias_method :previous_handler, :get_previous_handler
    
    # Enables or disables the event handler.
    # You can use this function to avoid having to remove the event handler from the chain, for example when implementing a dialog editor and changing from edit to test mode.
    # @see Wx::EvtHandler#get_evt_handler_enabled 
    # @param enabled [true,false]  true if the event handler is to be enabled, false if it is to be disabled.
    # @return [void]
    def set_evt_handler_enabled(enabled) end
    alias_method :evt_handler_enabled=, :set_evt_handler_enabled
    
    # Sets the pointer to the next handler.
    # See {Wx::EvtHandler#process_event} for more info about how the chains of event handlers are internally used. Also remember that {Wx::EvtHandler} uses double-linked lists and thus if you use this function, you should also call {Wx::EvtHandler#set_previous_handler} on the argument passed to this function: 
    # 
    #   handlerA->SetNextHandler(handlerB);
    #   handlerB->SetPreviousHandler(handlerA);
    # @see How Events are Processed 
    # @param handler [Wx::EvtHandler]  The event handler to be set as the next handler. Cannot be NULL.
    # @return [void]
    def set_next_handler(handler) end
    alias_method :next_handler=, :set_next_handler
    
    # Sets the pointer to the previous handler.
    # All remarks about {Wx::EvtHandler#set_next_handler} apply to this function as well.
    # @see How Events are Processed 
    # @param handler [Wx::EvtHandler]  The event handler to be set as the previous handler. Cannot be NULL.
    # @return [void]
    def set_previous_handler(handler) end
    alias_method :previous_handler=, :set_previous_handler
    
    # Unlinks this event handler from the chain it's part of (if any); then links the "previous" event handler to the "next" one (so that the chain won't be interrupted).
    # E.g. if before calling {Wx::EvtHandler#unlink} you have the following chain: 
    #  then after calling <code>B->Wx::EvtHandler#unlink</code> you'll have:
    # @return [void]
    def unlink; end
    
    # Returns true if the next and the previous handler pointers of this event handler instance are NULL.
    # 
    # @see Wx::EvtHandler#set_previous_handler
    # @see  Wx::EvtHandler#set_next_handler 
    # @return [true,false]
    def is_unlinked; end
    alias_method :unlinked?, :is_unlinked
    
    # Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets.
    # The filters are called in LIFO order and {Wx::App} is registered as an event filter by default. The pointer must remain valid until it's removed with {Wx::EvtHandler.remove_filter} and is not deleted by {Wx::EvtHandler}.
    # @param filter [Wx::EventFilter] 
    # @return [void]
    def self.add_filter(filter) end
    
    # Remove a filter previously installed with {Wx::EvtHandler.add_filter}.
    # It's an error to remove a filter that hadn't been previously added or was already removed.
    # @param filter [Wx::EventFilter] 
    # @return [void]
    def self.remove_filter(filter) end
    
    # Constructor.
    # @return [EvtHandler]
    def initialize; end
    
    
    protected
    
    # Method called by {Wx::EvtHandler#process_event} before examining this object event tables.
    # This method can be overridden to hook into the event processing logic as early as possible. You should usually call the base class version when overriding this method, even if {Wx::EvtHandler} itself does nothing here, some derived classes do use this method, e.g. {Wx::Window} implements support for {Wx::Validator} in it.
    # Example: 
    # 
    #   class MyClass : public BaseClass // inheriting from wxEvtHandler
    #   {
    #   ...
    #   protected:
    #       virtual bool TryBefore(wxEvent& event)
    #       {
    #           if ( MyPreProcess(event) )
    #               return true;
    #   
    #           return BaseClass::TryBefore(event);
    #       }
    #   };
    # @see Wx::EvtHandler#process_event 
    # @param event [Wx::Event] 
    # @return [true,false]
    def try_before(event) end
    
    # Method called by {Wx::EvtHandler#process_event} as last resort.
    # This method can be overridden to implement post-processing for the events which were not processed anywhere else.
    # The base class version handles forwarding the unprocessed events to {Wx::App} at {Wx::EvtHandler} level and propagating them upwards the window child-parent chain at {Wx::Window} level and so should usually be called when overriding this method: 
    # 
    #   class MyClass : public BaseClass // inheriting from wxEvtHandler
    #   {
    #   ...
    #   protected:
    #       virtual bool TryAfter(wxEvent& event)
    #       {
    #           if ( BaseClass::TryAfter(event) )
    #               return true;
    #   
    #           return MyPostProcess(event);
    #       }
    #   };
    # @see Wx::EvtHandler#process_event 
    # @param event [Wx::Event] 
    # @return [true,false]
    def try_after(event) end
    
  end # EvtHandler
  

end