Class: MenuView

• Inheritance
• Description
• Related information
• Class protocol
  • defaults
  • instance creation
• Instance protocol
  • accessing-behavior
  • accessing-items
  • accessing-look
  • accessing-misc
  • accessing-submenus
  • disabled scrolling
  • drawing
  • event handling
  • initialization & release
  • private
  • queries
  • redrawing
  • selections
  • showing
  • submenu notifications
• Examples

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--ListView
                  |
                  +--SelectionInListView
                     |
                     +--MenuView
                        |
                        +--ClickMenuView
                        |
                        +--CodeCompletionHelpMenuView

Package:

stx:libwidg

Category:

Views-Menus

Version:

rev: 1.200 date: 2019/05/28 09:14:27

user: cg

file: MenuView.st directory: libwidg

module: stx stc-classLibrary: libwidg

Author:

Claus Gittinger

Description:

Notice:
    MenuView is going to be obsoleted - use Menu & MenuItem,
    and display them in a MenuPanel for new applications.

a menu view used for both pull-down-menus and pop-up-menus (and also,
for nonModal menus, such as the OldLaunchers click-menu).
the action to be performed can be defined either as:

1) action:aBlockWithOneArg
   which defines a block to be called with the line number (1..n)
   of the selected line.

2) selectors:selectorArray [args: argArray] [receiver:anObject]
   which defines the messages to be sent to the model or
   receiver. Giving an explicit receiver overrides the model.

It is also possible to define both actionBlock and selectorArray.

The wellknown popups are created by wrapping a MenuView into an instance of
PopUpMenu (read the description of popupmenu).

menu entries starting with '\c' are check-entries.
menu entries starting with '\b' are checkBox-entries.
menu entries starting with '\t' are thumbUp/Down-entries.
menu entries conisting of '-' alone, are separating lines.
menu entries conisting of '=' alone, are double separating lines.


StyleSheet defaults:

    menuFont                    font to use for menus

    menuViewBackground          view background (should be same as menuBackgroundColor)
    menuForegroundColor         foreground color
    menuBackgroundColor         background color

    menuShadowColor             shadow color for 3D effects
    menuLightColor              lightColor for 3D effects
    menuHilightForegroundColor  hilighted items foregroundColor
    menuHilightBackgroundColor  hilighted items backgroundColor

    menuHilightFrameColor       frame arounf hilighted items (or nil, if none)
                                defaults to selectionHilightFrameColor
    menuHilightLevel            3D level of selected items
    menuHilightStyle            #openwin or nil (special kludge)
    menuSeparatingLineLevel     3D level of sep. lines
    menuSeparatingLineInset     left/right inset of sep. lines
    menuDisabledForegroundColor foreground color of disabled items
    menuCheckColor              color to use for check marks
    menuFont                    font to use

other values and some defaults are inherited via SelectionInListViews
styles (i.e. look for selectionForegroundColor ...)

Related information:

    PopUpMenu
    PullDownMenu
    ClickMenuView
    LineMenu
    PatternMenu

Class protocol:

 showAcceleratorKeys

 showAcceleratorKeys: aBoolean

 updateStyleCache

extract values from the styleSheet and cache them in class variables

usage example(s):

self updateStyleCache

 forMenu: aTopMenu

create and return a new menuView, which will be contained in
aTopMenus superView

 labels: labels

create and return a new MenuView. The parent view,
selectors and receiver should be set later.

 labels: labels selector: aSelector args: argArray receiver: anObject for: aTopMenu

create and return a new MenuView
- receiverObject gets message aSelector with argument from
argArray for ALL entries

 labels: labels selector: aSelector args: argArray receiver: anObject in: aTopMenu

create and return a new MenuView
- receiverObject gets message aSelector with argument from
argArray for all entries

 labels: labels selectors: selArray

create and return a new MenuView. The parent veiw
and receiver should be set later.

 labels: labels selectors: selArray accelerators: shorties

create and return a new MenuView. The parent veiw
and receiver should be set later.

 labels: labels selectors: selArray accelerators: shorties args: argArray receiver: anObject

create and return a new MenuView. The parent view
should be set later.

 labels: labels selectors: selArray accelerators: shorties args: argArray receiver: anObject for: aTopMenu

