changelog-plugins.html

系统任务管理器

<li> If a plugin implements instant apply (so no apply_config() and it
	is NULL in the GkrellmMonitor struct), then if the plugins config
	page is selected, there will be no "Apply" button shown since
	it, ...ummm...  doesn't apply.</li>
<li> For plugins which have an apply_config(), now there is an
	implied apply if the user leaves the plugins config page
	by selecting another monitor. </li>
</ul>

<h4>Changes for version 2.0.1 - 2.0.2</h4>
None.

<h4>Changes for version 2.0.0</h4>
See the gkrellm-2.0 porting guide.

<h4>Changes for version 1.2.10 - 1.2.11</h4>
None.

<h4>Changes for version 1.2.9</h4>
Some added functions (see the Plugin Programmers Reference for more functions):
	<pre><font size="-1">
Style   *gkrellm_meter_style_by_name(gchar *name);
Style   *gkrellm_panel_style_by_name(gchar *name);
Style   *gkrellm_chart_style_by_name(gchar *name);
	</font></pre>
which provide for using a custom style
with values set with
StyleMeter or StylePanel lines in the gkrellmrc.  If you have extra
krells you want to allow to be themed, this can clean up your code
by eliminating a bunch
of gkrellm_get_gkrellmrc_integer() or gkrellm_get_gkrellmrc_string()
calls.
See the Themes file and gkrellmss.c in GKrellMSS 0.4 (when I release it)
for a working example of this.
<p>
Style margin changes for more layout control.  Usually these will be set
by a theme author in the gkrellmrc:
	<ul>
		<li>There is now a left and right panel margin instead of the single
		"margin".  These are in a new Margin struct which also includes
		the top and bottom margin.  Use gkrellm_get_style_margins() to
		access the themed margin values.</li>
		<li>The Style struct has new krell_left_margin and krell_right_margin
		for setting krell margins independently of panel margins.</li>
	</ul>
<p>

<h4>Changes for version 1.2.6 - 1.2.8</h4>
None.

<h4>Changes for version 1.2.5</h4>
Added some functions.
	<pre><font size="-1">
void    gkrellm_set_krell_expand(Style *, gchar *);
void    gkrellm_insert_krell_nth(Panel *, Krell *, gint);
void    gkrellm_insert_decal_nth(Panel *, Decal *, gint);
gboolean gkrellm_in_decal(Decal *, GdkEventButton *);
void    gkrellm_decal_button_connect(DecalButton *, void (*func)(), void *);
void    gkrellm_decal_button_right_connect(DecalButton *, void (*func)(), void *);
void    gkrellm_set_button_sensitive(DecalButton *, gboolean);
void    gkrellm_hide_button(DecalButton *);
void    gkrellm_show_button(DecalButton *);
	</font></pre>

The DecalButton callback function prototype adds a "gpointer data" so
you don't have to reference button->data.

<h4>Changes for version 1.2.3 - 1.2.4</h4>
None.

<h4>Changes for version 1.2.2</h4>
Added some functions.  Some of them are (for controlling decals and krells):
	<pre><font size="-1">
void          gkrellm_set_krell_margins(Panel *, Krell *k, gint, gint);
void          gkrellm_move_krell_yoff(Panel *, Krell *, gint);
void          gkrellm_draw_decal_on_chart(Chart *, Decal *, gint, gint);
void          gkrellm_move_decal(Panel *, Decal *, gint, gint);
void          gkrellm_decal_on_top_layer(Decal *, gboolean);
	</font></pre>

<h4>Changes for version 1.2.1</h4>
None.

