include/OffscreenGecko/browser.h File Reference

Browser object. More...

#include "embedding.h"

Go to the source code of this file.

Namespaces

namespace  OSGK

Classes

struct  OSGK::Browser
 Browser - encapsulates the display of content. More...
struct  OSGK_Browser
 Browser - encapsulates the display of content. More...

Keyboard events

See also:
Keyboard input notes


enum  {
  OSGKKey_First = 0x110000, OSGKKey_Backspace = OSGKKey_First, OSGKKey_Tab, OSGKKey_Return,
  OSGKKey_Shift, OSGKKey_Control, OSGKKey_Alt, OSGKKey_CapsLock,
  OSGKKey_Escape, OSGKKey_Space, OSGKKey_PageUp, OSGKKey_PageDown,
  OSGKKey_End, OSGKKey_Home, OSGKKey_Left, OSGKKey_Up,
  OSGKKey_Right, OSGKKey_Down, OSGKKey_Insert, OSGKKey_Delete,
  OSGKKey_F1, OSGKKey_F2, OSGKKey_F3, OSGKKey_F4,
  OSGKKey_F5, OSGKKey_F6, OSGKKey_F7, OSGKKey_F8,
  OSGKKey_F9, OSGKKey_F10, OSGKKey_F11, OSGKKey_F12,
  OSGKKey_NumLock, OSGKKey_ScrollLock, OSGKKey_Meta
}
 Supported keys for up/down keyboard events. More...
enum  OSGK_KeyboardEventType { keDown, keUp, kePress }
 Type of keyboard event. More...
int osgk_browser_event_key (OSGK_Browser *browser, unsigned int key, OSGK_KeyboardEventType eventType)
 Send keyboard input to a browser object.

Progress queries

enum  OSGK_LoadState { loadLoading, loadFinished }
 URI loading state. More...
float osgk_browser_query_load_progress (OSGK_Browser *browser)
 Poll the loading progress.
OSGK_LoadState osgk_browser_query_load_state (OSGK_Browser *browser)
 Poll the loading state.

Mouse events

enum  OSGK_MouseButton { mbLeft, mbRight, mbMiddle }
 Mouse button ID. More...
enum  OSGK_MouseButtonEventType { meDown, meUp, meDoubleClick }
 Type of mouse button event. More...
enum  OSGK_WheelAxis { waVertical, waHorizontal }
 Posssible axes for mouse wheel movement. More...
enum  OSGK_WheelDirection { wdPositive, wdNegative, wdPositivePage, wdNegativePage }
 Wheel scrolling direction. More...
void osgk_browser_event_mouse_button (OSGK_Browser *browser, OSGK_MouseButton button, OSGK_MouseButtonEventType eventType)
 Send a mouse button event to a browser object.
void osgk_browser_event_mouse_move (OSGK_Browser *browser, int x, int y)
 Send a mouse move event to a browser object.
void osgk_browser_event_mouse_wheel (OSGK_Browser *browser, OSGK_WheelAxis axis, OSGK_WheelDirection direction)
 Send a mouse wheel event to a browser object.

Enumerations

enum  OSGK_AntiAliasType { aaNone, aaGray, aaSubpixel }
 Possible anti-aliasing types. More...

Functions

OSGK_Browser * osgk_browser_create (OSGK_Embedding *embedding, int width, int height)
 Create a new browser object.
void osgk_browser_focus (OSGK_Browser *browser)
 Give focus to a browser object.
OSGK_AntiAliasType osgk_browser_get_antialias (OSGK_Browser *browser)
 Get antialiasing type of a browser object.
int osgk_browser_get_preferred_dimensions (OSGK_Browser *browser, int *preferredWidth, int *preferredHeight, int maxWidth=-1)
 Get the preferred dimensions of the displayed content.
void osgk_browser_navigate (OSGK_Browser *browser, const char *uri)
 Navigate a browser to a given URI.
void osgk_browser_resize (OSGK_Browser *browser, int width, int height)
 Resize a browser object to the specified dimensions.
void osgk_browser_set_antialias (OSGK_Browser *browser, OSGK_AntiAliasType aaType)
 Set antialiasing type for a browser object.
User data
Allows to attach arbitrary user data to a browser object.

int osgk_browser_get_user_data (OSGK_Browser *browser, unsigned int key, void **data)
 Get a user data value from a browser object.
int osgk_browser_set_user_data (OSGK_Browser *browser, unsigned int key, void *data, int overrideData=0)
 Set a user data value on a browser object.
Pixel data acquisition
const unsigned char * osgk_browser_lock_data (OSGK_Browser *browser, int *isDirty=0)
 Lock the pixel data for a browser object.
int osgk_browser_query_dirty (OSGK_Browser *browser)
 Query if a browser object is 'dirty' (if the displayed data has changed since the last time the data was requested).
