home *** CD-ROM | disk | FTP | other *** search
/ Aminet 18 / aminetcdnumber181997.iso / Aminet / dev / gui / gauge.lha / gauge.doc < prev    next >
Encoding:
Text File  |  1997-01-26  |  11.4 KB  |  353 lines
  1. TABLE OF CONTENTS
  2.  
  3. gauge/--background--
  4. gauge/DisposeGauge
  5. gauge/GetGaugeA
  6. gauge/NewGaugeA
  7. gauge/SetGaugeA
  8. gauge/--background--                                     gauge/--background--
  9.  
  10.    PURPOSE
  11.     The "Amiga User Interface Style Guide" contains an example of how
  12.     a progress requester should look like (page 29), but this example
  13.     has no "teeth". It is just a visual cue, you still have to implement
  14.     the requester yourself. Around Christmas Day, the issue was brought
  15.     up in comp.sys.amiga.programmer how to program these progress
  16.     requesters. This is my attempt at solving the problem.
  17.  
  18.    GOALS
  19.     - The progress requester should be entirely self-contained and
  20.       reentrant.
  21.     - It should be simple to find out if the user has hit the
  22.       "Stop" button.
  23.     - Creation and management of the requester should follow a
  24.       familiar model.
  25.     - The display should be font sensitive.
  26.  
  27.    IMPLEMENTATION
  28.     The implementation consists of a set of BOOPSI objects, which are
  29.     linked together, plus a display element for the gauge. This is
  30.     similar to how Intuition builds system requesters and has the
  31.     advantage of delegating the work load of refreshing and maintaining
  32.     the display to Intuition. The application to create the display
  33.     just has to listen for the user to hit the "Stop" button, it need
  34.     not worry about housekeeping work.
  35.  
  36.     The gauge creation code is reentrant, it was written with SAS/C
  37.     in mind. The only compiler dependant part is the custom class
  38.     dispatcher. You must initialize IntuitionBase, GfxBase,
  39.     UtilityBase and SysBase for the gauge code to work.
  40.  
  41.    COPYRIGHT AND USAGE RESTRICTIONS
  42.     This implementation is Copyright © 1997 by Olaf `Olsen' Barthel.
  43.     It is freely distributable. I place no restrictions on its usage.
  44.     You may use this code in commercial software or shareware programs
  45.     without having to pay royalties to me. An acknowledgement would
  46.     still be nice, though :^) If you find bugs in the code or make
  47.     enhancements, please notify me. I would like to keep this code
  48.     updated, so everyone will be able to take advantage of it.
  49.  
  50.     My electronic mail address:
  51.  
  52.         olsen@sourcery.han.de
  53.  
  54.     My postal address:
  55.  
  56.         Olaf Barthel
  57.         Brabeckstrasse 35
  58.         D-30559 Hannover
  59.         Federal Republic of Germany
  60.  
  61. gauge/DisposeGauge                                         gauge/DisposeGauge
  62.  
  63.    NAME
  64.     DisposeGauge -- Close a progress requester Window.
  65.  
  66.    SYNOPSIS
  67.     DisposeGauge(Gauge)
  68.  
  69.     VOID DisposeGauge(struct Gauge *);
  70.  
  71.    FUNCTION
  72.     When you are finished with the work the progress gauge represents,
  73.     you should close the gauge Window. This routine will close the
  74.     display opened by NewGaugeA().
  75.  
  76.    INPUTS
  77.     Gauge - Pointer to a Gauge structure as created by NewGaugeA().
  78.         NULL is a valid parameter.
  79.  
  80.    EXAMPLE
  81.     /* Close the gauge display */
  82.  
  83.     DisposeGauge(gauge);
  84.  
  85.    SEE ALSO
  86.     NewGaugeA
  87.  
  88. gauge/GetGaugeA                                               gauge/GetGaugeA
  89.  
  90.    NAME
  91.     GetGaugeA -- Obtain information about the gauge display.
  92.  
  93.    SYNOPSIS
  94.     Attributes = GetGaugeA(Gauge,TagList)
  95.  
  96.     LONG GetGaugeA(struct Gauge *,struct TagItem *);
  97.  
  98.     Attributes = GetGauge(Gauge,Tags);
  99.  
  100.     LONG GetGauge(struct Gauge *,...);
  101.  
  102.    FUNCTION
  103.     The Gauge structure is meant to be opaque, you should not peek
  104.     inside to find the information you need, such as the pointer
  105.     to the Window the display is built on top of. Rather, use this
  106.     routine to find out about it. This routine also provides means
  107.     to find out if a user has hit the "Stop" button.
  108.  
  109.    INPUTS
  110.     Gauge - Pointer to a Gauge structure as created by NewGaugeA().
  111.         NULL is a valid parameter.
  112.  
  113.     TagList - Pointer to a table of TagItem structures.
  114.         NULL is a valid parameter.
  115.  
  116.     If you provide a tag list, the following item types are valid:
  117.  
  118.     GAUGE_MsgPort (struct MsgPort *) - Pointer to the port IntuiMessages
  119.         arrive at the gauge Window.
  120.  
  121.     GAUGE_Window (struct Window *) - Pointer to the Window the progress
  122.         requester is built on top of. If the gauge display is using a shared
  123.         message arrival port, you can use the Window pointer to find out if
  124.         an input event was meant for the gauge display rather than a different
  125.         Window.
  126.  
  127.     GAUGE_Hit (LONG) - If the user hit the "Stop" button, this routine will
  128.         return TRUE, FALSE otherwise.
  129.  
  130.     GAUGE_SigBit (LONG) - Provides the signal bit of the message arrival
  131.         port the gauge Window uses.
  132.  
  133.    RESULT
  134.     Attributes - Number of attributes this function could provide
  135.         information on.
  136.  
  137.    EXAMPLE
  138.     /* Find out whether the user has hit the "Stop" button. */
  139.  
  140.     LONG stop;
  141.  
  142.     if(GetGauge(gauge,
  143.         GAUGE_Hit,&stop,
  144.     TAG_END) == 1)
  145.     {
  146.         if(stop)
  147.             printf("user wants to stop the work in progress.\n");
  148.         else
  149.             printf("the work in progress can continue.\n");
  150.     }
  151.     else
  152.     {
  153.         printf("something is wrong.\n");
  154.     }
  155.  
  156.    NOTES
  157.     If this function returns a number smaller than the actual number
  158.     of attributes you inquired about, some of the variables you have
  159.     provided will not be initialized.
  160.  
  161.    SEE ALSO
  162.     NewGaugeA
  163.     gadtools.library/GT_GetGadgetAttrs
  164.  
  165. gauge/NewGaugeA                                               gauge/NewGaugeA
  166.  
  167.    NAME
  168.     NewGaugeA -- Create a progress gauge display requester
  169.  
  170.    SYNOPSIS
  171.     Gauge = NewGaugeA(TagList)
  172.  
  173.     struct Gauge *NewGaugeA(struct TagItem *);
  174.  
  175.     Gauge = NewGauge(Tags);
  176.  
  177.     struct Gauge *NewGauge(Tag firstTag,...);
  178.  
  179.    FUNCTION
  180.     The "Amiga User Interface Style Guide" gives an example of how a
  181.     progress requester should look like (page 29). This example
  182.     lacks "teeth" as it just represents a visual cue, not something
  183.     you can work with--until you implement it. NewGaugeA() will create
  184.     such a progress requester.
  185.  
  186.    INPUTS
  187.     You control the initial attributes of the gauge display with
  188.     tagitems:
  189.  
  190.     GAUGE_Window (struct Window *) - The parent Window to "attach"
  191.         the gauge to. The gauge display will appear on the same Screen
  192.         as the parent Window, centred within the bounds of the Window.
  193.         These are the only relations to the "parent" Window.
  194.  
  195.     GAUGE_Screen (struct Screen *) - The Screen to open the gauge on.
  196.         The gauge will appear centred within the visible part of
  197.         this Screen.
  198.  
  199.     GAUGE_PubScreen (struct Screen *) - Pointer to a Public Screen the
  200.         gauge display should be opened on as a Visitor Window. The gauge
  201.         will appear centred within the visible part of this Screen.
  202.  
  203.     GAUGE_PubScreenName (STRPTR) - Name of a Public Screen the gauge
  204.         display should be opened on as a Visitor Window. If the named
  205.         Screen cannot be found, the display will default to open on the
  206.         Default Public Screen. You can control the fall-back behaviour
  207.         with the GAUGE_PubScreenFallback tag.
  208.  
  209.     GAUGE_PubScreenFallback (BOOL) - If the named Public Screen the
  210.         display is to open on cannot be found, the gauge display will
  211.         default to open on the Default Public Screen. In most cases,
  212.         this will be the Workbench Screen. This tag controls whether
  213.         the fall-back will take place or whether the display will fail
  214.         to open.
  215.         (Default: TRUE)
  216.  
  217.     GAUGE_UserPort (struct MsgPort *) - You can have multiple Windows
  218.         sharing the IntuiMessage arrival MsgPort. If you with to share
  219.         some other Window's arrival port with the gauge display, you
  220.         can specify the port address with this tag.
  221.  
  222.     GAUGE_ButtonLabel (STRPTR) - There is one single button in the
  223.         gauge display, which when hit by the user indicates that
  224.         whatever action in progress the gauge represents should be
  225.         brought to a stop. By default, this button bears the label
  226.         "Stop". You can provide a replacement label, such as for
  227.         localization, using this tag.
  228.         (Default: "Stop")
  229.  
  230.     GAUGE_Title (STRPTR) - The gauge display bears a title which tells
  231.         about the action in progress the display indicates. This title
  232.         will be eventually be the title of the progress Window. Steps
  233.         will be taken to make the progress gauge Window large enough to
  234.         show the complete title.
  235.         (Default: "")
  236.  
  237.     GAUGE_Fill (LONG) - Progress is shown with a bar that grows from
  238.         left to right. You specify how far the bar should grow with this
  239.         tags in percentage, i.e. a value of 0 will show no bar, 50 will
  240.         show a bar that covers half its maximum size and 100 will produce
  241.         the complete bar. Any values outside this range will be truncated
  242.         to the range.
  243.         (Default: 0)
  244.  
  245.    RESULT
  246.     Gauge - Pointer to a Gauge structure that represents the progress
  247.         requester Window and its contents. You should not peek the data
  248.         this structure holds, but use the GetGaugeA() function instead.
  249.         If NewGaugeA() cannot create the progress display, it will return
  250.         NULL.
  251.  
  252.    EXAMPLE
  253.     /* Create the progress report Window and wait for the user to
  254.      * hit the "Stop" button. Make it look like the example in
  255.      * the "Amiga User Interface Style Guide".
  256.      */
  257.  
  258.     struct Gauge *gauge;
  259.     struct MsgPort *port;
  260.  
  261.     gauge = NewGauge(
  262.         GAUGE_Title, "Rendering \"Boing.Ball\"",
  263.         GAUGE_Fill,  40,
  264.     TAG_END);
  265.  
  266.     if(gauge != NULL)
  267.     {
  268.         GetGauge(&gauge,
  269.             GAUGE_MsgPort,&port,
  270.         TAG_END);
  271.  
  272.         WaitPort(port);
  273.  
  274.         DisposeGauge(gauge);
  275.     }
  276.  
  277.    NOTES
  278.     Unless you provide a MsgPort to be used as the IntuiMessage
  279.     arrival port, this function will create one for you. To find
  280.     out about this port, use GetGaugeA().
  281.  
  282.     If this function is not told about the Screen it should open
  283.     the progress requester Window on, it will default to opening
  284.     the Window on the Default Public Screen. Usually, this will
  285.     be the Workbench Screen.
  286.  
  287.     The gauge Window contains one single button the user can
  288.     hit if the action the requester represents should be aborted.
  289.     In this event, an IDCMP_GADGETUP message will be generated.
  290.     This is the *only* type of event the gauge Window can generate.
  291.     Thus, when you receive any kind of input from this Window you
  292.     can be certain that the user wants to stop the work in progress.
  293.  
  294.    SEE ALSO
  295.     intuition.library/OpenWindow
  296.     intuition.library/OpenWindowTagList
  297.  
  298. gauge/SetGaugeA                                               gauge/SetGaugeA
  299.  
  300.    NAME
  301.     SetGaugeA -- Change the title or the position of the
  302.         progress indicator of the gauge display.
  303.  
  304.    SYNOPSIS
  305.     SetGaugeA(Gauge,TagList)
  306.  
  307.     VOID SetGaugeA(struct Gauge *Gauge,struct TagItem *);
  308.  
  309.     SetGauge(Gauge,Tags);
  310.  
  311.     VOID SetGauge(struct Gauge *,...);
  312.  
  313.    FUNCTION
  314.     After you have opened the progress requester display, you
  315.     will want to change the indicator that shows how far the
  316.     work the requester represents has progressed. Occasionally,
  317.     the requester title may need changing, too, as work progresses
  318.     into a different phase.
  319.  
  320.    INPUTS
  321.     Gauge - Pointer to a Gauge structure as created by NewGaugeA().
  322.         NULL is a valid parameter.
  323.  
  324.     TagList - Pointer to a table of TagItem structures.
  325.         NULL is a valid parameter.
  326.  
  327.     If you provide a tag list, the following item types are valid:
  328.  
  329.     GAUGE_Title (STRPTR) - The gauge display bears a title which tells
  330.         about the action in progress the display indicates. This title
  331.         will be eventually be the title of the progress Window. Steps
  332.         will be taken to make the progress gauge Window large enough to
  333.         show the complete title.
  334.  
  335.     GAUGE_Fill (LONG) - Progress is shown with a bar that grows from
  336.         left to right. You specify how far the bar should grow with this
  337.         tags in percentage, i.e. a value of 0 will show no bar, 50 will
  338.         show a bar that covers half its maximum size and 100 will produce
  339.         the complete bar. Any values outside this range will be truncated
  340.         to the range.
  341.  
  342.    EXAMPLE
  343.     /* Set the fill indicator to 70% */
  344.  
  345.     SetGauge(gauge,
  346.         GAUGE_Fill, 70,
  347.     TAG_END);
  348.  
  349.    SEE ALSO
  350.     NewGaugeA
  351.     intuition.library/SetAttrsA
  352.  
  353.