<h4>Changes for version 1.2.0</h4>
Any plugin using charts will require coding changes and a recompile.
Charts are now automatically user configurable with a right click on a chart.
There are too many new functions to cover here, so look over the updated
plugin programmers reference and especially the chart demo1.c program.
All of the "chartconfig" and "chartdata" functions are new.  The create
and destroy functions are changed to gkrellm_chart_create() and
gkrellm_chart_destroy().  You should no longer do awkward settings such
as chart->previous = blah (use gkrellm_monotonic_chartdata()) or
chart->scale_max = 0 (chart scaling is now handled properly)
A couple of key points to note are:
<ul>
	<li>Charts no longer automatically have two data sets.  There is a new
	ChartData struct which is added to Charts as needed.  To handle a
	variable number of data layers, the store data routine is changed
	to a varargs <br>
	&nbsp &nbsp &nbsp &nbsp gkrellm_store_chartdata(Chart *, gulong total, ...);
	</li>
	<li>There are several chart config options all handled automatically.  But
	you do need to save and load the config - see demo1.c
	</li>
</ul>

Plugins that use panels do not require a recompile, but I've made
the chart and panel coding styles cleaner and more consistent by adding
some functions you should migrate to.  When you do,
your plugin will depend on GKrellM version >= 1.2.0.
These are for coding cleanups and some new functions:
	<ul>
	<li>If you have a spare right click, you can have it call<br>
     &nbsp &nbsp &nbsp &nbsp gkrellm_open_config_window(Monitor *);<br>
	and the config window will be opened right to your plugin's config page.
	</li>
	<li>Use gkrellm_panel_create() instead of gkrellm_create_panel().
	Use gkrellm_panel_configure() instead of gkrellm_configure_panel().
	Use gkrellm_panel_enable_visibility() instead of
	gkrellm_enable_visibility()
	(or you could use gkrellm_hide_panel() and gkrellm_show_panel()).
	See the plugin programmers reference for usage.
	</li>
	<li> After you upgrade to using these new functions, there should
	be no need to worry about managing stuff that gkrellm should be
	handling.  ie, you should never have to make
	any gkrellm_monitor_height_adjust() or gkrellm_pack_side_frame() calls.
	Also, decal/krell lists will be automatically destroyed prior to
	create plugin calls (but you can override this) and you should no
	longer set krell->previous
	(use gkrellm_monotonic_krell_values()).  Also if you destroy a panel,
	you will no longer need to destroy lists, adjust monitor height,
	or g_free() the Panel struct storage.
	<p>
	Look at the revised demos in the programmers
	reference.  Also look at the bottom of gkrellm_public_proto.h for the
	list of functions that should be replaced.
	</li>
</ul>


<h4>Changes for version 1.0.8</h4>
None

<h4>Changes for version 1.0.7</h4>
None

<h4>Changes for version 1.0.6</h4>
/usr/lib/gkrellm/plugins and /usr/local/lib/gkrellm/plugins are now also
searched to comply with the FHS.

<h4>Changes for version 1.0.5</h4>
None

<h4>Changes for version 1.0.4</h4>
<blockquote>
Looking ahead a bit (some months?) when I get to 1.1.0
I want the gkrellm namespace to be cleaned up.  I'm defining
that to mean that if you do a "nm -u plugin.so" the undefined symbols
expected to link to gkrellm will be only GK and gkrellm_XXX symbols.
Starting with 1.0.4 gkrellm_private_proto.h is no longer included
by gkrellm.h and it is not installed in the include directory.  I 
have temporarily moved some symbols affecting a few plugins
from private to public proto.h.  I hope I moved enough so
that all current plugins I know of will still compile.  The plan is
when 1.1.0 arrives I will do the "Cut Here" at the bottom of
gkrellm_public_proto.h, so source will need to be in sync
by then.<br>
<b>To check if you need changes,
#ifdef out the part that will be cut and see if you get warnings
compiling with -Wall.</b><br>
If you have changes to make or want to use any new functions below,
make your source dependent on version 1.0.4 as described in the
changes for version 1.0.3.
<p>
Added some handy utility routines (most were already in
gkrellm_private_proto.h without a gkrellm_ prefix):
	<pre><font size="-1">
	GtkWidget *gkrellm_create_tab(GtkWidget *, gchar *);
	gchar   *gkrellm_entry_get_text(GtkWidget **);
	void    gkrellm_spin_button(GtkWidget *, GtkWidget **, gfloat, gfloat, gfloat,
	                gfloat, gfloat, gint, gint, void (*func)(), gpointer, gboolean, gchar *);
	void    gkrellm_check_button(GtkWidget *, GtkWidget **, gboolean, gboolean, gint, gchar *);
	gchar   *gkrellm_homedir(void);
	gboolean gkrellm_dup_string(gchar **, gchar *);
	gchar   *gkrellm_make_config_file_name(gchar *, gchar *);
	struct tm *gkrellm_get_current_time();
	</font></pre>
