include/OffscreenGecko/embedding.h File Reference

Embedding object. More...

#include "baseobj.h"
#include "componentmgr.h"
#include "geckomem.h"
#include "string.h"

Go to the source code of this file.

Namespaces
namespace	OSGK
Classes
struct	OSGK::Embedding
	OffscreenGecko embedding object, the 'mother' of all OffscreenGecko objects. More...
struct	OSGK::EmbeddingOptions
	Embedding options object. More...
struct	OSGK_Embedding
	OffscreenGecko embedding object, the 'mother' of all OffscreenGecko objects. More...
struct	OSGK_EmbeddingOptions
	Embedding options object. More...
Defines
#define	OSGK_API_VERSION   1
	The version number of the OffscreenGecko API.
Enumerations
enum	{ jsgPrivileged = 1 }
	Flags for JavaScript global registration. More...
Functions
static OSGK_Embedding *	osgk_embedding_create (OSGK_GeckoResult *geckoResult=0)
	Create a new embedding object.
static OSGK_Embedding *	osgk_embedding_create_with_options (OSGK_EmbeddingOptions *options, OSGK_GeckoResult *geckoResult=0)
	Create a new embedding object.
OSGK_ComponentMgr *	osgk_embedding_get_component_mgr (OSGK_Embedding *embedding)
	Get Gecko component manager wrapper.
nsIComponentManager *	osgk_embedding_get_gecko_component_manager (OSGK_Embedding *embedding)
	Get interface for actual Gecko component manager.
nsIComponentRegistrar *	osgk_embedding_get_gecko_component_registrar (OSGK_Embedding *embedding)
	Get interface for actual Gecko component registrar.
OSGK_GeckoMem *	osgk_embedding_get_gecko_mem (OSGK_Embedding *embedding)
	Get Gecko memory allocator object.
nsIServiceManager *	osgk_embedding_get_gecko_service_manager (OSGK_Embedding *embedding)
	Get interface for actual Gecko service manager.
void	osgk_embedding_options_add_components_path (OSGK_EmbeddingOptions *options, const char *path)
	Add a path with application-specific XPCOM components and type libraries.
void	osgk_embedding_options_add_search_path (OSGK_EmbeddingOptions *options, const char *path)
	Add a path to be searched for XULrunner upon initialization.
OSGK_EmbeddingOptions *	osgk_embedding_options_create (void)
	Create a new embedding options object.
void	osgk_embedding_options_set_profile_dir (OSGK_EmbeddingOptions *options, const char *profileDir, const char *localProfileDir=0)
	Set the profile directory used by XULrunner.
int	osgk_embedding_register_js_global (OSGK_Embedding *embedding, const char *name, const char *contractID, unsigned int flags, OSGK_String **previousContract=0, OSGK_GeckoResult *geckoResult=0)
	Register a global object for JavaScript scripting.
Focus helpers
void	osgk_embedding_clear_focus (OSGK_Embedding *embedding)
	Clear focus so no browser is focused.
int	osgk_embedding_get_auto_focus (OSGK_Embedding *embedding)
	Get whether auto-focus is enabled.
void	osgk_embedding_set_auto_focus (OSGK_Embedding *embedding, int autoFocus)
	Enable/disables "auto-focus".

---

Detailed Description

Embedding object.

---

Define Documentation

#define OSGK_API_VERSION   1

The version number of the OffscreenGecko API.

---

Enumeration Type Documentation

anonymous enum

Flags for JavaScript global registration.

Enumerator:

jsgPrivileged

Global is only accessible from privileged scripts.

---

Function Documentation

void osgk_embedding_clear_focus

(

OSGK_Embedding *

embedding

)

Clear focus so no browser is focused.

Proper clearing of focus is needed for some things such as e.g. preventing caret displaying.

Parameters:

embedding

The embedding object.

static OSGK_Embedding* osgk_embedding_create

(

OSGK_GeckoResult *

geckoResult = 0

)

[inline, static]

Create a new embedding object.

An embedding is the 'mother' of all OffscreenGecko objects.

Parameters:

geckoResult

Returns the result code from Gecko. Can be 0.

static OSGK_Embedding* osgk_embedding_create_with_options	(	OSGK_EmbeddingOptions *	options,
		OSGK_GeckoResult *	geckoResult = 0
	)			[inline, static]

Create a new embedding object.

An embedding is the 'mother' of all OffscreenGecko objects.

Parameters:

	options	A set of options for the embedding to be created.
	geckoResult	Returns the result code from Gecko. Can be 0.

int osgk_embedding_get_auto_focus

