wiki:GtkAPIProposal

Version 2 (modified by bdash@webkit.org, 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