Re: [lmi] Generating screenshots automatically

[Greg Chicares]

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

On 2009-02-12 15:15Z, Vadim Zeitlin wrote:
>
>  I have a first working version of XRCShot tool which is capable of
> generating screenshots of the specified panel defined in an XRC file
> annotated with the help texts for its children.

I uploaded a specimen of your prototype's output here:

https://savannah.nongnu.org/file/skin_plan_panel.png?file_id=17446

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

Yes, that's important. A dynamic_cast seems perfectly appropriate.

> 2. The size of lower HTML window is guessed rather than computed, i.e. it
>    could easily become too small for the text shown in it. This is a
>    somewhat serious problem as it means I'd have to change my approach of
>    showing wxHtmlWindow on screen as I do now and render HTML off screen,
>    but -- thanks to Vaclav's help with this -- this should be easy to do as
>    well.

Okay, you're rendering the screenshot and its annotations all together into
one graphic, as we originally discussed.

Perhaps we should consider an alternative idea:
 - render the screenshot into a graphic
 - embed the screenshot in an html <img>
 - write the annotations in html <p> paragraphs
Then the result is html instead of (e.g.) png. What I think we gain
is that the html annotations could someday contain hyperlinks.

>  There are also some missing features, please let me know which of those
> would be useful (and in which order):

See below, but to summarize, in decreasing priority order:
  (4) iterate now; defer naming if feasible
  (3) defer: not needed this month
  (5) obviated by alternative suggested for (2) above?
  (6) omit (just use png)

> 3. Currently only wxPanels are supported, and not wxDialogs or wxFrames.

For lmi, the hardest part is annotating the tabbed dialogs, which are
large, complex, and likely to change often; so that's where automation
is most beneficial.

Other UI elements such as you list, as well as wxMenu and wxToolBar,
might be nice for a completely generic UI-documentation tool, but I'm
not sure they'd all be very useful. For one thing, <help> text for a
pulled-down menu can be viewed on the statusbar, cycling through the
menuitems with the up- and down-arrows, and toolbar <help> text can
be seen on the statusbar by running the mouse over the toolbar--so
there's already an easy way for end users to go through the entire
scope of these UI elements. OTOH, today there's no easy way for them
to see <help> text for every field in a tabbed dialog: clicking [?]
for every field is too cumbersome.

For another thing, menu and toolbar commands are already documented in
the user manual, e.g.:
  http://www.nongnu.org/lmi/menu_commands.html#menu_file
so there's no immediate need to automate that. However, in the long
term, it would be good to generate that html automatically. That's not
a mere frill, either: the whole theme of this work is that manually-
written documentation tends to become out of date, and indeed this part
  http://www.nongnu.org/lmi/menu_commands.html#menu_illus
is no longer synchronized with the program: the second and third commands
now have their own icons, and the fourth and fifth no longer exist.

Soon I'll be conducting user training in a remote office, and it'd be
embarrassing to field questions about those defects. "Oh, we designed
this in a way that invites defects to creep in, and didn't have the
discipline to remove them, so...just ignore the documentation that I've
prepared for your reference"?

Furthermore, we've already fielded questions about this in our main office.
If we don't copy all icons from both the "sources" and "web" repositories
into an end-user distribution, including those that have become obsolete
in one repository but not the other, then we get missing-image runtime
errors. Discussing this issue has consumed more effort than it would have
taken to keep both repositories synchronized, but synchronization slipped
through the cracks as "urgent" priorities were piled upon us. In the long
term, automation saves both expense and embarrassment.

For the time being, though, we'll fix those defects manually. We should
focus on automating annotated screenshots for the tabbed dialogs now.
When that's all finished, we can return to wxMenu etc. in a future month.

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

Iterating over all panels automatically is pretty important. Do we need
to choose a final naming convention now? It's probably better to defer
that if we can, because we're still in the prototyping stage.

> 5. HTML is currently hardcoded but could be made configurable by using a
>    template in an external file.

I'm not quite sure what the template would look like; but might this
question vanish if we pursue the alternative in (2) above?

> 6. Output format is always PNG but we could allow selecting among any of
>    formats supported by wx.

We recently converted all lmi graphics to png (except for the unavoidable
'lmi.ico' for msw), and I see no reason ever to use any other format.