wiki:GtkAPIProposal

Version 1 (modified by christian@twotoasts.de, 15 years ago) (diff)

--

/* Private structure type */ typedef struct WebiPrivate_ WebiPrivate;

/*

  • Main object structure */

typedef struct Webi_ Webi;

struct Webi_ {

GtkBin parent; /*< private >*/ WebiPrivate *_priv;

};

/ Structure used to set device type. */ typedef enum {

WEBI_DEVICE_TYPE_SCREEN, WEBI_DEVICE_TYPE_HANDHELD, WEBI_DEVICE_TYPE_PRINTER

} WebiDeviceType;

/ Rendering engine settings structure

  • Rendering engine settings structure. */

typedef struct WebiSettings_ WebiSettings; struct WebiSettings_ {

gboolean javascript_enabled; gboolean java_enabled; gboolean plugins_enabled; gboolean autoload_images; gfloat minimum_font_size; gfloat default_font_size; gfloat default_fixed_font_size; const gchar* default_text_encoding; const gchar* serif_font_family; const gchar* sans_serif_font_family; const gchar* fixed_font_family; const gchar* standard_font_family; const gchar* cursive_font_family; const gchar* fantasy_font_family; const gchar* user_agent_string;

/ Full url (including port) of the proxy to use. If NULL, empty (""), */ const gchar* http_proxy;

/ Rendering Mode */ const WebiDeviceType device_type;

};

typedef struct WebiLoadStatus_ WebiLoadStatus;

/ Type of the status message. */ typedef enum {

/ Report start loading a resource */ WEBI_LOADING_START, / Report progress in loading a resource */ WEBI_LOADING, / Report a successful resource load */ WEBI_LOADING_COMPLETE, / Report an error in resource loading. */ WEBI_LOADING_ERROR

} WebiStatus;

/ Status message. */ struct WebiLoadStatus_ {

/ Status of the loading process. */ WebiStatus status;

/ Number of files to download */ guint files;

/ Number of files received with Content-Length set*/ guint filesWithSize;

/ Number of files received */ guint ready;

/ Bytes available for resource. */ guint size;

/ Bytes received from resource. */ guint received;

/ Total size of the resources including those that didn't have

Content-Length set. */

guint totalSize;

/ Bytes received total. */ guint totalReceived;

/ Error code. */ gint statusCode;

};

typedef struct WebiPromptArgs_ WebiPromptArgs;

/ Type of message prompt if message prompt was an alert (ok button), confirm (yes/no) or input (textfield, ok, cancel).

*/

typedef enum {

/ alert (ok button)*/ WEBI_ALERT, /confirm (yes/no)*/ WEBI_CONFIRM, /or input (textfield, ok, cancel) */ WEBI_INPUT

} WebiPromptType;

/ Structure used to pass arguments of javascript prompt messages

*/

struct WebiPromptArgs_ {

/*<public>*/

/ Flag specifying if message prompt was an alert (ok button), confirm (yes/no) or

  • input (textfield, ok, cancel). */

WebiPromptType type;

/ The prompt message*/ const gchar* msg;

/ default input text.

  • if type == WEBI_INPUT contains default input text to be shown in input field */

const gchar* default_input;

/ text entered in the prompt textfield

  • should be set if type == WEBI_INPUT
  • string will be deallocated by signaller with g_free().
  • ie. there's an ownership change. */

gchar* out_input;

/ flag specifying if the button pressed was ok or cancel, yes or no

  • \TRUE means ok or yes
  • \FALSE means cancel or no */

gboolean out_ok_pressed;

};

typedef struct WebiAuthArgs_ WebiAuthArgs;

/ Structure used to pass arguments of javascript prompt messages

*/

struct WebiAuthArgs_ {

/*< public >*/ / realm of authentication */ const gchar* realm;

/ Out parameter containing username from user.

  • string will be deallocated by caller with g_free().
  • ie. there's an ownership change.*/

gchar* out_username;

/ Out parameter containing password from user.

  • string will be deallocated by caller with g_free()
  • ie. there's an ownership change. */

gchar* out_password;

/ flag specifying if the button pressed was ok or cancel

  • \TRUE means ok
  • \FALSE otherwise */

gboolean out_ok_pressed;

};

typedef struct WebiCookie_ WebiCookie;

/ Structure used to pass arguments of javascript prompt messages

*/

struct WebiCookie_ {

/*<public>*/

/ Whole cookie */ const gchar* cookie;

/ Cookie name */ const gchar* name;

/ Cookie value */ const gchar* value;

/* Cookie comment */ const gchar* comment;

/* Cookie domain */ const gchar* domain;

/* Cookie TTL */ const gchar* maxAge;

/* Cookie path */ const gchar* path;

/* Is cookie secure? */ gboolean secure;

/* Cookie-specification version. */ gint version;

/ Out argument - user accepted the cookie. */ gboolean out_accept_cookie;

};

