eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'TypeConverter':

Home

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

Class: TypeConverter

Inheritance:

   Object
   |
   +--Model
      |
      +--ValueModel
         |
         +--PluggableAdaptor
            |
            +--TypeConverter
Package:
stx:libview2
Category:
Interface-Support-Models
Version:
rev: 1.101 date: 2024/04/22 17:45:18
user: stefan
file: TypeConverter.st directory: libview2
module: stx stc-classLibrary: libview2

Description:


a typeConverter can be used as an editField's model
(remember, that an editField expects a string in its model),
to convert the field's string value to some object and vice versa.
Its main use is when building interfaces with inputFields,
where the datum to be entered is a non-string and you
want to have the entered value be converted automatically.
(and vice versa, to convert the datum to a string).

No real new functionality is added here 
- all is inherited from PluggableAdapter; 
however, some specialized instance creation methods are added here.

Notice: 
    this class was implemented using protocol information
    from alpha testers - it may not be complete or compatible to
    the corresponding ST-80 class. 
    If you encounter any incompatibilities, please forward a note 
    describing the incompatibility verbal (i.e. no code) to the ST/X team.


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

instance creation
o  onDateValue: aValueHolder
create and return a typeConverter, which retrieves
a date via #value, and converts
a date-string to a date via #value:.
Useful as an editField's model, which operates on some
date value (or aspectAdaptor, which adapts to a numeric slot)

o  onNumberValue: aValueHolder
create and return a typeConverter, which retrieves
a value's string representation via #value, and converts
a number-string to a value via #value:.
Useful as an editField's model, which operates on some
numeric value (or aspectAdaptor, which adapts to a numeric slot)

o  onNumberValue: aValueHolder format: formatString
create and return a typeConverter, which retrieves
a value's string representation via #value, and converts
a number-string to a value via #value:.
Useful as an editField's model, which operates on some
numeric value (or aspectAdaptor, which adapts to a numeric slot)

o  onNumberValue: aValueHolder leftPaddedTo: aSize with: aCharacter
create and return a typeConverter, which retrieves
a value's string representation via #value, and converts
a number-string to a value via #value:.
Useful as an editField's model, which operates on some
numeric value (or aspectAdaptor, which adapts to a numeric slot)

Usage example(s): 

  |m|
  m := 5 asValue.
  ((EditField model:(TypeConverter onNumberValue:m leftPaddedTo:2 with:$-)) width:100) openAt:(200@200).
  m inspect.

o  onNumberValue: aValueHolder minValue: min maxValue: max
create and return a typeConverter, which retrieves
a value's string representation via #value, and converts
a number-string to a value via #value:.
Useful as an editField's model, which operates on some
numeric value (or aspectAdaptor, which adapts to a numeric slot)

o  onNumberValue: aValueHolder postDecimalDigits: numPostDecimalDigits
create and return a typeConverter, which retrieves
a value's string representation via #value, and converts
a number-string to a value via #value:.
Useful as an editField's model, which operates on some
numeric value (or aspectAdaptor, which adapts to a numeric slot)

o  onNumberValue: aValueHolder printfFormat: formatString
create and return a typeConverter, which retrieves
a value's string representation via printf, and converts
a number-string by reading it as a number.
Useful as an editField's model, which operates on some
numeric value (or aspectAdaptor, which adapts to a numeric slot),
and you want to control the number of digits

o  onSymbolValue: aValueHolder
create and return a typeConverter, which retrieves
a symbol-values string representation via #value, and converts
a string to a symbol via #value:.
Useful as an editField's model, which operates on some
numeric value (or aspectAdaptor, which adapts to a numeric slot)

o  onTimeValue: aValueHolder
create and return a typeConverter, which retrieves
a time via #value, and converts
a time-string to a time via #value:.
Useful as an editField's model, which operates on some
date value (or aspectAdaptor, which adapts to a numeric slot)

queries
o  possiblePrintConverterTypes
presented in the typeConverter UI-builder menu

Instance protocol:

accessing
o  subject
return the subject to be converted

o  subject: newSubject
set the subject to be converted

o  value: newValue
convert and change

input testing
o  setNumberValue: value inModel: model fromInput: string
for invalid numbers, the model is set to nil.
By this, the dependents are forced to update their contents
(that is: a bad input string will lead to a cleared input field here).

standard converters-date & time
o  convertOldVWDateFormatSpecifierToNewSTXFormat: oldFormatSpec
private helper to convert an old (VW) format-Array
of the form:
'mm/dd/yyyy' (VW-backward compatibility)
into:
'%m %d %y' (new ST/X format)

