module Symbiont
  module Enclosers

    # Used to identify a web object or action on a web object as existing
    # within an enclosing window object. The window can be referenced using
    # either the title attribute of the window or a direct URL. The URL does
    # not have to be the entire URL; it can just be a page name.
    #
    # @param [Hash] locator the :title or :url of the window
    # @param [Proc; optional] block any code that should be executed as an
    # action on or within the window
    #
    # @example
    #   page.within_window(title: "Report Page")
    #   page.within_window(url: report.html)
    def within_window(locator, &block)
      @platform.within_window(locator, &block)
    end

    # 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=Symbiont.page_level_wait, message=nil, &block)
      @platform.wait_for(timeout, message, &block)
    end
    
    # Provides a context for an action that will generate a JavaScript alert
    # message box. The alert invocation will be overridden by the platform.
    #
    # @param [Proc] block the code that generates the alert
    # @return [String] the message contained in the alert message box
    #
    # @example
    #   response = @page.will_alert do
    #     @page.submitForm
    #   end
    def will_alert(&block)
      @platform.will_alert(&block)
    end
    
    # Provides a context for an action that will generate a JavaScript
    # confirmation message box. The confirmation invocation will be
    # overridden by the platform.
    #
    # @param [bool] true to accept the confirmation, false to cancel it
    # @param [Proc] block the code that generates the confirmation
    # @return [String] the message contained in the confirmation message box
    #
    # @example
    #   response = @page.will_confirm(true) do
    #     @page.areYouSure
    #   end
    def will_confirm(response, &block)
      @platform.will_confirm(response, &block)
    end
    
    # Provides a context for an action that will generate a JavaScript prompt
    # message box. The prompt invocation will be overridden by the platform.
    #
    # @param [String] response the value to be used in the prompt
    # @param [Proc] block the code that generates the prompt
    # @return [Hash] :message for the prompt message, :default_value for
    # the value that the prompt had before the response was applied
    #
    # @example
    #   response = @page.will_prompt("use this") do
    #     @page.useValue
    #   end
    def will_prompt(response, &block)
      @platform.will_prompt(response, &block)
    end
    
  end # module: Enclosers
end # module: Symbiont