void osgk_browser_unlock_data (OSGK_Browser *browser, const unsigned char *data)
 Unlock the pixel data for a browser object obtained by an earlier osgk_browser_lock_data() call.

Detailed Description

Browser object.

Enumeration Type Documentation

anonymous enum

Supported keys for up/down keyboard events.

Enumerator:
OSGKKey_First 
OSGKKey_Backspace 
OSGKKey_Tab 
OSGKKey_Return 
OSGKKey_Shift 
OSGKKey_Control 
OSGKKey_Alt 
OSGKKey_CapsLock 
OSGKKey_Escape 
OSGKKey_Space 
OSGKKey_PageUp 
OSGKKey_PageDown 
OSGKKey_End 
OSGKKey_Home 
OSGKKey_Left 
OSGKKey_Up 
OSGKKey_Right 
OSGKKey_Down 
OSGKKey_Insert 
OSGKKey_Delete 
OSGKKey_F1 
OSGKKey_F2 
OSGKKey_F3 
OSGKKey_F4 
OSGKKey_F5 
OSGKKey_F6 
OSGKKey_F7 
OSGKKey_F8 
OSGKKey_F9 
OSGKKey_F10 
OSGKKey_F11 
OSGKKey_F12 
OSGKKey_NumLock 
OSGKKey_ScrollLock 
OSGKKey_Meta 

enum OSGK_AntiAliasType

Possible anti-aliasing types.

Enumerator:
aaNone  Disable anti-aliasing.
aaGray  Gray-level antialiasing (default).
aaSubpixel  Allow subpixel antialiasing (aka ClearType).

This should only be used when it's known that a surface pixel will exactly match an LCD pixel. If that's not the case output will have color fringes.

enum OSGK_KeyboardEventType

Type of keyboard event.

Enumerator:
keDown  Key was pressed.
keUp  Key was released.
kePress  Key was pressed.

enum OSGK_LoadState

URI loading state.

Enumerator:
loadLoading  Loading is in progress.
loadFinished  Loading is completed.

enum OSGK_MouseButton

Mouse button ID.

Enumerator:
mbLeft  Left mouse button.
mbRight  Right mouse button.
mbMiddle  Middle mouse button.

enum OSGK_MouseButtonEventType

Type of mouse button event.

Enumerator:
meDown  Mouse button was pressed.
meUp  Mouse button was released.
meDoubleClick  Mouse button was double-clicked.

enum OSGK_WheelAxis

Posssible axes for mouse wheel movement.

Enumerator:
waVertical  Vertical axis (the 'typical' scroll direction).
waHorizontal  Horizontal axis (some mice have that).

enum OSGK_WheelDirection

Wheel scrolling direction.

Enumerator:
wdPositive  Scroll down (vertical)/right (horizontal).
wdNegative  Scroll up (vertical)/left (horizontal).
wdPositivePage  Scroll a page down (vertical)/right (horizontal).
wdNegativePage  Scroll a page up (vertical)/left (horizontal).

Function Documentation

OSGK_Browser* osgk_browser_create ( OSGK_Embedding *  embedding,
int  width,
int  height 
)

Create a new browser object.

Browsers encapsulate the display of content.

Parameters:
embedding Parent embedding object.
width Width of the display area.
height Height of the display area.

int osgk_browser_event_key ( OSGK_Browser *  browser,
unsigned int  key,
OSGK_KeyboardEventType  eventType 
)

Send keyboard input to a browser object.

Parameters:
browser The browser object.
key The code of the affected key. It can be either one of the OSGKKey_ codes are a Unicode character.
eventType The type of event.
Returns:
Whether the key was handled (non-zero) or not (zero).
See also:
KeyboardInputNotes, OSGKKey_Backspace

void osgk_browser_event_mouse_button ( OSGK_Browser *  browser,
OSGK_MouseButton  button,
OSGK_MouseButtonEventType  eventType 
)

Send a mouse button event to a browser object.

Parameters:
browser The browser object.
button The affected button.
eventType The type of event.

void osgk_browser_event_mouse_move ( OSGK_Browser *  browser,
int  x,
int  y 
)

Send a mouse move event to a browser object.

Parameters:
browser The browser object.
x The X coordinate of the new mouse cursor position.
y The Y coordinate of the new mouse cursor position.

void osgk_browser_event_mouse_wheel ( OSGK_Browser *  browser,
OSGK_WheelAxis  axis,
OSGK_WheelDirection  direction 
)

Send a mouse wheel event to a browser object.

Parameters:
browser The browser object.
axis The axis of the scrolled wheel.
direction The scroll direction.

void osgk_browser_focus ( OSGK_Browser *  browser  ) 

Give focus to a browser object.