o  date
setup the converter to convert from a string to a date
and vice versa. Nil is converted to todays date-string,
likewise, an empty string is converted back to todays date.

o  dateDDMMYYYY
setup the converter to convert from a string to a date formatted by printFormat
DD-MM-YYYY; see also Date>>printFormat:
This is a backward compatibility method for very old code to print european-style dates.
Please use dateWithFormat: which is much more flexible.

Usage example(s): 

     |vh|

     vh := Date today asValue.
     TypeConverter new
        dateDDMMYYYY
            model:vh;
            value.    
     vh value

Usage example(s): 

     |vh|

     vh := Date today asValue.
     TypeConverter new
        dateDDMMYYYY
            model:vh;
            value:'12-01-2008'.    
     vh value

o  dateMMDDYYYY
setup the converter to convert from a string to a date formatted by printFormat
MM/DD/YYYY; see also Date>>printFormat:
This is a backward compatibility method for very old code to print us-style dates.
Please use dateWithFormat: which is much more flexible.

Usage example(s): 

     |vh|

     vh := Date today asValue.
     TypeConverter new
        dateMMDDYYYY
            model:vh;
            value.    
     vh value

Usage example(s): 

     |vh|

     vh := Date today asValue.
     TypeConverter new
        dateMMDDYYYY
            model:vh;
            value:'01/12/2008'.    
     vh value

o  dateOrNil
setup the converter to convert from a string to a date
and vice versa. Invalid dates are converted to nil; likewise,
a nil date is converted to an empty string.

o  dateOrNilWithFormat: aFormatString
setup the converter to convert from a string to a date
and vice versa. Invalid dates are converted to nil; likewise,
a nil date is converted to an empty string.
The format string must have one of the forms:
'mm/dd/yyyy' (for VW-backward compatibility)
or:
'%m %d %y'

o  dateToText
setup the converter to convert from a string to a date
and vice versa. Nil is converted to todays date-string,
likewise, an empty string is converted back to todays date.

o  dateToTextFormattedBy: printFormat
setup the converter to convert from a string to a date formatted by printFormat
and vice versa. Nil is converted to todays date-string,
likewise, an empty string is converted back to todays date.
Uses the old, obsolete ST80 printFormat (see Date printFormat:)

o  dateWithFormat: aFormatString
setup the converter to convert from a string to a date
and vice versa. Invalid dates are converted to nil; likewise,
a nil date is converted to an empty string.
The format string must have one of the forms:
'mm/dd/yyyy' (for VW-backward compatibility)
or:
'%m %d %y'

see Date addPrintBindingsTo:language: for a format description.

Usage example(s): 

     |vh|

     vh := Date today asValue.
     (TypeConverter new
        dateWithFormat:'%m%d%y')
            model:vh;
            value.    
     vh value

o  dateWithFormat: aFormatString orDefault: defaultValue
setup the converter to convert from a string to a date and vice versa.
Invalid dates are converted to nil;
likewise, a nil date is converted to an empty string.
The format string must have one of the forms:
'mm/dd/yyyy' (for VW-backward compatibility)
or:
'%m %d %y'

see Date addPrintBindingsTo:language: for a format description.

o  dateWithFormat: aFormatString orDefault: defaultValue language: lang
setup the converter to convert from a string to a date and vice versa.
Invalid dates are converted to nil;
likewise, a nil date is converted to an empty string.
The format string must have one of the forms:
'mm/dd/yyyy' (for VW-backward compatibility)
or:
'%m %d %y'

see Date addPrintBindingsTo:language: for a format description.

o  dateYYYYMMDD
setup the converter to convert from a string to a date formatted by printFormat
MM/DD/YYYY; see also Date>>printFormat:
This is a backward compatibility method for very old code to print us-style dates.
Please use dateWithFormat: which is much more flexible.

Usage example(s): 

     |vh|

     vh := Date today asValue.
     TypeConverter new
        dateYYYYMMDD
            model:vh;
            value.    
     vh value

Usage example(s): 

     |vh|

     vh := Date today asValue.
     TypeConverter new
        dateYYYYMMDD
            model:vh;
            value:'2008-11-30'.    
     vh value

o  monthAndYear
setup the converter to convert from a string to a date
and vice versa. Invalid dates are converted to nil; likewise,
a nil date is converted to an empty string.
see Date addPrintBindingsTo:language: for a format description.

Usage example(s): 

     |vh|

     vh := Date today asValue.
     (TypeConverter new monthAndYear)
            model:vh;
            value.    
     vh value

