module: add a refresh_in() interface function

Modules can implement this to allow e.g. particles to force a refresh
after a certain amount of time.

module.c

@@ -10,12 +10,17 @@ module_common_new(void)
     mod->bar = NULL;
     mtx_init(&mod->lock, mtx_plain);
     mod->private = NULL;
-    mod->run = NULL;
+
     mod->destroy = &module_default_destroy;
-    mod->content = NULL;
     mod->begin_expose = &module_default_begin_expose;
     mod->expose = &module_default_expose;
     mod->end_expose = &module_default_end_expose;
+
+    /* No defaults for these; must be provided by implementation */
+    mod->run = NULL;
+    mod->content = NULL;
+    mod->refresh_in = NULL;
+
     return mod;
 }
 

module.h

@@ -30,12 +30,37 @@ struct module {
     int (*run)(struct module_run_context *ctx);
     void (*destroy)(struct module *module);
 
-    struct exposable *(*content)(struct module *mod);
+    /*
+     * Called by bar when it needs to refresh
+     *
+     * begin_expose() should return a module_expose_context, where the
+     * 'exposable' member is an instantiated particle, 'width' is the
+     * total width of the module, and 'private' is context data for
+     * the module (i.e. it's not touched by the bar).
+     *
+     * expose() should render the exposable
+     *
+     * end_expose() performs cleanup (destroy exposable etc)
+     *
+     * Note that for most modules, using the default implementations
+     * (module_default_*) is good enough. In this case, implement
+     * 'content()' instead (see below).
+     */
     struct module_expose_context (*begin_expose)(struct module *mod, cairo_t *cr);
     void (*expose)(const struct module *mod,
                    const struct module_expose_context *ctx,
                    cairo_t *cr, int x, int y, int height);
     void (*end_expose)(const struct module *mod, struct module_expose_context *ctx);
+
+    /*
+     * Called by module_default_begin_expose(). Should return an
+     * exposable (an instantiated particle).
+     */
+    struct exposable *(*content)(struct module *mod);
+
+    /* refresh_in() should schedule a module content refresh after the
+     * specified number of milliseconds */
+    bool (*refresh_in)(struct module *mod, long milli_seconds);
 };
 
 struct module *module_common_new(void);