eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'MenuPanel':

Home

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

Class: MenuPanel

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--MenuPanel
                  |
                  +--ColorMenu
                  |
                  +--FontMenu
Package:
stx:libwidg2
Category:
Views-Menus
Version:
rev: 1.832 date: 2024/04/26 11:40:21
user: cg
file: MenuPanel.st directory: libwidg2
module: stx stc-classLibrary: libwidg2

Description:


a menu panel used for both pull-down-menus and pop-up-menus.

Due to some historic leftover, there are two mechanisms for menus:
    1) the (very) old MenuView (which inherits from SelectionInListView)
    2) this new MenuPanel.

this will eventually replace most of the MenuView and PopUpMenu stuff.
(and hopefully be ST-80 compatible...)

To create a menu, there exists a MenuEditor which can generate
menu specifications, from which a MenuPanel can be dynamically created.


Notice:
    This is going to replace the obsolete MenuView.



cg: this code is so ugly - needs a complete rewrite...


copyright
COPYRIGHT (c) 1997 by eXept Software AG
             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:

class initialization
o  initialize
self initialize

default icons
o  delayedMenuIndicator
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self delayedMenuIndicator inspect
     ImageEditor openOnClass:self andSelector:#delayedMenuIndicator
     Icon flushCachedIcons

o  iconIndicationDisabledOff
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconIndicationDisabledOff inspect
     ImageEditor openOnClass:self andSelector:#iconIndicationDisabledOff
     Icon flushCachedIcons

o  iconIndicationDisabledOn
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconIndicationDisabledOn inspect
     ImageEditor openOnClass:self andSelector:#iconIndicationDisabledOn
     Icon flushCachedIcons

o  iconIndicationOff
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconIndicationOff inspect
     ImageEditor openOnClass:self andSelector:#iconIndicationOff
     Icon flushCachedIcons

o  iconIndicationOn
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconIndicationOn inspect
     ImageEditor openOnClass:self andSelector:#iconIndicationOn
     Icon flushCachedIcons

o  iconRadioGroupDisabledOff
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconRadioGroupDisabledOff inspect
     ImageEditor openOnClass:self andSelector:#iconRadioGroupDisabledOff

o  iconRadioGroupDisabledOn
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconRadioGroupDisabledOn inspect
     ImageEditor openOnClass:self andSelector:#iconRadioGroupDisabledOn
     Icon flushCachedIcons

o  iconRadioGroupEnteredOff

o  iconRadioGroupEnteredOn

o  iconRadioGroupOff
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconRadioGroupOff inspect
     ImageEditor openOnClass:self andSelector:#iconRadioGroupOff

o  iconRadioGroupOn
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self iconRadioGroupOn inspect
     ImageEditor openOnClass:self andSelector:#iconRadioGroupOn

o  menuIndicator
This resource specification was automatically generated
by the ImageEditor of ST/X.

Usage example(s): 

     self menuIndicator inspect
     ImageEditor openOnClass:self andSelector:#menuIndicator
     Icon flushCachedIcons

defaults
o  defaultBackgroundColor
(comment from inherited method)
return the default background color for drawing - usually,
that is the same as the viewBackgroundColor.

o  defaultLevel
self defaultLevel

o  delayedMenuIndicatorOffset
returns an additional offset between the label and the
delayedMenu indication (i.e. the down-arrow icon)

o  maxShortCutSearchLevel
1 means: only search in top items.
2 means: search one level of menus.
used to be 10

o  maxShortCutSearchLevel: anInteger
1 means: only search in top items.
2 means: search one level of menus.

o  menuIndicatorOffset
returns an additional offset between the label and the
delayedMenu indication (i.e. the down-arrow icon)

o  mnemonicIdentifier
returns the identifier each mnemonic starts with;
ex:
&File mnemonic := Cmdf
F&ile mnemonic := Cmdi
.....

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

Usage example(s): 

     self updateStyleCache

image registration
o  image: anImage onDevice: aDevice
Images := nil

o  lightenedImage: anImage onDevice: aDevice
LigthenedImages := nil

o  releaseCachedImagesFromDevice: aGraphicsDevice
flush cached resources before saving a snapshot
(do not save them in the image)

instance creation
o  fromSpec: aSpec

o  fromSpec: aSpec receiver: aReceiver

o  labels: labels

o  labels: labels nameKeys: nameKeys

o  labels: labels nameKeys: nameKeys receiver: aReceiver

o  labels: labels receiver: aReceiver

o  menu: aMenu

o  menu: aMenu receiver: aReceiver
cg: the reasoning behind this code is absolutely unclear.

private
o  subMenu: aSubMenu
create a submenu; can be redefined in derived classes

startup & release
o  preSnapshot
flush cached resources before saving a snapshot
(do not save them in the image)

utilities
o  processAmpersandCharactersFor: aLabel withAccessCharacterPosition: accessCharacterPositionOrNil
replace &x by the short-key attribute (i.e. remove & and underline x)
The position is either specified by an accessCharacter position (useful if computed
or fix), or by an ampersand escape.
Double ampersands are replaced by a single one.

Instance protocol:

accepting
o  accept
(comment from inherited method)
accept the current contents by executing the accept-action and/or changeMessage.

