eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'MenuView':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: MenuView

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--ListView
                  |
                  +--SelectionInListView
                     |
                     +--MenuView
                        |
                        +--ClickMenuView
                        |
                        +--CodeCompletionHelpMenuView
Package:
stx:libwidg
Category:
Views-Menus
Version:
rev: 1.214 date: 2024/04/09 12:19:21
user: stefan
file: MenuView.st directory: libwidg
module: stx stc-classLibrary: libwidg

Description:


Warning: 
    this is a very old class which was written well before many improved
    successors and tools were added. A lot of stuff you find here is kept for backward
    compatibility.

    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 ...)

[caveat:
    this is a very old inhabitant of the matrix, which looks ugly by todays standards.
    It is no longer really maintained but left in for the few users in the system.
    Please use MenuPanel and MenuItems instead.


copyright
COPYRIGHT (c) 1989 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

defaults
o  showAcceleratorKeys

o  showAcceleratorKeys: aBoolean

o  updateStyleCache
extract values from the styleSheet and cache them in class variables

Usage example(s): 

     self updateStyleCache

instance creation
o  forMenu: aTopMenu
create and return a new menuView, which will be contained in
aTopMenus superView

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

o  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

o  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

o  labels: labels selectors: selArray
create and return a new MenuView. The parent veiw
and receiver should be set later.

o  labels: labels selectors: selArray accelerators: shorties
create and return a new MenuView. The parent veiw
and receiver should be set later.

o  labels: labels selectors: selArray accelerators: shorties args: argArray receiver: anObject
create and return a new MenuView. The parent view
should be set later.

o  labels: labels selectors: selArray accelerators: shorties args: argArray receiver: anObject for: aTopMenu
create and return a new MenuView for a topMenu

o  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

o  labels: labels selectors: selArray accelerators: shorties receiver: anObject
create and return a new MenuView. The parent view
should be set later.

o  labels: labels selectors: selArray args: argArray
create and return a new MenuView. The parent view
should be set later.

o  labels: labels selectors: selArray args: argArray receiver: anObject
create and return a new MenuView. The parent view
should be set later.

o  labels: labels selectors: selArray args: argArray receiver: anObject for: aTopMenu
create and return a new MenuView for a topMenu

o  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

o  labels: labels selectors: selArray receiver: anObject
create and return a new MenuView. The parent view
should be set later.

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

o  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:

accessing-behavior
o  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.

o  disable: indexOrNameOrSelector
disable an entry

o  disableAll
disable all entries

o  disableAll: collectionOfIndicesOrNames
disable an collection of entries

o  enable: indexOrNameOrSelector
enable an entry

o  enableAll: collectionOfIndicesOrNames
enable an collection of entries

o  hideOnRelease: aBoolean

o  isEnabled: indexOrNameOrSelector
return true, if the item at anIndexOrName is enabled

o  setEnable: indexOrNameOrSelector to: aBoolean
enable/disable an entry

o  shortKeys
( an extension from the stx:libtool package )

accessing-items
o  acceleratorAt: indexOrNameOrSelector
return an individual shortKey

o  acceleratorAt: indexOrNameOrSelector put: aKey
set an individual accelerator

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

o  actionAt: indexOrNameOrSelector
return an individual action

o  actionAt: indexOrNameOrSelector put: aBlock
set an individual action

o  actions

o  actions: aCollectionOfActionBlocks
set all actions

o  addItemList: list after: itemNameOrSelectorOrIndex
Modified (format): / 28-05-2019 / 10:50:58 / Claus Gittinger

o  addItemList: list resources: resources after: itemNameOrSelectorOrIndex

o  addItemList: list resources: resources before: itemNameOrSelectorOrIndex

o  addLabel: aLabel selector: aSelector
add another label/selector pair at the end

o  addLabel: aLabel selector: aSelector action: aBlock
add another label/selector pair at the end

o  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.

Usage example(s): 

     |v1 v2 v3 v4|

     v1 := CodeView new open.

     v2 := CodeView new open.
     v2 middleButtonMenu:
        (v2 editMenu addLabel:'new entry' selector:#foo after:#pasteSelection; yourself).

     v3 := CodeView new open.
     v3 middleButtonMenu:
        (v3 editMenu addLabel:'new entry' selector:#foo after:#others; yourself).

     v4 := CodeView new open.
     v4 middleButtonMenu:
        (v4 editMenu addLabel:'new entry' selector:#foo after:1; yourself).

o  addLabel: aLabel selector: aSelector arg: anArg
add another label/selector/argument trio.
OBSOLETE

o  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.

o  addLabels: moreLabels selectors: moreSelectors
add more labels and selectors at the END

o  addLabels: moreLabels selectors: moreSelectors accelerators: shorties
add more labels and selectors at the END

o  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.

o  addLabels: moreLabels selectors: moreSelectors accelerators: shorties before: aLabelOrSelectorOrIndex
Modified (format): / 28-05-2019 / 10:51:48 / Claus Gittinger

o  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.

o  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 entry's 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): 

     |v1 v2 v3 v4 v5 m|


     v1 := CodeView new open.
     v1 contents:'original menu'.

     v2 := CodeView new open.
     v2 contents:'before copy'.
     m := v2 editMenu.
     m
        addLabels:#('new entry1' 'new entry2') 
        selectors:#(foo bar) 
        before:#copySelection 
        accelerators:#(Copy Cut Paste).
     v2 middleButtonMenu:m.

     v3 := CodeView new open.
     v3 contents:'before again '.
     m := v3 editMenu.
     m
        addLabels:#('new entry1' 'new entry2') 
        selectors:#(foo bar) 
        before:#again.
     v3 middleButtonMenu:m.

     v4 := CodeView new open.
     v4 contents:'at beginning '.
     m := v4 editMenu.
     m
        addLabels:#('new entry1' 'new entry2' '-') 
        selectors:#(foo bar nil) 
        before:1.
     v4 middleButtonMenu:m.

     v5 := CodeView new open.
     v5 contents:'at end '.
     m := v5 editMenu.
     m
        addLabels:#('-' 'new entry1' 'new entry2') 
        selectors:#(nil foo bar).
     v5 middleButtonMenu:m.

o  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.

o  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.

Usage example(s): 

     |v1 v2 v3 v4 m|


     v1 := CodeView new open.

     v2 := CodeView new open.
     m := v2 editMenu.
     m
	addLabels:#('new entry1' 'new entry2') 
	selectors:#(foo bar) 
	before:'paste'.
     v2 middleButtonMenu:m.

     v3 := CodeView new open.
     m := v3 editMenu.
     m
	addLabels:#('new entry1' 'new entry2') 
	selectors:#(foo bar) 
	before:#again.
     v3 middleButtonMenu:m.

     v4 := CodeView new open.
     m := v4 editMenu.
     m
	addLabels:#('new entry1' 'new entry2') 
	selectors:#(foo bar) 
	before:1.
     v4 middleButtonMenu:m.

o  addLabels: moreLabels selectors: moreSelectors resources: resources
add more labels and selectors at the END

o  addLabels: moreLabels selectors: moreSelectors resources: resources accelerators: shorties
add more labels and selectors at the END

o  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.

o  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.

Usage example(s): 

     |v1 v2 v3 v4 m|


     v1 := CodeView new open.

     v2 := CodeView new open.
     m := v2 editMenu.
     m
        addLabels:#('new entry1' 'new entry2') 
        selectors:#(foo bar) 
        before:'paste'.
     v2 middleButtonMenu:m.

     v3 := CodeView new open.
     m := v3 editMenu.
     m
        addLabels:#('new entry1' 'new entry2') 
        selectors:#(foo bar) 
        before:#again.
     v3 middleButtonMenu:m.

     v4 := CodeView new open.
     m := v4 editMenu.
     m
        addLabels:#('new entry1' 'new entry2') 
        selectors:#(foo bar) 
        before:1.
     v4 middleButtonMenu:m.

o  addSeparatingLine
add a separating line at the END

o  addSeparatingLineAfter: aLabelOrSelectorOrIndex
add a separating line after an item

o  addSeparator
add a separating line at the END.
compatibility with Menu

o  args
return the argument array

o  args: anArray
set the argument array

o  argsAt: indexOrNameOrSelector put: something
set an individual argument (to be passed with selector or action block)

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

o  checkFlags: aCollectionOfBooleansOrNils

o  checkToggleAt: indexOrNameOrSelector
return a check-toggles boolean state.
If the item is not a check-item, return nil.

o  checkToggleAt: indexOrNameOrSelector put: aBoolean
set/clear a check-toggle

o  hasItems
return true, if I have items

o  indexOf: indexOrNameOrSelector
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.

o  items
for menuPanel compatibility: return a list of menu items.
That is mimicri (mostly for the STXGuiBrowser, I guess)

o  labelAt: indexOrNameOrSelector
return an individual label

o  labelAt: indexOrNameOrSelector put: aString
change the label at index to be aString

o  labels
return the menu-labels

o  labels: text
set the labels to the argument, text

o  labels: text selectors: selArray accelerators: shorties args: argArray receiver: anObject
set all relevant stuff

o  labels: text selectors: selArray args: argArray receiver: anObject
set all relevant stuff

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

o  receiver
return the receiver of the message

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

o  remove: indexOrName
remove the label at index

o  selectorAt: indexOrNameOrSelector
return an individual selector

o  selectorAt: indexOrNameOrSelector put: aSelector
set an individual selector

o  selectors
return the selector array

o  selectors: anArray
set the selector array

accessing-look
o  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.

accessing-misc
o  masterView
return the popup-masterview I am contained in.

o  masterView: aPopUpView
set the popup-masterview I am contained in.

o  selection: index
set the selection

o  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.

o  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.

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

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

o  validateSelection: index
not really selectable, but a separating line

accessing-submenus
o  subMenuAt: indexOrNameOrSelector
return a submenu, or nil

o  subMenuAt: indexOrNameOrSelector put: aPopUpMenu
define a submenu

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

disabled scrolling
o  makeSelectionVisible

drawing
o  drawAccelerator: aSymbolicKey inVisibleLine: visLineNr with: fg and: bg
draw the accelerator at the right.

o  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

o  drawVisibleLine: visLineNr with: fg and: bg
a normal entry

o  drawVisibleLineSelected: visLineNr with: fg and: bg
redraw a single line as selected.

event handling
o  buttonMotion: state x: x y: y
(comment from inherited method)
mouse-move while button was pressed - handle selection changes

o  buttonPress: button x: x y: y
(comment from inherited method)
clicked into the selection ?

o  buttonRelease: button x: x y: y
(comment from inherited method)
stop any autoscroll

o  keyPress: aKey x: x y: y
Return, space or the (virtual) MenuSelect
key trigger a selected entry.

o  pointerLeave: state
self setSelectionForX:-1 y:-1. "force deselect"

initialization & release
o  create
(comment from inherited method)
I cache font parameters here - they are used so often ...

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

o  fetchDeviceResources
fetch device colors, to avoid reallocation at redraw time

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

o  initStyle
setup viewStyle specifics

o  initialize
stupid - have to redo this ...

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

o  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)

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

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

o  labelWithoutDoubleAmpersands: label

o  performSelectedAction
ST-80 style model notification

o  recomputeSize
resize myself to my preferred size
OBSOLETE - use resize

o  resize
resize myself to my preferred size

o  resizeIfChanged

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

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

queries
o  computePreferredExtent
compute & return my preferredExtent from labels width's

o  doAccessCharacterTranslation

o  selectedItemHasSubmenu

o  shortKeyInset
compute the width req'd for the shortKey

o  shortKeyPrefixFor: aModifier
obsolete?

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

o  wantsFocusWithButtonPress

redrawing
o  redrawFromVisibleLine: start to: stop
redraw a line range - redefined to care for special entries.

o  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.

o  redrawVisibleLine: visLine col: col
redefined to always draw a full line - for openwin handling

o  redrawVisibleLine: visLine from: startCol
redefined to always draw a full line - for openwin handling

o  redrawVisibleLine: visLine from: startCol to: endCol
redefined to always draw a full line - for openwin handling

selections
o  isValidSelection: aNumber
return true, if aNumber is ok for a selection lineNo

showing
o  realize

o  show

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

submenu notifications
o  cancelDelayedSubmenuHideOrShowAction

o  hideSubmenu
hide the currently shown subMenu (if any)

o  regainControl
take over pointer control from a submenu

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

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

o  showSubmenu: index
show subMenu at index

o  submenuTriggered
submenu has performed some action - have to deselect here

Examples:


See real examples in PopUpMenu & PullDownMenu Examples: Notice: normally, menuviews are wrapped into either a popup- menu or pulldown-menu. But they can also be used stand-alone as in the following 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

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 22 Dec 2024 03:12:28 GMT