diff options
author | Roland Knall <roland.knall@br-automation.com> | 2017-02-24 09:58:49 +0100 |
---|---|---|
committer | Roland Knall <rknall@gmail.com> | 2017-02-24 09:04:48 +0000 |
commit | 3697192ea2097d867aab61faa966f4c938be8199 (patch) | |
tree | 64186bd41d5e1891a573e58f81b9ef7d221dd76f /doc | |
parent | 321386e9f49d88b64f48868c6e4079b2073547a1 (diff) |
pluginif: Add documentation for toolbar interface
Add the documentation for the new toolbar interface
to the README file
Change-Id: I9dd37dc4f31760ccd1c9a3e6ae379cd6f9ca1db9
Reviewed-on: https://code.wireshark.org/review/20261
Reviewed-by: Roland Knall <rknall@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/README.plugins | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/doc/README.plugins b/doc/README.plugins index bf40f456f9..faed57d155 100644 --- a/doc/README.plugins +++ b/doc/README.plugins @@ -290,6 +290,10 @@ is encouraged to update their plugins as outlined below: 6 How to plugin related interface options +To demonstrate the functionality of the plugin interface options, a demonstration +plugin exists (pluginifdemo). To build it using cmake, the build option ENABLE_PLUGINIFDEMO +has to be enabled. + 6.1 Implement a plugin GUI menu A plugin (as well as built-in dissectors) may implement a menu within @@ -352,6 +356,110 @@ The following methods exist so far: /* Jumps to the given frame number */ WS_DLL_PUBLIC void plugin_if_goto_frame(guint32 framenr); +6.3 Implement a plugin specific toolbar + +A toolbar may be registered which allows implementing an interactive user +interaction with the main application. The toolbar is generated using the following +code: + + ext_toolbar_t * tb = ext_toolbar_register_toolbar("Plugin Interface Demo Toolbar"); + +This registers a toolbar, which will be shown underneath "View->Additional Toolbars" in +the main menu, as well as the popup action window when right-clicking on any other tool- +or menubar. + +It behaves identically to the existing toolbars and can be hidden as well as defined to +appear specific to selected profiles. The name with which it is being shown is the given +name in this function call. + +6.3.1 Register elements for the toolbar + +To add items to the toolbar, 4 different types of elements do exist. + + * BOOLEAN - a checkbox to select / unselect + * BUTTON - a button to click + * STRING - a text field with validation options + * SELECTOR - a dropdown selection field + +To add an element to the toolbar, the following function is being used: + + ext_toolbar_add_entry( ext_toolbar_t * parent, ext_toolbar_item_t type, const gchar *label, + const gchar *defvalue, const gchar *tooltip, gboolean capture_only, GList * value_list, + gboolean is_required, const gchar * regex, ext_toolbar_action_cb callback, gpointer user_data) + + parent_bar - the parent toolbar for this entry, to be registered by ext_toolbar_register_toolbar + name - the entry name (the internal used one) for the item, used to send updates to the element + label - the entry label (the displayed name) for the item, visible to the user + defvalue - the default value for the toolbar element + - EXT_TOOLBAR_BOOLEAN - 1 is for a checked element, 0 is unchecked + - EXT_TOOLBAR_STRING - Text already entered upon initial display + tooltip - a tooltip to be displayed on mouse-over + capture_only - entry is only active, if a capture is active + callback - the action which will be invoked after the item is activated + value_list - a non-null list of values created by ext_toolbar_add_val(), if the item type + is EXT_TOOLBAR_SELECTOR + valid_regex - a validation regular expression for EXT_TOOLBAR_STRING + is_required - a zero entry for EXT_TOOLBAR_STRING is not allowed + user_data - a user defined pointer, which will be added to the toolbar callback + +In case of the toolbar type EXT_TOOLBAR_SELECTOR a value list has to be provided. This list +is generated using ext_toolbar_add_val(): + + GList * entries = 0; + entries = ext_toolbar_add_val(entries, "1", "ABCD", FALSE ); + entries = ext_toolbar_add_val(entries, "2", "EFG", FALSE ); + entries = ext_toolbar_add_val(entries, "3", "HIJ", TRUE ); + entries = ext_toolbar_add_val(entries, "4", "KLM", FALSE ); + +6.3.2 Callback for activation of an item + +If an item has been activated, the provided callback is being triggered. + + void toolbar_cb(gpointer toolbar_item, gpointer item_data, gpointer user_data) + +For EXT_TOOLBAR_BUTTON the callback is triggered upon a click on the button, for +EXT_TOOLBAR_BOOLEAN and EXT_TOOLBAR_SELECTOR the callback is triggered with every change +of the selection. + +For EXT_TOOLBAR_STRING either the return key has to be hit or the apply button pressed. + +The parameters of the callback are defined as follows: + + toolbar_item - an element of the type ext_toolbar_t * representing the item that has been + activated + item_data - the data of the item during activation. The content depends on the item type: + - EXT_TOOLBAR_BUTTON - the entry is null + - EXT_TOOLBAR_BOOLEAN - the entry is 0 if the checkbox is unchecked and 1 if it is checked + - EXT_TOOLBAR_STRING - a string representing the context of the textbox. Only valid strings + are being passed, it can be safely assumed, that an applied regular expression has + been checked. + - EXT_TOOLBAR_SELECTOR - the value of the selected entry + user_data - the data provided during element registration + +6.3.3 Sending updates to the toolbar items + +A plugin may send updates to the toolbar entry, using one of the following methods. The parameter +silent defines, if the registered toolbar callback is triggered by the update or not. + + void ext_toolbar_update_value(ext_toolbar_t * entry, gpointer data, gboolean silent) + + - EXT_TOOLBAR_BUTTON, EXT_TOOLBAR_STRING - the displayed text (on the button or in the textbox) + are being changed, in that case data is expected to be a string + - EXT_TOOLBAR_BOOLEAN - the checkbox value is being changed, to either 0 or 1, in both cases + data is expected to be an integer sent by GINT_TO_POINTER(n) + - EXT_TOOLBAR_SELECTOR - the display text to be changed. If no element exists with this text, + nothing will happen + + void ext_toolbar_update_data(ext_toolbar_t * entry, gpointer data, gboolean silent) + + - EXT_TOOLBAR_SELECTOR - change the value list to the one provided with data. Attention! this + does not change the list stored within the item just the one in the displayed combobox + + void ext_toolbar_update_data_by_index(ext_toolbar_t * entry, gpointer data, gpointer value, + gboolean silent) + + - EXT_TOOLBAR_SELECTOR - change the display text for the entry with the provided value. Both + data and value must be gchar * pointer. ---------------- |