home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Extra 1997 #2 / Amiga Plus Extra 1997 #2.iso / system / mui / developer / autodocs / mui_numeric.doc < prev    next >
Encoding:
Text File  |  1997-02-16  |  12.7 KB  |  405 lines
  1. TABLE OF CONTENTS
  2.  
  3. Numeric.mui/Numeric.mui
  4. Numeric.mui/MUIA_Numeric_Default
  5. Numeric.mui/MUIA_Numeric_Format
  6. Numeric.mui/MUIA_Numeric_Max
  7. Numeric.mui/MUIA_Numeric_Min
  8. Numeric.mui/MUIA_Numeric_Reverse
  9. Numeric.mui/MUIA_Numeric_RevLeftRight
  10. Numeric.mui/MUIA_Numeric_RevUpDown
  11. Numeric.mui/MUIA_Numeric_Value
  12. Numeric.mui/MUIM_Numeric_Decrease
  13. Numeric.mui/MUIM_Numeric_Increase
  14. Numeric.mui/MUIM_Numeric_ScaleToValue
  15. Numeric.mui/MUIM_Numeric_SetDefault
  16. Numeric.mui/MUIM_Numeric_Stringify
  17. Numeric.mui/MUIM_Numeric_ValueToScale
  18. Numeric.mui/Numeric.mui
  19.  
  20.     Numeric class is the base class for everything that
  21.     deals with the input (and display) of integer numbers.
  22.     Numeric class itself does not feature any GUI elements, it
  23.     just offers some basic attributes and methods which are
  24.     common to all types of sliders. Creating direct instances
  25.     of this class usually doesn't make any sense. Instead, use
  26.     one of the included subclasses like Slider.mui,
  27.     Numericbutton.mui or Knob.mui to select the type of gadget
  28.     you need.
  29.  
  30.     Numeric class and the supplied subclasses communicate with a
  31.     set of methods. By writing subclasses which override some of
  32.     them, you can change the behaviour of all sliders to fit
  33.     your requirements. You could e.g. enhance the builtin value
  34.     formatting code which is limited to simple printf-style
  35.     strings by replacing the MUIM_Numeric_Stringify method with
  36.     something more complicated. Or you turn your sliders to
  37.     logarythmic scales by replacing MUIM_Numeric_ValueToScale
  38.     and MUIM_Numeric_ScaleToValue.
  39.  
  40.     Imagine you would like a slider which doesn't only display a
  41.     users age but also makes comments depending on the current
  42.     value, e.g. "13 years (Teenie)" ... "25 years (Twen)" ...
  43.     All you have to do is to write a subclass of any of MUI's
  44.     builtin slider types which does nothing but replace
  45.     MUIM_Numeric_Stringify with your code. See the supplied 
  46.     "Slidorama" demo program to see how this might work.
  47.  
  48.     MUI features several different subclasses of Numeric.mui:
  49.     Slider.mui creates an ordinary slider like the ones of
  50.     previous MUI releases. Numericbutton.mui creates a
  51.     space-saving slider, only the value is shown in the user
  52.     interface as kind of a button. When the user clicks on this
  53.     button, a slider pops up to adjust the value. Knob.mui
  54.     displays a very nice designed turning wheel but also offers
  55.     popup possibilities for those who don't like turning a knob
  56.     with the mouse. "Slidorama" demo shows everything that
  57.     is available.
  58.  
  59.     All slider gadgets offer configuration options and make it
  60.     easy for the user to enable things he likes and disable
  61.     things he dislikes. However, it's your choice to decide 
  62.     which basic type of gadget shall be used.
  63.  
  64.     If really none of the supplied subclasses of Numeric.mui
  65.     suits your requirements, you may of course write custom
  66.     classes for numeric data input. If you use Numeric.mui as
  67.     base class, you won't need to think about the basic stuff
  68.     like min and max values and formatting.
  69.  
  70.     Keyboard control (TAB, cursor keys, MUIA_ControlChar) is
  71.     handled my Numeric.mui automatically, subclasses will not
  72.     have to care about it.
  73. Numeric.mui/MUIA_Numeric_Default
  74.  
  75.     NAME
  76.     MUIA_Numeric_Default -- (V11) [ISG], LONG
  77.  
  78.     FUNCTION
  79.     Adjust the default value for a numeric input/display gadget.
  80.     When the object receives a MUIM_Numeric_SetDefault method,
  81.     it sets its value to the one given here.
  82.  
  83.     Each type of slider can have a default value to which the
  84.     user can always return immediately by some action depending
  85.     on the implementation of the subclass. Knob.mui e.g. resets
  86.     to defaults after a double click in the knob area.
  87.  
  88.     The default value can also be reached by pressing the
  89.     toggle key (usually SPACE) on an active numeric gadget.
  90.  
  91.     MUIA_Numeric_Default defaults to 0.
  92.  
  93.     SEE ALSO
  94.     MUIA_Numeric_Max, MUIA_Numeric_Value, MUIA_Numeric_Min,
  95.     MUIM_Numeric_SetDefault
  96. Numeric.mui/MUIA_Numeric_Format
  97.  
  98.     NAME
  99.     MUIA_Numeric_Format -- (V11) [ISG], STRPTR
  100.  
  101.     FUNCTION
  102.     printf-style string to describe the format of the slider
  103.     display.
  104.  
  105.     Whenever a subclass of Numeric.mui thinks its time to render
  106.     a new value, it doesn't simply write it to a string but
  107.     instead calls MUIM_Numeric_Stringify. This method of Numeric
  108.     class looks for the specified MUIA_Numeric_Format in its data
  109.     structures and fills a string with the current value.
  110.     In detail, things work like his:
  111.  
  112.     - Some slider object (e.g. a knob) receives a MUIM_Draw method.
  113.     - The MUIM_Draw implementation of the knob object reads
  114.       the current value of the Numeric class and calls
  115.       MUIM_Numeric_Stringify with this valuse.
  116.     - MUIM_Numeric_Stringify of numeric class reads the current
  117.       format and sprintf()s the given value to a buffer. The
  118.       buffer is returned the caller.
  119.     - After all this stuff, the MUIM_Draw implementation
  120.       receives a nice string as result code and finally puts
  121.       it somewhere into the window.
  122.  
  123.     All this method stuff might sound a bit crazy, but in fact its
  124.     quite powerful. If you write a subclass of any of MUI's slider
  125.     classes which simply replaces MUIM_Numeric_Stringify with
  126.     your own code, you can create any string you like for display
  127.     in these sliders. You might e.g. want to display a nice formatted
  128.     time string (hh:mm:ss) in a slider knob which adjusts a number
  129.     of seconds. Or you need to adjust a baudrate from a hand of
  130.     predefined values. Just overrided MUIM_Numeric_Stringify and
  131.     you have the choice how the slider value translates into
  132.     a string.
  133.  
  134.     If you dont override MUIM_Numeric_Stringify, the method
  135.     reaches Numeric class which simply does a sprintf() with
  136.     the defined MUIA_Numeric_Format.
  137.  
  138.     Note well: The maximum length of the result string for
  139.     MUIA_Numeric_Format is limited to 32 characters. If you
  140.     need more, you *must* override the method.
  141.  
  142.     MUIA_Numeric_Format defaults to "%ld".
  143.  
  144.     SEE ALSO
  145.     MUIA_Numeric_Max, MUIA_Numeric_Value, MUIA_Numeric_Min,
  146.     MUIM_Numeric_Stringify, MUIM_Numeric_StringifyValue
  147. Numeric.mui/MUIA_Numeric_Max
  148.  
  149.     NAME
  150.     MUIA_Numeric_Max -- (V11) [ISG], LONG
  151.  
  152.     FUNCTION
  153.     Adjust the maximum value for a numeric input/display
  154.     gadget.
  155.  
  156.     Numeric class will automatically clip its value to make
  157.     it fit between MUIA_Numeric_Min and MUI_Numeric_Max. Also,
  158.     minimum and maximum values are used for several internal
  159.     calculations such as the maximum space required to display
  160.     a numeric value.
  161.  
  162.     You may change MUIA_Numeric_Min and MUIA_Numeric_Max with
  163.     SetAttrs(), but current MUI versions will *not* update
  164.     the objects and with the windows width or height if your
  165.     change causes the value display to change it's minimum
  166.     and/or maximum pixel sizes. The slider position itself 
  167.     will be updated though.
  168.  
  169.     MUI treats all values in numeric class as signed
  170.     longwords, so that's the limit for all tags.
  171.  
  172.     MUIA_Numeric_Max defaults to 100.
  173.  
  174.     NOTES
  175.     This attribute replaces the MUIA_Slider_Max tag of
  176.     previous MUI releases. For compatibility reasons,
  177.     both have the same hex value. Nevertheless, always
  178.     use MUIA_Numeric_Max in new code.
  179.  
  180.     SEE ALSO
  181.     MUIA_Numeric_Min, MUIA_Numeric_Value, MUIA_Numeric_Default,
  182.     MUIM_Numeric_GetPixelSize, MUIM_Numeric_ValueToScale,
  183.     MUIM_Numeric_ScaleToValue
  184. Numeric.mui/MUIA_Numeric_Min
  185.  
  186.     NAME
  187.     MUIA_Numeric_Min -- (V11) [ISG], LONG
  188.  
  189.     FUNCTION
  190.     Adjust the minimum value for a numeric input/display
  191.     gadget.
  192.  
  193.     Numeric class will automatically clip its value to make
  194.     it fit between MUIA_Numeric_Min and MUI_Numeric_Max. Also,
  195.     minimum and maximum values are used for several internal
  196.     calculations such as the maximum space required to display
  197.     a numeric value.
  198.  
  199.     You may change MUIA_Numeric_Min and MUIA_Numeric_Max with
  200.     SetAttrs(), but current MUI versions will *not* update
  201.     the objects and with the windows width or height if your
  202.     change causes the value display to change it's minimum 
  203.     and/or maximum pixel sizes. The slider position itself 
  204.     will be updated though.
  205.  
  206.     MUI treats all values in numeric class as signed
  207.     longwords, so that's the limit for all tags.
  208.  
  209.     MUIA_Numeric_Min defaults to 0.
  210.  
  211.     NOTES
  212.     This attribute replaces the MUIA_Slider_Min tag of
  213.     previous MUI releases. For compatibility reasons,
  214.     both have the same hex value. Nevertheless, always
  215.     use MUIA_Numeric_Min in new code.
  216.  
  217.     SEE ALSO
  218.     MUIA_Numeric_Max, MUIA_Numeric_Value, MUIA_Numeric_Default,
  219.     MUIM_Numeric_GetPixelSize, MUIM_Numeric_ValueToScale,
  220.     MUIM_Numeric_ScaleToValue
  221. Numeric.mui/MUIA_Numeric_Reverse
  222.  
  223.     NAME
  224.     MUIA_Numeric_Reverse -- (V11) [ISG], BOOL
  225.  
  226.     FUNCTION
  227.     Reverse the display of a numeric gadget.
  228.  
  229.     When set to TRUE, the MUIM_Numeric_ScaleToValue
  230.     and MUIM_Numeric_ValueToScale methods are effected
  231.     in a way that makes your gadget behave "reverse".
  232.     Its minimum numeric value will be mapped to the
  233.     maximum scale value of the display and vice versa.
  234.  
  235.     MUIA_Numeric_Reverse defaults to FALSE.
  236.  
  237.     NOTES
  238.     This attribute replaces the MUIA_Slider_Reverse tag
  239.     of previous MUI releases. For compatibility reasons,
  240.     both have the same hex value. Nevertheless, always
  241.     use MUIA_Numeric_Reverse in new code.
  242.  
  243.     SEE ALSO
  244.     MUIA_Numeric_Max, MUIA_Numeric_Value, MUIA_Numeric_Default,
  245.     MUIM_Numeric_ValueToScale, MUIM_Numeric_ScaleToValue
  246. Numeric.mui/MUIA_Numeric_RevLeftRight
  247.  
  248.     NAME
  249.     MUIA_Numeric_RevLeftRight -- (V11) [ISG], BOOL
  250.  
  251.     FUNCTION
  252.     Reverse the function of left/right keys.
  253.  
  254.     Under some circumstances it might be desirable to
  255.     reverse the keyboard control for a slider gadget.
  256.     This tag might help.
  257.  
  258.     MUIA_Numeric_RevLeftRight defaults to FALSE.
  259.  
  260.     SEE ALSO
  261.     MUIA_Numeric_Max, MUIA_Numeric_Value, MUIA_Numeric_Default,
  262.     MUIA_Numeric_Reverse, MUIA_Numeric_RevUpDown
  263. Numeric.mui/MUIA_Numeric_RevUpDown
  264.  
  265.     NAME
  266.     MUIA_Numeric_RevUpDown -- (V11) [ISG], BOOL
  267.  
  268.     FUNCTION
  269.     Reverse the function of up/down keys.
  270.  
  271.     Under some circumstances it might be desirable to
  272.     reverse the keyboard control for a slider gadget.
  273.     This tag might help.
  274.  
  275.     MUIA_Numeric_RevUpDown defaults to FALSE.
  276.  
  277.     SEE ALSO
  278.     MUIA_Numeric_Max, MUIA_Numeric_Value, MUIA_Numeric_Default,
  279.     MUIA_Numeric_Reverse, MUIA_Numeric_RevUpDown
  280. Numeric.mui/MUIA_Numeric_Value
  281.  
  282.     NAME
  283.     MUIA_Numeric_Value -- (V11) [ISG], LONG
  284.  
  285.     FUNCTION
  286.     Adjust the current value for a numeric input/display
  287.     gadget. Numeric class will automatically clip this
  288.     value to make it fit between MUIA_Numeric_Min and
  289.     MUI_Numeric_Max.
  290.  
  291.     Whenever a new value is set, the object receices a
  292.     new MUIM_Draw method to get a chance to update its
  293.     display.
  294.  
  295.     MUIA_Numeric_Default defaults to 0.
  296.  
  297.     NOTES
  298.     This attribute replaces the MUIA_Slider_Level tag of
  299.     previous MUI releases. For compatibility reasons,
  300.     both have the same hex value. Nevertheless, always
  301.     use MUIA_Numeric_Value in new code.
  302.  
  303.     SEE ALSO
  304.     MUIA_Numeric_Min, MUIA_Numeric_Max, MUIA_Numeric_Default,
  305.     MUIM_Numeric_Stringify
  306. Numeric.mui/MUIM_Numeric_Decrease
  307.  
  308.     NAME
  309.     MUIM_Numeric_Decrease (V11)
  310.  
  311.     SYNOPSIS
  312.     DoMethod(obj,MUIM_Numeric_Decrease,LONG amount);
  313.  
  314.     FUNCTION
  315.     Decrease the value of a numeric class object.
  316.  
  317.     SEE ALSO
  318.     MUIM_Numeric_Increase, MUIA_Numeric_Value
  319. Numeric.mui/MUIM_Numeric_Increase
  320.  
  321.     NAME
  322.     MUIM_Numeric_Increase (V11)
  323.  
  324.     SYNOPSIS
  325.     DoMethod(obj,MUIM_Numeric_Increase,LONG amount);
  326.  
  327.     FUNCTION
  328.     Increase the value of a numeric class object.
  329.  
  330.     SEE ALSO
  331.     MUIM_Numeric_Decrease, MUIA_Numeric_Value
  332. Numeric.mui/MUIM_Numeric_ScaleToValue
  333.  
  334.     NAME
  335.     MUIM_Numeric_ScaleToValue (V11)
  336.  
  337.     SYNOPSIS
  338.     DoMethod(obj,MUIM_Numeric_ScaleToValue,LONG scalemin, LONG scalemax, LONG scale);
  339.  
  340.     FUNCTION
  341.     This method takes the given sale values and transforms them to
  342.     something between the numeric objects min and max values.
  343.  
  344.     RESULT
  345.     The transformed value.
  346. Numeric.mui/MUIM_Numeric_SetDefault
  347.  
  348.     NAME
  349.     MUIM_Numeric_SetDefault (V11)
  350.  
  351.     SYNOPSIS
  352.     DoMethod(obj,MUIM_Numeric_SetDefault,);
  353.  
  354.     FUNCTION
  355.     This method does nothing but reset the value to its
  356.     default. Defaults can be adjusted through
  357.     MUIA_Numeric_Default.
  358.  
  359.     Only implementors of custom slider classes will need
  360.     this method. Sending it from applications doesnt make
  361.     any sense.
  362.  
  363.     SEE ALSO
  364.     MUIA_Numeric_Value, MUIA_Numeric_Default
  365. Numeric.mui/MUIM_Numeric_Stringify
  366.  
  367.     NAME
  368.     MUIM_Numeric_Stringify (V11)
  369.  
  370.     SYNOPSIS
  371.     DoMethod(obj,MUIM_Numeric_Stringify,LONG value);
  372.  
  373.     FUNCTION
  374.     Call this method in your subclass whenever you want to
  375.     translate a value into a string. A pointer to a
  376.     string buffer is returned.
  377.  
  378.     Only implementors of custom slider classes will need
  379.     this method. Sending it from applications doesnt make
  380.     any sense.
  381.  
  382.     EXAMPLE
  383.     ... somewhere in your Draw method ...
  384.  
  385.     get(obj,MUIA_Numeric_Value,&val);
  386.     buf = DoMethod(obj,MUIM_Numeric_Stringify,val);
  387.     Text(rp,buf,strlen(buf));
  388.  
  389.     SEE ALSO
  390.     MUIA_Numeric_Value, MUIA_Numeric_Format
  391. Numeric.mui/MUIM_Numeric_ValueToScale
  392.  
  393.     NAME
  394.     MUIM_Numeric_ValueToScale (V11)
  395.  
  396.     SYNOPSIS
  397.     DoMethod(obj,MUIM_Numeric_ValueToScale,LONG scalemin, LONG scalemax);
  398.  
  399.     FUNCTION
  400.     This method takes the current value of the numeric object and
  401.     transforms it to another scale determined by the parameters.
  402.  
  403.     RESULT
  404.     The transformed value.
  405.