gtkui: widget api documented and extended to cover more functions

4 files changed, 88 insertions, 10 deletions

diff --git a/plugins/gtkui/gtkui.c b/plugins/gtkui/gtkui.c
index 877e7d1f..caab3be4 100644
--- a/plugins/gtkui/gtkui.c
+++ b/plugins/gtkui/gtkui.c
@@ -1377,5 +1377,15 @@ static ddb_gtkui_t plugin = {
     .gui.plugin.message = gtkui_message,
     .gui.run_dialog = gtkui_run_dialog_root,
     .get_mainwin = gtkui_get_mainwin,
+    .w_reg_widget = w_reg_widget,
+    .w_unreg_widget = w_unreg_widget,
+    .w_is_registered = w_is_registered,
+    .w_get_rootwidget = w_get_rootwidget,
+    .w_create = w_create,
+    .w_set_name = w_set_name,
+    .w_destroy = w_destroy,
+    .w_append = w_append,
+    .w_replace = w_replace,
+    .w_remove = w_remove,
     .api_version = GTKUI_API_VERSION,
 };
diff --git a/plugins/gtkui/gtkui_api.h b/plugins/gtkui/gtkui_api.h
index 9117e46b..30bf7090 100644
--- a/plugins/gtkui/gtkui_api.h
+++ b/plugins/gtkui/gtkui_api.h
@@ -37,26 +37,54 @@ typedef struct ddb_gtkui_widget_s {
     
     uint32_t flags;
 
-    const char *(*load) (struct ddb_gtkui_widget_s *w, const char *s);
+    // all the functions here are overloads, so they are not mandatory
+    // they can be implemented to add custom code to normal widget code
+    // they can be NULL if you don't need them, or you can set them to
+    // standard functions (more below)
+
+    // this function will be called after the widget is visible and needs to
+    // [re]initialize itself
+    // e.g. splitter widget sets the grip position in the init
+    void (*init) (struct ddb_gtkui_widget_s *container);
 
+    // save your custom parameters in the string using strncat
+    // for example, if you need to write width and height:
+    // strncat (s, "100 200", sz);
     void (*save) (struct ddb_gtkui_widget_s *w, char *s, int sz);
 
+    // this is to read custom widget parameters, e.g. width and height
+    // you will be passed a string looking like "100 200 {"
+    // you will need to read params, and return the new pointer, normally it
+    // should be pointing to the "{"
+    const char *(*load) (struct ddb_gtkui_widget_s *w, const char *s);
+
+    // custom destructor code
     void (*destroy) (struct ddb_gtkui_widget_s *w);
 
+    // custom append code
+    // if left NULL, appending will not be supported
+    // you should use standard w_container_add if your widget is derived from
+    // GTK_CONTAINER
     void (*append) (struct ddb_gtkui_widget_s *container, struct ddb_gtkui_widget_s *child);
-    void (*remove) (struct ddb_gtkui_widget_s *container, struct ddb_gtkui_widget_s *child);
 
-    // this function will be called after the widget is visible and needs to
-    // [re]initialize itself
-    // e.g. splitter widget should set the grip position
-    void (*init) (struct ddb_gtkui_widget_s *container);
+    // custom remove code
+    // you should use w_container_remove if your widget is derived from
+    // GTK_CONTAINER
+    void (*remove) (struct ddb_gtkui_widget_s *container, struct ddb_gtkui_widget_s *child);
 
+    // custom replace code
+    // default replace will call remove;destroy;append
+    // but you can override if you need smarter behaviour
+    // look at the splitter and tabs implementation for more details
     void (*replace) (struct ddb_gtkui_widget_s *container, struct ddb_gtkui_widget_s *child, struct ddb_gtkui_widget_s *newchild);
 
+    // implement this if you want to handle deadbeef broadcast messages/events
     int (*message) (struct ddb_gtkui_widget_s *w, uint32_t id, uintptr_t ctx, uint32_t p1, uint32_t p2);
 
+    // this will be called to setup the menu widget in design mode
     void (*initmenu) (struct ddb_gtkui_widget_s *w, GtkWidget *menu);
 
+    // you shouldn't touch this list normally, the system takes care of it
     struct ddb_gtkui_widget_s *children;
     struct ddb_gtkui_widget_s *next; // points to next widget in the same container
 } ddb_gtkui_widget_t;