o  printfWithFormat: aFormatString
setup the converter to convert from a string to a value by reading it as number
and generates a string via printf.
Typically used with numbers.
Invalid numbers are converted to nil;
likewise, a nil value is converted to an empty string.

o  printfWithFormat: aFormatString orDefault: defaultValue
setup the converter to convert from a string to a value by reading it as number
and generates a string via printf.
Invalid numbers are converted to defaultValue;
likewise, a nil value is converted to an empty string.

o  time

o  time12H
setup the converter to convert from a string to a time formatted by 12 hours
and vice versa.

o  time24H
setup the converter to convert from a string to a time formatted by 24 hours
and vice versa.

o  timeDuration
setup the converter to convert from a string to a timeduration and vice versa.

o  timeDurationOrNil
setup the converter to convert from a string to a timeDuration and vice versa.

o  timeOfClass: timeClass withFormat: aFormatString orDefault: defaultValue
setup the converter to convert from a string to a time and vice versa.
TimeClass is the class that should be used (e.g. Time or Timestamp).
Invalid times are converted to defaultValue; likewise,
a nil time is converted to an empty string.

o  timeOfClass: timeClass withFormat: aFormatString orDefault: defaultValue language: langOrNil
setup the converter to convert from a string to a time
and vice versa. TimeClass is the class that should be used (e.g. Time or Timestamp).
Invalid times are converted to defaultValue; likewise,
a nil time is converted to an empty string.

o  timeOrNil
setup the converter to convert from a string to a time and vice versa.

o  timeStampOrNil
setup the converter to convert from a string to a timeStamp and vice versa.

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

o  timeToText
setup the converter to convert from a string to a time
and vice versa.

o  timeToTextFormattedBy: format
setup the converter to convert from a string to a time formatted by format
and vice versa.

o  timestamp
setup the converter to convert from a string to a timestamp and vice versa.

o  timestampOrNil
setup the converter to convert from a string to a timestamp and vice versa.

o  year
setup the converter to convert from a string to a date
and vice versa. Invalid dates are converted to nil; likewise,
a nil date is converted to an empty string.
see Date addPrintBindingsTo:language: for a format description.

Usage example(s): 

     |vh|

     vh := Date today asValue.
     (TypeConverter new year)
            model:vh;
            value.    
     vh value

standard converters-misc
o  arrayLiteralOrStringOrSymbolOrNil
setup the converter to convert from a string to either a literal
Array, a String or a symbol and vice versa.
Invalid strings (i.e. empty) are converted to nil;
nil values are converted to an empty string.
This is a very special converter (for the GUI builder)
- probably not belonging to here

o  arrayLiteralOrSymbolOrNil
setup the converter to convert from a string to either a literal
Array or a symbol and vice versa.
Invalid strings (i.e. empty) are converted to nil;
nil values are converted to an empty string.
This is a very special converter (for the GUI builder)
- probably not belonging to here

o  fileSize
setup the converter to convert from a fileSize string to a number
and vice versa.
A fileSize can have a scale of 1000 (k or kB), 1024 (ki or kiB),
1000*1000 (m or mB), 1024*1024 (mi or miB), 1000*1000*1000 (g or gB), 1024*1024*1024 (gi or giB).

o  frequency
setup the converter to convert from a frequency string to a number
and vice versa.
A frequency can have a scale of 1000 (k or kHz),
1000*1000 (m or MHz), 1000*1000*1000 (g or GHz).

o  literal
setup the converter to convert from a string to a literal
and vice versa. Invalid symbols (i.e. empty) are converted to nil;
nil values are converted to an empty string.
true, false, Numbers are parsed

o  objectOrNilOfType: timeOrDateClass
common code for timeOrNil, dateOrNil and timeStampOrNil

o  smalltalkCorner
setup the converter to convert from a string to a point object
and vice versa. The string used is the point's storeString.
Invalid strings (i.e. empty) are converted to nil.

o  smalltalkExtent
setup the converter to convert from a string to a point object
and vice versa. The string used is the point's storeString.
Invalid strings (i.e. empty) are converted to nil.

o  smalltalkObject
setup the converter to convert from a string to any smalltalk object
and vice versa. The string used is the objects storeString.
Invalid strings (i.e. empty) are converted to nil.

o  smalltalkObjectOrNil
setup the converter to convert from a string to any smalltalk object
and vice versa. The string used is the objects storeString.
Invalid strings (i.e. empty) are converted to nil.

o  smalltalkObjectOrNilWithClass: classOfObject
setup the converter to convert from a string to a smalltalk object
and vice versa. The string used is the objects storeString.
Invalid strings (i.e. empty) are converted to nil.
This is a very special converter (for the GUI builder)
- probably not belonging to here

