module Symbiont
  module Enclosers
    
    # Used to identify a web object as existing within an enclosing object
    # like a frame or an iframe. It is possible to nest by passing in parent
    # enclosers as the second parameter.
    #
    # @param [String] locator how an encloser will be referenced; the
    # only valid locators here are :id, :index, and :name
    # @param encloser a parent encloser that is passed from a previous call
    # @param [optional] block that contains calls to web objects within the
    # encloser
    #
    # @example
    #   within_frame(id: "loginSection") do |encloser|
    #     text_field :username, id: "userName", frame: encloser
    #     button :login, id: "btnSubmit", frame: encloser
    #   end
    def within_frame(locator, encloser=nil, &block)
      encloser = [] if encloser.nil?
      encloser << locator
      block.call(encloser)
    end
    
    # Provides a context for an action that must succeed within a given time period.
    # The logic here is simply that the result of the action will be true (meaning
    # the action was carried out) or false, which means the action did not succeed
    # in the time allotted.
    #
    # @param [Integer] timeout the amount of time in seconds to wait
    # @param [String] message the text to return if the action did not occur in time
    # @param [Proc] block the code that calls the desired action
    #
    # @example
    #   @page.wait_for(5, 'page with expected title not found') do
    #     @page.title.should == "Test App"
    #   end
    def wait_for(timeout=10, message=nil, &block)
      @platform.wait_for(timeout, message, &block)
    end
    
    def will_alert(&block)
      @platform.will_alert(&block)
    end
    
    def will_confirm(response, &block)
      @platform.will_confirm(response, &block)
    end
    
    def will_prompt(response, &block)
      @platform.will_prompt(response, &block)
    end
    
  end # module: Enclosers
end # module: Symbiont