typedef struct WebiWindowProperties_ WebiWindowProperties;

/ Structure used to pass arguments of javascript prompt messages

*/

struct WebiWindowProperties_ {

/*<public>*/ /* Are toolbars wisible. */ gboolean toolbarsVisible;

/* is status bar visible. */ gboolean statusBarVisible;

/* are scroll bars visible. */ gboolean scrollbarsVisible;

/* Is window resizable. */ gboolean isResizable;

};

/ Structure used to get and set window size and content rectangle size. */ typedef enum {

WEBI_CONTENT_SIZE, WEBI_WINDOW_SIZE

} WebiWindowSize;

/*

  • Class definition */

typedef struct WebiClass_ WebiClass; struct WebiClass_ {

GtkBinClass parent;

/*signals*/

/ Location change indication signal.

  • use \webi_get_location() to get the url string
  • @emited when current page changes.
  • @param self the engine which sent the signal */

void (* location) (Webi * self);

/ Title change indication signal.

  • use \webi_get_title() to get the title string
  • @emited when title of current page changes.
  • @param self the engine which sent the signal */

void (* title) (Webi * self);

/ Load start indication signal.

  • @emited when page loading is started
  • @param self the engine which sent the signal */

void (* load_start) (Webi * self);

/ Load start indication signal.

  • @emited when page loading is stopped.
  • @emited on error
  • @param self the engine which sent the signal */

void (* load_stop) (Webi * self);

/ Set cookie indication signal.

  • @emited when a cookie is received from network
  • @param self the engine which sent the signal
  • @param cookie The actual cookie received.
  • @return \FALSE if don't allow cookie to be set
  • \TRUE if cookie should be set */

gboolean (* set_cookie) (Webi * self, WebiCookie * cookie);

/ javascript status change indication signal

  • use \webi_get_status_text() to get the status string *
  • @emited when javascript status changes.
  • @param self the engine which sent the signal */

void (* status_text) (Webi * self);

/ Page load status change indication signal

*

  • @emited when page load status changes.
  • @param self the engine which sent the signal
  • @param status status of the engine. */

void (* status) (Webi * self, WebiLoadStatus * status);

/ javascript prompt and alert request signal

  • must be synchronous
  • @emited when javascript generates an alert
  • @emited when javascript generates an prompt *
  • @param self the engine which sent the signal
  • @param args used to pass information between browser and engine (in and out)
  • see #WebiPromptAgs */

void (* req_js_prompt) (Webi *self, WebiPromptArgs* args);

/ HTTP Auth

  • must be synchronous
  • @emited when javascript generates an alert
  • @emited when javascript generates an prompt *
  • @param self the engine which sent the signal
  • @param args used to pass information between browser and engine (in and out)
  • see #WebiPromptAgs */

void (* req_auth_prompt) (Webi *self, WebiAuthArgs* args);

/ javascript/html new window request signal

  • must be synchronous *
  • @emited when javascript requests to create a new window
  • @emited when html link contains target="_blank" -attribute *
  • @param self the engine which sent the signal
  • @param url the URL string loading by newengine.
  • @return newengine The new engine of the new window
  • or \NULL if new window creation is not allowed */

Webi * (* req_new_window) (Webi *self, const gchar *url);

void (* show_window) (Webi *self, WebiWindowProperties* features); void (* close_window) (Webi *self);

void (* set_window_properties) (Webi *self, WebiWindowProperties* features); void (* get_window_size) (Webi *self, WebiWindowSize * type, GtkAllocation * size); void (* set_window_size) (Webi *self, WebiWindowSize * type, GtkRequisition * size);

/ Set device type signal

  • must be synchronous *
  • @emited when user wants to change device type used in rendering and
  • style sheet selection
  • @param self the engine which sent the signal
  • @param newDeviceType The new device type of current window */

void (* set_device_type) (Webi *self, WebiDeviceType type);

/ Get device type signal

  • must be synchronous *
  • @emited when user wants to change device type used in rendering and
  • style sheet selection
  • @param self the engine which sent the signal
  • @param newDeviceType The new device type of current window */

WebiDeviceType (* get_device_type) (Webi *self);

void (* mouse_over) (Webi *self, const gchar* link_title, const gchar* link_label, const gchar* link_url, const gchar* link_target);

/ selection change signal*/ void (* selection) (Webi *self);

#if 0

/* not implemented at the moment */ void (* req_file_attach) (Webi *self); void (* file_upload_finished) (Webi *self); void (* file_upload_finished) (Webi *self);

#endif

};

/*

  • Public methods */

/ Returns GObject type for KHTML html renderer class

  • Returns GObject type for KHTML html renderer class. *
  • @return type for KHTML html renderer class */

