Bad Documentation: menuMgr.navigateToMenu makes menu unable to scroll up

[luwenjin]

How to reproduce:

1. Open Example simpleU8g2
2. Add menuMgr.navigateToMenu(&menuSettings, &menuSettingsSaveSettings); to the end of onStartToasting function
3. Run the firmware, select Start toasting >>
4. the menu will focus on Settings, and unable to move the cursor up.

p.s. But if I change the code to menuMgr.navigateToMenu(&rootMenuItem(), &menuSettings), it will focus on Settings and free to scroll up and down.

[davetcc]

Unless I'm mistaken (please correct me if I'm wrong) it seems that you're trying to add sub menus as navigation items. However, it should always be the first child item that is added. Again, it looks like the docs are not very clear on this, I'll clean up the documentation so it makes it clear that pushing navigation should always be done using the first menu item and not the sub-menu.

If that is the case, you can get the suitable item for adding calling getChild() on the submenu,

[luwenjin]

I was trying to navigate to another submenu by code.

For example, if I have such menu structure

root
  + B
    - B1
    - B2
  + C
    - C1 >>

If my cursor is on C1, in C1's callback, can I use menuMgr.navigateToMenu to navigate to the submenu of B and make the cursor on B2 ? How ?

[davetcc]

If you wanted to present another menu you'd normally get the first child item and present that.

For example:

menuMgr.navigateToMenu(menuSub.getChild());

menuMgr.navigateToMenu(menuSub.getChild(), &menuIemToBeActive);

Thanks for raising this, I've made the guide much clearer: http://thecoderscorner.com/products/arduino-libraries/tc-menu/menumanager-and-iteration/#navigation-around-menus

[luwenjin]

So, If I want to present menu B2, I shall call menuMgr.navigateToMenu(menuB.getChild(), &menuB2);, am I right?

[davetcc]

Yes, that should do what you want, it will push menuB's first item onto the navigation stack and then make B2 active.

[luwenjin]

It works as expected! 😄

But I still feel the usage is a bit counter intuitive.
If I can call menuMgr.navigateToMenu(menuB.getChild(), &menuB2) to active menu B2 would be more straightforward, for the first argument is redundant.

I can understand the current method may be due to uni-directional linked list,
but as a user's perspective, I still hope the navigateToMenu can be simplified.

[davetcc]

The only thing that is possible is to add a helper method navigateToSubMenu that deals with the indirection, but it wouldn't work for root. But for root you'd normally just call menuMgr.resetMenu(true) anyway.

Maybe providing null to that function would do a resetMenu(true) meaning it was univeral.

[luwenjin]

but it wouldn't work for root

I don't quite understand how does navigateToSubMenu(menuItem) unable to to work for root.
Root is a menuItem, if we need to select the first menu item in the top level, it seems navigateToSubMenu(&rootMenuItem()) will do it without ambiguity.

[davetcc]

