File > Examples menu

[Paul Stoffregen]

I'm hoping we can discuss the Examples menu layout and maybe come to a
consensus on possible improvements?

My main hope is to make Arduino's library search hierarchy visually
apparent, especially when a user has multiple/conflicting copies of a
library installed.

Currently the Examples menu is grouped into 3 categories:

Built-in Examples
Examples from Libraries
Examples from Custom Libraries

I'd like to propose 4 categories, the built in examples, and 3
categories which represent libraries in the user's sketchbook, libraries
from the currently selected architecture, and the bundled libraries.
How exactly these would be displayed, and in what order, I'm not
entirely sure. I'm imaging the category for arch would show the
architecture name, perhaps in abbreviated form? Like "Libraries for
Arduino SAMD Boards" or "Libraries for Arduino AVR Boards". Maybe
"Examples from" is redundant, and better wording could make the other
library categories clearer? Again, I'm not sure what the best words
might be... I just hope something better can be figured out?

I'd also like to propose showing the overridden libraries. Again,
exactly how I'm not entirely sure, but perhaps they'd be
disabled/unclickable. Or maybe they'd have text like "overridded"
appended, maybe clickable but all their examples disabled? The main
idea is to show very visibly when a copy of something like Ethernet is
in the sketchbook, that the Ethernet bundled library is still present
but overridden.

Since 1.6.3, we've had improving info & error messages for library
conflicts. But user confusion still regularly occurs, partly because
the message appear and are noticed only after problems occur, partly
because the full pathnames aren't always meaningful, especially on
Windows and Mac where filesystem heirarchy is often obscured from view.
Hopefully by arranging the Examples menu and by making the overridden
libraries apparent in the menu, we can give users a better conceptual
understanding early on. In my dream world, novice users could easily
understand *before* uploading what they're using a custom copy they
installed in their sketchbook (months or years ago and forgot since)
which overrides all others, or clearly know they're using an
architecture which overrides a builtin lib.

I know any change to the GUI is a big deal and many people have strong
opinions. I hope we can improve things...

[Tom Igoe]

I’m like the idea of to improving the Examples menu, but I’m not sure I understand what you’re proposing. Can you explain your overridden libraries concept a bit more? a sketch would help, even crude, if you’ve got one.

t.

> --
> You received this message because you are subscribed to the Google Groups "Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.

[Paul Stoffregen]

On 03/11/2016 05:44 AM, Tom Igoe wrote:
> Can you explain your overridden libraries concept a bit more?

Library override has been a standard feature Arduino has supported for a
very long time.

In ancient times, like 0012-ish, Arduino had only a single location for
libraries.

Then the ability to override Arduino's libs with your own copy was
added. If you put copy of a library into the libraries folder within
your sketckbook, it would override anything with the same name in Arduino.

Of course, few people knew of this feature, until eventually (thanks
mostly to Adafruit) this folder was automatically created and populated
with a readme file. Adafruit and others published tutorials,
instructing users how to install customized copies of libraries.

With 1.6.x (and the 1.5.x betas) supporting multiple architectures, this
was expanded to a 3 tier system. Libraries supplied with particular
architecture override those in Arduino's libraries, and libs in the
sketchbook libraries override both of the others.

Starting with 1.6.2, we now have the Library Manager, which automates
downloading and installing libs to the sketchbook libraries folder.
It's pretty much the same as people following Adafruit's manual
tutorials, without the human errors.

Few people really understand library overrides, probably because we've
never really made it visually apparent. My hope is we can restructure
the Examples menu in a way that doesn't demand attention, but does
visually represent the 3 tiers. My main hope is there's nothing
extraordinary about this change in the common case where libs do not
conflict. But in the troublesome cases where a user has a conflict, I
want to very visibly show the overridden libs which *can't* be used, so
they have a strong visual cue that duplicate copies exist, and they can
understand which one Arduino will really use.

[Tom Igoe]

This makes sense. It’s not just connected to the examples, though. The same three-tier structure should probably be reflected in the Sketch -> Include Library menu.

I’m not totally sure of the solution yet either. I can see the sense of an additional tier, but personally if a library’s got an override copy in ~/Documents/Arduino/libraries, I’d like to see the two marked next to each other somehow. When they’re in separate tiers, I tend to think of them as separate and non-conflicting. This is another case where Alice might have a good idea, so I am cc:ing her here as well. Alice, the full thread is on the developer’s list.

What do others think?

[David Mellis]

This seems like a lot of information to convey in a menu, but maybe it's possible? I think the Include Library menu would be a more natural place to show overridden libraries than the example menu. But isn't there also already a message that prints when you compile using a library that is overriding another one?

Also, to what extent is the problem with library priority / placement itself vs. people's understanding of it? For instance, if updates to built-in libraries didn't go in the user's sketchbook (and therefore override libraries in third-party hardware folders), how much of the problem would that deal with? What other ways do you notice people ending up with libraries overridden without realizing it?

[Paul Carpenter]

The examples menu and Include Libray menu are two different actions, I do agree with better organisation, preferably same tree structure now the problem in my view is Examples tree should list ALL and never disable examples.

My reasoning is this

1. You may not have a board or even the correct board set whne looking at Examples tree
   
2. Examples tree actaually opens another instance of the IDE with that example open as a SEPARATE sketch, which you may use to see how something is done to make your sketch do something similar.
3. Include Library is actually inserting the necessary include statement ONLY in the CURRENT TAB
4. Include library also includes too many headers, so if a library has private include headers even if you have selected a library it will include all the *.h files in the folder NOT just the library.h file.

So the whole Include Library probably could do with an overhaul.

Perhaps on libraries with Include Library, only when a board is selected will the architecture specific ones be highlighted, general ones always highlighted. The library architecture does not have specific board properties to limit to a board.

[Paul Stoffregen]

Quick question: can anyone point me to boards which make use of the referenced core feature *and* provide customized libraries as part of their platform package?

I'm working this patch to (hopefully) improve the Examples menu.  Referenced cores are a subtle corner case which I'd really like to test with actual published boards, if any exist.

[per1234]

https://github.com/JChristensen/mighty-1284p/tree/v1.6.3

[Paul Stoffregen]

Thanks.  That really helps.  :)

If anyone's curious how this looks, I'm working on a patch that shows which libraries are provided by currently selected platform.  Currently some go into "Examples from Libraries" and others into "Examples from Custom Libraries", seemingly randomly.  Normally this patch adds just 1 extra section.  When a board references another core, two extra sections are added:


(hopefully this image will come through.....)

[Paul Stoffregen]

I submitted a pull request. Test builds are available, if anyone's
curious to see first-hand how this changes the Examples menu.

https://github.com/arduino/Arduino/pull/5178

I realize there's much more urgent stuff going on, and perhaps there may
be controversy about any changes to GUI stuff like this menu. But if
anyone's interested, please give the test build a look. I've personally
answered quite a few user questions, such as "why isn't library XYZ in
the menu" which I hope will be solved by this improvement. Should this
Examples menu change become part of a future Arduino release? Please
let me know what you think?