Proper focus management is required for some things such as e.g. proper caret display.

Parameters:
browser The browser object to give focus to.
Remarks:
Focus can be taken away by giving it to another browser object or clearing it with osgk_embedding_clear_focus().

OSGK_AntiAliasType osgk_browser_get_antialias ( OSGK_Browser *  browser  ) 

Get antialiasing type of a browser object.

Parameters:
browser The browser object.
Returns:
The antialiasing type.

int osgk_browser_get_preferred_dimensions ( OSGK_Browser *  browser,
int *  preferredWidth,
int *  preferredHeight,
int  maxWidth = -1 
)

Get the preferred dimensions of the displayed content.

The preferred dimensions are the dimensions at which no scrollbars have to be displayed and no lines have to be wrapped.

Parameters:
browser The browser object.
preferredWidth Returns the preferred width.
preferredHeight Returns the preferred height.
maxWidth Sets the maximum returned width. If -1 the width is unbounded.
Returns:
Whether obtaining the preferred width was successful. If not, the values referenced by preferredWidth and preferredHeight are unchanged.
Remarks:
The returned preferred width may be larger than maxWidth if scrollbars would be displayed. Thus, if providing a maximum width of 0, the returned preferred width is the minimal width at which no scrollbars are displayed.

int osgk_browser_get_user_data ( OSGK_Browser *  browser,
unsigned int  key,
void **  data 
)

Get a user data value from a browser object.

Parameters:
browser The browser object.
key The key by which the user data is identified.
data Pointer to the variable to receive the user data.
Returns:
Whether getting the user data value was successful (non-zero) or not (zero).

const unsigned char* osgk_browser_lock_data ( OSGK_Browser *  browser,
int *  isDirty = 0 
)

Lock the pixel data for a browser object.

Parameters:
browser The browser object.
isDirty Returns whether the browser is 'dirty' (ie the displayed data has changed since the last time the data was requested). Can be 0.
Returns:
A pointer to the pixel data, in BGRA byte order. Alpha is premultiplied.
Remarks:
  • You need to call osgk_browser_unlock_data() after finishing processing the returned data.
  • Multiple calls to osgk_browser_lock_data() for the same browser object are allowed; however, as long as the data is at least locked once it may not be updated and reflect changes to the displayed content.
  • The returned buffer has the dimensions of the browser object at the time of locking.

void osgk_browser_navigate ( OSGK_Browser *  browser,
const char *  uri 
)

Navigate a browser to a given URI.

Parameters:
browser The browser object.
uri The URI to navigate to. Encoding is UTF-8.

int osgk_browser_query_dirty ( OSGK_Browser *  browser  ) 

Query if a browser object is 'dirty' (if the displayed data has changed since the last time the data was requested).

Parameters:
browser The browser object.
Returns:
0 if data is unchanged, 1 if changed.

float osgk_browser_query_load_progress ( OSGK_Browser *  browser  ) 

Poll the loading progress.

Parameters:
browser The browser object.
Returns:
A float value between 0 and 1 where 0 means loading did not progress and 1 means loading is completed.
Remarks:
This function is intended for feedback display. To programmatically check whether a URI was loaded completely use osgk_brower_query_load_state().

OSGK_LoadState osgk_browser_query_load_state ( OSGK_Browser *  browser  ) 

Poll the loading state.

Parameters:
browser The browser object.
Returns:
The loading state (loading or completed).

void osgk_browser_resize ( OSGK_Browser *  browser,
int  width,
int  height 
)

Resize a browser object to the specified dimensions.

Parameters:
browser The browser object to resize.
width New width.
height New height.

void osgk_browser_set_antialias ( OSGK_Browser *  browser,
OSGK_AntiAliasType  aaType 
)

Set antialiasing type for a browser object.

Parameters:
browser The browser object.
aaType The antialiasing type.

int osgk_browser_set_user_data ( OSGK_Browser *  browser,
unsigned int  key,
void *  data,
int  overrideData = 0 
)

Set a user data value on a browser object.

Parameters:
browser The browser object.
key The key by which the user data is identified.
data The user data value.
overrideData Whether to replace the user data if some data was already associated with the given key. If non-zero, any existing data will replaced with the given value and success is returned. If zero, any existing data will not be replaced, and failure is returned when some data was already set.
Returns:
Whether setting the user data value was successful (non-zero) or not (zero).

void osgk_browser_unlock_data ( OSGK_Browser *  browser,
const unsigned char *  data 
)

Unlock the pixel data for a browser object obtained by an earlier osgk_browser_lock_data() call.

Parameters:
browser The browser object.
data The data pointer as returned by osgk_browser_lock_data().
Warning:
Do not use the data after this function!

Generated on Sun Nov 2 18:15:18 2008 for OffscreenGecko by  doxygen 1.5.4