Other uninteresting changes are: Added some session manager plugin helper
functions so I could write the gkrellm-gnome plugin and exported sensor
reading functions for special purpose sensor monitoring plugins.
</blockquote>

<h4>Changes for version 1.0.3</h4>
<ul>
<li> You can run <b>gkrellm -p plugin-under-test.so</b> to load the plugin
	you are working on in the current directory.  Should be a development
	time saver.
</li>	
<li>
I am changing the way top and bottom margins are specified in panels.
Previously labels and decals were margined by using the top and
bottom borders of the background image.  Now there are new
<b>top_margin</b> and <b>bottom_margin</b> values in the Style struct to go
with the existing <b>margin</b> value (which is used for both
left and right margins).  Most
plugins probably don't care about this since the gkrellm create and
configure routines handle most placements, but if you were using
any <b>border.top</b> or <b>border.bottom</b> references for positioning,
you should use the new routine:
	<pre><font size="-1">
    void  gkrellm_get_top_bottom_margins(Style *s, gint *top, gint *bot)
	</font></pre>

This routine determines if a theme is using the new top_margin and
bottom_margin values and returns them, otherwise it will return the old
top and bottom border values so existing themes will not break.
</li>
<p>
<li>
Two new Style copying functions needed to fix a bad programming practice
I had promoted in my demo programs:
	<pre><font size="-1">
    Style     *gkrellm_copy_style(Style *src_style);
    TextStyle *gkrellm_copy_textstyle(TextStyle *src_style);
	</font></pre>

Previously I had suggested
copying a style to a plugin local style like so:
	<pre><font size="-1">
    Style *my_style, *style;

    style     = gkrellm_meter_style(DEFAULT_STYLE);
    my_style  = gkrellm_style_new0();
    *my_style = *style;
	</font></pre>

But I goofed and this is no good.  If you have such code please change it.
It should now be done like so:
	<pre><font size="-1">
    Style *my_style, *style;

    style    = gkrellm_meter_style(style_id);
    my_style = gkrellm_copy_style(style);
	</font></pre>

<b>NOTE:</b> Just to emphasize a point, you should never have a static
local Style or TextStyle declared.  You should use the above copy
function so the style can be initialized with a themes gkrellmrc settings.
</li>
<p>
<li>
If you do use the above new routines and don't want to clutter your code
with #ifdefs to make it compatible with old GKrellM versions, I suggest
making your plugin require version 1.0.3.  After all, I don't think it's
unreasonable to ask someone installing your latest plugin
version to also have installed a recent GKrellM version.  It's what I
would do and it can keep your code base clean.  You can enforce
this requirement in your header file after you include gkrellm.h:
	<pre><font size="-1">
    #include &lt;gkrellm/gkrellm.h&gt;
    #if  !defined(GKRELLM_VERSION_MAJOR) \
         || (GKRELLM_VERSION_MAJOR==1 && GKRELLM_VERSION_MINOR==0 && GKRELLM_VERSION_REV<3)
    #error This plugin requires GKrellM version >= 1.0.3
    #endif
	</font></pre>
	
Notice that in 1.0.3 you can now use GKRELLM_VERSION_MAJOR instead of just
VERSION_MAJOR.
Similarly, if you want to clean out ugly #ifdef'ed code sections
for previous versions of your plugin, just do it!
But if you want to conditional on a GKrellM version prior to 1.0.3, you
can't use the GKRELLM_VERSION_MAJOR.
Ie. if you #ifdef'ed in some of the new functions for 0.10.0, clean them
out and put in your header:
	<pre><font size="-1">
    #include &lt;gkrellm/gkrellm.h&gt;
    #if &nbsp (VERSION_MAJOR==0) && (VERSION_MINOR<10)
    #error This plugin requires GKrellM version >= 0.10.0
    #endif
	</font></pre>
