[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lmi-commits] [lmi] master e4ec715 4/7: Rewrite documentation
From: |
Greg Chicares |
Subject: |
[lmi-commits] [lmi] master e4ec715 4/7: Rewrite documentation |
Date: |
Wed, 23 May 2018 21:18:25 -0400 (EDT) |
branch: master
commit e4ec715bcbb253487425fdf6c39a028b9b1c9035
Author: Gregory W. Chicares <address@hidden>
Commit: Gregory W. Chicares <address@hidden>
Rewrite documentation
---
wx_table_generator.cpp | 77 +++++++++++++++++++-------------------------------
1 file changed, 29 insertions(+), 48 deletions(-)
diff --git a/wx_table_generator.cpp b/wx_table_generator.cpp
index d3eba37..d14ea59 100644
--- a/wx_table_generator.cpp
+++ b/wx_table_generator.cpp
@@ -33,49 +33,44 @@
// accessible? But their values can also be changed by clients, and
// isn't that undesirable?
-// Under what circumstances might columns be hidden, centered, or clipped?
+// Elasticity and clipping
//
-// General answer:
-// In principle, all of those are independent. In practice, inelastic
-// columns are centered and elastic columns are clipped and only the
-// former can be hidden. But I don't think this low level class should impose
-// such high level constraints on its use, which is why it doesn't do it.
+// Most columns are inelastic: they have a fixed minimum width and
+// are not clipped lest crucial information (e.g., part of a number)
+// be lost. The archetypal elastic column is a personal name, whose
+// width is practically unlimited and might even exceed the total page
+// width; it is better to truncate one extremely long personal name
+// than to present an error message and produce no report at all.
//
-// - is_hidden()
+// An ideal report generator might call GetTextExtent() on every row
+// of data to determine a column's ideal width, but this one favors
+// speed by setting a presumptive maximum width for each column.
+// Therefore, it treats a personal-name column as having no natural
+// width at all. Its minimum width might be set equal to its header
+// width, but such a refinement is needless in the problem domain. In
+// the most extreme case, all inelastic columns would fit, but there
+// would be not a single pixel available for elastic columns, which
+// would all in effect be dropped; again, in the problem domain, that
+// would actually be preferable to failing to produce any output.
//
-// All potential data are passed for every row; is_hidden() suppresses
-// any column that needs to be filtered out.
+// Therefore, elastic columns are clipped, and inelastic ones are not.
+// All other column properties are independent, and specified by
+// arguments, but clipping depends on the elasticity argument. It is
+// distinguished only because clipping is a distinct layout operation.
//
-// - is_clipped()
-//
-// And what sort of columns need to be clipped? As currently implemented,
-// this function is equivalent to is_elastic()--i.e., only
-// the "Participant" column on group quotes?
-// Answer: Currently, yes, as it's the only elastic column.
-//
-// Does this all boil down to...
-// - left-align and clip the group-quote "Participant" column
-// - center all other group-quote columns
-// - ignore all these accessors for illustration PDFs
-// ?
-// Answer: yes.
-
-// - is_hidden(): A hidden column is present in the data passed into
-// this class, but is to be suppressed so that it doesn't appear in
-// the output at all.
+// - is_hidden(): Data for every row of all potential columns are
+// passed into this class; hidden columns are suppressed so that
+// they don't appear in the output at all.
//
// - is_elastic(): An elastic column has no innate fixed or preferred
// width. After all inelastic columns have claimed their required
// widths, any remaining width available is prorated among elastic
// columns, which therefore may be wider than their widest contents
// or narrower than their narrowest. As a consequence, elastic
-// columns must be clipped if necessary.
+// columns are clipped--vide supra.
//
-// - is_clipped(): Indicate whether column contents need to be
-// clipped when outputting it. Only elastic columns are clippable:
-// for example, personal names are of unbounded length and might
-// even exceed the total page width. Inelastic columns, OTOH, have
-// fixed minimum widths and must never be clipped.
+// - is_clipped(): A clipped column is truncated to fit its allotted
+// space. Only elastic columns are clipped--vide supra.
class wx_table_generator::column_info
{
@@ -513,25 +508,11 @@ void wx_table_generator::compute_column_widths()
return;
}
- // Lay out elastic columns in whatever space is left over
- // after accounting for all inelastic columns.
+ // Lay out elastic columns in whatever space is left over after
+ // accounting for all inelastic columns. Clip to make them fit.
//
// If there's more than enough space for them, then expand them
// to consume all available space.
- //
- // If there isn't enough space for their headers and contents,
- // then clip them. Motivation: the archetypal elastic
- // column is a personal name, which has practically unlimited
- // width. On a group premium quote, numeric columns must never
- // be truncated, but truncating one extremely long personal name
- // is preferable to failing to produce any quote at all. It would
- // of course be possible to take the header of such a column as
- // its minimal width, but that would be a useless refinement in
- // the problem domain. In the most extreme conceivable case, all
- // inelastic columns would fit, but there would be not a single
- // pixel available for elastic columns and they would all
- // in effect be dropped; again, in the problem domain, that would
- // actually be preferable to failing to produce any output.
if(n_elastic)
{
int const width_of_each_elastic_column
- [lmi-commits] [lmi] master updated (716c729 -> 9f0eebc), Greg Chicares, 2018/05/23
- [lmi-commits] [lmi] master 15f8f62 1/7: Rename some local variables for concinnity, Greg Chicares, 2018/05/23
- [lmi-commits] [lmi] master 21260f8 3/7: Rename a member function, Greg Chicares, 2018/05/23
- [lmi-commits] [lmi] master 149a288 6/7: Improve a local variable's name, Greg Chicares, 2018/05/23
- [lmi-commits] [lmi] master e4ec715 4/7: Rewrite documentation,
Greg Chicares <=
- [lmi-commits] [lmi] master 151a1ea 2/7: Add missing period at end of sentence, Greg Chicares, 2018/05/23
- [lmi-commits] [lmi] master 9f0eebc 7/7: Rename certain local variables, Greg Chicares, 2018/05/23
- [lmi-commits] [lmi] master f1a98e0 5/7: Improve concinnity, Greg Chicares, 2018/05/23