create and return a new MenuView for a topMenu

 labels: labels selectors: selArray accelerators: shorties args: argArray receiver: anObject in: aView

create and return a new MenuView in aView
- receiverObject gets message from selectorArray with argument
from argArray

 labels: labels selectors: selArray accelerators: shorties receiver: anObject

create and return a new MenuView. The parent view
should be set later.

 labels: labels selectors: selArray args: argArray

create and return a new MenuView. The parent view
should be set later.

 labels: labels selectors: selArray args: argArray receiver: anObject

create and return a new MenuView. The parent view
should be set later.

 labels: labels selectors: selArray args: argArray receiver: anObject for: aTopMenu

create and return a new MenuView for a topMenu

 labels: labels selectors: selArray args: argArray receiver: anObject in: aView

create and return a new MenuView in aView
- receiverObject gets message from selectorArray with argument
from argArray

 labels: labels selectors: selArray receiver: anObject

create and return a new MenuView. The parent view
should be set later.

 labels: labels selectors: selArray receiver: anObject for: aTopMenu

 labels: labels selectors: selArray receiver: anObject in: aView

create and return a new MenuView in aView
- receiverObject gets message from selectorArray without argument

Instance protocol:

 action

(comment from inherited method)
return the action block to be performed on select.
With useIndex==true, the block gets the selectionIndex as arg,
otherwise, it gets the selectionValue.

 disable: indexOrName

disable an entry

 disableAll

disable all entries

 disableAll: collectionOfIndicesOrNames

disable an collection of entries

 enable: indexOrName

enable an entry

 enableAll: collectionOfIndicesOrNames

enable an collection of entries

 hideOnRelease: aBoolean

 isEnabled: indexOrName

return true, if the item at anIndexOrName is enabled

 setEnable: indexOrName to: aBoolean

enable/disable an entry

 shortKeys
( an extension from the stx:libtool package )

 accelerators: collectionOfShortKeys

set the accelerator keys collection.
You should pass translated symbolic keys - the menu will automatically
show the untranslated original key sequences.

 actionAt: indexOrName

return an individual action

 actionAt: indexOrName put: aBlock

set an individual action

 actions

 actions: aCollectionOfActionBlocks

set all actions

 addItemList: list after: itemNameOrSelectorOrIndex

Modified (format): / 28-05-2019 / 10:50:58 / Claus Gittinger

 addItemList: list resources: resources after: itemNameOrSelectorOrIndex

 addItemList: list resources: resources before: itemNameOrSelectorOrIndex

 addLabel: aLabel selector: aSelector

add another label/selector pair at the end

 addLabel: aLabel selector: aSelector action: aBlock

add another label/selector pair at the end

 addLabel: aLabel selector: aSelector after: aLabelOrSelectorOrIndex

insert another label/selector pair at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addLabel: aLabel selector: aSelector arg: anArg

add another label/selector/argument trio.
OBSOLETE

 addLabel: aLabel selector: aSelector before: aLabelOrSelectorOrIndex

insert another label/selector pair at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addLabels: moreLabels selectors: moreSelectors

add more labels and selectors at the END

 addLabels: moreLabels selectors: moreSelectors accelerators: shorties

add more labels and selectors at the END

 addLabels: moreLabels selectors: moreSelectors accelerators: shorties after: aLabelOrSelectorOrIndex

insert more labels/selectors at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.
If such an item is not found, insert the new items at the END.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addLabels: moreLabels selectors: moreSelectors accelerators: shorties before: aLabelOrSelectorOrIndex

Modified (format): / 28-05-2019 / 10:51:48 / Claus Gittinger

 addLabels: moreLabels selectors: moreSelectors accelerators: shorties resources: resources after: aLabelOrSelectorOrIndex

insert more labels/selectors at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.
If such an item is not found, insert the new items at the END.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addLabels: moreLabels selectors: moreSelectors accelerators: shorties resources: resources before: aLabelOrSelectorOrIndex

insert more labels/selectors at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.
If such an item is not found, insert the new items at the beginning.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

usage example(s):

^ self addLabels:moreLabels selectors:moreSelectors resources:resources

 addLabels: moreLabels selectors: moreSelectors after: aLabelOrSelectorOrIndex