o  accept: anItemOrNil
this is the topMenu: close the menu and accept the item (if not nil)

o  accept: anItem index: anIndex toggle: aState receiver: aReceiver
really accept an item

o  accept: anItemOrNil isUserAction: isUserAction
this is the topMenu: close the menu and accept the item (if not nil)

Usage example(s): 

acceptAction := [ self accept:itemAcceptedOrNil index:itemIdx toggle:tgState receiver:recv ].

o  acceptIsUserAction: isUserAction
accept the current selected item;
isUserAction is false, if indirectly accepted
(only when coming via a dialog's ok button)

o  acceptItem: anItemOrNil inMenu: aMenu

o  acceptItem: anItemOrNil inMenu: aMenu isUserAction: isUserAction
toggle if accepting due to a button release or return-key;

o  lastItemAccepted
returns last item selected or nil

o  lastValueAccepted
returns last value accepted or nil

accessing
o  args
returns a collection of arguments or nil

o  args: something
define arguments for each item

o  argsAt: stringOrNumber
gets the argument of an item or nil

o  argsAt: stringOrNumber put: anArgument
sets the argument of an item

o  labelAt: stringOrNumber
gets the label of an item or nil

o  labelAt: stringOrNumber put: aLabel
sets the label of an item

o  labels
returns a collection of labels's or nil

o  labels: labels
define labels for each item

o  nameKeyAt: stringOrNumber
gets the nameKey of an item or nil

o  nameKeyAt: stringOrNumber put: aNameKey
sets the nameKey of an item

o  nameKeys
returns a collection of nameKeyss or nil

o  nameKeys: something
define nameKeys for each item

o  originator

o  valueAt: stringOrNumber
gets value of an item; a block, valueHolder, ...

o  valueAt: stringOrNumber put: aBlockOrValueHolderOrSelector
sets value of an item; a block, valueHolder, ...

o  values: something
define values for each item

accessing-behavior
o  disableAll
disable all items; not the menu in case of enabled

o  disableAll: collectionOfIndicesOrNames
disable an collection of items

o  doAccessCharacterTranslation
true if &-chars in a label are to be treated as accessCharacter indicators.
Can be set to false to leave accessCharacter unchanged

o  doAccessCharacterTranslation: aBoolean
true if &-chars in a label are to be treated as accessCharacter indicators.
Can be set to false to leave accessCharacter unchanged

o  enableAll
enable all items; not the menu in case of disabled

o  enableAll: collectionOfIndicesOrNames
enable an collection of items

o  enabled
returns enabled state

o  enabled: aBooleanOrNil
change enabled state of menu

o  enabledAt: stringOrNumber
gets the enabled state of an item (given by name or index)

o  enabledAt: stringOrNumber put: aBoolean
sets the enabled state of an item

o  exclusivePointer: aBoolean
Do nothing here. Compatibility with PopUpListController

o  hideOnRelease

o  hideOnRelease: aBoolean

o  isEnabled: stringOrNumber
gets the enabled state of an item (given by name or index)

o  menuPerformer: anObject
set the menu-receiver. That's the one who gets the messages ( both from myself and
from all submenus no specific receiver is defined ).

o  receiver
get the menu-receiver. That's the one who gets the messages ( both from myself and
from all submenus no specific receiver is defined ).

o  receiver: anObject
set the menu-receiver. That's the one who gets the messages ( both from myself and
from all submenus no specific receiver is defined ).

o  shortcutKeyAt: stringOrNumber
gets the shortCutKey of an item or nil

o  shortcutKeyAt: stringOrNumber put: aKey
sets the shortCutKey of an item

o  shortcutKeys
returns a collection of shortcutKeys or nil

o  shortcutKeys: something
define shortcutKeys for each item

accessing-channels
o  enableChannel: aValueHolder
set my enableChannel

o  menuChannel

o  menuHolder: aValueHolder
set my menuHolder

accessing-color & font
o  activeBackgroundColor
get the background drawing color used to highlight selection

o  activeForegroundColor
get the foreground color used to highlight selections

o  backgroundColor: aColor
set the background drawing color. You should not use this method;
instead, leave the value as defined in the styleSheet.

o  buttonActiveBackgroundColor
get the background drawing color used to highlight button selection

o  buttonActiveForegroundColor
get the foreground drawing color used to highlight button selection

o  buttonEdgeStyle
get the button edge style

o  buttonEnteredBackgroundColor
get the background drawing color used to highlight entered button items

o  buttonEnteredFrameColor
get the frame color used to highlight entered button items

o  buttonEnteredLevel
get the 3D-level used to highlight entered button items

o  buttonHalfLightColor
get the background drawing color used to half light button frame

o  buttonHalfShadowColor
get the background drawing color used to half shadow button frame

o  buttonLightColor
get the background drawing color used to light button frame

o  buttonPassiveBackgroundColor
get the background drawing color used for button

o  buttonShadowColor
get the background drawing color used to shadow button frame

o  disabledEtchedForegroundColor
return the color used for etching disabled items.
If nil, no 3D effect is drawn.

o  disabledForegroundColor
return the foreground color used by disabled items

o  enteredBackgroundColor
return the background color for entered items

