Re[2]: [lmi] Generating screenshots automatically

[Vadim Zeitlin]

On Sat, 14 Feb 2009 14:51:18 +0000 Greg Chicares <address@hidden> wrote:

GC> [hopping from
GC>   http://lists.nongnu.org/archive/html/lmi/2009-02/msg00021.html
GC> to unify message threading]

 Hello,

 I'm replying to all of

http://lists.nongnu.org/archive/html/lmi/2009-02/msg00022.html
http://lists.nongnu.org/archive/html/lmi/2009-02/msg00023.html
http://lists.nongnu.org/archive/html/lmi/2009-02/msg00024.html
(not http://lists.nongnu.org/archive/html/lmi/2009-02/msg00025.html)
http://lists.nongnu.org/archive/html/lmi/2009-02/msg00026.html

in a single message because they're not independent and I thought it would
be more convenient to discuss all different issues together. To avoid
losing important questions I've used special prefix "GQ" for them below.
The letter "G" is explained by the existence of another marker "VQ" for the
questions to Vaclav. In both cases I'd appreciate if you could answer them,
thanks in advance!


 First let me address the narrow issues related to the initially envisioned
command line utility for creating screenshots of the windows defined in XRC
files as it still remains useful, AFAICS.

GC> On 2009-02-12 15:15Z, Vadim Zeitlin wrote:
GC> 
GC> >  It already looks not too bad, and so far I spent less than 3 hours on it
GC> > only. It's far from being finished however, there are at least the
GC> > following 2 big problems I'm aware of:
GC> >
GC> > 1. Radio box items help texts are not handled: this will need some changes
GC> >    to the code as currently I iterate over all windows and radio box items
GC> >    are not windows, but this won't be difficult to do (at the price of
GC> >    having to explicitly test for wxRadioBox using dynamic_cast).
GC> 
GC> Yes, that's important. A dynamic_cast seems perfectly appropriate.

 This is done now.

GC> > 2. The size of lower HTML window is guessed rather than computed

 I still didn't have time to do this (and it might be rendered irrelevant
if we decide to generate HTML) but I do know how to do it so it's not a
problem any more.
 
GC> > 3. Currently only wxPanels are supported, and not wxDialogs or wxFrames.
GC> 
GC> For lmi, the hardest part is annotating the tabbed dialogs, which are
GC> large, complex, and likely to change often; so that's where automation
GC> is most beneficial.
...
GC> When that's all finished, we can return to wxMenu etc. in a future month.

 I'm afraid my question was insufficiently well-formulated. In fact I
didn't think at all about wxMenu and wxToolBar. And I'm very glad to leave
them for the future as I have no idea how to make menu screenshots right
now anyhow.

 All I wanted to ask is whether each individual window for which we want to
generate a screenshot is always going to be a wxPanel or if we also need to
be able to take such screenshots of wxDialogs (I don't see any wxFrames at
all in LMI XRC files). I.e., to be even more precise, should this work for
"dialog_containing_preferences_notebook" and "dialog_containing_notebook"?
(GQ1)

GC> > 4. You need to specify the name of the panel to load from the XRC file as
GC> >    shown above. The tool could also iterate over all panels but it's not
GC> >    clear what should be used for the output file name and the title in the
GC> >    screenshot in this case (currently both can be specified on command
GC> >    line).
GC> 
GC> Iterating over all panels automatically is pretty important.

 Ok, I'll add it, thanks. Vaclav, is there a way to find all top-level
objects defined in an XRC file or will I need to parse XML to do this? (VQ1)

 Also, I assumed we wanted to have one PNG (or one HTML) file per top-level
object, but maybe we want to have one output file per each input XRC file
or even one output file combining everything defined in all input XRC files?
(GQ2)

GC> Do we need to choose a final naming convention now?

 No, I'll just use something simple for now (e.g. <xrc_name>_<object_name>)
and we can always change it later.