insert more labels/selectors at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.
If such an item is not found, insert the new items at the END.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addLabels: moreLabels selectors: moreSelectors before: aLabelOrSelectorOrNumber

insert more labels/selectors at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.
If such an item is not found, insert the new items at the beginning.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addLabels: moreLabels selectors: moreSelectors resources: resources

add more labels and selectors at the END

 addLabels: moreLabels selectors: moreSelectors resources: resources accelerators: shorties

add more labels and selectors at the END

 addLabels: moreLabels selectors: moreSelectors resources: resources after: aLabelOrSelectorOrIndex

insert more labels/selectors at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.
If such an item is not found, insert the new items at the END.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addLabels: moreLabels selectors: moreSelectors resources: resources before: aLabelOrSelectorOrIndex

insert more labels/selectors at some place.
Being very friendly here, allowing label-string, selector or numeric
index for the argument aLabelOrSelectorOrNumber.
If such an item is not found, insert the new items at the beginning.

To be independent of the entries label, we recommend you use the selector
as index; in systems which translate strings for national variants,
this makes your code easier to maintain.

 addSeparatingLine

add a separating line at the END

 addSeparatingLineAfter: aLabelOrSelectorOrIndex

add a separating line after an item

 addSeparator

add a separating line at the END.
compatibility with Menu

 args

return the argument array

 args: anArray

set the argument array

 argsAt: indexOrName put: something

set an individual selector

 checkFlags

return an array filled with the check-mark flags.
Non check-menu items have a nil entry in this array.

 checkFlags: aCollectionOfBooleansOrNils

 checkToggleAt: indexOrName

return a check-toggles boolean state.
If the item is not a check-item, return nil.

 checkToggleAt: indexOrName put: aBoolean

set/clear a check-toggle

 hasItems

return true, if I have items

 indexOf: indexOrName

return the index of the label named:aName or
the index in the selector list if it's a symbol.
If indexOrName is not a valid item, return 0.

 items

for menuPanel compatibility: return a list of menu items

 labelAt: indexOrName put: aString

change the label at index to be aString

 labels

return the menu-labels

 labels: text

set the labels to the argument, text

 labels: text selectors: selArray accelerators: shorties args: argArray receiver: anObject

set all relevant stuff

 labels: text selectors: selArray args: argArray receiver: anObject

set all relevant stuff

 menuPerformer: someone

set the menuPerformer of the message.
This also sets the menuPerformer in all subMenus.

 receiver

return the receiver of the message

 receiver: anObject

set the receiver of the message.
This also sets the receiver in all subMenus.

 remove: indexOrName

remove the label at index

 selectorAt: indexOrName

return an individual selector

 selectorAt: indexOrName put: aSelector

set an individual selector

 selectors

return the selector array

 selectors: anArray

set the selector array

 someMenuItemLabeled: aLabel

find a menu item.
Currently, in ST/X, instances of MenuItem are only created as dummy

 font: aFont

adjust size for new font.
CAVEAT: with the addition of Text objects,
this method is going to be obsoleted by a textStyle
method, which allows specific control over
normalFont/boldFont/italicFont parameters.

 masterView

return the popup-masterview I am contained in.

 masterView: aPopUpView

set the popup-masterview I am contained in.

 selection: index

set the selection

 setSelection: index

(comment from inherited method)
select line, aNumber or deselect if argument is nil;
scroll to make the selected line visible.
*** No model and/or actionBlock notification is done here.

 sizeFixed: aBoolean

(comment from inherited method)
set/clear the fix-size attribute, if supported by concrete subclasses.
Views which want to resize themselfes as appropriate to their contents
should cease to do so and take their current size if sizeFixed is set to
true. Currently, only supported by Labels.
This does NOT prevent the window manager from resizing the view,
instead it tell the view to NOT resize ITSELF.
Added here to provide a common protocol for all views.

 superMenu

ret the menu I am contained in
- need this to hide main menus when a submenu performed its action

 superMenu: aMenu

set the menu I am contained in
- need this to hide main menus when a submenu performed its action

 validateSelection: index

not really selectable, but a separating line

 subMenuAt: indexOrName

return a submenu, or nil

 subMenuAt: indexOrName put: aPopUpMenu

define a submenu

 subMenuShown