o  enteredForegroundColor
return the foreground color for entered items

o  font: aFont
set the font

o  foregroundColor
return the passive foreground color

o  foregroundColor: aColor
set the foregroundColor drawing color. You should not use this method;
instead leave the value as defined in the styleSheet.

o  maxAbsoluteButtonLevel
returns the maximum absolute button level; used to compute the preferred
extent of a button

o  selectionFrameBrightColor
get the selection frame bright color

o  selectionFrameDarkColor
get the selection frame dark color

o  setFont: aFont
set the font if the argument is nonNil;
Return nil, if the font was unchanged; otherwise, return the old font

o  suppressSeparatingLines

accessing-dimensions
o  computePreferredExtent
compute and returns my preferred extent

o  height
default height

o  maxExtent
notice, the position-dependent query: if there is a larger secondary screen,

Usage example(s): 

don't know, assume there is no maxExtent

o  origin: origin
changed due to menu in horizontal panel, if the origin
changed we have to rearrange the menu items if size not fixed

o  preferredExtentOfItems
compute and returns my preferred extent including all items
!!! changes have influence on method #rearrangeItems !!!

o  preferredWidth: aWidthOrNil
used for example by combo box to setup the preferred width for the popup menu.
If nil (default), the width is computed from the contained items.
If not nil, the width is the maximum from the contained items and the required width.

o  shortKeyInset
left inset of shortcutKey

o  sizeFixed: aBoolean
set/clear the fix-size attribute.
If true (the default), the menuPanel will not change its size when items become visible/invisible.
If false, it will resize itself to adapt to the number of visible items

o  stringOffsetXfor: anItem
return the x offset for a MenuItem where to draw the text

o  subMenuIndicationWidth

accessing-interactors
o  iconIndicationDisabledOff

o  iconIndicationDisabledOn

o  iconIndicationOff

o  iconIndicationOn

o  iconRadioGroupDisabledOff

o  iconRadioGroupDisabledOn

o  iconRadioGroupEnteredOff

o  iconRadioGroupEnteredOn

o  iconRadioGroupOff

o  iconRadioGroupOn

accessing-items
o  enteredItem
return the item over which the mouse pointer is located;
nil if the mouse is not over any item

o  hasItems
return true, if I have items

o  itemAt: stringOrNumber do: aOneArgBlock
evaluate the block for an item and return the result from the block. In case that
the item does not exist nil is returned

o  itemAt: stringOrNumber do: aOneArgBlock ifAbsent: exceptionBlock
evaluate the block for an item and return the result from the block.
In case that the item does not exist,
the value from exception block is returned (no arguments)

o  itemAtIndex: anIndex
returns item at an index or nil

o  items
returns the list of items or nil.
Warning: do not change this list - it is mine !

o  numberOfItems
gets number of items

accessing-look
o  accessCharacterPositionAt: stringOrNumber
get the access character position for a textLabel

o  accessCharacterPositionAt: stringOrNumber put: anIndexOrNil
get the access character position for a textLabel

o  accessCharacterPositions
returns a collection of accessCharacterPositions or nil

o  accessCharacterPositions: something
define accessCharacterPositions for each item

o  buttonActiveLevel
get the buttons active level

o  buttonPassiveLevel
get the buttons passive level

o  centerItems

o  centerItems: aBoolean

o  fitFirstPanel
gets true if the first panel in the menu hierarchy must be fit
to the extent of its superView

NOT SUPPORTED

o  fitFirstPanel: aBoolean
NOT SUPPORTED.
should return true if the first panel in the menu hierarchy must fit
to the extent of its superView

o  groupSizes
gets collection of group sizes

o  groupSizes: aGroupSizes
sets collection of group sizes

o  hasVerticalLayout
return true if the layout is vertical

o  hasVerticalLayout: aBoolean
set the layout: vertical( true ) or horizontal( false )

o  level: anInt
(comment from inherited method)
set my 3D effect level relative to superView in nr of pixels

o  rightArrow

o  rightArrowShadow

o  showGroupDivider
get the enabled flag for showing groupDiveders

o  showGroupDivider: aBoolean
set the enabled flag for showing groupDiveders

o  showSeparatingLines
gets true if drawing of separating lines is enabled.

o  showSeparatingLines: aBoolean
turn on/off drawing of separating lines.

o  verticalLayout
return true if the layout is vertical

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

o  verticalLayout: aBoolean
set to true if the layout is vertical; false for horizontal

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

accessing-style
o  buttonInsetX
returns the verical button space

o  buttonInsetY
returns the verical button space

o  delayInSecondsBeforeOpeningSubmenu
answer the seconds a submenu will be delayed before
open; an already open submenu than will be closed

o  drawMenuIndicatorSeparatorLine
^ styleSheet at:#'menu.drawMenuIndicatorSeparatorLine' default:false

o  enteredLevel
returns the enter-level for an unselected item moved through

o  groupDividerSize
returns the width of a group divider

o  itemMargin
returns the margin of an item

o  itemSpace
returns the additional space for an item in a (vertical) panel

o  menuIndicatorVerticalPosition
#center, #top or #bottom

Usage example(s): 