@@ -64,10 +92,38 @@ typedef struct ddb_gtkui_widget_s {
 typedef struct {
     DB_gui_t gui;
     int api_version;
+
+    // returns main window ptr
     GtkWidget * (*get_mainwin) (void);
-    void (*reg_widget) (const char *type, ddb_gtkui_widget_t *(*create_func) (void));
-    void (*unreg_widget) (const char *type);
-    ddb_gtkui_widget_t * (*get_root_widget) (void);
-} ddb_gtkui_t;
 
+    // register the new widget
+    void (*w_reg_widget) (const char *type, const char *title, ddb_gtkui_widget_t *(*create_func) (void));
+
+    // unregister the widget
+    void (*w_unreg_widget) (const char *type);
+
+    // returns 1 if a widget of the specified is registered
+    int (*w_is_registered) (const char *type);
+
+    // returns toplevel widget
+    ddb_gtkui_widget_t * (*w_get_rootwidget) (void);
+
+    // create a widget oof specified type
+    ddb_gtkui_widget_t * (*w_create) (const char *type);
+
+    // set widget name
+    void (*w_set_name) (ddb_gtkui_widget_t *w, const char *name);
+
+    // destroy the widget
+    void (*w_destroy) (ddb_gtkui_widget_t *w);
+
+    // append the widget to container
+    void (*w_append) (ddb_gtkui_widget_t *cont, ddb_gtkui_widget_t *child);
+
+    // replace existing child widget with another widget
+    void (*w_replace) (ddb_gtkui_widget_t *w, ddb_gtkui_widget_t *from, ddb_gtkui_widget_t *to);
+
+    // remove the widget from its container
+    void (*w_remove) (ddb_gtkui_widget_t *cont, ddb_gtkui_widget_t *child);
+} ddb_gtkui_t;
 #endif
diff --git a/plugins/gtkui/widgets.c b/plugins/gtkui/widgets.c
index 296500e9..e787304c 100644
--- a/plugins/gtkui/widgets.c
+++ b/plugins/gtkui/widgets.c
@@ -564,6 +564,12 @@ w_unreg_widget (const char *type) {
     fprintf (stderr, "gtkui w_unreg_widget: widget type %s is not registered\n", type);
 }
 
+int
+w_is_registered (const char *type) {
+    // FIXME
+    return 0;
+}
+
 ddb_gtkui_widget_t *
 w_create (const char *type) {
     for (w_creator_t *c = w_creators; c; c = c->next) {
diff --git a/plugins/gtkui/widgets.h b/plugins/gtkui/widgets.h
index b22aba98..93bdfd48 100644
--- a/plugins/gtkui/widgets.h
+++ b/plugins/gtkui/widgets.h
@@ -42,6 +42,9 @@ w_reg_widget (const char *type, const char *title, ddb_gtkui_widget_t *(*create_
 void
 w_unreg_widget (const char *type);
 
+int
+w_is_registered (const char *type);
+
 ddb_gtkui_widget_t *
 w_create (const char *type);
 
@@ -58,6 +61,9 @@ void
 w_append (ddb_gtkui_widget_t *cont, ddb_gtkui_widget_t *child);
 
 void
+w_replace (ddb_gtkui_widget_t *w, ddb_gtkui_widget_t *from, ddb_gtkui_widget_t *to);
+
+void
 w_remove (ddb_gtkui_widget_t *cont, ddb_gtkui_widget_t *child);
 
 ddb_gtkui_widget_t *