Class PluggableButtonView

Inheritance:

Object  »
  View  »
    PluggableButtonView

A PluggableButtonView is a combination of an indicator for a boolean value stored in its model and an action button. The action of a button is often, but not always, to toggle the boolean value that it shows.

Preferred controller class: PluggableButtonController.
Possible model classes:

• Button
  for a visual element that is clicked on to trigger an action (action button)
• Switch
  for a visual element that is clicked to toggle between two different states (switch button)
• OneOnSwitch
  for a visual element that is grouped with other switches in such a way that at most one switch can be turned on (radio button)
• an individually written model
  for a visual element that
  • can change its label
  • has a popup menu
  • uses the values of argumentsSelector and argumentsProvider to communicate with its model

Instance variables:

• label - String, Text, DisplayText, Paragraph, Form
  label is a DisplayObject or an object that can be used to create a DisplayObject. The DisplayObject is displayed as switch label.

• getStateSelector - Symbol (message selector)
  The name of an unary message that is sent to the model to access the current button state. For a model that is a kind of Switch, this selector should be either #isOn or #isOff.

• actionSelector - Symbol (message selector)
  The name of a message that is sent to the model to trigger an action. For a model that is a kind of Switch, this selector should be either #turnOn or #turnOff. When instance variables argumentsProvider and argumentsSelector are not nil, actionSelector should name a method that is sent with one argument, otherwise, it should name a method that is sent without arguments.

• getLabelSelector - Symbol (message selector)
  The name of an unary message that is sent to the model to obtain a new switch label. Class Switch and its subclasses do not support switch labels. To use a PluggableButtonView with a changing label, an individually written model has to be used.

• getMenuSelector - nil or Symbol (message selector)
  nil for a view that does not offer a menu. For a view that offers a menu, the name of a message that is sent with one or with two arguments. Class Switch and its subclasses do not support menus. To use a PluggableButtonView with a menu, an individually written model has to be used.

• shortcutCharacter - Character
  A character that triggers an action. This feature is only used by FormMenuView. A PluggableButtonView that is not a subview of a FormMenuView does not react to input from the keyboard.

• askBeforeChanging - Boolean
  This variable is initialized to false.

• triggerOnMouseDown - Boolean
  This variable is initialized to false.

• complemented - Boolean
  This variable is for internal use only. The button is displayed complemented (selected) when this variable has the value true and normal (unselected) when this variable has the value false. This variable is initialized to false.

• argumentsProvider - nil or Object
  When not nil, this object is required to understand the message whose name is stored in argumentsSelector.

• argumentsSelector - nil or Symbol (message selector)
  The name of an unary message that is sent to a non-nil object to obtain an argument value from argumentsProvider. The argument value is used when the actionSelector is sent to the model. Class Switch and its subclasses do not support the use of actions that are provided with arguments. To use that feature, an individually written model has to be used.

Important Class Methods

For the creation of initialized instances, the class protocol provides a set of five dedicated class methods. Method on:getState:action:label:menu: is the most general of these methods, three others are shortened variants that provide reasonable default values for some parameters of the general method.

• on: anObject getState: getStateSel action: getActionSel label: getLabelSel menu: getMenuSel
  Answers an instance that is initialized with all selectors that the instance needs to communicate with its model. Selector usage is:

  • getStateSel
    The name of an unary message that is sent to the model to access the current button state.
  • getActionSel
    The name of a message that is sent to the model to trigger an action. When instance variables argumentsProvider and argumentsSelector are not nil, actionSelector should name a method that is sent with one argument, otherwise, it should name a method that is sent without arguments
  • setLabelSel
    The name of an unary message that is sent to the model to obtain a new switch label.
  • setMenuSel
    The name of a message that is sent with one or with two arguments.

• on: anObject getState: getStateSel action: getActionSel label: getLabelSel
  This shortened variant of the general instance creation method is used when no menu is needed.

• on: anObject getState: getStateSel action: getActionSel
  This shortened variant of the general instance creation method is used when neither a menu nor a label is needed.

• on: anObject
  This shortened variant of the general instance creation method creates an instance with state access selector #isOn and action selector #switch.

A PluggableButtonView is a combination of an indicator for a boolean value stored in its model and an action button. The action of a button is often, but not always, to toggle the boolean value that it shows. Its pluggable selectors are:

• getStateSelector
  fetch a boolean value from the model
• actionSelector
  invoke this button's action on the model

Either of the above selectors can be nil, meaning that the model does not supply behavior for the given action, and the default behavior should be used. For example, if getStateSelector is nil, then this button shows the state of a read-only boolean that is always false.

The model informs a pluggable view of changes by sending #changed: to itself with getStateSelector as a parameter. The view tells the model when the button is pressed by sending actionSelector.

A PluggableButtonView can display either a Form or one of the following: String, Text, DisplayText, Paragraph.

Options:

• askBeforeChanging
  have model ask user before allowing change that could lose edits. The model is asked with the method okToChange which has to return a boolean value.
• triggerOnMouseDown
  do button action on mouse down (vs. up) transition
• shortcutCharacter
  a place to record an optional shortcut key

For proper placement of a DisplayObject, a PluggableButtonView assign a value to the instance variable offset. It is therefore not possible to share a Form or a DisplayText between several instances of PluggableButtonView.

To display the text on a switch in a larger font, you should create a DisplayText. The following piece of code may serve as a template:

   | text textStyle displayText |

  text := Text string: string
               attribute: TextEmphasis normal.

  textStyle := TextStyle default copy.
  textStyle defaultFontIndex: (textStyle fontIndexOfSize: 21).

  displayText := DisplayText text: text
                             textStyle: textStyle.
  displayText foregroundColor: Color black
              backgroundColor: Color lightGreen.

  switch label: displayText