Xfce Wiki

Sub domains
 

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
dev:monitor-plugin [2013/03/18 01:25] – created andrzejrdev:monitor-plugin [2013/03/23 13:45] (current) – [Sample API 2] nick
Line 4: Line 4:
  
 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. 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 "indicators" on the panel (that's how indicator plugin works)? Even if such functionality is not needed now, it may be necessary if the panel is used in a non-X environment (one that does not support widget embedding). So far, this page assumes that this feature is //not// needed. --- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/19 00:00//
  
 ====== Basic Architecture ====== ====== Basic Architecture ======
Line 16: Line 18:
 Preferably, the library should provide a base class of a monitor-logic object, with some virtual functions populated. 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://rhaalovely.net/cgit/xfce4-monitor-plugin/ --- //[[landry@xfce.org|Landry Breuil]] 2013/03/18 22:05//
 ====== Features ====== ====== Features ======
  
Line 23: Line 26:
     * A user readable and translatable name,     * A user readable and translatable name,
     * A user readable and translatable description,     * A user readable and translatable description,
-    * An icon (48px?)+    * Version number, if not hard to do or a lot of additional work --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 16:10// 
 +    * An icon (32px, dnd size--- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/18 10:36// 
 +      * Icon-name. The item dialog show dnd size icons (32px)  --- //[[nick@xfce.org|Nick Schermer]] 2013/03/18 09:49//
   * Monitor-logic should not call any UI operations directly, i.e. it should not have no direct access to XfcePanelPlugin object.   * 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?     * Perhaps we should allow creating generic Gtk objects for configuration UI?
Line 38: Line 43:
         * Should be translatable when it makes sense,         * Should be translatable when it makes sense,
         * (should support Pango markup?)         * (should support Pango markup?)
 +        * (what about custom widgets like the weather plugin's scrollbox? how would these be handled?  --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 16:31//
       * If icon and labels are shown, Monitor-UI should arrange them in one of the following layouts:       * 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.         * 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.         * 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 "small" representation, assuming that all labels fit in a single row. --- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/18 10:36//
         * Perhaps this should be configurable at the panel level, not in each plugin separately.         * 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 labels are shown, they should be stacked vertically and centered.
Line 47: Line 54:
       * Calls a specified callback in 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?)       * 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). --- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/18 10:50//
       * Displays a popup with a range widget (e.g. for setting audio volume)       * Displays a popup with a range widget (e.g. for setting audio volume)
       * Displays a popup with a text entry field.       * Displays a popup with a text entry field.
 +    * For each button, Monitor-UI should provide a tooltip information, consisting of: --- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/18 10:50//
 +      * An icon,
 +      * A (pango formatted?) label.
   * Provide a standard XfcePanelPlugin context menu shown when right mouse button is clicked.   * Provide a standard XfcePanelPlugin context menu shown when right mouse button is clicked.
   * If "About" is clicked, Monitor-UI should display a dialog box with following information:   * If "About" is clicked, Monitor-UI should display a dialog box with following information:
     * "About" should only be visible if requested by Monitor-logic.     * "About" should only be visible if requested by Monitor-logic.
 +      * There can be a set function to enable about (like xfce_panel_plugin_menu_show_about) and a vfunc/signal to show the about dialog (gtk_show_about_dialog is easy enough). --- //[[nick@xfce.org|Nick Schermer]] 2013/03/18 09:53//
 +        * Or we can build in at least a basic "About" dialog in the base class. BTW, one more problem with a "set_" function is that it would add a circular dependency between Monitor_logic and Monitor_UI (otherwise, there is no need for Monitor_logic to include Monitor_UI header). --- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/18 10:36//
     * Icon, name and description displayed in the "Add New Items" dialog box.     * Icon, name and description displayed in the "Add New Items" dialog box.
 +      * Extracted from the desktop file, no need to set that twice. --- //[[nick@xfce.org|Nick Schermer]] 2013/03/18 09:53//
 +        * Which object should do the extraction, Monitor-UI or Monitor-logic? The latter may be useful if there is any processing to do on these strings (is there?). --- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/18 10:46// 
     * Copyright, as provided by the Monitor-logic.     * Copyright, as provided by the Monitor-logic.
     * A detail description, as provided by Monitor-logic.     * A detail description, as provided by Monitor-logic.
 +      * Also in the about dialog, short description in the .desktop file.
     * A list of authors to populate "Credits", as provided by Monitor-logic.     * A list of authors to populate "Credits", as provided by Monitor-logic.
 +      * See about dialog.
     * A text of the license to populate "License", as provided by Monitor-logic.     * A text of the license to populate "License", as provided by Monitor-logic.
 +      * Can also be displayed in the about dialog.
   * If "Properties" is clicked, Monitor-UI should call a specified callback in Monitor-logic.   * If "Properties" is clicked, Monitor-UI should call a specified callback in Monitor-logic.
     * "Properties" should only be visible if requested by Monitor-logic.     * "Properties" should only be visible if requested by Monitor-logic.
     * Note: this assumes that Monitor-logic would then display a config dialog, which would require it to perform some UI operations. (any better solution?)     * 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. --- //[[nick@xfce.org|Nick Schermer]] 2013/03/18 09:53// 
 +        * 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) --- //[[ndrwrdck@gmail.com|Andrzej]] 2013/03/18 10:36// 
 +        * This part sounds tricky; Alternatively, how about only creating an abstract "template" plugin that does all the basics but is supposed to be extended by the plugin developer?   --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 16:28// 
 +      * 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.  --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 16:25//
  
 ===== Optional ===== ===== Optional =====