But suppose it is SubMenu item (and it sometimes is on designs I've done), then do you show that or root? The only way would be to pass in a specially defined constant (probably null is best) to select root.

This is why navigate is the way it is at the moment..

[davetcc]

For example

menuMgr.navigateToSubMenu(ROOT_MENU);
menuMgr.navigateToSubMenu(menuMySub);

[luwenjin]

let's take this menu as an example:

root
  + B
    - B1
    - B2
  + C
    - C1 >>

In my opinion:

• menuMgr.navigateToSubMenu(B); should show

app name
-----
> B
  C

• menuMgr.navigateToSubMenu(B1); should show

B
-----
> B1
  B2

• menuMgr.navigateToSubMenu(B2); should show

B
-----
  B1
> B2

Did you mean by this way, the problem is unable to navigate to this?

> B
-----
  B1
  B2

[davetcc]

I think what you're suggesting now is how it works presently, you navigate to the first child that you want to present. To be honest, I think once understood, it's by far the clearest way given how the menu is structured on the device. Maybe we could have a new function like the one you suggest, where you skip needing to know which parent menu the item is in, something like: menuMgr.navigateAndActivate(thisItem);. Where it locates the right menu list and puts it on display and then activates the item.

[luwenjin]

I totally agree, after your first few comments, I've known how to use menuMgr.navigateToMenu, It provides full functionality to menu navigation, I will have no problem using it later on.

Just share some new user experience here:
When I wanted to navigate the menus at first, I did not lookup the document throughly (already scanned a few times for other problems), I just looked up the function list brought up by the IDE and find which function is likely to meet my needs.
I found navigateToMenu, seems to be what I want, I tried it with a few combinations, and failed.
My main confusion at that time was: I already know where I want to put my cursor on, why should I provide another menuItem.
And my main 'mistake' is not adding .getChild() to the first argument.
As a new user to this library, I encountered this obstacle, and other new users might encounter this too, bringing them a steeper learning curve.

Here is the document brought up by vscode:

I might mostly be misled by the description of the first argument.
Here I see the word "root", it immediately brought me to the concept of "root" in the Designer UI, which is the parent of the menu.
But actually the first argument represent the first menuItem of the menu I want to display.
Maybe change the description will solve the confusion, but I'll never know for sure, because I can't unlearn what I've already learned 😆
Since I'm not a native English speaker, I'm not able to provide any suggestions on the description, sorry for that.

As for providing another API like menuMgr.navigateAndActivate(thisItem), I will feel guilty if you add this to the library, it's more redundant to the library than the first argument of menuMgr.navigateToMenu😆

Maybe optimize the description of the first argument is enough.

[luwenjin]

I have another thought about this argument.

What if the menu is not a customed one, but I say customMenu=true, will it be stored in the history?
If the essence is whether storing to the history or not, how about naming it to something like skipHistory?

[davetcc]

Thanks, I think I have the context now, I don't think a new method is needed, I just need to make sure that the inline code documentation is a lot clearer when 3.0 comes out shortly

[davetcc]

Do you think we can we close this out now? The improved docs are below, if you can think of anything missing, or better wording please let me know and I'll change.

	 * Make the menu item `theNewItem` the ROOT of the current menu on display, this item should be either the item referred
	 * to by `rootMenuItem()` or the first child item of a submenu, normally obtained by calling `menuSub.getChild()` on the
	 * submenu. If `skipHistory` is false, this navigation will be put into the navigation history, and the back menu
	 * will then cleanly go back through this item.
	 * @param theNewItem the first child menu item of the submenu (or root item)
	 * @param possibleActive the item to activate or null for default
	 * @param skipHistory set to true if this menu is custom and should not be stored in the history

[luwenjin]

I not sure if I understand how the history works, does history only effect how the prev/next button works ?

[davetcc]

	 * Make the menu item `theNewItem` the ROOT of the current menu on display, this item should be either the item referred
	 * to by `rootMenuItem()` or the first child item of a submenu, normally obtained by calling `menuSub.getChild()` on the
	 * submenu. When we navigate to a new item, by default menu manager keeps breadcrumbs to be able to go back nicely
	 * afterwards. If you are navigiating to a dynamic menu that should not go into this history, set skipHistory to true. 
	 * 
	 * There is more information about this online see:
	 * https://www.thecoderscorner.com/products/arduino-libraries/tc-menu/menumanager-and-iteration/#navigation-around-menus
	 *
	 * @param theNewItem the first child menu item of the submenu (or root item)
	 * @param possibleActive the item to activate or null for default
	 * @param skipHistory set to true if this menu is custom and should not be stored in the history

Includes a link to some just now improved documentation. This is probably the most complex interact most devs will have with the library, needs well documenting.

[luwenjin]

Nice place to have the doc link. 👍

After reading the inline/online doc, I still have some confusions:

1. What is a "custom menu" exactly? I can see from the online document, a "custom menu" is only related to a dialog, and nothing else, is it an alias of dialog? or there are other staff can be categorized as "custom menu"?
2. In the online doc, under "Navigation around menus", there is a table. On the 3rd row of "Now on display" column, it's "sub1/sub2/dialog", so I thought this should be the history stack. But in the texts below, it says "As the dialog is a custom transient item, it is not added to the navigation history.". Then I'm confused, there is no breadcrumb to hold "sub1/sub2/dialog" on the display, so it's actually NOT on display. And since the dialog is a floating menu, it's not belonged to sub2. So what does this hierarchical relationship mean ?
3. When does the history pop back happen? I can guess these behavior will trigger a pop back (correct me if i'm wrong):
   • select the header
   • select back button
   • call resetMenu(false)
     If I need to decide the value of skipHistory, I need to know where the history take part in, but I can't know it from the doc.