return the currently visible submenu - or nil if there is none

 makeSelectionVisible

 drawAccelerator: aSymbolicKey inVisibleLine: visLineNr with: fg and: bg

draw the accelerator at the right.

 drawCheckLine: line inVisibleLine: visLineNr with: fg and: bg

draw an on/off-mark (or the space for it).
Supported checkmark types:
\c simple mark; space if off
\b box mark
\t thumbsUp/thumbsDown mark

 drawVisibleLine: visLineNr with: fg and: bg

a normal entry

 drawVisibleLineSelected: visLineNr with: fg and: bg

redraw a single line as selected.

 buttonMotion: state x: x y: y

(comment from inherited method)
mouse-move while button was pressed - handle selection changes

 buttonPress: button x: x y: y

(comment from inherited method)
clicked into the selection ?

 buttonRelease: button x: x y: y

(comment from inherited method)
stop any autoscroll

 keyPress: aKey x: x y: y

Return, space or the (virtual) MenuSelect
key trigger a selected entry.

 pointerLeave: state

self setSelectionForX:-1 y:-1. "force deselect"

 create

 destroy

have to destroy the submenus manually here,
since they are no real subviews of myself

 fetchDeviceResources

fetch device colors, to avoid reallocation at redraw time

 initEvents

(comment from inherited method)
will be sent by create - can be redefined by subclasses to enable
view events

 initStyle

setup viewStyle specifics

 initialize

stupid - have to redo this ...

 recreate

when recreated after a snapin or a migration, resize myself, in case
font dimensions have changed on the display

 reinitialize

this is called right after snapIn;
a kind of kludge - reset cursor (in case the save was
done with myself being shown and active)

 isCheckItem: line

return true if \c, \b or \t is contained in the line arg.
Care for '\\'.

 isGraphicItem: line

redefine in subclasses to return false,
if no graphicLines are wanted (codeCompletionView does this)

 labelWithoutDoubleAmpersands: label

 performSelectedAction

ST-80 style model notification

 recomputeSize

resize myself to my preferred size
OBSOLETE - use resize

 resize

resize myself to my preferred size

 resizeIfChanged

 selectionChangedFrom: oldSelection

(comment from inherited method)
selection has changed. Call actionblock and/or send changeMessage if defined

 setSelectionForX: x y: y now: now

select whatever is under x/y coordinate - if there is
a subMenu, show it

 computePreferredExtent

compute & return my preferredExtent from labels width's

 selectedItemHasSubmenu

 shortKeyInset

compute the width req'd for the shortKey

 shortKeyPrefixFor: aModifier

obsolete?

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 wantsFocusWithButtonPress

 redrawFromVisibleLine: start to: stop

redraw a line range - redefined to care for special entries.

 redrawVisibleLine: visLineNr

redefined from normal list-line drawing, to handle special
lines. These are:
lines consisting of '-' only: draw a horizontal separating line
lines consisting of '=' only: draw double separating line
empty line : leave blank
there may be more in the future.

 redrawVisibleLine: visLine col: col

redefined to always draw a full line - for openwin handling

 redrawVisibleLine: visLine from: startCol

redefined to always draw a full line - for openwin handling

 redrawVisibleLine: visLine from: startCol to: endCol

redefined to always draw a full line - for openwin handling

 isValidSelection: aNumber

return true, if aNumber is ok for a selection lineNo

 realize

 show

 unmap

unmap the view - the view stays created (but invisible), and can be remapped again later.

 cancelDelayedSubmenuHideOrShowAction

 hideSubmenu

hide the currently shown subMenu (if any)

 regainControl

take over pointer control from a submenu

 showActive

submenu is about to perform a menu-action - show wait cursor here as well

 showPassive

submenu has finished its menu-action - show normal cursor again

 showSubmenu: index

show subMenu at index

 submenuTriggered

submenu has performed some action - have to deselect here

Examples:

    |m|
    m := MenuView
            labels:#('foo'
                     'bar'
                     'baz')
            selectors:#(
                        #foo
                        #bar
                        #baz)
            receiver:nil.
    m open

    |m|
    m := MenuView
            labels:#('foo'
                     'bar'
                     'baz')
            selectors:#foo:
            args:#(1 2 3)   
            receiver:nil.
    m open