brainstorming menu customization

[Josef Templ]

This topic, originally addressed by Robert's posting in https://forum.blackboxframework.org/viewtopic.php?f=41&t=716&start=20#p6830,
is for collecting ideas regarding improved flexibility in menu customization.

- Josef

[Robert]

I have been doing some work on this topic, which, as usual, is proving to be more difficult than anticipated!

I won't be ready to say much here for a few days - possibly longer!

[Robert]

I have now given this some detailed thought.

Motivation:

Over the years I have accumulated many changes & additions I like to make to the standard distribution menus. This causes three problems (I operate in a Client / Server configuration, where the Server directory contains only unmodified standard distribution files):

1 - There is a lot of unnecessary duplication between my menus and the standard ones.

2 - My directory structure is cluttered with extra folders & files:

\\Server\System
\\Server\System\Rsrc
\\Server\System\Rsrc\Menus.odc
\\Server\Dev
\\Server\Dev\Rsrc
\\Server\Dev\Rsrc\Menus.odc
\\Server\Form
\\Server\Form\Rsrc
\\Server\Form\Rsrc\Menus.odc
\\Server\Text
\\Server\Text\Rsrc
\\Server\Text\Rsrc\Menus.odc

3 - (This is the serious one!) Keeping my menus consistent with changes in the standard ones is inconvenient and error prone.


So I propose adding a mechanism whereby only desired changes to the standard menus need be listed in the Client directory; all the changes would be in a single file, which might be called

\\Client\MenuDeltas.odc

There are two things to discuss: how this mechanism should behave in detail (ie what is its feature set), and how it might be implemented. This posting only addresses the first point; I shall make another posting with some brief comments on the second later. There is little point discussing the implementation in detail until the feature set becomes at least somewhat stable.

Description of Behaviour:

There would be a single file describing all the desired menu changes. It would look just like the current menus, except for a few small changes I will describe below.
The first change is that it would have no "INCLUDE" lines.

Some terminology:
The text from, and including, "MENU" to the next "END" I call a menu. Each menu file contains several menus.
The lines between adjacent structure keywords "MENU", "SEPARATOR" & "END" I call a paragraph.
Each line in a paragraph I call an item, which comprises a label, a shortcut, a command, and a guard.
Each menu is followed by a menuname. It may also be followed by a menuguard.

The standard menus are read from file, as are the delta menus. These are then merged as follows:

1 - Each standard menu is associated with a delta menu if possible. Association means they have the same menuname and menuguard.

2 - Non-associated standard menus are kept unmodified. Non-associated delta menus are discarded.

3 - In associated menus each paragraph of the standard menu is associated with the corresponding paragraph of the delta menu. By corresponding I mean the first standard paragraph is associated with the first delta paragraph, and so on.

4 - Items in associated paragraphs are associated if they have the same label.
Associated standard items are replaced by the corresponding delta item.
Non-associated items are listed in the order: standard items followed by delta items.


This is the basic behaviour, but it can be refined by using non-standard delta menu file features as follows:

1 - If, in the delta menu file, either of the keywords "MENU" or "SEPARATOR" is followed by a "+" sign a new paragraph is inserted; it takes its items from the delta menu only.

2 - If, in the delta menu file, either of the keywords "MENU" or "SEPARATOR" is followed by a "-" sign the next paragraph in the standard menu is deleted.

3 - If, in the delta menu file, an item has shortcut "-", and no command or guard, the associated item is deleted from the standard menu.

4 - If, in the delta menu file, a non-associated item is preceeded by an integer, it not inserted after the standard items in that paragraph, but in the position indicated by the number.

5 - If, in the delta menu file, a non-associated menu is followed by an integer, it is not discarded, but inserted as the n th menu in the file.

I give an example below of the delta menu I would use for my Tools menu; it is much shorter than current full menu I need to have.

Code: Select all

MENU "#Dev:&Tools"
   "ViewSizer..."   ""    "StdCmds.OpenToolDialog ('Wands/Rsrc/ViewSizer', '(Wands)ViewSizer')"
            "TextCmds.SingletonGuard"
   "Mascara..."   ""    "StdCmds.OpenToolDialog ('Wands/Rsrc/Mascara', '(Wands)Mascara')"   "TextCmds.EditGuard"
   SEPARATOR
3   "Insert Commander End"   ""   "DevCommanders.DepositEnd; StdCmds.PasteView"   "StdCmds.PasteViewGuard"
   SEPARATOR
   SEPARATOR
   "#Dev:&Create Target"   "T"   "StdLinks.CreateTarget"   "StdLinks.CreateGuard"
   SEPARATOR
   SEPARATOR   +
   "Insert Left"   "*F5"   "DevSelectors.DepositLeft; StdCmds.PasteView"   "StdCmds.PasteViewGuard"
   "Insert Middle"   "*F6"   "DevSelectors.DepositMiddle; StdCmds.PasteView"   "StdCmds.PasteViewGuard"
   "Insert Right"   "*F7"   "DevSelectors.DepositRight; StdCmds.PasteView"   "StdCmds.PasteViewGuard"
END


[Robert]

Implementation Comments:

I see the implementation having four parts:

1 - A menu file scanner & parser
2 - A data structure to hold the menu information
3 - A merging algorithm to create the required menu structure from the standard & delta structures
4 - An output process to exploit this merged structure.