^ styleSheet at:#'menu.menuIndicatorVerticalPosition' default:#bottom

o  selectionFollowsMouse
returns true if the selection follows the mouse

o  shortcutKeyOffset
returns the offset for a shortcutKey

accessing-submenu
o  subMenuAt: stringOrNumber
gets the current submenu of an item; if the submenu is nil, the
submenu is generated if specified otherwise nil is returned.

o  subMenuAt: stringOrNumber put: aSubMenu
sets the submenu of an item

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

activation & deactivation
o  closeMenus
close all menus without accepting

o  hide
hide the view, leave its modal event loop

o  show
realize the view at its last position;
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

o  showAt: aPoint
realize the view at aPoint.
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

o  showAt: aPoint resizing: aBoolean
realize the view at aPoint; return nil if no item was selected,
or if I have already performed.
Return the items value, otherwise.
Notice, that this is returned back to the one who started this
menu (i.e. the view or controller), which will perform the action
if a non-nil is returned.

o  showAtPointer
realize the view at the current pointer position.
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

o  showCenteredIn: aView
make myself visible at the screen center.
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

o  startUp
realize the menu at the current pointer position
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

o  startUpAt: aPoint
realize the menu at aPoint
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

o  startUpFor: originatingWidget
realize the menu at the current pointer position
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

o  startUpOrNil
realize the menu at the current pointer position
return the value of the selectedItem or nil, of none was selected
(unless the menu has already performed its action, by sending an appropriate message
to some performer)

adding & removing
o  addItem: aMenuItem
add a menuItem at the end;
useful to build a menu programmatically (or, to add more items dynamically)

o  addSeparator

o  createAtIndex: anIndexOrNil
create an item and add this item to the index. In case of nil, the item
is added to the end. If the index is not valid nil is returned;
otherwise the new created item is returned.

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

o  createItemAtIndex: anIndexOrNil
create an item and add this item to the index.
In case of nil, the item is added to the end.
If the index is not valid, nil is returned;
otherwise the new created item is returned.

o  remove: stringOrNumber
remove the first item which is assigned to stringOrNumber;
if found, remove and return it

o  removeAll
remove all items and submenus

change & update
o  update: something with: aParameter from: changedObject
changed due to menu in horizontal panel

converting
o  asMenu
convert contents to a menu

o  fromSpec: aMenuSpec
build from spec

o  menu: aMenu
setup from a menu

dependents access
o  addDependencies
add all dependencies

o  removeDependencies
remove all dependencies

drawing
o  delayedInvalidateItem: anItem repairNow: aBool
an item changed; invalidate the item's layout

o  disabledRedrawDo: aBlock
evaluate a block without redrawing within the block; after processing
of the block a redraw might be performed

o  drawButtonEdgesFor: anItem level: aLevel

o  drawFocusForItem: anItem
draw a dotted rectangle around an item to indicate that it has the keyboard focus

o  drawGroupDividerFor: item inset: groupDivInset
draw a group divider

o  drawItemsX: x y: y width: w height: h
redraw items and groups

o  drawLabelEdgeFor: anItem selected: isSelected

o  drawScrollButtonAt: aDirection bounds: bounds
draw a scroll button

o  invalidateItem: anItem repairNow: aBool
an item changed; invalidate the item's layout

o  mustRearrange
force rearrange (i.e. set the rearrange flag)

o  rearrangeGroups
implements the groupIdentifier #right/#conditionalRight in a horizontal menu

o  rearrangeItems
recompute the layout of each item
!!! changes have influence on method #preferredExtentOfItems !!!

o  rearrangeItemsIfItemVisibilityChanged
check for items which can change its visibility;
if at least one item exists, rearrange all items

o  redrawX: x y: y width: w height: h
redraw a damage

o  updateEnteredItem

enumerating & searching
o  collect: aOneArgBlock
evaluate the argument, aOneArgBlock for every item in the menuPanel
and return a collection of the results

o  detectItem: aBlock
returns the item for which aBlock returns true.

o  detectItemForKey: aKey
returns the item assigned to a key, accessCharacter or starts with.
if no item is detected nil is returned.

o  detectItemForLabel: aLabel

o  detectItemForNameKey: aKey

o  do: aOneArgBlock
evaluate the argument, aOneArgBlock for every item in the menuPanel.

o  findFirst: aOneArgBlock
find the index of the first item,
for which evaluation of the argument, aOneArgBlock returns true;
return its index or 0 if none detected.

o  findLast: aOneArgBlock
find the last item, for which evaluation of the argument, aOneArgBlock
returns true; return its index or 0 if none detected.

o  firstItemSelectable
returns the first item which is selectable or nil

o  indexOf: something
returns index of an item assigned to an index, nameKey, textLabel or value if symbol.
If no item match 0 is returned. No range checks are performed on a number argument

o  indexOfItem: anItem
returns the index of the item or 0

o  itemForWhich: checkBlock

o  itemsDo: aBlock

o  itemsDoWithIndex: aBlock

o  keysAndValuesDo: aTwoArgBlock
evaluate the argument, aTwoArgBlock for every item in the menuPanel.

event handling
o  buttonMotion: state x: x y: y
open or close the corresponding submenu