But, if you are going to do this, why not just make a clean break?
Go ahead and use the first example using GKRELLM_VERSION_XXX defines,
and be done with it!
</li>
</ul>

<h4>Changes for version 1.0.0 - 1.0.2</h4>
None.

<h4>Changes for version 0.10.5</h4>
Added these routines:
<ul>
	<li>gkrellm_config_modified()</li>
	<li>gkrellm_chart_images_override()</li>
	<li>gkrellm_get_gkrellmrc_integer()</li>
	<li>gkrellm_get_gkrellmrc_string()</li>
</ul>
See the Plugins programmers reference for descriptions.

<h4>Changes for version 0.10.2 - 0.10.4</h4>
None.

<h4>Changes for version 0.10.1</h4>
<ul>
<li>There has been a loose end with controlling plugin placement when
multiple plugins are placing themselves before the same monitor.  So far
this placement has been determined by the order plugins are read from the
plugin directories and this in turn is a function of the order they
were written into the directory.  There is no alphabetical sorting
at all.  So to give some control, plugins can now specify a gravity value
from 0 to 15 in the placement parameter.  Think of it as higher gravity
pulling a plugin down in its placement slot.  If you see no reason your
plugin should care about this level of control then do nothing, no
code changes are required.  But if there is some reason you prefer your
plugin be biased downwards, then give it gravity like so:
<pre>
#ifdef GRAVITY
#define MY_PLACEMENT (MON_APM | GRAVITY(8))
#else
#define MY_PLACEMENT (MON_APM)
#endif
</pre>
If there is a very strong reason to bias it down, give it gravity 15.
If you want placement with respect to another plugin that has gravity,
then give yours a gravity value just above or below the gravity for the
other plugin.  Many plugins can just pass this by and be fine with the
default zero gravity.  
<p>
<li>Cleaned out all GK.debug usage from GKrellM source so it is now solely for
plugin use.   You can run "gkrellm -debug" or "gkrellm -debugN" where N is
an arbitrary integer you pick for your plugin specific use.  Basically,
use "if (GK.debug)" for general debugging, or use "if (GK.debug == N)"
for debugging isolated to your plugin.   I guess just rely on chance
and squatters rights and just pick an N that
you hope does not collide with some other plugin.
</ul>

<h4>Changes for version 0.10.0</h4>
<blockquote>
Final release check list (some details are below):
<ul>
	<li>Fix GK struct references - only xxx_tick and debug references are OK.
	<li>Consider adding style_id support - use the new functions.
	<li>Consider using gkrellm_load_image() to load custom #included images.
</ul>

<h5>Details</h5>
New functions (see plugin programmers reference):
<pre><font size="-1">
gboolean gkrellm_load_image(gchar *name, gchar **xpm, GdkImlibImage **im, gchar *subdir);
gboolean gkrellm_set_image_border(gchar *name, gchar **xpm, Style *style);
gint     gkrellm_add_chart_style(Monitor *mon, gchar *name);
gint     gkrellm_add_meter_style(Monitor *mon, gchar *name);
gint     gkrellm_lookup_chart_style_id(gchar *name);
gint     gkrellm_lookup_meter_style_id(gchar *name);
gchar    *gkrellm_get_theme_path(void);
void     gkrellm_add_info_text_string(GtkWidget *text, gchar *string);
</font></pre>

The GK structure is changing.
It has always been the case that the only safe parts of GK to
access are the debug and xxx_tick parts.
If any plugin directly accesses the structure (does not use the
gkrellm_XXX() helper functions) for image or style pointers
it's pretty certain it will break.
Also, even if you did use gkrellm_XXX() functions to access images or styles
for other monitors (not the DEFAULT_STYLE) you will now get unexpected
results (but should not crash).  Use the gkrellm_lookup_xxxx_style_id()
functions to get a style_id for other monitors.