# :stopdoc:
# Copyright (c) 2023 M.J.N. Corino, The Netherlands
#
# This software is released under the MIT license.


# Additional event handler methods documentation stubs.
# :startdoc:



module Wx

  class EvtHandler

    # Removes all (Ruby) installed EventFilter-s.
    # @return [void]
    def self.clear_filters; end

    # Public method to register the mapping of a custom event type
    # +konstant+ (which should be a unique integer; one will be created if
    # not supplied) to a custom event class +klass+. If +meth+ and +arity+
    # are given, a convenience evt_handler method called +meth+ will be
    # created, which accepts +arity+ arguments (specify both or neither).
    # @param klass [Class] event class
    # @param konstant [Integer] unique event type id (if nil a unique value will be autogenerated)
    # @param meth [String,Symbol] optional event handler method name
    # @param arity [Integer] event handler method arity (should be 0, 1 or 2 if not nil)
    # @return [Integer] unique event type id
    def self.register_class(klass, konstant = nil, meth = nil, arity = nil) end

    # Connects the given event handler dynamically for id(s) and event type.
    #
    # This is the core event connecting method.
    # In Ruby using named event connector methods like {Wx::EvtHandler#evt_menu} is highly recommended as using #connect
    # does not provide any better options (less even) than using named event connectors as all event connecting is dynamic.
    #
    # @param [Integer] first_id The first ID of the identifier range to be associated with the event handler. Should be Wx::ANY_ID for events that do not require identifiers.
    # @param [Integer] last_id The last ID of the identifier range to be associated with the event handler. Should be Wx::ANY_ID for events requiring a single identifier (like {Wx::MenuEvt}).
    # @param [Integer] evt_id The event type identifier like {Wx::EVT_MENU}.
    # @param [Proc,Method] handler The event handler proc or method.
    # @return [Boolean] Always returns true.
    def connect(first_id, last_id, evt_id, handler) end

    # Disconnects any event handler connected for the specified id(s) and event type.
    #
    # Looks up connected event handler(s) using the specified parameters as search criteria and returning true if (a)
    # matching handler(s) has(have) been found and removed.
    #
    # @note Note that in wxRuby it is not possible to remove a specific handler if multiple (chained) handler(s) have been connected.
    #
    # @param [Integer] first_id The first ID of the identifier range associated with the event handler. Should be Wx::ANY_ID for events that have no associated identifiers.
    # @param [Integer] last_id The last ID of the identifier range associated with the event handler. Should be Wx::ANY_ID for events that have a single identifier associated.
    # @param [Integer,Symbol,nil] evt_id The event type identifier like {Wx::EVT_MENU} or event connector symbol (like `:evt_menu`).
    # @return [Boolean] Returns true if any event handler found and removed, false otherwise.
    def disconnect(first_id, last_id, evt_id) end

    # Processes an event, searching event tables and calling zero or more suitable event handler function(s).
    #
    # Normally, your application would not call this function: it is called in the wxWidgets implementation to
    # dispatch incoming user interface events to the framework (and application).
    #
    # However, you might need to call it if implementing new functionality (such as a new control) where you
    # define new event types, as opposed to allowing the user to override virtual functions.
    #
    # In wxRuby this method can not be effectively overridden.
    # In order to override default event processing define a try_before(event) or try_after(event) method
    # as member of a derived EvtHandler class.
    #
    # The normal order of event table searching is as follows:
    #
    # 1. {Wx::App#filter_event} is called. If it returns anything but -1 (default) the processing stops here.
    # 2. #try_before (if it exists, otherwise the C++ default implementation) is called (this is where {Wx::Validator} are taken into account for {Wx::Window} objects). If this returns true, the function exits.
    # 3. If the object is disabled (via a call to {Wx::EvtHandler#set_evt_handler_enabled}) the function skips to step (7).
    # 4. Dynamic event table of the handlers bound using Bind<>() is searched in the most-recently-bound to the most-early-bound order. If a handler is found, it is executed and the function returns true unless the handler used {Wx::Event#skip} to indicate that it didn't handle the event in which case the search continues.
    # 5. Static events table of the handlers bound using event table macros is searched for this event handler in the order of appearance of event table macros in the source code. If this fails, the base class event table is tried, and so on until no more tables exist or an appropriate function was found. If a handler is found, the same logic as in the previous step applies.
    # 6. The search is applied down the entire chain of event handlers (usually the chain has a length of one). This chain can be formed using {Wx::EvtHandler#set_next_handler}
    #    Note that in the case of Wx::Window you can build a stack of event handlers (see {Wx::Window#push_event_handler} for more info). If any of the handlers of the chain return true, the function exits.
    # 7. #try_after (if it exists, otherwise the C++ default implementation) is called: for the {Wx::Window} object this may propagate the event to the window parent (recursively). If the event is still not processed, {#process_event} on the {Wx::THE_APP} object is called as the last step.
    #
    # Notice that steps (2)-(6) are performed in {#process_event_locally} which is called by this function.
    #
    # @param event [Wx::Event]  Event to process.
    # @return [true,false] true if event has been processed
    def process_event(event) end

    # Process a command, supplying the window identifier, command event identifier, and member function or proc.
    # @param [Integer] id window identifier
    # @param [Integer] evt_id event type identifier
    # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
    # @yieldparam [Wx::CommandEvent] event event to handle
    def evt_command(id, evt_id, meth = nil, &block) end

    # Process a command for a range of window identifiers, supplying the minimum and maximum window identifiers, command event identifier, and member function or proc.
    # @param [Integer] id1 minimum window identifier
    # @param [Integer] id2 maximum window identifier
    # @param [Integer] evt_id event type identifier
    # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
    # @yieldparam [Wx::CommandEvent] event event to handle
    def evt_command_range(id1, id2, evt_id, meth = nil, &block) end

    # Processes Wx::WindowDestroyEvent events.
    # In wxRuby Wx::Event#skipped will be forced to true after the provided
    # handler has finished to make sure the event is propagated as it is
    # required that Wx::App gets to handle the event in the end.
    # @yieldparam [Wx::WindowDestroyEvent] event event to handle
    def evt_window_destroy(&block) end

    # Processes {Wx::EVT_TIMER} events. See {Wx::TimerEvent}.
    # @param [Integer,Wx::Enum,Wx::Timer] id timer id
    # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
    # @yieldparam [Wx::TimerEvent] event the event to handle
    def evt_timer(id, meth = nil, &block) end

    # Schedule a call for asynchronous execution (at idle time).
    # @param meth [Symbol,String,Method,Proc] (name of) method or proc to call
    # @param args [Array<Object>] optional arguments to pass to the call
    # @return [void]
    # @yield [*args] optional arguments
    def call_after(meth = nil, *args, &block) end

    # Process a {Wx::EVT_HOTKEY} event.
    # @wxrb_require WXOSX|WXMSW
    # @param [Integer] id hotkey id
    # @param [String,Symbol,Method,Proc] meth (name of) method or handler proc
    # @yieldparam [Wx::KeyEvent] event the event to handle
    def evt_hotkey(id, meth = nil, &block) end

  end

end