o  buttonPress: button x: x y: y
any button pressed; open or close the corresponding submenus

o  buttonRelease: button x: x y: y
button release action; accept selection and close all views

o  exposeX: x y: y width: w height: h
e'=================== expose **** {x} x {y} -> {w}/{h}' printCR.

o  handleSizeChanged: how from: oldExtentOrNil
if a rearrange is already pending...

o  keyPress: key x: x y: y
any key is pressed

o  mapped
if I come up with a pressed button, react on release instead.

o  mouseWheelMotion: buttonState x: x y: y amount: amount deltaTime: dTime
mousewheel action

o  pointerLeave: state
I'have the focus; if no button pressed, than keep the selection

o  sizeChanged: how from: oldExtentOrNil
my view has changed the size (not the contents)

Usage example(s): 

^ super sizeChanged:how.

event handling-processing
o  clearImplicitGrab

o  dispatchEvent: ev withFocusOn: focusView delegate: doDelegate
dispatch and handle an event

o  handleButtonMotion: state atPoint: motionPoint
invalidate affected menu items
and possibly open or close corresponding submenus.
If I am a sub(sub-) menu, this message is forwarded from the
top level menu to me

o  handleButtonPress: button atPoint: aPoint
a button pressed; open or close the corresponding submenus

o  handleCursorKey: aKey
handle a cursor key

o  handleKeyPress: key
any key is pressed

o  handlePointerLeave: state

o  handleReturnPressed
return (or space) key is pressed

o  handleScrollerEvent: ev
handle a scroller event;
because I have grabbed the pointer, the event's coordinate
is relative to my view, and must be xlated to the scroller.
Return true if the event is handled (i.e. a scroller event)

o  pointerEntersItem: anItemOrNil
the pointer moves over an item or nil;
restore the old item and redraw the new item highlighted.

o  processHideMenuEvent: ev
to be filled...

o  processMenuEnterItemEvent: ev
to be filled...