GType webi_get_type ();

/ Creates new html rendering engine

  • Creates new html rendering engine widget. To be able to view web pages,
  • add returned widget to a container and show the container. *
  • @return html rendering engine widget */

GtkWidget * webi_new ();

/ Starts loading of a new url

  • Starts loading of a new url. Loading is asynchronous. *
  • @emit "load-start" signal on start
  • @emit "load-stop" signal when loading stops, ie. succesfully loaded page, or error
  • @param self the engine to use
  • @param url the url to load */

void webi_load_url (Webi * self, const gchar * url);

/ Reloads current url

  • reloads current url */

void webi_refresh (Webi * self);

/ Cancels the load currently in progress, if any

  • Cancels the load currently in progress, if any.
  • @emit "load-stop" *
  • @param self the engine to use */

void webi_stop_load (Webi * self);

/ Checks the browsing history position relative to the beginning of the history

  • Checks if the engine is at the beginning of browsing history.
  • @return \TRUE if browsing history has previous elements
  • \FALSE otherwise */

gboolean webi_can_go_back (Webi * self);

/ Checks the browsing history position relative to the end of the history

  • Checks if the engine is at the end of browsing history.
  • @return \TRUE if browsing history has successive elements
  • \FALSE otherwise */

gboolean webi_can_go_forward (Webi * self);

/ Directs browser engine to the previous url in the browsing history

  • Directs browser engine to the previous url in the browsing history.
  • @emit "load-start" see \webi_load_url
  • @emit "load-stop" see \webi_load_url */

void webi_go_back (Webi * self);

/ Directs browser engine to the next url in the browsing history

  • Directs browser engine to the next url in the browsing history. *
  • @emit "load-start" see \webi_load_url
  • @emit "load-stop" see \webi_load_url */

void webi_go_forward (Webi * self);

/ Returns the url of the currently loaded page

  • Returns the url of the currently loaded page.
  • The string contains the full url used, including
  • the protocol. It can be absolute or relative.
  • The string must not be freed (const). *
  • @return the url string of the currently loaded page. */

const gchar* webi_get_location (Webi * self);

/ Returns the title of the currently loaded page

  • Returns the title of the currently loaded page.
  • If the page contains a frameset, title is the title of the
  • frameset. *
  • @return the title of the currently loaded page. */

const gchar* webi_get_title (Webi * self);

/ Returns a status string set by javascript

  • Returns a string that javascript has set to be used
  • usually in the statusbar of the browser. *
  • @return javascript status string */

const gchar* webi_get_status_text (Webi * self);

/ Returns internal representation of the engine

  • Returns internal representation of the engine.
  • Can be used in C++ code. Exposes the public NRCore api
  • to the user. This may be needed if certain functionality
  • is not implemented in C interface.
  • usage not recommended
  • Used with:
  • OSBB::Bridge* engine = 0;
  • Webi* khtml_engine = webi_new();
  • engine = static_cast<OSB::Bridge*>(webi_get_internal (engine)); * */

void* webi_get_internal (Webi * self);

/ Sets the settings of the rendering engine

  • Sets the settings of the rendering engine. * */

void webi_set_settings (Webi * self, const WebiSettings* settings);

/ Prints the internal render tree of the engine.

*

  • Can be used in C++ debug code. This
  • usage not recommended */

const gchar* webi_render_tree (Webi * self);

/ Toggles the emission of internal constructed load status messages

  • Sets the emission of internal constructed load status messages
  • Signalö emitted is status-text *
  • @param flag \TRUE if you want to receive internal status messages for loading \FALSE if not

*/ void webi_set_emit_internal_status (Webi * self, gboolean flag);

/ Sets the device type used for current window.

*

  • @param self the engine which sent the signal
  • @param newDeviceType The new device type of current window */

void webi_set_device_type (Webi * self, WebiDeviceType device);

/ Gets the device type used for current window.

*

  • @param self the engine which sent the signal
  • @param newDeviceType The new device type of current window */

WebiDeviceType webi_get_device_type (Webi * self);

void webi_set_group (Webi* self, const gchar* group);

const gchar* webi_get_group (Webi* self);

void webi_set_text_multiplier (Webi* self, gfloat multiplier); gfloat webi_get_text_multiplier (Webi* self);

gboolean webi_find (Webi* self, const gchar* text, gboolean case_sensitive, gboolean dir_down);

/ Gets the active selection.

  • The returned string must be freed with g_free()
  • Returns "" if selection is not active */

gchar* webi_get_current_selection_as_text(Webi* self);

/ Gets the engine user agent string.

  • The returned string can be used to construct browser-specific
  • user-agent strings */

const gchar* webi_get_engine_user_agent_string ();

#ifdef cplusplus } #endif /* cplusplus */

#endif