I have a Test harness implementation. It is used to design the detailed behaviour; it is NOT intended to be a prototype for a final implementation.

1 - The menu file scanner & parser is based on my module LibAsciiMappers. It should be fairly easy to replace it by standard BlackBox code, as a menu file scanner and parser already exists.

2 - The data structure I use is based on linked lists, as implemented in LibCycles. It may be convenient to copy a small subset of this module for this purpose in a final implementation.

3 - The merging algorithm, which is a bit delicate, can probably be used as is, once (if) the detailed behaviour is agreed.

4 - The test output process uses LibFmtrs to write an updated file to the Log window. That would need to be replaced with something that creates the internal BlackBox data structure. I don't know what that is, but, again, such code must already exist.


If anyone wants to experiment with this test harness I can post it; it does use SubSystem Lib as a dependancy. It cannot damage your installation as the only thing it does is write to the Log.

[Josef Templ]

Before we talk about the implementation, I would like to collect more requirements.

The proposal is based on a single Menu modification file, if I understand it correctly.
But I would like to have the possibility to extend menus (e.g Dev) by adding a subsystem from CPC (e.g. Srcnav).
This particular example needs a single menu item that is best placed in the Dev menu.
I could imagine a mechanism that allows the subsystem Srcnav to specify that there should be a menu item added to Dev,
maybe with an option to specify the insertion point.
Then it suffices to have Srcnav installed and there is no need to manipulate the menus manually.

Another requirement is that often I would like to enable or disable menus, for example Obx or Tut
is only for beginners or for exceptional situations. It should be possible to switch menus off and on.

- Josef

[Robert]

The proposal is based on a single Menu modification file, if I understand it correctly.
But I would like to have the possibility to extend menus (e.g Dev) by adding a subsystem from CPC (e.g. Srcnav).
This particular example needs a single menu item that is best placed in the Dev menu.
I could imagine a mechanism that allows the subsystem Srcnav to specify that there should be a menu item added to Dev,
maybe with an option to specify the insertion point.
Then it suffices to have Srcnav installed and there is no need to manipulate the menus manually.

This sounds like a small extension to my proposal: Menus are defined as at the moment using \\Server\Subsys\Rsrc\Menus.odc, or, if it exist, \\Client\Subsys\Rsrc\Menus.odc.
This is then, as proposed, modified by \\Client\MenuDeltas.odc as described above.
This could then be further modified by \\Client\Subsys\Rsrc\MenuDeltas.odc in precisely the same way.
An example to do as you suggest, eg put a new option on the third line of the fourth paragraph, would be

Code: Select all

MENU "#Dev:&Dev"
  SEPARATOR
  SEPARATOR
  SEPARATOR
3 "#Srcnav:New option"  "F8", "SrcnavModule.Command" "SrcnavModule.Guard"
END

There could be problems if several subsystems update the same menu, because the order is currently indeterminate. Maybe we could ignore that!

Another requirement is that often I would like to enable or disable menus, for example Obx or Tut
is only for beginners or for exceptional situations. It should be possible to switch menus off and on.

This is a different kind of requirement as you are talking about some user interface; whereas the discussion above has no user interface.
There is currently the module CpcMenus (written by Helmut) which does this. I use it. It operates on menu files, rather than individual menus.
I don't like the "crude" way it operates by changing file names, but that does mean it can work without changing the current framework. But, if we are considering updating the framework, I think we can design something a bit more sophisticated.

[Josef Templ]

Another requirement is providing a programming interface to the menus.
Currently everything is described in the Menus file with a DSL (domain specific language).
This is great as a foundation but it has its limits.
For making changes or for more dynamic behavior of menu items an API would provide
the maximum flexibility. Menu API calls could be added to the Config file for automation.

- josef

[Robert]

Another requirement is providing a programming interface to the menus.

Does anyone have any experience with another language / programming environment that does this?

[Zinn]

I propose to add one new keyword:

Code: Select all

APPENDMENU "#Dev:&Dev"
   SEPARATOR
   "#Srcnav:New option"  "F8", "SrcnavModule.Command" "SrcnavModule.Guard"
END


It appends the menu to the existing menu. Without APPEND it replace the existing menu as it is doing now.

All other things should be done via the new programming interface for the menu.

- Helmut

[Josef Templ]

Without APPEND it replace the existing menu as it is doing now.

I have tested the current behavior.
It adds another top-level menu with the same name.
But that's only a detail.

I am not sure that a new keyword is required.
Nobody uses multiple menus (or replaced menus) with identical names.
We could implement that as appending to the existing menu.

What concerns me is the question of an insertion point.
Appending at the end is better than nothing but inserting
at a specific position would be even better.

One possibility would be to use the name of an existing menu item as a cursor.
In the case of the Srcnav subsystem the provided Menus file would look like this if the
new menu item is to be inserted after the 'Open File List' menu item.

Code: Select all

MENU "#Dev:&Dev"
   "#Dev:&Open File List"
   "#Srcnav:&Navigator"   "G"   "SrcnavUI.InitDialog('Srcnav/Rsrc/Tool')"   "TextCmds.FocusGuard"
END


The advantage of this approach is that any menu item can serve as insertion point,
without any change of existing Menus files.
If the name of the cursor menu item is not found, it would fall back to the default, i.e.
append at the end.

- Josef