o  processMenuSelectItemEvent: ev
if I was started as a modal Dialog, the activating windowGroup
has already been nilled after the Menu disappeared
(mustNilWindowGroup in SimpleView >> #openModal:inGroup:asPopup:).

o  updateHelpForItem: anItemOrNil
give the app a chance to present the help text in its info line

focus handling
o  canTab
depends whether I'am a toolbar and selectable items exists

o  focusComesByTab
returns true if focus comes by tab and should be drawn

o  focusComesByTab: aBoolean
only handled for toolBars

o  hasKeyboardFocus: aBoolean
notification from the windowGroup that I got/lost the keyboard focus.

o  showFocus: focusComesByTab
(comment from inherited method)
highlight myself somehow to tell user that I have the focus.
If explicit is true, the focus came via focusStepping (i.e. tabbing);
if false, it came via the window manager (i.e. pointer entering).
Only change my border, if this is an explicit focusChange.

o  showNoFocus: focusByTab
(comment from inherited method)
undo the effect of showFocus.
Explicit tells if the focus came via focusStepping (i.e. tabbing)
or via the window manager (i.e. pointer entering).
Only change my border, if this is an explicit focusChange.

o  supportsFocusOnTab
returns true if focus is supported

o  wantsFocusWithButtonPress
needs only the focus if I'am a toolbar; all events are delegated
to my subMenus

grabbing
o  doGrab

o  doUngrab: forceDo

o  grabKeyboard
grap the keyboard; keep previous grab

o  grabMouseAndKeyboard
get exclusive access to pointer and keyboard

o  grabPointerWithCursor: aCursorOrNil
grap the pointer; keep previous grab

o  ungrabKeyboard
ungrap the keyboard; restore previous grab

o  ungrabMouseAndKeyboard
ungrab resources (mouse and keyboard)

o  ungrabPointer
ungrap the pointer; restore previous grab

help
o  helpSpecProvider: aSpecProvider
pluggable helpspec provider

o  helpText
return the helpText for the currently selected item (empty if none).

Usage example(s): 

^ self helpTextForItem:selection

o  helpTextAt: aPoint
return the helpText for aPoint (i.e. when mouse-pointer is moved over an item).
If there is a selection, that item's helpText is used (ignoring the given point).
cg: this is wrong - should (and does) always show the helptext under the pointer

o  helpTextForItem: anItem
returns the helpText for an item (nil if none)

o  helpTextForKey: aKey
first try my application to provide the text,
then, in case I have a pluggable helpSpec, try that

help specs
o  helpSpec
allows subclasses to provide texts

image registration
o  imageOnMyDevice: anImage
returns image registered on device

o  lightenedImageOnDevice: anImage
returns lightened image registered on device

initialization & release
o  addToCurrentProject
ignored here

o  create
maybe create the shadow view for a popUp menu

o  createVisibleScroller
create a scroller (like a scrollbar, but without step-buttons) if neccessary

o  destroy
destroy items and shadowView; remove dependencies

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

o  initStyle
initialize style specific stuff

o  initialize
set default configuration

o  map
grab the pointer here, when visible (but not if control has already been lost).
If the grab fails, try again and unmap myself if that fails too.

o  realize
realize menu and shadowView

Usage example(s): 

Because of #saveUnder of ShadowView the order of realize is significant:
         shadowView must be realized before self

o  recreate
this is called after a snapin or a migration.
If the image was saved with an active menu, hide the menu

o  reinitStyle
handle style change while being open (win32 only - for now)

o  unmap
unmap the view - the view stays created (but invisible), and can be remapped again later.
If we have a popup supermenu, it will get all keyboard and mouse events.

o  updateLevelAndBorder
update level & border

keyboard control
o  mnemonicViewNext: aKeyEvent
a mnemonicKey event as forwarded from the keyboardProcessor - if there
is the mnemonic-key defined for any menuItem, handle the menuItem and
return the topMenu otherwise nil.

o  openMenusFromItemIndices: anItemIndiceList
open all menus derived from sequence of item indices

o  processCollectedShortcutIndices: indices
first lookup in current open submenus

o  processShortcut: aKeyEvent
a shortcutKey event as forwarded from the keyboardProcessor.
If there is a shortcut-key defined, process it and return true.
Otherwise return false.

o  selectItemIndicesFor: aOneArgBlock maxDepth: maxDepth from: aStart to: aStop ignoreSubmenuBlock: ignoreSubmenueBlock
returns the sequence of indices up to the item for which the block returns true.
The first entry is the topmenu, the last entry the item for which the block returns
true. If no item is detected, nil is returned.
If the ignoreSubmenueBlock is not nil, the menu under the item (argument to the block)
is created and passed through if the block returns false.
Otherwise the item is not asked for its submenu.

misc
o  raiseDeiconified

o  superMenu
returns supermenu or nil

o  topMenu
returns the topMenu; the one having no superMenu

printing & storing
o  printOn: aStream
(comment from inherited method)
append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

The default here is to output the receiver's class name.
BUT: this method is heavily redefined for objects which
can print prettier.

private
o  application
optimize access to retrive the application

o  onEachPerform: aSelector withArgList: aList
on each item perform selector with an argument derived from aList

o  registerImageOnDevice: anImage
|image|

o  superMenu: aSuperMenu
set my supermenu from which i'am activated

o  withMenuAndItemAt: srcPoint do: aBlock

private-activation
o  activeMenu
returns the current active menu or self (the top menu)

o  activeMenu: aMenu
set the current active menu

o  becomesActiveMenu
submenu becomes the active menu

o  clearLastActiveMenu
reset the current active menu

o  mapTime
get the time the menu was activated or nil

o  mapTime: aTimestamp
set the time the menu was activated

private-scrolling
o  autoScroll: delta

o  hasScrollButtonAt: aDirectionSymbol
returns true if a visible scroll button at aDirectionSymbol exists

o  hasScrollButtons
marked as obsolete by cg at 24-Aug-2021

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

o  hasScrollerAt: aDirection
marked as obsolete by cg at 24-Aug-2021

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

o  hasScrollers
marked as obsolete by cg at 24-Aug-2021

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

o  indexOfFirstItemShown
answer the index of the first shown item or 0 if there is none

o  indexOfItemAtScroller: aDirection
returns the index of the item under the scroller or 0

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

o  indexOfLastItemShown
answer the index of the last shown item or 0

o  installAutoScroll
Transcript showCR: e'{Timestamp now} y: {y}'.

o  makeItemVisible: anItem
make an item visible

o  needScrollButtonAt: aDirectionSymbol
returns true if a visible scroll button at aDirectionSymbol is needed

o  needScrollButtons
returns true if any scroll button is needed

o  offsetForScroller
marked as obsolete by cg at 24-Aug-2021

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

o  pageDown
scroll one page down

o  pageUp
scroll one page up

o  scrollActivity
returns the one and only per-menu scrollActivity

o  scrollActivityIsActive

o  scrollActivityOrNil

o  scrollButtonBoundsAt: aDirectionSymbol
returns the bounds of the scroller at aDirectionSymbol,
which is #NEXT or #PREV
Warning: this is the current state, based upon the current view's extent
THUS: you cannot ask in a sizeChange for this info.

o  scrollButtonDirectionAtPoint: aPoint
returns the scroller-direction-symbol at aPoint, #PREV, #NEXT or nil

o  scrollDown
scroll one line down

Usage example(s): 

if there is no scroller and no scrollDown button, then do nothing

o  scrollTo: aNewOrigin redraw: doRedraw allowScrollBeyondContents: allowScrollBeyondContents
change origin to have newOrigin be visible at the top-left.

o  scrollToBottom
scroll to last visible item

o  scrollToTop
scroll to first visible item

o  scrollUp
scroll one line up

Usage example(s): 

if there is no scroller and no scrollUp button, then do nothing

o  scrollerBoundsAt: aDirectionSymbol
marked as obsolete by cg at 24-Aug-2021

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

o  scrollerDirectionAtPoint: aPoint
marked as obsolete by cg at 24-Aug-2021

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

o  scrollerInstanceOrNil
answer the scroller instance if there is one

o  stopScrollActivity

o  updateScroller
scroller thumbHeight: (self innerHeight asPercentFrom:(self heightOfContents)).

o  viewOrigin
return the viewOrigin;
that's the coordinate of the first shown item

o  widthOfScroller
answer the width for a (vertical) scroller
or 0 if no scroller is needed; i.e. possibly scroll buttons.

private-searching
o  detectGrabMenu
returns the menu which is responsible for the grap; the last opened menu

o  detectMenuAtGrabPoint: aGrabPoint
returns the menu which contains the grab-point

o  grabMenuItemAtPoint: aPoint
returns the item in the active menu at aPoint or nil if none detected.
aPoint is relative to myself and might be outside, if I have gabbed the mouse
and a submenu is currently active)