o  smalltalkObjectOrNilWithClass: classOfObject comment: commentString
setup the converter to convert from a string to a smalltalk object
and vice versa. The string used is the objects storeString.
Invalid strings (i.e. empty) are converted to nil.
This is a very special converter (for the GUI builder)
- probably not belonging to here

o  smalltalkObjectWithClass: classOfObject
setup the converter to convert from a string to a smalltalk object
and vice versa. The string used is the objects storeString.
Invalid strings (i.e. empty) are converted to nil.
This is a very special converter (for the GUI builder and ImageEditor)

o  smalltalkObjectWithClass: classOfObject comment: commentString
setup the converter to convert from a string to a smalltalk object
and vice versa. The string used is the objects storeString.
Invalid strings (i.e. empty) are converted to nil.
This is a very special converter (for the GUI builder and ImageEditor)

o  smalltalkOrigin
setup the converter to convert from a string to a point object
and vice versa. The string used is the point's storeString.
Invalid strings (i.e. empty) are converted to nil.

o  smalltalkPoint
setup the converter to convert from a string to a point object
and vice versa. The string used is the points storeString.
Invalid strings (i.e. empty) are converted to nil.
This is a very special converter (for the GUI builder)
- probably not belonging to here

o  symbolOrBooleanOrNil
setup the converter to convert from a string to a symbol or boolean
and vice versa. Invalid symbols (i.e. empty) are converted to nil;
nil values are converted to an empty string.
In addition, the strings true/false convert to/from booleans.

o  symbolOrNil
setup the converter to convert from a string to a symbol
and vice versa. Invalid symbols (i.e. empty) are converted to nil;
nil values are converted to an empty string.

o  symbolOrNumberOrNil
setup the converter to convert from a string to a symbol or number
and vice versa. Invalid symbols (i.e. empty) are converted to nil;
nil values are converted to an empty string.

standard converters-numbers
o  hexadecimal
setup the converter to convert from a hexadecimal string to a number
and vice versa.

o  integer
setup the converter to convert from a string to an integer
and vice versa. Invalid integers are converted to nil.

o  integerCStyle
setup the converter to convert from a string to an integer
and vice versa. Supports CStyle 0x/0b and 0 prefixes
Invalid integers are converted to nil.

o  integerOrNil
setup the converter to convert from a string to an integer
and vice versa. Invalid numbers are converted to nil.

o  integerOrNilToTextMinValue: minVal maxValue: maxVal format: formatStringOrNil
setup the converter to convert from a string to an integer or nil
and vice versa, but clamping the integer into the range.

o  integerToHexTextMinValue: minVal maxValue: maxVal format: formatStringOrNil
setup the converter to convert from a string to a number
and vice versa, but clamping the number into the range.

o  integerToText
setup the converter to convert from a string to a integer
and vice versa.

o  integerToTextCStyle
setup the converter to convert from a string to a integer
and vice versa. SUpports C-style integers in the form 0x, 0b 0
and also Smalltalk radix integers

o  integerToTextMinValue: minVal maxValue: maxVal format: formatStringOrNil
setup the converter to convert from a string to a number
and vice versa, but clamping the number into the range.

o  integerToTextMinValue: minVal maxValue: maxVal radix: base format: formatStringOrNil
setup the converter to convert from a string to a number
and vice versa, but clamping the number into the range.

o  integerToTextStrict: strict
setup the converter to convert from a string to a integer
and vice versa.
If strict, no other characters are allowed after the digits

o  integerWithThousandsSeparator

o  integerWithThousandsSeparator: sep
setup the converter to convert from a string to a number with thousands separator
and vice versa.

o  number
setup the converter to convert from a string to a number
and vice versa. Invalid numbers are converted to nil.

o  numberOrNil
setup the converter to convert from a string to a number
and vice versa. Invalid numbers are converted to nil.

o  numberOrNilToTextMinValue: minVal maxValue: maxVal
setup the converter to convert from a string to a number or nil
and vice versa, but clamping the number into the range.

o  numberOrNilToTextMinValue: minVal maxValue: maxVal format: formatStringOrNil
setup the converter to convert from a string to a number or nil
and vice versa, but clamping the number into the range.

o  numberOrPointOrNil
setup the converter to convert from a string to a number or point
and vice versa. Invalid numbers/points are converted to nil.

o  numberOrStringOrSymbolOrNil
setup the converter to convert from a string to either a numeric literal
or a symbol and vice versa.
Invalid strings (i.e. empty) are converted to nil;
nil values are converted to an empty string.
This is a very special converter (for the GUI builder)
- probably not belonging to here

