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