o  itemAt: stringOrNumberOrPoint
returns item assigned to an index, nameKey, textLabel or value if symbol.
If no item match nil is returned.

o  itemAtPoint: aPoint
returns the item at aPoint or nil if none detected.
aPoint is within myself
(which might be outside, if I have gabbed the mouse
and a submenu is currently active)

o  superMenuAtPoint: aPoint
returns the superMenu which contains aPoint, or nil if none detected

queries
o  container: aView
I am no longer a popUpView

o  containsPoint: aPoint
returns true if the argument, aPoint is contained by the view

o  containsPointX: x y: y
returns true if point is contained by the view

o  hasGroupDividerAt: anIndex
returns true if a divider is defined at an index

o  hasGroupDividers
returns true if any group divider exists

o  hasPerformed

o  isFitPanel
returns true if the panel is the first in the menu hierarchy
and must be fit to the extent of its superView;
Obsolete: NO LONGER SUPPORTED

o  isPopUpView
return true, if I want to come up without decoration
and raise to top immediately.

o  isVerticalLayout
marked as obsolete by cg at 24-Aug-2021

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

o  isViewWrapper

o  type

queries-contents
o  heightOfContents
return the height of the (visible) contents in pixels.

selection
o  hasSelection
returns true if a selection exists

o  openDelayed: anItem

o  openDelayed: anItemOrNil afterSeconds: seconds

o  selectAndOpenDelayed: anItemOrNil
change selection to an item or nil

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

o  selectAndOpenDelayed: anItemOrNil after: delayTimeInSeconds
change selection to an item or nil;
If the item has a submenu, open it after some delay time.
The delay time is needed, in case you try to move into the
just opened submenu, and come across another item (if the supermenu)
while doing so (i.e. moving to down-east from the selected item)

o  selection
returns current selected item or nil

o  selection: anItemOrNil
change selection to an item or nil
if the item has a submenu, the first item might be auto selected (style-sheet)

o  selection: anItemOrNil openMenu: openMenu
change selection to an item or nil

o  selectionIndex
returns index of current selection or 0

o  selectionIndex: anIndex
set selection at an index

