eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ButtonController':



Class: ButtonController



rev: 1.96 date: 2024/02/23 11:31:28
user: cg
file: ButtonController.st directory: libwidg
module: stx stc-classLibrary: libwidg


ButtonControllers are used with buttons and handle all user interaction.
These are automatically created when a Button is created, therefore no manual
action is required for creation.
In normal applications, you don't have to care for the controller; 
access to the controllers behavior is possible via messages to the button.
(setting actions, controlling autorepeat etc.)

A ButtonController supports 3 types of notifications:
    MVC change notification - as usual
    channel notifications   - through the pressChannel/releaseChannels
    action callBack         - through pressAction / releaseAction blocks.

Notifications are made in the above order (i.e. an actionBlock sees the model
already changed, if there is a model).

Having multiple mechanisms here is both historic and to make the life
of simple applications easier - most buttons don't need a model or notification
channels and simply perform some action.
In general: actionBlocks are useful, if there is a single subject which
needs to be told about the press (i.e. actionButtons); 
models should be used when the button represents some value in some other
Channels are much like the MVC approach, however, these are useful if
press/release/label etc. may come from different objects, and a single 
(synthetic) model does not make sense or is not appropriate.

Actually, the channels are the most general - and the other mechanism could
(and will, maybe) based upon them; after all, an actionBlock is a channel,
whcih sends #value to its block ....

See examples in the Button class.

[Instance variables:]

  enableChannel           <ValueHolder    pressing is allowed (default: true)
                           on Boolean>    

  pressed                 <Boolean>       true if currently pressed (read-only)

  entered                 <Boolean>       true if the cursor is currently in this view

  isTriggerOnDown         <Boolean>       controls if the action should be executed on
                                          press or on release (default: on release).

  isToggle                <Boolean>       controls if the button should show toggle
                                          behavior (as opposed to one-shot behavior)

  pressActionBlock        <Block>         block to evaluate when pressed (default: noop)

  releaseActionBlock      <Block>         block to evaluate when released (default: noop)

  autoRepeat              <Boolean>       auto-repeats when pressed long enough (default: false)

  initialDelay            <Number>        seconds till first auto-repeat (default: 0.2)

  repeatDelay             <Number>        seconds of repeat intervall (default: 0.025)

  repeatBlock             <Block>         block evaluated for auto-repeat (internal)

  active                  <Boolean>       true during action evaluation (internal)


COPYRIGHT (c) 1995 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:

o  defaultInitialDelay
when autorepeat is enabled, and button is not released,
start repeating after initialDelay seconds

o  defaultRepeatDelay
when autorepeat is enabled, and button is not released,
repeat every repeatDelay seconds

Instance protocol:

o  action

o  action: aBlock
convenient method: depending on the setting the triggerOnDown flag,
either set the press-action & clear any release-action or
vice versa, set the release-action and clear the press-action.

o  autoRepeat
turn on autorepeat. OBSOLETE; use #autoRepeat:

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

o  autoRepeat: aBoolean
turn on/off autorepeat

o  beButton
make the receiver act like a button; that's the default, anyway

o  beRadioButton
make the receiver act like a radioButton;
That is like a toggle, but do not allow turning myself off
by buttonPress (instead, must be turned off by another button or programmatically)

o  beToggle
make the receiver act like a toggle

o  beTriggerOnDown
make the receiver act on button press

o  beTriggerOnUp
make the receiver act on button release

o  disable
alternative invokation; redirected to basic mechanism

o  doubleClickAction
return the doubleClickAction; that's the block which gets evaluated
when the button is double-clicked (if non-nil).
Seldom used with buttons

o  doubleClickAction: aBlock
define the action to be performed on double click

o  enable
alternative invokation; redirected to basic mechanism

o  enabled: aBoolean
disable the button

o  isAutoRepeat

o  isTriggerOnDown
return true, if I trigger on press
(in contrast to triggering on up, which is the default)

o  pressAction
return the pressAction; that's the block which gets evaluated
when the button is pressed (if non-nil)

o  pressAction: aBlock
define the action to be performed on press

o  releaseAction
return the releaseAction; that's the block which gets evaluated
when the button is released (if non-nil)

o  releaseAction: aBlock
define the action to be performed on release

o  triggerOnDown: aBoolean
set/clear the flag which controls if the action block is to be evaluated
on press or on release.
(see also ST-80 compatibility methods beTriggerOn*)

o  enableChannel
return the valueHolder holding the enable boolean value

o  enableChannel: aValueHolder
set the valueHolder, which holds the enable boolean value

o  pressChannel

o  pressChannel: aChannel

o  releaseChannel

o  releaseChannel: aChannel

o  active
return true, if I am active;
that is: currently performing my action.
This query can be used to avoid multiple redraws.

o  active: aBoolean

o  enabled
return true, if I am enabled

o  entered
return true, if the mouse pointer is currently in my view

o  entered: aBoolean

o  pressed
return true, if I am pressed

o  pressed: aBoolean

o  setPressed: aBoolean

o  toggle
toggle and perform the action

o  toggleNoAction
toggle, but do NOT perform any action

event handling
o  buttonMotion: buttonState x: x y: y
(comment from inherited method)
mouse was moved with button pressed in my view; nothing done here

o  buttonMultiPress: button x: x y: y
(comment from inherited method)
a mouse button was pressed again shortly after in my view

o  buttonPress: button x: x y: y
simulate momentary loss of focus to force accept into models in other components

o  buttonRelease: button x: x y: y
button was released - if enabled, perform releaseaction

o  enableStateChanged
this is sent, whenever the enable value has changed

o  keyPress: key x: x y: y
trigger on Return and space, if I am the focusView of my group
(i.e. if I got an explicit focus)

o  performAction
ST-80 style model notification ...
this updates the model (typically, a ValueHolder)

o  performShortcutAction

o  pointerEnter: state x: x y: y
mouse pointer entered my view.
Redraw with enteredColors if they differ from the normal colors

o  pointerLeave: state
mouse pointer left my view.
Redraw with normal colors if they differ from enteredColors

o  repeat
this is sent from the autorepeat-block, when the button has been pressed long
enough; it simulates a release-press, by evaluating both release
and press actions.

Usage example(s):

don't repeat, if a release is pending ...

o  requestAutoAccept
request to autoAccept from a keyboardProcessor.
AutoAccept is always allowed

o  controlInitialize

o  initialize
must be called if redefined

o  reinitialize

o  release
release all dependencies

ST/X; WebServer 1.702 at 20f6060372b9.unknown:8081; Thu, 30 May 2024 08:52:02 GMT