(

OSGK_Embedding *

embedding

)

Get whether auto-focus is enabled.

Parameters:

embedding

The embedding object.

Returns:

Whether auto-focus is enabled (non-null) or disabled (null).

See also:

osgk_embedding_set_auto_focus

OSGK_ComponentMgr* osgk_embedding_get_component_mgr

(

OSGK_Embedding *

embedding

)

Get Gecko component manager wrapper.

Parameters:

embedding

Embedding object.

Returns:

Pointer to Gecko component manager wrapper.

Remarks:

The returned object has no reference implicitly added.

nsIComponentManager* osgk_embedding_get_gecko_component_manager

(

OSGK_Embedding *

embedding

)

Get interface for actual Gecko component manager.

Parameters:

embedding

Embedding object.

Returns:

Interface of Gecko component manager.

Remarks:

The returned interface has no reference implicitly added.

nsIComponentRegistrar* osgk_embedding_get_gecko_component_registrar

(

OSGK_Embedding *

embedding

)

Get interface for actual Gecko component registrar.

Parameters:

embedding

Embedding object.

Returns:

Interface of Gecko component registrar.

Remarks:

The returned interface has no reference implicitly added.

OSGK_GeckoMem* osgk_embedding_get_gecko_mem

(

OSGK_Embedding *

embedding

)

Get Gecko memory allocator object.

Parameters:

embedding

Embedding object.

Returns:

Pointer to Gecko memory allocator object.

Remarks:

The returned object has no reference implicitly added.

nsIServiceManager* osgk_embedding_get_gecko_service_manager

(

OSGK_Embedding *

embedding

)

Get interface for actual Gecko service manager.

Parameters:

embedding

Embedding object.

Returns:

Interface of Gecko service manager.

Remarks:

The returned interface has no reference implicitly added.

void osgk_embedding_options_add_components_path	(	OSGK_EmbeddingOptions *	options,
		const char *	path
	)

Add a path with application-specific XPCOM components and type libraries.

Parameters:

	options	The embedding options object.
	path	Components path to add.

void osgk_embedding_options_add_search_path	(	OSGK_EmbeddingOptions *	options,
		const char *	path
	)

Add a path to be searched for XULrunner upon initialization.

Parameters:

	options	The embedding options object.
	path	Search path to add.

OSGK_EmbeddingOptions* osgk_embedding_options_create

(

void

)

Create a new embedding options object.

Encapsulates parameters for configuring creation and initialization of the embedding environment.

void osgk_embedding_options_set_profile_dir	(	OSGK_EmbeddingOptions *	options,
		const char *	profileDir,
		const char *	localProfileDir = 0
	)

Set the profile directory used by XULrunner.

This directory stores persistent data such as caches and preferences.

Parameters:

	options	The embedding options object.
	profileDir	The profile directory.
	localProfileDir	Optionally the "local" profile directory, "local" in the sense of machine-local (as opposed to the "normal" profile directory which is assumed to be possibly accessed via network). If given, the "local" directory is used to store data which would be rather large for network transfer and isn't required to "follow" the user around (such as caches). If not given the "normal" profile directory is used for such data as well.

Remarks:

A profile directory is optional; XULrunner works without, but obviously preferences can't be stored, and startup may be slower due the unavailability of some caches (especially when custom components are used). The directory will be created if needed.

int osgk_embedding_register_js_global	(	OSGK_Embedding *	embedding,
		const char *	name,
		const char *	contractID,
		unsigned int	flags,
		OSGK_String **	previousContract = 0,
		OSGK_GeckoResult *	geckoResult = 0
	)

Register a global object for JavaScript scripting.

Parameters:

	embedding	Embedding object.
	name	Identifier of the global object.
	contractID	Contract ID used to instantiate the object.
	flags	Registration flags.
	previousContract	Optionally receives a previously registered contract ID for the given identifier.
	geckoResult	Optionally receives the Gecko result code for the registration.

Returns:

Whether the registration was successful (non-null) or not (null).

See also:

jsgPrivileged

void osgk_embedding_set_auto_focus	(	OSGK_Embedding *	embedding,
		int	autoFocus
	)

Enable/disables "auto-focus".

Auto-focus means that a browser object will get focus as soon as any event is sent to it. Proper focus handling is needed for some things such as e.g. caret handling; automatically giving the focus to a browser object receiving an event is usually a sufficient strategy to prevent oddities arising from wrong or lacking focus handling without burdening you, the user, too much. Auto-focus is by default on.

Parameters:

	embedding	The embedding object.
	autoFocus	Whether to enable(non-null) or disable(null) the auto-focus feature.

---