o  setSelection: anItemOrNil
anItemOrNil ~~ selection ifTrue:[

testing
o  isMenu
true if this is a menu panel

translation
o  translateGrabPoint: aGrabPoint
translate the grab point into self

o  translateMenuPoint: aPoint toMenu: aMenu
translate a point into another menu its point

Private classes:

    Item
    ScrollActivity

Examples:


a PullDownMenu 
  |top mview labels|

  top := StandardSystemView new.

  labels := #( 'foo' 'bar' 'baz' 'test') copy.
  labels at:4 put:(LabelAndIcon label:'test' icon:(ToolbarIconLibrary cutIcon)).

  mview := MenuPanel in:top.
  mview labels:labels.
  (mview itemAt:1) enabled:false.
  (mview itemAt:4) enabled:false.
  top extent:(mview preferredExtent + 20).
  top open.

  |top mview desc s1 s2 s3 img lbs labels|

  top := StandardSystemView new.

  mview := MenuPanel in:top.

  labels := #( 'foo' 'bar' 'baz' 'test' 'claus' ).
  mview level:2.
  mview hasVerticalLayout:false.
  img := Image fromFile:'bitmaps/SBrowser.xbm'.
  lbs := Array with:'foo' with:'bar' with:img with:'baz' with:'test' with:'ludwig'.
  mview labels:lbs.
  mview shortcutKeyAt:2 put:#Cut.
  mview accessCharacterPositionAt:1 put:1.
  mview accessCharacterPositionAt:2 put:2.

  mview enabledAt:5 put:false.
  mview groupSizes:#( 2 2 ).
  s1 := MenuPanel labels:labels.
  s1 accessCharacterPositionAt:1 put:1.
  s1 accessCharacterPositionAt:2 put:2.
  s1 groupSizes:#( 2 2 ).
  s2 := MenuPanel labels:#( '1' nil '2' '-' '3' '=' '4' ' ' '5' ).
  s3 := MenuPanel labels:lbs.

  s1 subMenuAt:2 put:s2.
  s1 subMenuAt:3 put:(MenuPanel labels:lbs).
  s2 subMenuAt:3 put:s3.
  s3 subMenuAt:3 put:(MenuPanel labels:labels).
  s3 shortcutKeyAt:3 put:$q.

  mview subMenuAt:1 put:s1.
  mview subMenuAt:4 put:(MenuPanel labels:lbs).
  (mview subMenuAt:4) shortcutKeyAt:3 put:#Copy.
  s1 shortcutKeyAt:1 put:#Copy.
  s1 shortcutKeyAt:3 put:#Paste.

  mview subMenuAt:2 put:(MenuPanel labels:labels).
  top extent:(mview preferredExtent).
  top open.
a PullDownMenu with applications 
  |top menu view item|

  top  := StandardSystemView extent:240@100.
  menu := MenuPanel in:top.
  menu labels:#( 'foo' 'Application' 'Clock' ).
  menu hasVerticalLayout:false.

  menu subMenuAt:1 put:(MenuPanel labels:#( 'bar' 'baz' )).
  menu subMenuAt:2 put:(MenuPanel labels:#( 'foo' 'bar' 'baz' )).

  view := ClockView new.
  view preferredExtent:100@100.
  item := menu itemAt:3.
  item submenu:view.

  view := ImageView new.
  view image:(Image fromScreen:(0@0 corner:200@200)).
  view preferredExtent:(200@200).
  item := menu itemAt:2.
  item submenu:view.

  menu origin:0@0 corner:1.0@30.
  top open.
a PopUpMenu 
  |mview desc s1 s2 s3 img lbs labels|

  mview := MenuPanel new.
  labels := #( 'foo' 'bar' 'baz' ).
  mview level:2.

  img := Image fromFile:'bitmaps/SBrowser.xbm'.
  lbs := Array with:'foo' with:'bar' with:img with:'baz' with:'test'.
  mview labels:lbs.

  s1 := MenuPanel labels:labels.
  s2 := MenuPanel labels:#( '1' nil '2' '-' '3' '=' '4' ' ' '5' ).
  s3 := MenuPanel labels:lbs.
  s1 subMenuAt:2 put:s2.
  s1 subMenuAt:3 put:(MenuPanel labels:lbs).
  s2 subMenuAt:3 put:s3.
  s3 subMenuAt:3 put:(MenuPanel labels:labels).
  s3 shortcutKeyAt:3 put:$q.

  mview subMenuAt:1 put:s1.
  mview subMenuAt:4 put:(MenuPanel labels:lbs).
  (mview subMenuAt:4) shortcutKeyAt:3 put:#Copy.
  s1 shortcutKeyAt:1 put:#Copy.
  s1 shortcutKeyAt:3 put:#Paste.

  mview subMenuAt:2 put:(MenuPanel labels:labels).
  mview startUp
a menu spec 
  |menu|

  menu := MenuPanel menu:
      #(#Menu #( #(#MenuItem
                  #label: 'File'
                  #submenu:
                    #(#Menu #(#(#MenuItem #label: 'quit' #value:#quit )
                               (#MenuItem
                                  #label: 'edit'
                                  #submenu:
                                    #(#Menu #( #(#MenuItem #label: 'edit'  #value:#edit )
                                               #(#MenuItem #label: 'close' #value:#close)
                                             )
                                             nil
                                             nil
                                     )
                                )
                               #(#MenuItem #label: 'help' #value:#help )
                             )
                             nil
                             nil
                     )
               )
              #(#MenuItem #label: 'Inspect' #value:#inspectMenu )
              #(#MenuItem #label: 'Bar'
                          #submenu:
                             #(#Menu #( #(#MenuItem #label: 'bar 1' #value:#bar1 )
                                        #(#MenuItem #label: 'bar 2' #value:#bar2 )
                                      )
                                      nil
                                      nil
                              )
               )
            )
            #( 2 )
            nil
       ) decodeAsLiteralArray.

  menu hasVerticalLayout:false.
  Transcript showCR:(menu startUp).
many items; menuPanel embedded in another (top) view: 
  |top mview labels|

  top := StandardSystemView new.

  labels := (1 to:50) collect:[:n | e'item{n}'].

  mview := MenuPanel in:top.
  mview labels:labels.
  mview hasVerticalLayout:true.
  (mview itemAt:1) enabled:false.
  (mview itemAt:4) enabled:false.
  mview extent:(mview preferredExtent x @ 1.0).
  top extent:(mview preferredExtent + 20).
  top open.
huge number of items; menuPanel embedded in another (top) view: 
  |top mview labels|

  top := StandardSystemView new.

  labels := (1 to:150) collect:[:n | e'item{n}'].

  mview := MenuPanel in:top.
  mview labels:labels.
  mview hasVerticalLayout:true.
  (mview itemAt:1) enabled:false.
  (mview itemAt:4) enabled:false.
  mview extent:(mview preferredExtent x @ 1.0).
  top extent:(mview preferredExtent + 20).
  top open.
many items; menuPanel as popup: 
  |mview labels|

  labels := (1 to:50) collect:[:n | e'item{n}'].

  mview := MenuPanel new.
  mview labels:labels.
  mview hasVerticalLayout:true.
  (mview itemAt:1) enabled:false.
  (mview itemAt:4) enabled:false.
  mview open.
huge number of items; menuPanel as popup: 
  |mview labels|

  labels := (1 to:150) collect:[:n | e'item{n}'].

  mview := MenuPanel new.
  mview labels:labels.
  mview hasVerticalLayout:true.
  (mview itemAt:1) enabled:false.
  (mview itemAt:4) enabled:false.
  mview extent:(mview preferredExtent x @ 1.0).
  mview open.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 22 Dec 2024 01:08:49 GMT