Update documentations in plugin.h header file.
authorAndriy Grytsenko <andrej@rep.kiev.ua>
Sun, 17 Aug 2014 21:37:38 +0000 (00:37 +0300)
committerAndriy Grytsenko <andrej@rep.kiev.ua>
Sun, 17 Aug 2014 21:37:38 +0000 (00:37 +0300)
src/configurator.c
src/panel.c
src/plugin.c
src/plugin.h
src/private.h

index 6190e4d..135d77c 100644 (file)
@@ -500,7 +500,7 @@ on_sel_plugin_changed( GtkTreeSelection* tree_sel, GtkWidget* label )
     {
         GtkTreeView* view = gtk_tree_selection_get_tree_view( tree_sel );
         GtkWidget *edit_btn = GTK_WIDGET(g_object_get_data( G_OBJECT(view), "edit_btn" ));
-        LXPanelPluginInit *init;
+        const LXPanelPluginInit *init;
         gtk_tree_model_get( model, &it, COL_DATA, &pl, -1 );
         init = PLUGIN_CLASS(pl);
         gtk_label_set_text( GTK_LABEL(label), _(init->description) );
@@ -521,7 +521,7 @@ on_plugin_expand_toggled(GtkCellRendererToggle* render, char* path, GtkTreeView*
         gboolean old_expand, expand, fill;
         guint padding;
         GtkPackType pack_type;
-        LXPanelPluginInit *init;
+        const LXPanelPluginInit *init;
         LXPanel *panel;
 
         gtk_tree_model_get( model, &it, COL_DATA, &pl, COL_EXPAND, &expand, -1 );
@@ -745,7 +745,7 @@ static void on_add_plugin( GtkButton* btn, GtkTreeView* _view )
     g_hash_table_iter_init(&iter, classes);
     while(g_hash_table_iter_next(&iter, &key, &val))
     {
-        register LXPanelPluginInit *init = val;
+        register const LXPanelPluginInit *init = val;
         if (init->superseded)
             continue;
         if (!init->one_per_system || !_class_is_present(init))
@@ -813,7 +813,7 @@ void modify_plugin( GtkTreeView* view )
     GtkTreeModel* model;
     GtkTreeIter it;
     GtkWidget* pl;
-    LXPanelPluginInit *init;
+    const LXPanelPluginInit *init;
 
     if( ! gtk_tree_selection_get_selected( tree_sel, &model, &it ) )
         return;
index 49c0b5c..78a3dbc 100644 (file)
@@ -319,7 +319,7 @@ static void process_client_msg ( XClientMessageEvent* ev )
                 plugins = gtk_container_get_children(GTK_CONTAINER(p->priv->box));
                 for (pl = plugins; pl; pl = pl->next)
                 {
-                    LXPanelPluginInit *init = PLUGIN_CLASS(pl->data);
+                    const LXPanelPluginInit *init = PLUGIN_CLASS(pl->data);
                     if (init->show_system_menu)
                         /* queue to show system menu */
                         init->show_system_menu(pl->data);
@@ -1055,7 +1055,7 @@ GtkMenu* lxpanel_get_plugin_menu( LXPanel* panel, GtkWidget* plugin, gboolean us
 {
     GtkWidget  *menu_item, *img;
     GtkMenu *ret,*menu;
-    LXPanelPluginInit *init;
+    const LXPanelPluginInit *init;
     char* tmp;
 
     ret = menu = GTK_MENU(gtk_menu_new());
@@ -1483,7 +1483,7 @@ void _panel_set_panel_configuration_changed(LXPanel *panel)
     plugins = p->box ? gtk_container_get_children(GTK_CONTAINER(p->box)) : NULL;
     for( l = plugins; l; l = l->next ) {
         GtkWidget *w = (GtkWidget*)l->data;
-        LXPanelPluginInit *init = PLUGIN_CLASS(w);
+        const LXPanelPluginInit *init = PLUGIN_CLASS(w);
         if (init->reconfigure)
             init->reconfigure(panel, w);
     }
@@ -2002,7 +2002,7 @@ GtkWidget *panel_separator_new(LXPanel *panel)
     return gtk_hseparator_new();
 }
 
-gboolean _class_is_present(LXPanelPluginInit *init)
+gboolean _class_is_present(const LXPanelPluginInit *init)
 {
     GSList *sl;
 
index 3837a2c..cdd172d 100644 (file)
@@ -58,14 +58,14 @@ do {\
     extern LXPanelPluginInit lxpanel_static_plugin_##pc; \
     lxpanel_register_plugin_type(#pc, &lxpanel_static_plugin_##pc); } while (0)
 
-static inline LXPanelPluginInit *_find_plugin(const char *name)
+static inline const LXPanelPluginInit *_find_plugin(const char *name)
 {
     return g_hash_table_lookup(_all_types, name);
 }
 
 static GtkWidget *_old_plugin_config(LXPanel *panel, GtkWidget *instance)
 {
-    LXPanelPluginInit *init = PLUGIN_CLASS(instance);
+    const LXPanelPluginInit *init = PLUGIN_CLASS(instance);
     Plugin * plugin;
 
     g_return_val_if_fail(init != NULL && init->new_instance == NULL, NULL);
@@ -77,7 +77,7 @@ static GtkWidget *_old_plugin_config(LXPanel *panel, GtkWidget *instance)
 
 static void _old_plugin_reconfigure(LXPanel *panel, GtkWidget *instance)
 {
-    LXPanelPluginInit *init = PLUGIN_CLASS(instance);
+    const LXPanelPluginInit *init = PLUGIN_CLASS(instance);
     Plugin * plugin;
 
     g_return_if_fail(init != NULL && init->new_instance == NULL);
@@ -388,6 +388,8 @@ void lxpanel_plugin_adjust_popup_position(GtkWidget * popup, GtkWidget * parent)
     int screen_height = gdk_screen_height();
     if ((x + allocation.width) > screen_width) x = screen_width - allocation.width;
     if ((y + allocation.height) > screen_height) y = screen_height - allocation.height;
+    if (y < 0) y = 0;
+    if (x < 0) x = 0;
 
     /* Move the popup to position. */
     gdk_window_move(gtk_widget_get_window(popup), x, y);
@@ -430,7 +432,7 @@ gboolean lxpanel_launch_path(LXPanel *panel, FmPath *path)
 
 void lxpanel_plugin_show_config_dialog(GtkWidget* plugin)
 {
-    LXPanelPluginInit *init = PLUGIN_CLASS(plugin);
+    const LXPanelPluginInit *init = PLUGIN_CLASS(plugin);
     LXPanel *panel = PLUGIN_PANEL(plugin);
     GtkWidget *dlg = panel->priv->plugin_pref_dialog;
 
@@ -483,7 +485,7 @@ void _unload_modules(void)
     g_hash_table_iter_init(&iter, _all_types);
     while(g_hash_table_iter_next(&iter, &key, &val))
     {
-        register LXPanelPluginInit *init = val;
+        register const LXPanelPluginInit *init = val;
         if (init->new_instance == NULL) /* old type of plugin */
         {
             plugin_class_unref(init->_reserved1);
@@ -494,9 +496,9 @@ void _unload_modules(void)
     old_plugins_loaded = FALSE;
 }
 
-gboolean lxpanel_register_plugin_type(const char *name, LXPanelPluginInit *init)
+gboolean lxpanel_register_plugin_type(const char *name, const LXPanelPluginInit *init)
 {
-    LXPanelPluginInit *data;
+    const LXPanelPluginInit *data;
 
     /* validate it */
     if (init->new_instance == NULL || name == NULL || name[0] == '\0')
@@ -512,7 +514,7 @@ gboolean lxpanel_register_plugin_type(const char *name, LXPanelPluginInit *init)
     {
         if (init->init)
             init->init();
-        g_hash_table_insert(_all_types, g_strdup(name), init);
+        g_hash_table_insert(_all_types, g_strdup(name), (gpointer)init);
     }
 #if GLIB_CHECK_VERSION(2, 32, 0)
     g_rec_mutex_unlock(&_mutex);
@@ -557,7 +559,7 @@ static void _on_old_widget_destroy(GtkWidget *widget, Plugin *pl)
 
 GtkWidget *lxpanel_add_plugin(LXPanel *p, const char *name, config_setting_t *cfg, gint at)
 {
-    LXPanelPluginInit *init;
+    const LXPanelPluginInit *init;
     GtkWidget *widget;
     config_setting_t *s, *pconf;
     gint expand, padding = 0, border = 0, i;
@@ -637,7 +639,7 @@ GtkWidget *lxpanel_add_plugin(LXPanel *p, const char *name, config_setting_t *cf
 //    g_signal_connect(widget, "size-allocate", G_CALLBACK(on_size_allocate), p);
     gtk_widget_show(widget);
     g_object_set_qdata(G_OBJECT(widget), lxpanel_plugin_qconf, cfg);
-    g_object_set_qdata(G_OBJECT(widget), lxpanel_plugin_qinit, init);
+    g_object_set_qdata(G_OBJECT(widget), lxpanel_plugin_qinit, (gpointer)init);
     return widget;
 }
 
index 7c6ee86..a0411c9 100644 (file)
@@ -121,6 +121,7 @@ extern GQuark lxpanel_plugin_qdata; /* access to plugin private data */
  * Retrieves instance data attached to the widget.
  */
 #define lxpanel_plugin_get_data(_i) g_object_get_qdata(G_OBJECT(_i),lxpanel_plugin_qdata)
+
 /**
  * lxpanel_plugin_set_data
  * @_i: instance widget
@@ -134,20 +135,81 @@ extern GQuark lxpanel_plugin_qdata; /* access to plugin private data */
  */
 #define lxpanel_plugin_set_data(_i,_data,_destructor) g_object_set_qdata_full(G_OBJECT(_i),lxpanel_plugin_qdata,_data,_destructor)
 
-/* register new plugin type - can be called from plugins init() too */
-extern gboolean lxpanel_register_plugin_type(const char *name, LXPanelPluginInit *init);
+/**
+ * lxpanel_register_plugin_type
+ * @name: name of new plugin type
+ * @init: plugin-specific type descriptor
+ *
+ * Register new plugin type. Can be called from plugins init() callback too.
+ *
+ * Returns: %TRUE in case of success.
+ */
+extern gboolean lxpanel_register_plugin_type(const char *name, const LXPanelPluginInit *init);
 
-/* few helper functions */
+/**
+ * lxpanel_get_plugin_menu
+ * @panel: panel instance pointer
+ * @plugin: plugin instance pointer
+ * @use_sub_menu: %TRUE if panel management options should be in separated submenu
+ *
+ * Creates context menu for given @panel and @plugin.
+ *
+ * Returns: (transfer full): new menu widget.
+ */
 extern GtkMenu* lxpanel_get_plugin_menu(LXPanel* panel, GtkWidget* plugin, gboolean use_sub_menu);
+
+/**
+ * lxpanel_plugin_adjust_popup_position
+ * @popup: a widget to adjust position
+ * @plugin: a plugin instance
+ *
+ * Adjusts the position of a @popup window to ensure that it is not hidden
+ * by the panel and moves @popup near @plugin if possible.
+ */
 extern void lxpanel_plugin_adjust_popup_position(GtkWidget * popup, GtkWidget * plugin);
-                       /* Helper to move popup windows away from the panel */
+
+/**
+ * lxpanel_plugin_popup_set_position_helper
+ * @p: a panel instance
+ * @near: a widget to position the popup
+ * @popup: a widget to calculate position
+ * @px: (out): pointer to receive X coordinate
+ * @py: (out): pointer to receive Y coordinate
+ *
+ * Calculates desired position of @popup to be placed right to the widget
+ * @near accordingly to position of panel @p and returns its coordinates.
+ * Can be used in position-calculation callback for popup menus.
+ */
 extern void lxpanel_plugin_popup_set_position_helper(LXPanel * p, GtkWidget * near, GtkWidget * popup, gint * px, gint * py);
-                       /* Helper for position-calculation callback for popup menus */
+
+/**
+ * plugin_widget_set_background
+ * @widget: a widget
+ * @p: a panel instance
+ *
+ * Recursively set the background of @widget and its children. Can be
+ * used on a panel background configuration change.
+ */
 extern void plugin_widget_set_background(GtkWidget * widget, LXPanel * p);
-                       /* Recursively set the background of all widgets on a panel background configuration change */
+
+/**
+ * lxpanel_launch_path
+ * @panel: a panel instance
+ * @path: a path to launch
+ *
+ * Launches the @path either itself, or using default application.
+ *
+ * Returns: %TRUE if launch was successful.
+ */
 extern gboolean lxpanel_launch_path(LXPanel *panel, FmPath *path);
+
+/**
+ * lxpanel_plugin_show_config_dialog
+ * @plugin: a plugin instance
+ *
+ * Calls config() callback and shows configuration window.
+ */
 extern void lxpanel_plugin_show_config_dialog(GtkWidget* plugin);
-                       /* Calls config() callback and shows configuration window */
 
 G_END_DECLS
 
index c75527a..517e49f 100644 (file)
@@ -206,7 +206,7 @@ extern GQuark lxpanel_plugin_qconf; /* access to congig_setting_t data */
 
 #define PLUGIN_PANEL(_i) ((LXPanel*)gtk_widget_get_toplevel(_i))
 
-gboolean _class_is_present(LXPanelPluginInit *init);
+gboolean _class_is_present(const LXPanelPluginInit *init);
 
 void _panel_show_config_dialog(LXPanel *panel, GtkWidget *p, GtkWidget *dlg);