o  numberOrSymbolOrNil
setup the converter to convert from a string to either a numeric literal
or a symbol and vice versa.
Invalid strings (i.e. empty) are converted to nil;
nil values are converted to an empty string.
This is a very special converter (for the GUI builder)
- probably not belonging to here

o  numberToText
setup the converter to convert from a string to a number
and vice versa.

o  numberToText: numberOfPostDecimals
setup the converter to convert from a string to a number
and vice versa.

o  numberToTextFormattedBy: formatString
setup the converter to convert from a string to a number
and vice versa, using formatString.
The formatString is currently ignored when numbers are converted
from a string.

o  numberToTextLeftPaddedTo: aSize with: aCharacter
setup the converter to convert from a string to a number
and vice versa, using formatString.
The formatString is currently ignored when numbers are converted
from a string.

o  numberToTextMinValue: minVal maxValue: maxVal
setup the converter to convert from a string to a number
and vice versa, but clamping the number into the range.

o  numberToTextMinValue: minVal maxValue: maxVal format: formatStringOrNil
setup the converter to convert from a string to a number
and vice versa, but clamping the number into the range.

o  numberWithOptionalScale
setup the converter to convert from a string to a number
and vice versa. Invalid numbers are converted to nil.
The number may be followed by one of m (for million) or
k (for thousand). E.g.: '1m2k55'

o  numberWithOptionalScales: scaleDict
setup the converter to convert from a string to a number or nil
and vice versa; allow for scale characters (such as k for thousand).

E.g. '1m2k55'

o  numberWithOptionalScales: scaleDict andThousandsSeparator: sep
setup the converter to convert from a string to a number with thousands separator
and vice versa. Allow for scale characters (such as k for thousand)

o  numberWithThousandsSeparator
^ self numberWithThousandsSeparator:$'

o  numberWithThousandsSeparator: sep
setup the converter to convert from a string to a number with thousands separator
and vice versa.

testing
o  isTypeConverter

Examples:


convert a number to a string: 
    |v t i|

    v := 1 asValue.

    t := HorizontalPanelView new.
    t extent:200@50.
    t horizontalLayout:#fitSpace.

    i := EditField in:t.
    i model:(TypeConverter onNumberValue:v).
    t open.

    (Delay forSeconds:3) wait.
    v value:2.
convert a number to a string with range: 
    |v t i|

    v := 1 asValue.

    t := HorizontalPanelView new.
    t extent:200@50.
    t horizontalLayout:#fitSpace.

    i := EditField in:t.
    i model:(TypeConverter onNumberValue:v minValue:0 maxValue:100).
    t open.

    (Delay forSeconds:3) wait.
    v value:2.
convert a number to a string with printf: 
    |v t i|

    v := 1 asValue.

    t := HorizontalPanelView new.
    t extent:200@50.
    t horizontalLayout:#fitSpace.

    i := EditField in:t.
    i model:(TypeConverter onNumberValue:v printfFormat:'%5.3f').
    t open.

    (Delay forSeconds:3) wait.
    v value:2.
convert a date to a string: 
    |d v|

    v := nil asValue.

    d := DialogBox new.
    d addInputFieldOn:(TypeConverter onDateValue:v).
    d addOkButton.
    d open.
    d accepted ifTrue:[
        Transcript showCR:v value
    ]
convert with thousands: 
    |d v|

    v := 1234567 asValue.

    d := DialogBox new.
    d addInputFieldOn:((TypeConverter on:v) integerWithThousandsSeparator:$').
    d addOkButton.
    d open.
    d accepted ifTrue:[
        Transcript showCR:v value
    ]
convert with scale character: 
    |d v|

    v := 1234567 asValue.

    d := DialogBox new.
    d addInputFieldOn:((TypeConverter on:v) numberWithOptionalScale).
    d addOkButton.
    d open.
    d accepted ifTrue:[
        Transcript showCR:v value
    ]
convert with scale character and thousands separator: 
    |d v scaleDict|

    scaleDict := Dictionary new.
    scaleDict at:$t put:1000.
    scaleDict at:$k put:1000.
    scaleDict at:$m put:1000000.

    v := 1234567 asValue.

    d := DialogBox new.
    d addInputFieldOn:((TypeConverter on:v) 
                        numberWithOptionalScales:scaleDict 
                        andThousandsSeparator:$').
    d addOkButton.
    d open.
    d accepted ifTrue:[
        Transcript showCR:v value
    ]

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 23 Nov 2024 23:15:09 GMT