MICILE EZ_Webbrowser Documentation
version: 0.9
A few notes about our documentation:
  • The intentions of this documentation are to keep things simple.
  • Please see the examples at the end of each section for concrete examples of how to use each function.
  • If in doubt how to use a function, experiment!
  • We don't believe in writing more words just to make the documentation look more substantial
  • Quick Reference
    Function List
    Compatible Devices
    Web browser built into every tablet

    Note! The EZ_Webbrowser is a thin wrapper around a native pywebkitgtk object.

    We have found that the native pywebkitgtk object may be difficult for beginners to use, so we have wrapped it with a set of simpler function calls.

    Advanced users who wish to use pywebkitgtk directly can import pygtk, gtk, and webkit to directly access pywebkitgtk.

    More information about pywebkitgtk can be found at the official pywebkitgtk website

    Webbrowser Object Creation Function
    webbrowser_create(left, top, width, height)
    Creates the webbrowser component at the specified location.

    Returns a webbrowser object


    Webbrowser Object General Functions
    go_back()
    Navigates the webbrowser to the previous page in the history stack.
    This is equivilant to pressing the back button in a browser.
    go_forward()
    Navigates the webbrowser to the next page in the history stack.
    This is equivilant to pressing the forward button in a browser.
    hide()
    Hides the webbrowser.
    To restore a hidden webbrowser, use the show function.
    load_html_string(html)
    Renders the html passed in through the html parameter in the webbrowser.
    move(left, top, width, height)
    Moves the webbrowser to a new location on the screen.
    navigate(url)
    Navigates the webbrowser to a new url
    reload()
    Reloads the current page in the webbrowser.
    scroll_html_element_into_view(element_uid, backscrollamount)
    Scroll the webbpage so that the html element identified by element_uid is at the top of visible web page.

    Currently, this function can only be used with the an element_uid returned by an on_input_tag_clicked event.

    The backscrollamount parameter can be used to specify how much additional scrolling should be performed. For example, if the
    backscrollamount was set to 50, the web page would first be scrolled the top of the html element specified by element_uid
    and then scrolled down so that the top of the html element was 50 pixels further down the web page.
    show()
    Restores the webbrowser that was previously hidden by a call to webbrowser_hide.
    zoom(magnification)
    Zooms the page being displayed in the webbrowser by the level specified by the magnification parameter.
    magnification should be a floating point number, for example 1.1 would be 110% zoom and 0.5 would be 50% zoom.

    Webbrowser Object Pointer and Keyboard Functions
    pointer_click()
    Sends a click event to the webbrowser at the location of the current pointer.
    pointer_hide()
    Hides the pointer used by the webbrowser.
    To restore a hidden pointer, use the pointer_show function.
    pointer_move(x, y)
    Moves the webbrowser pointer.
    The x and y are constrained to the bounds of the webbrowser.
    pointer_set_offset(offset_x, offset_y)
    Sets the offset of the webbrowser pointer relative to the touchscreen point where the user's finger is at.
    It can be useful to set the pointer 50 pixels to the left of the actual touchscreen point so that the user can
    see with great precision exactly where the pointer is.

    This offset is only applied by the process_touch function.
    pointer_show()
    Restores the webbrowser pointer that was previously hidden by a call to pointer_hide.
    process_touch(point)
    Converts points returned by the ez_touchscreen touchscreen_finger_point() function to webbrowser pointer moves and clicks.
    send_key(key)
    Sends a character to the web browser as if it was sent by the keyboard.
    Use '\r' for return and '\b' for backspace.

    Webbrowser Object Scrolling Functions
    get_hscroll()
    Returns the current value of the horizontal scroll bar of the webbrowser.
    get_hscroll_max()
    Returns the maximum value of the horizontal scroll bar of the webbrowser.
    get_vscroll()
    Returns the current value of the vertical scroll bar of the webbrowser.
    get_vscroll_max()
    Returns the maximum value of the vertical scroll bar of the webbrowser.
    set_hscroll(value)
    Sets the new value of the horizontal scroll bar of the webbrowser
    set_vscroll(value)
    Sets the new value of the vertical scroll bar of the webbrowser

    Webbrowser Object Events
    on_input_element_clicked(webbrowser, element_uid)
    This event is called when the webbrowser pointer clicks on an input tag so that an application can display an on screen keyboard.

    Generally in order to accomodate an on screen keyboard, the webbrowser will need to be resized with the move function,
    then the scroll_html_element_into_view function will be called with the element_uid returned by this event to scroll
    the input tag into view since the webbrowser has been resized, possibly causing the input tag which the user clicked on
    to no longer be visible. Finally an onscreen keyboard such as an UI_MiniKeyboard can be displayed allowing the user to enter in text.
    The individual keys that are clicked on the onscreen keyboard should be passed to the webbrowser using the send_keys function.
    on_load_progress_changed(progress)
    This event is called when the progress of a load changes.
    The progress parameter will be an integer between 0 and 100.
    on_navigation_requested(url)
    This event is called before the webbrowser attempts to navigate to a new URL.

    Return True to block the navigation, return False to allow the navigation.

    An example is intercepting blacklisted URLs in this event and then using the load_html_string function
    to display an HTML message saying that this web page has been blocked.
    # --------------------------------------------------
    # webbrowser_demo.py
    #
    #   Simple webbrowser demo, no onscreen keyboard
    #   support in this simple demo so not that useful.
    #
    # --------------------------------------------------
     
    # Imports
    from ez_webbrowser_09 import *
    from ez_touchscreen_09 import *
    import time
     
    # Create a webbrowser
    webbrowser = webbrowser_create(4040720400)
    webbrowser.navigate("http://www.micile.com")
     
    # Main Loop
    while True:
        # grab the point from the touchscreen
        point = touchscreen_finger_point()
        
        # let the webbrowser process the touchpoints
        webbrowser.process_touch(point)
        
        # sleep to give the touchscreen time to react
        time.sleep(0.05)

    webbrowser demo

    # --------------------------------------------------
    # webbrowser_full_demo.py
    #
    #   Full webbrowser demo with on screen keyboard support,
    #   Back, Forward, Reload, and progress bar functionality.
    #
    # --------------------------------------------------
     
    # Imports
    from ez_graphics_09 import *
    from ez_touchscreen_09 import *
    from ez_webbrowser_09 import *
    from ez_ui_09 import *
    import time
     
    # Global Variables
    keyboard = None
    webbrowser = None
    progressbar = None
     
    """ --------------------------------------------------
        Event Handlers
    -------------------------------------------------- """
    # Event Handler for UI button clicks like Back, Forward, Reload, and Go
    def on_btn_clicked(btn):
        # globals
        global text_url
        global webbrowser
        
        # handle the different buttons
        if btn.name == 'btn_back':      webbrowser.go_back()
        if btn.name == 'btn_forward':   webbrowser.go_forward()
        if btn.name == 'btn_reload':    webbrowser.reload()
        if btn.name == 'btn_go':        webbrowser.navigate(text_url.text)
     
    # Event Handler for when keys are touched on the mini pop up keyboard
    def on_minikeyboard_key_clicked(key):
        # close the keyboard if return (\r) has been entered
        if key == '\r':
            keyboard.hide()
            webbrowser.move(1090740380)        
     
        # send the key to the web browser as a key press
        webbrowser.send_key(key)
            
    # Event Handler for when the user has closed the main keyboard and entered in a new URL
    def on_text_changed(textbox):
        # Navigate the webbrowser to the new URL
        if webbrowser is not Nonewebbrowser.navigate(textbox.text)
     
     
    # Event Handler fired before the main keyboard is shown
    def on_text_keyboard_after(textbox):
        # Hide the webbrowser if the main keyboard is shown on the screen
        webbrowser.show()
     
    # Event Handler fired after the main keyboard is hidden
    def on_text_keyboard_before(textbox):
        # Show the webbrowser if the main keyboard is no longer on the screen
        webbrowser.hide()
     
    # Event Handler fired if the user clicks on an input box in a web page
    def on_webbrowser_input_tag_clicked(browserelement_uid):
        # if the keyboard is not visible, resize the browser, make sure the input box
        # is scrolled to the top of the screen, and then show the mini keyboard
        if keyboard.visible == False:
            browser.move(1090740190)
            browser.scroll_html_element_into_view(element_uid0)
            keyboard.show()
     
    # Event Handler fired when the progress of a page load changes
    def on_webbrowser_load_progress_changed(browserprogress):
        # update the progressbar with a new value
        progressbar.value = int(progress)
        progressbar.text = "%s%%" % progress
     
     
    """ --------------------------------------------------
        Main
    -------------------------------------------------- """
    # Clear the screen
    clear_screen('black')
     
    # Create ui components
    panel = create_panel(00get_screen_width()90)
    btn_back    = panel.add_button     ('btn_back',     1010,  7540text='Back',                  on_click_handler=on_btn_clicked)
    btn_forward = panel.add_button     ('btn_forward',  9510,  7540text='Forward',               on_click_handler=on_btn_clicked)
    btn_reload  = panel.add_button     ('btn_reload',  18010,  7540text='Reload',                on_click_handler=on_btn_clicked)
    text_url    = panel.add_textbox    ('textbox',     2651040040text='http://www.micile.com'on_text_changed_handler=on_text_changed)
    btn_go      = panel.add_button     ('btn_go',      67510,  7540text='Go',                    on_click_handler=on_btn_clicked)
    progressbar = panel.add_progressbar('progressbar',  106078020)
    text_url.on_keyboard_before_show = on_text_keyboard_before
    text_url.on_keyboard_after_hide = on_text_keyboard_after
     
    # create a mini keyboard
    keyboard = UI_MiniKeyboard()
    keyboard.on_key_clicked = on_minikeyboard_key_clicked
     
    # Create a webbrowser
    webbrowser = webbrowser_create(1090740380)
     
    # Attach the event handlers
    webbrowser.on_input_tag_clicked = on_webbrowser_input_tag_clicked
    webbrowser.on_load_progress_changed = on_webbrowser_load_progress_changed
     
    # Setup the pointer so it is offset to the left of the finger by 50 pixels
    # This makes it much easier to see where the pointer is on the web page
    webbrowser.pointer_set_offset(-500)
     
    # Navgiate to the start page
    webbrowser.navigate(text_url.text)
     
    # Main Loop
    while True:
        # grab the point from the touchscreen
        point = touchscreen_finger_point()
        
        # let the ui panel process the touchpoints
        panel.process_touch(point)
     
        # let the webbrowser process the touchpoints
        webbrowser.process_touch(point)
     
        # read a single finger point from the touchscreen
        k = keyboard.process_touch(point)
     
        # sleep to give the touchscreen time to react
        time.sleep(0.05)
     

    webbrowser full demo