Line 71: Line 92:
     * (Monitor-UI should draw the "progress-bar" on top of the icon, so that it is visible even if only icon is shown).     * (Monitor-UI should draw the "progress-bar" on top of the icon, so that it is visible even if only icon is shown).
   * Monitor-UI or panel should generate periodic (configurable?) events for polling external events that are then propagated to Monito-logic objects. Doing this centrally in one place, reduces the number of CPU wake-ups.   * Monitor-UI or panel should generate periodic (configurable?) events for polling external events that are then propagated to Monito-logic objects. Doing this centrally in one place, reduces the number of CPU wake-ups.
 +    * 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? Does it really make a noticeable difference?" Maybe it makes a difference in powersave mode, if such a mode is planned. But how big are the gains in reality? One positive side-effect would be that all plugins update at once, which might perhaps look better and less chaotic, I'm not sure. On the other hand, could it lead to bad effects when all plugins update at the same time (jerkiness,...)? I'm all in for a central place to configure or enable general powersave mode, however. But then the plugins themselves might need to decide how to implement powersaving.  --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 21:25//
 +  * Decision needed: Font size and color selectable in the panel or in the plugin?  --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 16:10//
   * A recommendation: we should avoid "setters", "updaters" etc. in Monitor-logic API in favor of "getters" and signals - this makes both sides of the API deal with only its own tasks.   * A recommendation: we should avoid "setters", "updaters" etc. in Monitor-logic API in favor of "getters" and signals - this makes both sides of the API deal with only its own tasks.
 +  * Currently without a use-case, but perhaps it could be useful: Support reacting to external signals, e.g. via D-Bus?  --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 16:18//
 +  * Not sure this belongs here, but... as an alternative to making a plugin "small", could it somehow be achieved that a plugin can occupy more than one row but still have the "small" properties and so share space with another plugin?  --- //[[h.judt@gmx.at|Harald Judt]] 2013/03/19 21:13//
  
 ====== UI mockups ====== ====== UI mockups ======
Line 81: Line 106:
 ===== Vertical panel ===== ===== 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 "About" info be required 
 +      
 +      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 "About") but that would require describing the dialog somehow
 +                           // (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() //optional(?), return NULL if there is no 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/disabled
 +      
 +      poll_event(time)
 +  
 +
 +====== Sample API 2 ======
 +
 +http://users.xfce.org/~nick/proposal/indicator-api/
 +
 +  * 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/progressbar, label).
 +    * 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, GtkWidget *widget); to pack custom widgets. No idea if that is really useful and would affect the 'standardization' we try to accomplish here.
 +  * 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't hurt here :-).
 +    * Xfce4-taskmanager has a nice widget already.