GC> > 5. HTML is currently hardcoded but could be made configurable by using a
GC> >    template in an external file.
GC> 
GC> I'm not quite sure what the template would look like;

 Something like this:

        <html>
        <body>
        {{#WINDOW}}
        <em>${{WINDOW_NAME}}</em>:&nbsp;${{WINDOW_HELP}}<br/>
        {{/WINDOW}}
        </body>
        </html>

This (ugly) syntax is used by google-ctemplate library (see
http://code.google.com/p/google-ctemplate/). But even if it's painful to
read, it's not that bad and there doesn't seem to be many other alternative
template expansion libraries for C++ anyhow. And I already used this one in
another project recently and so would rather reuse it in this one if
possible instead of writing yet another template engine myself.

 And the syntax is not that important anyhow. What counts is that you (or
anyone else familiar with HTML) could modify it in any way you want in
order to achieve the appearance which you prefer. E.g. you could replace it
with

        <html>
        <body>
        <dl>
        {{#WINDOW}}
        <dt>${{WINDOW_NAME}}</dt><dd>${{WINDOW_HELP}}</dd>
        {{/WINDOW}}
        </dl>
        </body>
        </html>

And just rerun the program -- without any need to recompile it.

GC> but might this question vanish if we pursue the alternative in (2)
GC> above?

 I don't think so, rather on the contrary: if you produce HTML you probably
want more control over it than over PNG. E.g. you may want to be able to
specify CSS for the different elements and so on.

 So my question still remains: do you need to be able to configure the HTML
produced by the program (whether it's output directly or used to generate
PNG) or do you think hardcoding it inside the program itself is acceptable?
(GQ3)


On Sat, 14 Feb 2009 15:33:16 +0000 Greg Chicares <address@hidden> wrote:

GC> Yet another variation: instead of drawing lines or arrows to connect a
GC> control to its annotation, enumerate both serially. Then the annotations
GC> read as footnotes. Here's a specimen wherein to save time I number only
GC> five fields, but I think it makes the idea clear:
GC> 
GC>   
https://savannah.nongnu.org/file/skin_plan_panel-numbered.png?file_id=17447

 I really like this, it seems very clear. I wonder if we need to keep the
window names in the output if we do it like this -- aren't they superfluous
now? (GQ4)

GC> What's most important, though, is that numbers are probably easier to
GC> implement than arrows,

 Absolutely.

GC> The form of the numbers is an implementation detail, but let me toss
GC> out an idea or two here. Placement of the numbers on the screenshot
GC> could become tricky if we want them aligned with titles. In the specimen
GC> above, I manually placed 2-5 just outside the northwest corners of their
GC> controls, but put 1 in a different spot. Instead of letting this devolve
GC> into another NP-hard problem, why don't we just center each number on
GC> the center of its control?

 I could do it like this. OTOH placing them near the label shouldn't be too
difficult if we assume that the label is always the control preceding the
one we're processing (which should be always true, except for radio boxes,
as usual).

GC> I generally avoid using color on dialogs, but it can nevertheless be
GC> introduced by OS theming. I would suppose that most themes would let us
GC> use a full-hued red as a contrasting color in general.

 In the worst case I think it wouldn't be a huge restriction to ask people
to switch to the standard theme when producing the screenshots. After all,
the screenshots are supposed to represent the standard view of the dialog
and if you make it in some kaleidoscopic theme people might be confused.

GC> Drawing a circle around each number might make its footnote-nature more
GC> apparent. I suppose that'd be nice if it's not too difficult to do.

 No, at least not on the image itself. I don't think it's possible to use
rounded numbers in wxHTML easily though (by difficult way I mean that we
could always create a bitmap for each of them and include it in the HTML
using <img> tag). I'd be tempted to just use <ol> and <li> for this.
Vaclav, does wxHTML support specifying a different colour for <li>? (VQ2)
I'm looking at src/html/m_list.cpp right now but still don't see it easily,
mostly because I don't know what does wxHtmlWinParser::GetActualColor()
return.

GC> Is it possible in general to choose a number font that'll contrast with
GC> the dialog font? A larger font size or weight might also make the numbers
GC> stand out better.
GC> 
GC> If numbers tend to obscure part of a dialog over which they're superimposed,
GC> then we might want to make them, say, half-transparent. It's hard to guess
GC> right now whether that'd ever be worthwhile.

 Yes, I'll try to do it as simply as possible (just rounded numbers without
any transparency) and then we'll see if we need to improve it.



 This finishes the discussion of the current version of the tool, let me
now turn to its future evolution possibilities:

On Sat, 14 Feb 2009 18:29:35 +0000 Greg Chicares <address@hidden> wrote:

GC> On 2009-02-14 14:51Z, Greg Chicares wrote:
GC> > Okay, you're rendering the screenshot and its annotations all together 
into
GC> > one graphic, as we originally discussed.
GC> > 
GC> > Perhaps we should consider an alternative idea:
GC> >  - render the screenshot into a graphic
GC> >  - embed the screenshot in an html <img>
GC> >  - write the annotations in html <p> paragraphs
GC> > Then the result is html instead of (e.g.) png. What I think we gain
GC> > is that the html annotations could someday contain hyperlinks.
GC> 
GC> Let me say more about that. Here's a brief example:
GC> 
GC> <h2>The "Plan" screen</h2>
GC> <p>
GC>   <img src="plan.png" alt="[screenshot]">
GC> </p>
GC> <p>
GC>   <em>ProductName</em>:
GC>   <!-- All we have today is a one-word explanation: -->
GC>   Product
GC> </p>
GC> ...more annotation paragraphs

 There is no problem with generating this, of course. As a side note, this
probably automatically answers GQ2 above: if we do it like this, we need
one PNG per top-level object (unless we embed the image in HTML itself
using data:// schema but I don't think it's reasonable to do it for such
big bitmaps) but presumably only a single HTML file for all inputs.

 I also think that this answers GQ3: we absolutely do need a template
defining the non-variable parts of HTML in this file as otherwise you'd
almost surely need to manually edit the tool output every time after
running it.

GC> The problem, though, is that then there's no obvious way to create
GC> this html from the WXXRC file.

 It's worse than non-obvious, I still don't see any satisfactory way to do
it even after discussing it with Vaclav.

GC> Well, I could replace the <help> text:
GC> 
GC>   <object class="wxListBox" name="ProductName">
GC> -     <help>Product</help>
GC> +     <help><a href="external.html">External html link</a></help>
GC>   </object>
GC> 
GC> but then I've broken the wxHtmlHelp facility.

 Actually my preferred solution for the current state of wx is to do
something like this and define a custom help controller which would
separate the information which really needs to be shown in
context-sensitive help from the rest. This is a bit heavy but should work.

GC> I could propose adding a <userdata> element to the "common attributes"
GC> enumerated in 'tn0014.txt' for all controls--of course, only if that
GC> makes sense for wx in general--but if <userdata> is wanted today, then
GC> surely tomorrow a need for <userdata0>, <userdata1...> will arise; so
GC> that's probably not a good idea.

 Indeed. We need a generic extension mechanism.

GC> Or I could bastardize <tooltip> for that purpose, but that's too
GC> appalling.

 Agreed.

GC> Or I could write a slightly bigger file of present-xrc-contents +
GC> custom-extra-data, and generate the "real" '.xrc' files from that.

 Not really appealing neither.

GC> But wait: as an experiment, I modify 'skin.xrc' in this vein:
GC>   <object class="wxListBox" name="ProductName">
GC>       <help>Product</help>
GC> +     <foo>xyzzy</foo>
GC> and to my surprise it "works": the <foo> element seems to be ignored
GC> silently. Is that a behavior we can rely upon?

 Yes. As XRC allows you to define your own custom controls the set of
allowed tags in it is open. I was a bit surprised that the set of tags for
the standard controls was open too but Vaclav confirms that this is
intentional. So you could do something like this.

 It would be better to use a separate namespace, i.e. <lmi:description>
tag, instead of just <foo> (or just <description>). I'm not sure if wx XML
parser deals with namespaces correctly but it should and if it doesn't, it
shouldn't be difficult to fix it.

GC> I guess that'd mean we'd have to parse the xml, but then again we'd
GC> save the effort of rendering the text to png. What do you think?

 This would certainly work and Vaclav thinks that this is the best
solution. I don't like it that much because currently XRC parses XML but
simply throws away this information and I will need to reparse it again to
recover it. I'd prefer to be able to hook handlers for custom tags into XRC
parsing process but this would require some changes in wx. Please let me
know if you think it could be worthwhile to do it from LMI point of view.


 To finish with this I'd just like to mention the possibility that we might
not need any extra information at all: in principle we could just always
generate HTML of the form

        <a href="details.html#window_name">window_help</a>

and write details.html manually and simply ensure that the anchors with the
right names are defined.


On Sun, 15 Feb 2009 16:38:57 +0000 Greg Chicares <address@hidden> wrote:

GC> On 2009-02-14 22:28Z, Greg Chicares wrote:
GC> One more idea that might be useful: can your work be embedded in lmi?

 I don't see why not. But I don't know how exactly do you plan to invoke it
from the LMI GUI so for now I'll continue developing it as a standalone
utility -- but we will always be able to plug its code wherever you want to
call it from, it's already packaged as a simple function taking a couple of
parameters and returning a wxBitmap (this would be slightly more
complicated with HTML though).

 Regards,
VZ