On 2010-09-29 21:40-0400 Hezekiah M. Carty wrote:
> On Tue, Sep 28, 2010 at 6:46 PM, Alan W. Irwin
> <irwin@...> wrote:
>> On 2010-09-28 14:30-0700 Alan W. Irwin wrote:
>>> For the "simplest is best" reasons [...], I am going to drop cmap1
>>> from pllegend. I will try to finish that by late this afternoon.
>> Done as of revision 11231.
> While working on the OCaml interface to pllegend, I came up with a
> potential improvement to the C interface:
> What do you think of changing the pllegend API somewhat to allow only
> specifying the entries which are actually used? For example, if there
> are no symbols, the symbol arrays would be empty. If there are two
> lines and one box, there would be two elements in the line arrays and
> one in the box array. nlegend would still be the total number of
> entries in the legend, and opt_array would be used to specify where
> the legend entries are placed.
> Here is a example subset of parameters:
> nlegend: 4
> opt_array: PL_LEGEND_LINE, PL_LEGEND_LINE, PL_LEGEND_SYMBOL |
> PL_LEGEND_LINE, PL_LEGEND_LINE
> line_colors: red, blue, purple, green
> symbol_colors: blue, yellow
>> From these (plus styles, widths, symbols, etc), the legend would show up as:
> 1. blue symbols, red line
> 2. blue line
> 3. yellow symbols, purple line
> 4. green line
> Does this make sense? I think it would make passing arguments to
> pllegend a bit more predictable as no dummy entries are required, but
> I don't know if others would feel the same way.
> I'm willing to make an attempt at implementation if you think it is
> worth considering.
Thanks for thinking some more about what is possible with pllegend,
but in this case I do not like this idea. Instead, I prefer the
present identical dimensions for all quantities so that the same
position of each array always refers to the same legend entry. I
think that is much less confusing to users (see below for an example).
Furthermore, note I have been careful with the present implementation
to insure no unused quantities (as determined by the bits set in each
entry for opt_array) are ever referred to. So you only have to
specify quantities that opt_array indicates will actually be used. I
did specify all pllegend arrays completely for example 4 because I
wanted to facilitate my experimentation testing (and hopefully yours
as well) of that example legend with all combinations of possible
opt_array values, but full specification is not necessary, and once we
get to propagating example 4 post-release I will leave opt_array in
its present form, set the unused box arrays for that example to NULL,
and also simply ignore any unused quantities for each legend entry
rather than setting them. So the preparation and call will look like
// Draw a legend
// First legend entry.
opt_array = PL_LEGEND_LINE;
text_colors = 2;
text = "Amplitude";
line_colors = 2;
line_styles = 1;
line_widths = 1;
// note from the above opt_array the first symbol (and box) indices
// do not have to be specified
// Second legend entry.
opt_array = PL_LEGEND_LINE | PL_LEGEND_SYMBOL;
text_colors = 3;
text = "Phase shift";
line_colors = 3;
line_styles = 1;
line_widths = 1;
symbol_colors = 3;
symbol_scales = 1.;
symbol_numbers = 4;
symbols = 3;
// from the above opt_arrays we can completely ignore everything
// to do with boxes.
plscol0a( 15, 32, 32, 32, 0.90 );
pllegend( PL_LEGEND_BACKGROUND, 0.57, 0.85, 0.06, 15,
1.0, 1.0, 2.0,
1., text_colors, text,
NULL, NULL, NULL,
line_colors, line_styles, line_widths,
symbol_colors, symbol_scales, symbol_numbers, symbols );
Note the second entry above is especially complicated because two
plotted possibilities are specified for that entry, but a more normal
case would be only one plotted possibility (a box, line, or line of
symbols) alone for each entry which reduces what has to be specified.
I am also thinking about the possibility of specifying defaults for
many/most arrays that are set to NULL within pllegend for the core C
library. For example, if line_styles (or box_patterns) is NULL use a
continuous line (or solid fill for the box) for each entry, But this
change concerning the meaning of a NULL array in the core C version
doesn't change the core C version API so I intend to think some more
about this after the release before doing anything about it.
Also, for the many of our language bindings that allow function
overloading, I think as a convenience to users it would be fine to
have 7 overloaded pllegend possibilities corresponding to the 7
possibilities (assuming you are going to exclude the not, not, not
combination) of boxes or not; lines or not; and symbols or not. Also,
there may well be additional overloading possibilities when say
box_patterns or line_styles (or quite a few other possibilities with C
defaults) are missing from the argument list. But all of such
overloading considerations should be dealt with after the release.
Alan W. Irwin
Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).
Programming affiliations with the FreeEOS equation-of-state implementation
for stellar interiors (freeeos.sf.net); PLplot scientific plotting software
package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of
Linux Links project (loll.sf.net); and the Linux Brochure Project