eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'OptionBox':

Home

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

Class: OptionBox

Inheritance:

   Object
   |
   +--GraphicsMedium
      |
      +--DisplaySurface
         |
         +--SimpleView
            |
            +--View
               |
               +--TopView
                  |
                  +--StandardSystemView
                     |
                     +--ModalBox
                        |
                        +--DialogBox
                           |
                           +--OptionBox
Package:
stx:libwidg
Category:
Views-DialogBoxes
Version:
rev: 1.92 date: 2023/03/23 17:19:54
user: cg
file: OptionBox.st directory: libwidg
module: stx stc-classLibrary: libwidg

Description:


CAVEAT: this is a leftover - functionality has been merged into DialogBox
PLEASE use one of the `Dialog chooseXXX' methods instead of OptionBox.


Historic note:
   originally, ST/X had separate classes for the various entry methods;
   there were YesNoBox, EnterBox, InfoBox and so on.
   In the meantime, the DialogBox class (and therefore its alias: Dialog)
   is going to duplicate most functionality found in these classes.

   In the future, those existing subclasses' functionality is going to
   be moved fully into Dialog, and the subclasses will be replaced by dummy
   delegators. (They will be kept for backward compatibility, though).

 Description:
   OptionBoxes are like YesNoBoxes but with as many buttons as you like;
   this will finally be a superclass of WarnBox and YesNoBox - or maybe merged
   all into DialogBox..
   Use them for multiway questions.
   For a consistent user interface, the rightmost (last) button should be the default return
   button (i.e. pressing return in the box performs this buttons function).
   However, this is reversed automatically if the viewStyle says so (Windows vs. OSX vs. Linux),
   so the programmer MUST always put the no-actions (i.e. cancel) first and the ok-actions (yes) last.


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

easy startup
o  forRequest: title label: label image: anImage buttonLabels: labels values: values default: defaultValue
create a new optionBox and return it.
Does not open the box.

o  forRequest: title label: label image: anImage buttonLabels: labels values: values default: defaultValue helpTexts: helpTextsOrNil
create a new optionBox and return it.
Does not open the box.

o  request: title buttonLabels: labels values: values
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil if canceled

Usage example(s): 

     OptionBox
        request:'please select any'
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)

o  request: title buttonLabels: labels values: values default: defaultValue
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil if canceled.

Usage example(s): 

     OptionBox
        request:'please select'
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)
        default:3

o  request: title label: label buttonLabels: labels values: values
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil if canceled

Usage example(s): 

     OptionBox
        request:'please select'
        label:'select any'
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)

o  request: title label: label buttonLabels: labels values: values default: defaultValue
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil if canceled

Usage example(s): 

     OptionBox
        request:'please select'
        label:'select any'
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)
        default:3

o  request: title label: label buttonLabels: labels values: values default: defaultValue onCancel: cancelValue
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return cancelValue if canceled.

Usage example(s): 

     OptionBox
        request:'please select'
        label:'select any'
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)
        default:3
        onCancel:2

o  request: title label: label image: anImage buttonLabels: labels values: values
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil, if canceled.

Usage example(s): 

     OptionBox
        request:'please select'
        label:'select any'
        image:(WarningBox iconBitmap)
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)

o  request: title label: label image: anImage buttonLabels: labels values: values default: defaultValue
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil if canceled.

Usage example(s): 

     OptionBox
        request:'please select'
        label:'select any'
        image:(WarningBox iconBitmap)
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)
        default:3

o  request: title label: label image: anImage buttonLabels: labels values: values default: defaultValue onCancel: cancelValue
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return cancelValue if canceled.

Usage example(s): 

     OptionBox
        request:'please select'
        label:'select any'
        image:(WarningBox iconBitmap)
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)
        default:3
        onCancel:nil

o  request: title label: label image: anImage buttonLabels: labels values: values default: defaultValue onCancel: cancelValue helpTexts: helpTextsOrNil
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return cancelValue if canceled.

Usage example(s): 

     OptionBox
        request:'please select'
        label:'select any'
        image:(WarningBox iconBitmap)
        buttonLabels:#('one' 'two' 'three')
        values:#(1 2 3)
        default:3
        onCancel:nil

instance creation
o  title: titleString
create a new optionBox with title, aTitleString

o  title: titleString numberOfOptions: nOptions
create a new optionBox with title, aTitleString and nOptions options

obsolete
o  forRequest: title label: label form: anImage buttonLabels: labels values: values default: defaultValue
create a new optionBox and return it.
Does not open the box.

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

o  request: title label: label form: aForm buttonLabels: labels values: values
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil, if canceled.

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

o  request: title label: label form: aForm buttonLabels: labels values: values default: defaultValue
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return nil if canceled.

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

o  request: title label: label form: aForm buttonLabels: labels values: values default: defaultValue onCancel: cancelValue
create a new optionBox, open it modal and return the value of
the corresponding values collection. Return cancelValue if canceled.

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

Instance protocol:

accessing
o  action: actionBlock
define a single action for all buttons.
The action will be evaluated with the button index as argument.

o  actions: actionBlocks
define the actions

o  buttonTitles: titles actions: actionBlocks
define both button titles and actions

o  defaultButtonIndex: index
define which button is the default (i.e. return-) button.
By default, no returnButton is setup.
The argument must be an index 1..nButtons, or nil

o  numberOfOptions
return the number of options

o  numberOfOptions: nOptions
set the number of options - this is a private interface

accessing-components
o  buttons
return the buttons collection

o  labelPanel

accessing-look
o  buttonTitles: titles
set the button titles

o  form: aFormOrImage
historical leftover - define a form to be displayed left of the title

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

o  formLabel
return the label-view which displays a bitmap

o  image: aFormOrImage
set the image shown in the label-view

o  textLabel
return the label-view which displays a message string

o  title: aStringOrStringCollection
set the boxes title

o  title: aString numberOfOptions: nOptions
set the boxes title and number of options

help
o  buttonHelpTexts: helpTextsOrNil
annotate buttons with help texts.

initialization
o  initFormBitmap

o  initInfoBitmap

o  initWarnBitmap
WarnBitmap := Image fromFile:'bitmaps/Warning.xbm' resolution:100 on:Display

o  initYesNoBitmap

o  initialize
formLabel origin:(mm @ mm).

o  initializeButtons
no longer make the last button the default!

queries
o  computePreferredExtent
return a size to make everything fit into myself

Examples:


just opening (not real world examples, as you'd have to ask the box instance about the choice afterwards; see better usage examples below): 
   |box|

   box := OptionBox title:'hello' numberOfOptions:4.
   box showAtPointer

   |box|
   box := OptionBox title:'hello'.
   box buttonTitles:#('one' 'two' 'three').
   box defaultButtonIndex:3.
   box showAtPointer
showing a long list: 
   |box|
   box := OptionBox title:(1 to:100 collect:#asString) numberOfOptions:3.
   box buttonTitles:#('one' 'two' 'three').
   box defaultButtonIndex:3.
   box showAtPointer
performing an action: 
   |box|
   box := OptionBox title:'hello' numberOfOptions:3.
   box buttonTitles:#('one' 'two' 'three').
   box action:[:which | Transcript show:'button ';
                                   show: which;
                                   showCR:' was pressed'].
   box showAtPointer
returning a value: 
   |what|

   what := OptionBox
                 request:('text has not been accepted.\\Your modifications will be lost when continuing.') withCRs
                 label:' Attention'
                 image:(WarningBox iconBitmap)
                 buttonLabels:#('Abort' 'Accept' 'Continue')
                 values:#(#abort #accept #continue).
   Transcript showCR:what.
use callBack-hook to intercept creation: 
   |what|

   AboutToOpenBoxNotificationSignal handle:[:ex |
       |box|

       box := ex parameter.
       box verticalPanel
           add:(CheckBox label:'Do no show this Dialog again.'
                         model:false asValue).
       ex proceed.
   ] do:[
       what := OptionBox
                     request:('bla bla bla bla.\\You must bla bla bla!') withCRs
                     label:' Attention'
                     image:(WarningBox iconBitmap)
                     buttonLabels:#('Abort' 'Accept' 'Continue')
                     values:#(#abort #accept #continue)
                     default:#continue.
   ].
   Transcript showCR:what.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sun, 22 Dec 2024 05:26:16 GMT