Changes between Version 4 and Version 5 of GtkAPIProposal


Ignore:
Timestamp:
Apr 25, 2007 12:24:21 PM (15 years ago)
Author:
Kimmo Kinnunen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GtkAPIProposal

    v4 v5  
    3838
    3939----
    40 {{{
    41 /* Private structure type */
    42 typedef struct WebiPrivate_ WebiPrivate;
    4340
    44 /*
    45  * Main object structure
    46  */
    47 typedef struct Webi_ Webi;
     41The above api is now implemented in parts for gdk port. See following url for building instructions:
    4842
    49 struct Webi_ {
    50   GtkBin __parent__;
    51   /*< private >*/
    52   WebiPrivate *_priv;
    53 };
     43http://gtk-webcore.svn.sourceforge.net/viewvc/*checkout*/gtk-webcore/trunk/WebkitGtk/README
    5444
    55 /** Structure used to set device type. */
    56 typedef enum {
    57   WEBI_DEVICE_TYPE_SCREEN,
    58   WEBI_DEVICE_TYPE_HANDHELD,
    59   WEBI_DEVICE_TYPE_PRINTER
    60 } WebiDeviceType;
    61 
    62 /** Rendering engine settings structure
    63  *  Rendering engine settings structure.
    64  */
    65 
    66 typedef struct WebiSettings_ WebiSettings;
    67 struct WebiSettings_ {
    68   gboolean javascript_enabled;
    69   gboolean java_enabled;
    70   gboolean plugins_enabled;
    71   gboolean autoload_images;
    72   gfloat minimum_font_size;
    73   gfloat default_font_size;
    74   gfloat default_fixed_font_size;
    75   const gchar* default_text_encoding;
    76   const gchar* serif_font_family;
    77   const gchar* sans_serif_font_family;
    78   const gchar* fixed_font_family;
    79   const gchar* standard_font_family;
    80   const gchar* cursive_font_family;
    81   const gchar* fantasy_font_family;
    82   const gchar* user_agent_string;
    83 
    84   /** Full url (including port) of the proxy to use. If NULL, empty (""), */
    85   const gchar* http_proxy;
    86 
    87   /** Rendering Mode */
    88   const WebiDeviceType device_type;
    89 };
    90 
    91 typedef struct WebiLoadStatus_ WebiLoadStatus;
    92 
    93 /** Type of the status message. */
    94 typedef enum  {
    95         /** Report start loading a resource */
    96         WEBI_LOADING_START,
    97         /** Report progress in loading a resource */
    98         WEBI_LOADING,
    99         /** Report a successful resource load */
    100         WEBI_LOADING_COMPLETE,
    101         /** Report an error in resource loading. */
    102         WEBI_LOADING_ERROR
    103 } WebiStatus;
    104 
    105 /** Status message. */
    106 struct WebiLoadStatus_ {
    107   /** Status of the loading process. */
    108   WebiStatus status;
    109 
    110   /** Number of files to download */
    111   guint files;
    112 
    113   /** Number of files received with Content-Length set*/
    114   guint filesWithSize;
    115 
    116   /** Number of files received */
    117   guint ready;
    118 
    119   /** Bytes available for resource. */
    120   guint size;
    121 
    122   /** Bytes received from resource. */
    123   guint received;
    124 
    125   /** Total size of the resources including those that didn't have
    126       Content-Length set. */
    127   guint totalSize;
    128 
    129   /** Bytes received total. */
    130   guint totalReceived;
    131 
    132   /** Error code. */
    133   gint statusCode;
    134 };
    135 
    136 
    137 
    138 typedef struct WebiPromptArgs_ WebiPromptArgs;
    139 
    140 
    141 /** Type of message prompt if message prompt was an alert (ok button), confirm (yes/no) or input (textfield, ok, cancel).
    142  */
    143 typedef enum {
    144         /** alert (ok button)*/
    145         WEBI_ALERT,
    146         /**confirm (yes/no)*/
    147         WEBI_CONFIRM,
    148         /**or input (textfield, ok, cancel) */
    149         WEBI_INPUT
    150 } WebiPromptType;
    151 
    152 /** Structure used to pass arguments of javascript prompt messages
    153  */
    154 struct WebiPromptArgs_
    155 {
    156   /*<public>*/
    157 
    158   /** Flag specifying if message prompt was an alert (ok button), confirm (yes/no) or
    159    *  input (textfield, ok, cancel). */
    160   WebiPromptType type;
    161 
    162   /** The prompt message*/
    163   const gchar* msg;
    164 
    165   /**  default input text.
    166    *  if type == WEBI_INPUT contains default input text to be shown in input field */
    167   const gchar* default_input;
    168 
    169   /**  text entered in the prompt textfield
    170    *   should be set if type == WEBI_INPUT
    171    *  string will be deallocated by signaller with g_free().
    172    *  ie. there's an ownership change. */
    173   gchar* out_input;
    174 
    175   /** flag specifying if the button pressed was ok or cancel, yes or no
    176    * \TRUE means ok or yes
    177    * \FALSE means cancel or no
    178    */
    179   gboolean out_ok_pressed;
    180 };
    181 
    182 typedef struct WebiAuthArgs_ WebiAuthArgs;
    183 
    184 /** Structure used to pass arguments of javascript prompt messages
    185  */
    186 struct WebiAuthArgs_
    187 {
    188   /*< public >*/
    189   /** realm of authentication */
    190   const gchar* realm;
    191 
    192   /** Out parameter containing username from user.
    193    *  string will be deallocated by caller with g_free().
    194    *  ie. there's an ownership change.*/
    195   gchar* out_username;
    196 
    197   /** Out parameter containing password from user.
    198    *  string will be deallocated by caller with g_free()
    199    *  ie. there's an ownership change. */
    200 
    201   gchar* out_password;
    202 
    203   /** flag specifying if the button pressed was ok or cancel
    204    * \TRUE means ok
    205    * \FALSE otherwise  */
    206   gboolean out_ok_pressed;
    207 };
    208 
    209 typedef struct WebiCookie_ WebiCookie;
    210 
    211 /** Structure used to pass arguments of javascript prompt messages
    212  */
    213 struct WebiCookie_
    214 {
    215   /*<public>*/
    216 
    217   /** Whole cookie */
    218   const gchar* cookie;
    219 
    220   /** Cookie name */
    221   const gchar* name;
    222 
    223   /** Cookie value */
    224   const gchar* value;
    225 
    226   /* Cookie comment */
    227   const gchar* comment;
    228 
    229   /* Cookie domain */
    230   const gchar* domain;
    231 
    232   /* Cookie TTL */
    233   const gchar* maxAge;
    234 
    235   /* Cookie path */
    236   const gchar* path;
    237 
    238   /* Is cookie secure? */
    239   gboolean secure;
    240 
    241   /* Cookie-specification version. */
    242   gint version;
    243 
    244   /** Out argument - user accepted the cookie. */
    245   gboolean out_accept_cookie;
    246 };
    247 
    248 typedef struct WebiWindowProperties_ WebiWindowProperties;
    249 
    250 /** Structure used to pass arguments of javascript prompt messages
    251  */
    252 struct WebiWindowProperties_
    253 {
    254   /*<public>*/
    255   /* Are toolbars wisible. */
    256   gboolean toolbarsVisible;
    257 
    258   /* is status bar visible. */
    259   gboolean statusBarVisible;
    260 
    261   /* are scroll bars visible. */
    262   gboolean scrollbarsVisible;
    263 
    264   /* Is window resizable. */
    265   gboolean isResizable;
    266 };
    267 
    268 /** Structure used to get and set window size and content rectangle size. */
    269 typedef enum {
    270   WEBI_CONTENT_SIZE,
    271   WEBI_WINDOW_SIZE
    272 } WebiWindowSize;
    273 
    274 /*
    275  * Class definition
    276  */
    277 typedef struct WebiClass_ WebiClass;
    278 struct WebiClass_ {
    279   GtkBinClass __parent__;
    280 
    281   /*signals*/
    282 
    283 
    284   /** Location change indication signal.
    285    * use \webi_get_location() to get the url string
    286    * @emited when current page changes.
    287    * @param self the engine which sent the signal
    288    */
    289   void (* location) (Webi * self);
    290 
    291   /** Title change indication signal.
    292    * use \webi_get_title() to get the title string
    293    * @emited when title of current page changes.
    294    * @param self the engine which sent the signal
    295    */
    296   void (* title) (Webi * self);
    297 
    298   /** Load start indication signal.
    299    * @emited when page loading is started
    300    * @param self the engine which sent the signal
    301    */
    302   void (* load_start) (Webi * self);
    303 
    304   /** Load start indication signal.
    305    * @emited when page loading is stopped.
    306    * @emited on error
    307    * @param self the engine which sent the signal
    308    */
    309   void (* load_stop) (Webi * self);
    310 
    311   /** Set cookie indication signal.
    312    * @emited when a cookie is received from network
    313    * @param self the engine which sent the signal
    314    * @param cookie The actual cookie received.
    315    * @return \FALSE if don't allow cookie to be set
    316    *         \TRUE if cookie should be set
    317    */
    318   gboolean (* set_cookie) (Webi * self, WebiCookie * cookie);
    319 
    320   /** javascript status change indication signal
    321    * use \webi_get_status_text() to get the status string
    322    *
    323    * @emited when javascript status changes.
    324    * @param self the engine which sent the signal
    325    */
    326   void (* status_text) (Webi * self);
    327 
    328   /** Page load status change indication signal
    329    *
    330    * @emited when page load status changes.
    331    * @param self the engine which sent the signal
    332    * @param status status of the engine.
    333    */
    334   void (* status) (Webi * self, WebiLoadStatus * status);
    335 
    336   /** javascript prompt and alert request signal
    337    * must be synchronous
    338    * @emited when javascript generates an alert
    339    * @emited when javascript generates an prompt
    340    *
    341    * @param self the engine which sent the signal
    342    * @param args used to pass information between browser and engine (in and out)
    343    *        see #WebiPromptAgs
    344    */
    345   void (* req_js_prompt) (Webi *self, WebiPromptArgs* args);
    346 
    347   /** HTTP Auth
    348    * must be synchronous
    349    * @emited when javascript generates an alert
    350    * @emited when javascript generates an prompt
    351    *
    352    * @param self the engine which sent the signal
    353    * @param args used to pass information between browser and engine (in and out)
    354    *        see #WebiPromptAgs
    355    */
    356   void (* req_auth_prompt) (Webi *self, WebiAuthArgs* args);
    357 
    358   /** javascript/html new window request signal
    359    * must be synchronous
    360    *
    361    * @emited when javascript requests to create a new window
    362    * @emited when html link contains target="_blank" -attribute   *
    363    * @param self the engine which sent the signal
    364    * @param url the URL string loading by newengine.
    365    * @return newengine The new engine of the new window
    366    *        or \NULL if new window creation is not allowed
    367    */
    368   Webi * (* req_new_window) (Webi *self, const gchar *url);
    369 
    370   void (* show_window) (Webi *self, WebiWindowProperties* features);
    371   void (* close_window) (Webi *self);
    372 
    373   void (* set_window_properties) (Webi *self, WebiWindowProperties* features);
    374   void (* get_window_size) (Webi *self, WebiWindowSize * type, GtkAllocation * size);
    375   void (* set_window_size) (Webi *self, WebiWindowSize * type, GtkRequisition * size);
    376 
    377 
    378   /** Set device type signal
    379    * must be synchronous
    380    *
    381    * @emited when user wants to change device type used in rendering and
    382    *         style sheet selection
    383    * @param self the engine which sent the signal
    384    * @param newDeviceType The new device type of current window
    385    */
    386   void (* set_device_type) (Webi *self, WebiDeviceType type);
    387 
    388   /** Get device type signal
    389    * must be synchronous
    390    *
    391    * @emited when user wants to change device type used in rendering and
    392    *         style sheet selection
    393    * @param self the engine which sent the signal
    394    * @param newDeviceType The new device type of current window
    395    */
    396   WebiDeviceType (* get_device_type) (Webi *self);
    397 
    398   void (* mouse_over) (Webi *self, const gchar* link_title, const gchar* link_label, const gchar* link_url, const gchar* link_target);
    399 
    400   /** selection change signal*/
    401   void (* selection) (Webi *self);
    402 #if 0
    403   /* not implemented at the moment */
    404   void (* req_file_attach) (Webi *self);
    405   void (* file_upload_finished) (Webi *self);
    406   void (* file_upload_finished) (Webi *self);
    407 #endif
    408 
    409 };
    410 
    411 
    412 /*
    413  * Public methods
    414  */
    415 
    416 
    417 /** Returns GObject type for KHTML html renderer class
    418  * Returns GObject type for KHTML html renderer class.
    419  *
    420  * @return type for KHTML html renderer class
    421  */
    422 GType webi_get_type ();
    423 
    424 
    425 /** Creates new html rendering engine
    426  * Creates new html rendering engine widget. To be able to view web pages,
    427  * add returned widget to a container and show the container.
    428  *
    429  * @return html rendering engine widget
    430  */
    431 GtkWidget * webi_new ();
    432 
    433 /** Starts loading of a new url
    434  * Starts loading of a new url. Loading is asynchronous.
    435  *
    436  * @emit "load-start" signal on start
    437  * @emit "load-stop"  signal when loading stops, ie. succesfully loaded page, or error
    438  * @param self the engine to use
    439  * @param url the url to load
    440  */
    441 void webi_load_url (Webi * self, const gchar * url);
    442 
    443 /** Reloads current url
    444  * reloads current url
    445  */
    446 void webi_refresh (Webi * self);
    447 
    448 /** Cancels the load currently in progress, if any
    449  * Cancels the load currently in progress, if any.
    450  * @emit "load-stop"
    451  *
    452  * @param self the engine to use
    453  */
    454 void webi_stop_load (Webi * self);
    455 
    456 /** Checks the browsing history position relative to the beginning of the history
    457  * Checks if the engine is at the beginning of browsing history.
    458  * @return \TRUE if browsing history has previous elements
    459  *         \FALSE otherwise
    460  */
    461 gboolean webi_can_go_back (Webi * self);
    462 
    463 
    464 /** Checks the browsing history position relative to the end of the history
    465  * Checks if the engine is at the end of browsing history.
    466  * @return \TRUE if browsing history has successive elements
    467  *         \FALSE otherwise
    468  */
    469 gboolean webi_can_go_forward (Webi * self);
    470 
    471 /** Directs browser engine to the previous url in the browsing history
    472  * Directs browser engine to the previous url in the browsing history.
    473  * @emit "load-start" see \webi_load_url
    474  * @emit "load-stop" see \webi_load_url
    475  */
    476 void webi_go_back (Webi * self);
    477 
    478 /** Directs browser engine to the next url in the browsing history
    479  * Directs browser engine to the next url in the browsing history.
    480  *
    481  * @emit "load-start" see \webi_load_url
    482  * @emit "load-stop" see \webi_load_url
    483  */
    484 void webi_go_forward (Webi * self);
    485 
    486 /** Returns the url of the currently loaded page
    487  * Returns the url of the currently loaded page.
    488  * The string contains the full url used, including
    489  * the protocol. It can be absolute or relative.
    490  * The string must not be freed (const).
    491  *
    492  * @return  the url string of the currently loaded page.
    493  */
    494 const gchar* webi_get_location (Webi * self);
    495 
    496 /** Returns the title of the currently loaded page
    497  * Returns the title of the currently loaded page.
    498  * If the page contains a frameset, title is the title of the
    499  * frameset.
    500  *
    501  * @return the title of the currently loaded page.
    502  */
    503 const gchar* webi_get_title (Webi * self);
    504 
    505 /** Returns a status string set by javascript
    506  * Returns a string that javascript has set to be used
    507  * usually in the statusbar of the browser.
    508  *
    509  * @return javascript status string
    510  */
    511 const gchar* webi_get_status_text (Webi * self);
    512 
    513 /** Returns internal representation of the engine
    514  * Returns internal representation of the engine.
    515  * Can be used in C++ code. Exposes the public NRCore api
    516  * to the user. This may be needed if certain functionality
    517  * is not implemented in C interface.
    518  * usage not recommended
    519  * Used with:
    520  * OSBB::Bridge* engine = 0;
    521  * Webi* khtml_engine = webi_new();
    522  * engine = static_cast<OSB::Bridge*>(webi_get_internal (engine));
    523  *
    524  */
    525 void* webi_get_internal (Webi * self);
    526 
    527 /** Sets the settings of the rendering engine
    528  * Sets the settings of the rendering engine.
    529  *
    530  */
    531 void webi_set_settings (Webi * self, const WebiSettings* settings);
    532 
    533 /**  Prints the internal render tree of the engine.
    534  *
    535  * Can be used in C++ debug code. This
    536  * usage not recommended
    537  */
    538 const gchar* webi_render_tree (Webi * self);
    539 
    540 /** Toggles the emission of internal constructed load status messages
    541  * Sets the emission of internal constructed load status messages
    542  * Signalö emitted is status-text
    543  *
    544  * @param flag \TRUE if you want to receive internal status messages
    545  for loading
    546  \FALSE if not
    547 */
    548 void webi_set_emit_internal_status (Webi * self, gboolean flag);
    549 
    550 
    551 /** Sets the device type used for current window.
    552  *
    553  * @param self the engine which sent the signal
    554  * @param newDeviceType The new device type of current window
    555  */
    556 void webi_set_device_type (Webi * self, WebiDeviceType device);
    557 
    558 /** Gets the device type used for current window.
    559  *
    560  * @param self the engine which sent the signal
    561  * @param newDeviceType The new device type of current window
    562  */
    563 WebiDeviceType webi_get_device_type (Webi * self);
    564 
    565 
    566 void webi_set_group (Webi* self, const gchar* group);
    567 
    568 const gchar* webi_get_group (Webi* self);
    569 
    570 void webi_set_text_multiplier (Webi* self, gfloat multiplier);
    571 gfloat webi_get_text_multiplier (Webi* self);
    572 
    573 gboolean webi_find (Webi* self, const gchar* text, gboolean case_sensitive, gboolean dir_down);
    574 
    575 /** Gets the active selection.
    576  * The returned string must be freed with g_free()
    577  * Returns "" if selection is not active
    578  */
    579 gchar* webi_get_current_selection_as_text(Webi* self);
    580 
    581 /** Gets the engine user agent string.
    582  * The returned string can be used to construct browser-specific
    583  * user-agent strings
    584  */
    585 const gchar* webi_get_engine_user_agent_string ();
    586 
    587 #ifdef __cplusplus
    588 }
    589 #endif /* __cplusplus */
    590 
    591 #endif
    592 }}}