no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
Previous revisionLast revision | |||
— | dev:monitor-plugin [2013/03/23 12:49] – [Sample API 2] nick | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Scope ====== | ||
+ | Every Xfce panel plugin is required to reimplement UI, which makes writing basic plugins more difficult and leads to UI inconsistencies. | ||
+ | |||
+ | There is a need for a generic plugin that provides basic UI (icon, label(s), menu, etc., see below) and allows the plugin writer to implement only data collection logic. | ||
+ | |||
+ | Question: should this mechanism allow independent applications communicate with the plugin (e.g. via dbus) and display " | ||
+ | |||
+ | ====== Basic Architecture ====== | ||
+ | |||
+ | The plugin should be partitioned into two components: | ||
+ | |||
+ | * a library implementing UI consisting of one or more(?) buttons (called monitor-UI), | ||
+ | * a plugin implementing monitoring logic (called monitor-logic). | ||
+ | |||
+ | The panel should not assume that monitor-logic is implemented as e.g. a library written in C. In the future, this could be used for writing monitor plugins in scripting languages. | ||
+ | |||
+ | Preferably, the library should provide a base class of a monitor-logic object, with some virtual functions populated. | ||
+ | |||
+ | Note: I had started some months ago a skeleton of a gobject monitor plugin, intending to merge all monitors inside it, and using libgtop & upower for data collection. See http:// | ||
+ | ====== Features ====== | ||
+ | |||
+ | ===== Essential ===== | ||
+ | |||
+ | * The plugin should be visible in the "Add New Items" panel dialog as a separate item (i.e. not as a monitor-UI plugin that can be later configured to load some module). To populate the list of plugins the plugin should provide (via a .desktop file?): | ||
+ | * A user readable and translatable name, | ||
+ | * A user readable and translatable description, | ||
+ | * Version number, if not hard to do or a lot of additional work --- // | ||
+ | * An icon (32px, dnd size) --- // | ||
+ | * Icon-name. The item dialog show dnd size icons (32px) | ||
+ | * Monitor-logic should not call any UI operations directly, i.e. it should not have no direct access to XfcePanelPlugin object. | ||
+ | * Perhaps we should allow creating generic Gtk objects for configuration UI? | ||
+ | * Monitor-UI should provide following features to the Monitor-logic object: | ||
+ | * One or more (?) panel buttons logically grouped together and sorted. Each of them displaying at least one of following: | ||
+ | * An icon. | ||
+ | * The icon should be provided by Monitor-logic, | ||
+ | * Should come in multiple sizes and/or .svg format to fit different panel sizes. | ||
+ | * This means, if possible, Monitor-logic should not use Pixbuf objects as they do not scale well. | ||
+ | * Monitor-UI should scale the icon in a single panel row size. | ||
+ | * For UI consistency we should recommend every plugin to have an icon (but probably better not to make it mandatory via API). | ||
+ | * One or more (?) text labels (not GtkLabel objects, though). | ||
+ | * The text label should be provided by Monitor-logic. | ||
+ | * Should be translatable when it makes sense, | ||
+ | * (should support Pango markup?) | ||
+ | * (what about custom widgets like the weather plugin' | ||
+ | * If icon and labels are shown, Monitor-UI should arrange them in one of the following layouts: | ||
+ | * Stacked vertically - icon at the top, labels below. In this case, all objects should be centered. | ||
+ | * Horizontal grouping - icon on the left, on the right a vertical stack of labels. In this mode, all objects should be aligned left. | ||
+ | * In this mode, the plugin could default to a " | ||
+ | * Perhaps this should be configurable at the panel level, not in each plugin separately. | ||
+ | * If only labels are shown, they should be stacked vertically and centered. | ||
+ | * If only icon and is shown, it should be treated as a " | ||
+ | * For each button, Monitor-UI should provide a default action, configured by Monitor-logic, | ||
+ | * Calls a specified callback in Monitor-logic. | ||
+ | * Opens a menu specified (but not created) by Monitor-logic. (How to specify the menu? Glade?) | ||
+ | * Should this menu be merged with the context-menu of the plugin instead? This is what plugins do at the moment, and frees them to use LMB click for other purposes (indicator plugin makes these menus separate, though). --- // | ||
+ | * Displays a popup with a range widget (e.g. for setting audio volume) | ||
+ | * Displays a popup with a text entry field. | ||
+ | * For each button, Monitor-UI should provide a tooltip information, | ||
+ | * An icon, | ||
+ | * A (pango formatted?) label. | ||
+ | * Provide a standard XfcePanelPlugin context menu shown when right mouse button is clicked. | ||
+ | * If " | ||
+ | * " | ||
+ | * There can be a set function to enable about (like xfce_panel_plugin_menu_show_about) and a vfunc/ | ||
+ | * Or we can build in at least a basic " | ||
+ | * Icon, name and description displayed in the "Add New Items" dialog box. | ||
+ | * Extracted from the desktop file, no need to set that twice. --- // | ||
+ | * Which object should do the extraction, Monitor-UI or Monitor-logic? | ||
+ | * Copyright, as provided by the Monitor-logic. | ||
+ | * A detail description, | ||
+ | * Also in the about dialog, short description in the .desktop file. | ||
+ | * A list of authors to populate " | ||
+ | * See about dialog. | ||
+ | * A text of the license to populate " | ||
+ | * Can also be displayed in the about dialog. | ||
+ | * If " | ||
+ | * " | ||
+ | * Note: this assumes that Monitor-logic would then display a config dialog, which would require it to perform some UI operations. (any better solution?) | ||
+ | * Maybe it should always provide basic appearance settings, so user can configure this (the backend is only responsible for the data, not the display). When building the dialog the plugin can populate its own frame/box for additional settings that are required for the data collection. --- // | ||
+ | * Yes, appearance settings could be handled directly by Monitor-UI, but what about settings related to the actual function of the plugin? (e.g. location in weather plugin) --- // | ||
+ | * This part sounds tricky; Alternatively, | ||
+ | * Basic appearance settings could simply be provided by an entry in the context menu. I'd somehow rather associate this with the panel, or with the genericness of the plugin, e.g. font size, font color. | ||
+ | |||
+ | ===== Optional ===== | ||
+ | * For each button, Monitor-UI should provide a secondary action. | ||
+ | * Same features as for primary action. | ||
+ | * For each button, Monitor-UI should provide mouse scroll actions. | ||
+ | * When mouse wheel is turned, a specified callback in Monitor-logic should be called along with the direction of scrolling. | ||
+ | * For each button (only if Icon is shown?) Monitor-UI should provide a " | ||
+ | * Monitor-logic should be able to specify whether to enable/ | ||
+ | * (Monitor-UI should draw the " | ||
+ | * Monitor-UI or panel should generate periodic (configurable? | ||
+ | * The idea is nice and I thought about that too some time ago, but then there are plugins that update their widgets quite frequently and more frequently than others, so the questions here are more like: "Is it worth all the engineering? | ||
+ | * Decision needed: Font size and color selectable in the panel or in the plugin? | ||
+ | * A recommendation: | ||
+ | * Currently without a use-case, but perhaps it could be useful: Support reacting to external signals, e.g. via D-Bus? | ||
+ | * Not sure this belongs here, but... as an alternative to making a plugin " | ||
+ | |||
+ | ====== UI mockups ====== | ||
+ | |||
+ | ===== Horizontal panel ===== | ||
+ | |||
+ | ===== Deskbar mode ===== | ||
+ | |||
+ | ===== Vertical panel ===== | ||
+ | |||
+ | ====== Sample API ====== | ||
+ | |||
+ | ===== Monitor UI ===== | ||
+ | |||
+ | Monitor-UI API would be visible to the panel. | ||
+ | |||
+ | ===== Monitor logic ===== | ||
+ | |||
+ | Monitor-logic API would be visible to a plugin developer. | ||
+ | |||
+ | class XfceMonitor extends GObject | ||
+ | | ||
+ | //fields | ||
+ | list of XfceMonitorButton | ||
+ | | ||
+ | //methods | ||
+ | get_monitor_buttons() | ||
+ | | ||
+ | has_about() // should " | ||
+ | | ||
+ | get_name() // or taken from .desktop? | ||
+ | | ||
+ | get_plugin_icon() // ditto | ||
+ | | ||
+ | get_desciption() // ditto | ||
+ | | ||
+ | get_copyright() | ||
+ | | ||
+ | get_detail_desciption() | ||
+ | | ||
+ | get_credits() // perhaps hardcoded | ||
+ | | ||
+ | get_license() // ditto | ||
+ | | ||
+ | has_properties() // for config dialog | ||
+ | | ||
+ | properties_clicked() // show a config dialog from XfceMonitor object(?) | ||
+ | // ideally, this should be handled by XfceMonitorUI object instead | ||
+ | // (like " | ||
+ | // (glade?) | ||
+ | | ||
+ | //signals | ||
+ | signal monitor_button_added(button) | ||
+ | | ||
+ | signal monitor_button_removed(button) | ||
+ | | ||
+ | signal monitor_buttons_reordered | ||
+ | | ||
+ | class XfceMonitorButton extends GObject | ||
+ | | ||
+ | //fields | ||
+ | icon(s) | ||
+ | list of text_labels | ||
+ | | ||
+ | | ||
+ | //methods | ||
+ | get_icon(size) | ||
+ | | ||
+ | signal icon_changed() | ||
+ | | ||
+ | get_label_list() | ||
+ | | ||
+ | signal label_list_changed() | ||
+ | | ||
+ | | ||
+ | //primary action | ||
+ | get_primary_action_type() // returns enum: None, Callback, Menu, Range, TextField | ||
+ | | ||
+ | primary_action_callback() | ||
+ | | ||
+ | get_primary_menu() | ||
+ | | ||
+ | signal primary_menu_changed() | ||
+ | | ||
+ | primary_action_range_changed (percentage) | ||
+ | | ||
+ | primary_action_text_entered (text) | ||
+ | | ||
+ | | ||
+ | //secondary action | ||
+ | get_secondary_action_type() // returns enum: None, Callback, Menu, Range, TextField | ||
+ | | ||
+ | secondary_action_callback() | ||
+ | | ||
+ | get_secondary_menu() | ||
+ | | ||
+ | signal secondary_menu_changed() | ||
+ | | ||
+ | secondary_action_range_changed (percentage) | ||
+ | | ||
+ | secondary_action_text_entered (text) | ||
+ | | ||
+ | | ||
+ | //tooltip --- // Andrzej 2013/03/18 10:58// | ||
+ | | ||
+ | has_tooltip() | ||
+ | | ||
+ | get_tooltip_icon() // | ||
+ | | ||
+ | get_tooltip_label() | ||
+ | | ||
+ | signal tooltip_changed() | ||
+ | | ||
+ | | ||
+ | //mouse wheel event | ||
+ | mouse_wheel_event(direction) | ||
+ | | ||
+ | | ||
+ | //progress bar | ||
+ | has_progress_bar() | ||
+ | | ||
+ | progress_bar_value() | ||
+ | | ||
+ | signal progress_bar_changed() // either value or visibility | ||
+ | | ||
+ | // polling mechanism | ||
+ | polling_enabled() | ||
+ | | ||
+ | get_poll_interval() // returns interval in # of seconds | ||
+ | | ||
+ | signal poll_interval_changed() //changed interval or polling enabled/ | ||
+ | | ||
+ | poll_event(time) | ||
+ | | ||
+ | |||
+ | ====== Sample API 2 ====== | ||
+ | |||
+ | http:// | ||
+ | |||
+ | * Idea is the plugin shows preferences for the widgets: | ||
+ | * set their position, therefore the static names for both multiple items (in case of example the sysload plugin), but also the position of the indicator items (by default icon/ | ||
+ | * Plugins can pack a widget (vbox or a single frame) for the plugin specific settings. | ||
+ | * Color settings for progressbar and label. | ||
+ | * Graph appearance. | ||
+ | * An option would be a xfce_panel_indicator_item_add_width (XfcePanelIndicatorItem *item, const gchar *name, const gchar *display_name, | ||
+ | * Plugin is responsible for the updates (so its own gdk timeout). | ||
+ | * A graph widget could be a nice addition. It would at least merge the cpugraph and sysload plugins, making them both more functional (also graph of memory/swap usage), but also the netload and diskperf plugin would benefit. Bit of fancy cairo and transparency wouldn' |