changelog-plugins.html

系统任务管理器

Some other references are OK for now,
like GK.theme_path, but should be changed to the new gkrellm_get_theme_path()
under 0.10.0 (but consider using the new gkrellm_load_image() function
so you don't have to do any theme path processing at all).
<p>
Code references like these are a problem:
<pre>
    GK.XXX_style[id]      where XXX is chart, panel, or meter.
    GK.bg_XXX_image[id]   where XXX is chart, panel, meter, or grid.
    GK.krell_XXX_image[]  where XXX is panel or meter
    GK.monitor_height += p->h;
    UC.chart_width
    GK.decal_misc_pixmap
    some_function(XXX_STYLE) where XXX is APM, FS, CLOCK, CAL, etc.
</pre>
Fix them like this:
<pre>
    gkrellm_XXX_style(id);
    gkrellm_bg_XXX_image(id);
    gkrellm_krell_XXX_image(id);
    gkrellm_monitor_height_adjust(h);
    gkrellm_chart_width();
    gkrellm_decal_misc_pixmap();
    some_function(gkrellm_lookup_meter_style_id(XXX_STYLE_NAME));
</pre>
See the plugin programmers reference.  It has updated documentation on the
above new calls and the demo programs are updated as well.   The
short story is plugins can
now be themed at the same level as builtins.  Check the Styles and Themes
section.
<p>
Here's something that might help:
<ul>
	<li>Make your plugin compilable under 0.9.x or 0.10.x by doing this:<br>
		In a header or at the top of your source file:
<pre>
#if ((VERSION_MAJOR>0)||(VERSION_MINOR>9))
#define PLUGIN_STYLE style_id
static gint  style_id;
#else
    #define PLUGIN_STYLE DEFAULT_STYLE
#endif
</pre>
		Access styles and images by using PLUGIN_STYLE as an argument.
		And in the init_plugin() routine, add this:
<pre>
#if ((VERSION_MAJOR>0)||(VERSION_MINOR>9))
    style_id = gkrellm_add_meter_style(&plugin_mon, "somename");
#endif
</pre>
	<li>If you have custom images to load and want to use gkrellm_load_image(),
	it is more difficult to be compilable under 0.9.x and 0.10.x.  You
	could use #if around gkrellm_load_image() calls, or you could just
	not bother and have the requirement that the plugin needs 0.10.x.
</blockquote>


<h4>Changes for version 0.9.9</h4>
<blockquote>
Not much new for this release.  About the only thing is I have followed
the lead of several plugins and added a global function to get the nice
bold (and added italic) text into the Info/Help pages.   You can use it if
you want or keep doing it the way you have been, but one benefit is
that I have an alternate larger font size the user can select if he
wants.  Just insert &lt;b&gt; for bold or &lt;i&gt; for
bold italic in front of
strings in a string array, like this:
<pre><font size="-1">
gchar	*info_text[] =
    {
    "&lt;b&gt;The first ",
    "two words of this line are bold\n"
    "and the last two words of this line ",
    "&lt;i&gt;are italic\n"
    };
...
GtkWidget *text;

...
text = gtk_text_new(NULL, NULL);
gkrellm_add_info_text(text, info_text, sizeof(info_text) / sizeof(gchar *));
...
</font></pre>

If you look at the GKrellM source you will notice _( ) and N_( ) macros
around text strings.  There has been some interest in internationalizing
the program (Turbolinux Japan) and these macros support that.  I don't
know if this will extend to the plugins, so my suggestion is do whatever
you feel comfortable with (the macros are a no-op unless i18n is enabled).
If you choose to do this, then the above info_text declaration would look like:


<pre><font size="-1">
gchar	*info_text[] =
    {
    N_("&lt;b&gt;The first "),
    N_("two words of this line are bold\n"
    "and the last two words of this line "),
    N_("&lt;i&gt;are italic\n")
    };
</font></pre>


I'm giving some thought to a way for plugins to have custom theme images
(as do the builtins), but did not get to it for this release.  Maybe
next time.
</blockquote>

<h4>Changes for version 0.9.8</h4>
<ul>
<li>make install from source and package installation now installs the
	header files.  So, source for plugins can now<br>
	&nbsp &nbsp &nbsp <b>#include &lt;gkrellm/gkrellm.h&gt;</b>
	<br>as a default so people
	compiling plugins do not have to install them in the plugins source
	tree or edit the location of gkrellm.h.
<li>Fixed a bug where DecalButtons were not destroyed when
	gkrellm_destroy_panel() was called.
</ul>

<h4>Changes for version 0.9.7</h4>
<ul>
<li>IMPORTANT: init_plugin() returning NULL is now properly handled.
	Any plugin which
	finds it  cannot install itself because some resource is not available
	should not issue any error messages from the init_plugin() routine.
	If the resource deficiency is serious (some feature not compiled into
	the kernel, etc), the plugin should return NULL.  However, if the
	problem is resolvable (as in a permission problem or setup issue), then
	the plugin should return the address of the monitor structure as normal,
	but should then trap the problem and issue an error message in the
	create_plugin() routine.
	The reason
	for this is that there is now a system wide plugins directory where
	plugins for all users may be installed.  This means plugins may be
	loaded for users who do not want them enabled at all or
	who do not currently have
	permission to access resources needed by the plugin.
	A message in the init_plugin() routine will appear each time GKrellM
	is started and will probably just annoy the user.  The proper place
	for any messages, in the create_plugin() routine, will not be called
	unless the user has asked for the plugin to be enabled.  A message
	here could let the user know what is needed to make the plugin
	accessible, so you could issue the message and then return without
	creating your monitor.  And of course, your update routine needs
	to be aware if the plugin has actually been created.
<li>A flag can be or'ed into a placement value so a plugin can be placed
	after a builtin monitor instead of the default before the monitor.
	For example, to place a plugin after the file system monitors, use <br>
	(MON_FS | MON_INSERT_AFTER)<br>
	I think a good rule to follow would be
	to place a plugin before a particular
	monitor when you are doing it for appearance (ie that is where the
	plugin looks like it should go), but place the plugin "after" a monitor
	when there is a functional similarity between the builtin and plugin.
	Otherwise, a plugin which has a functional similarity and really should
	be placed right next to a builtin monitor may not end up in the right
	place if several plugins are asking to be placed in the same position.
	If I can use current plugins as an example, I think the Mailwatch
	would be a candidate to be placed after MON_MAIL because it has the
	similarity and it is likely to be enabled at the same time as the builtin
	mail monitor.
	The others are probably OK being placed before any particular monitor. 
	The powerbook_pmu plugin does
	not need to be placed after the builtin MON_APM because it will not
	be enabled at the same time the builtin apm monitor is enabled.
</ul>

<h4>Changes for version 0.9.6</h4>
As of 0.9.6 I want to make name changes (and one prototype change)
for these four routines.
But for several versions, I'll keep them around to avoid breaking plugins.
<pre><font size="-1">

Decal   *gkrellm_create_text_decal(Panel *p, gchar *, TextStyle *, Style *, gint, gint, gint);
Decal   *gkrellm_create_pixmap_decal(Panel *, GdkPixmap *, GdkBitmap *, gint, Style *);
void    gkrellm_draw_pixmap_decal(Panel *, Decal *, gint);
void    gkrellm_draw_text_decal(Panel *, Decal *, gchar *, gint);

They are changed to:

Decal   *gkrellm_create_decal_text(Panel *p, gchar *, TextStyle *, Style *, gint, gint, gint);
Decal   *gkrellm_create_decal_pixmap(Panel *, GdkPixmap *, GdkBitmap *, gint, Style *, gint, gint);
void    gkrellm_draw_decal_pixmap(Panel *, Decal *, gint);
void    gkrellm_draw_decal_text(Panel *, Decal *, gchar *, gint);
</font></pre>
Plugins writers should migrate these four routines at their convenience.
This is simply done by replacing
the names, and in the case of gkrellm_create_decal_pixmap(), the following
two calls are equivalent:
<pre><font size="-1">
    gkrellm_create_pixmap_decal(p, pixmap, mask, depth, style);
    gkrellm_create_decal_pixmap(p, pixmap, mask, depth, style, -1, -1);
</font></pre>


<hr size="4">
<h4>Changes for version 0.9.0</h4>

The API for plugins is changed for version 0.9.0.  There are a few
prototype changes and coding style changes.  One change is necessary
because GKrellM now resizes and changes themes without restarting.
This changes the create_plugin() routine from a one time create
function to a create event function which can be repeatedly called.

<pre><font size="-1">
-------------------------------------------------------------------
Coding style change: create_plugin() 

-------------The old style--------------:

static void
create_plugin(GtkWidget *vbox)
	{
	Chart	*chart;
	Panel	*p;

	chart = gkrellm_chart_new0();
	p = chart->panel = gkrellm_panel_new();
	...

	/* Create decals, krells. Configure panel, create panel, create chart */
	...

	gtk_signal_connect(GTK_OBJECT(p->drawing_area), "expose_event",
			(GtkSignalFunc) panel_expose_event, NULL);
	gtk_signal_connect(GTK_OBJECT(chart->drawing_area),"expose_event",
			(GtkSignalFunc) chart_expose_event, NULL);
	}

--------------The new style-------------:

static void
create_plugin(GtkWidget *vbox, gint first_create)
	{
	Chart	*chart;
	Panel	*p;

	if (first_create)
		{
		chart = gkrellm_chart_new0();
		p = chart->panel = gkrellm_panel_new();
		}
	else
		{
		gkrellm_destroy_krell_list(p);
		gkrellm_destroy_decal_list(p);
		}
	...

	/* Create decals, krells. Configure panel, create panel, create chart
	|  just as before.
	|
	| If you create any local pixmaps, widgets, etc you should destroy
	| them or not create them again if this is not the first_create to
	| avoid memory leaks.  You could test for first_create or objects != NULL.
	| See the plugin_example.c for code marked with MMM.
	*/
	...

	if (first_create)
		{
		gtk_signal_connect(GTK_OBJECT(p->drawing_area), "expose_event",
				(GtkSignalFunc) panel_expose_event, NULL);
		gtk_signal_connect(GTK_OBJECT(chart->drawing_area),"expose_event",
				(GtkSignalFunc) chart_expose_event, NULL);
		}
	}



================================================================
Coding style change: panel decal and krell lists are now a GList.

-------------The old style--------------:
Krell *k;

for (k = chart->panel->krell; k; k = k->next)
	{
	...
	}

-------------The new style--------------:
Krell   *k;
GList   *list;

for (list = chart->panel->krell; list; list = list->next)
	{
	k = (Krell *) list->data;
	...
	}

Same change for panel->decal.



================================================================
Coding style change: gkrellm_default_textstyle() function defunct:

-------------The old function--------------:
gkrellm_default_textstyle(p->textstyle, TEXTSTYLE_XXX, style);

-------------Is replaced with several functions--------------:
p->textstyle = gkrellm_panel_textstyle(DEFAULT_STYLE);
p->textstyle = gkrellm_chart_textstyle(DEFAULT_STYLE);
p->textstyle = gkrellm_meter_textstyle(DEFAULT_STYLE);
p->textstyle = gkrellm_chart_alt_textstyle(DEFAULT_STYLE);
p->textstyle = gkrellm_panel_alt_textstyle(DEFAULT_STYLE);
p->textstyle = gkrellm_meter_alt_textstyle(DEFAULT_STYLE);

Use these functions in context.  If you have created a chart with panel
and want to write text on the panel, use gkrellm_panel_textstyle().


================================================================
Function prototype changes (see gkrellm_public_proto.h):

Change gkrellm_create_krell() calls from:
	k = gkrellm_create_krell(krell_image, &p->krell, style);
to
	k = gkrellm_create_krell(p, krell_image, style);


Change gkrellm_create_xxx_decal() calls from:
	d = gkrellm_create_text_decal(label, TEXTSTYLE_XXX, &p->decal,
					style, x, y, w);
	d = gkrellm_create_pixmap_decal(pixmap, mask, n_decals, &p->decal, style);
to
	d = gkrellm_create_text_decal(p, label, textstyle, style, x, y, w);
	d = gkrellm_create_pixmap_decal(p, pixmap, mask, n_decals, style);


================================================================
Monitor structure change:
The pre-spacer and post-spacer members are gone.  There is no longer
a bg_spacer.



=================================================================
Notes:
If you create a krell you can reference it later in two ways (if
it is only a single krell in a panel or meter area):

1) save a pointer to the created krell, and reference that:
	my_krell = gkrellm_create_krell(p, krell_image, style);
	my_krell->full_scale = xx;

2) Don't save a pointer and reference the krell from the GList:
	gkrellm_create_krell(p, krell_image, style);
	KRELL(p)->full_scale = xx;

   Note that in this case you cannot use the old reference style:
	p->krell->full_scale = xx;

If you have more than one krell per panel or meter area, use the first
referencing method, save pointers to all the krells you create.

The same two referencing examples apply to decals as well.


=================================================================
New:
Decals can be converted to buttons.  The plugins_example.c now
creates two decal buttons, so look there.
</font>
</pre>
</body>
</html>