home *** CD-ROM | disk | FTP | other *** search
/ Aminet 18 / aminetcdnumber181997.iso / Aminet / dev / misc / prog_bar.lha / prog_bar / Docs / prog_bar.doc < prev    next >
Encoding:
Text File  |  1997-01-12  |  12.6 KB  |  410 lines
  1. Prog_Bar v1.1 Function List
  2. ===========================
  3.  
  4.     CreateProgBarA()
  5.     CreateProgBar()
  6.     SetProgBarAttrsA()
  7.     SetProgBarAttrs()
  8.     FreeProgBar()
  9.     RefreshProgBar()
  10.     UpdateProgBar()
  11.     ResetProgBar()
  12.     ClearProgBar()
  13.     ClearBar()
  14.     ClearText()
  15.  
  16.  
  17.  
  18. CreateProgBarA() / CreateProgBar()
  19. ----------------------------------
  20.  
  21. NAME
  22.         CreateProgBarA -- Allocates and initialises a progress bar.  (V1.0)
  23.         CreateProgBar -- Varargs stub for CreateProgBarA().  (V1.0)
  24.  
  25. SYNOPSIS
  26.         bar = CreateProgBarA ( Wnd, Left, Top, Width, Height, Size,
  27.                                taglist )
  28.  
  29.         PBAR *CreateProgBarA ( struct Window *, UWORD, UWORD, UWORD, UWORD,
  30.                                UWORD, struct TagList * )
  31.  
  32.         bar = CreateProgBar ( Wnd, Left, Top, Width, Height, Size,
  33.                               First_Tag, ... )
  34.  
  35.         PBAR *CreateProgBar ( struct Window *, UWORD, UWORD, UWORD, UWORD,
  36.                               UWORD, Tag, ... )
  37.  
  38. FUNCTION
  39.         Allocates  a  new  PBAR  structure,  initialises  it  to the default
  40.         values,  or  any  values  specified  in  the function call, and then
  41.         renders the progress bar to the specified window.
  42.  
  43. INPUTS
  44.         Wnd     - A pointer to the window in which the progress bar is to be
  45.                   rendered.
  46.         Left    - The X position of the progress bar.
  47.         Top     - The Y position of the progress bar.
  48.         Width   - The Width of the progress bar.
  49.         Height  - The Height of the progress bar.
  50.         Size    - The  logical  size of the progress bar.  This is the value
  51.                   represented  by  the full bar.  It is not connected to the
  52.                   visual dimensions of the progress bar.
  53.         taglist - A   pointer  to  an  array  of  tags  specifying  optional
  54.                   parameters which will modify the behaviour of the progress
  55.                   bar.  If the default values are all that are required this
  56.                   can  be  NULL.  See SetProgBarAttrs() for more information
  57.                   about the various tags available.
  58.  
  59. RESULT
  60.         bar - If successful these functions will return a pointer to the new
  61.               progress  bar.   This  pointer  should  be  kept as it will be
  62.               needed  to  identify  the  progress  bar  for  all  the  other
  63.               functions.   These  functions  will only fail due to a lack of
  64.               memory, in which case the returned value will be NULL.
  65.  
  66. BUGS
  67.         None known
  68.  
  69. SEE ALSO
  70.         SetProgBarAttrs() FreeProgBar() RefreshProgBar() UpdateProgBar()
  71.  
  72.  
  73.  
  74. SetProgBarAttrsA() / SetProgBarAttrs()
  75. --------------------------------------
  76.  
  77. NAME
  78.         SetProgBarAttrsA -- Changes  the  behaviour  or  appearance  of  the
  79.                             progress bar.  (V1.0)
  80.         SetProgBarAttrs -- Varargs stub for SetProgBarAttrs().  (V1.0)
  81.  
  82. SYNOPSIS
  83.         SetProgBarAttrsA ( PBar, taglist )
  84.  
  85.         void SetProgBarAttrsA ( PBAR *, struct TagList * )
  86.  
  87.         SetProgBarAttrs ( PBar, First_Tag, ... )
  88.  
  89.         void SetProgBarAttrs ( PBAR *, Tag, ... )
  90.  
  91. FUNCTION
  92.         Changes  the  behaviour  or  appearance  of  a  progress bar to that
  93.         specified  by  the optional tags.  It will perform all the necessary
  94.         calculations and redraw the display.
  95.  
  96. INPUTS
  97.         PBar    - A  pointer to the progress bar to be altered.  This is the
  98.                   pointer returned by CreateProgBar().
  99.         taglist - A  pointer  to  a  tag  list.   The  available tags are as
  100.                   follows.
  101.  
  102.             PB_LeftEdge          The X position of the progress bar.
  103.             PB_TopEdge           The Y position of the progress bar.
  104.             PB_Width             The Width of the progress bar.
  105.             PB_Height            The Height of the progress bar.
  106.             PB_Direction         The  Direction  in  which  the progress bar
  107.                                  will grow.  Available options are
  108.                   PBDE_RIGHT     From Left to Right  ( default ).
  109.                   PBDE_LEFT      From Right to Left.
  110.                   PBDE_UP        From Bottom to Top.
  111.                   PBDE_DOWN      From Top to Bottom.
  112.             PB_BarColour         The  pen  number  of  the  bar's foreground
  113.                                  colour.  The default value is 3 (Blue).
  114.             PB_BarBackColour     The  Pen  number  of  the  bar's background
  115.                                  colour.  The default value is 0 (Grey).
  116.             PB_BarSize           The logical size of the progress bar.
  117.             PB_BarValue          The  current Value of the progress bar.  It
  118.                                  is better to use UpdateProgBar()  to change
  119.                                  this  value  if  this  is  the only change.
  120.                                  However,  the  option  has been supplied so
  121.                                  that  the  value can be altered at the same
  122.                                  time  as  other  changes  are made.  If the
  123.                                  value  supplied  is greater than PB_BarSize
  124.                                  the actual value stored will be PB_BarSize.
  125.                                  This   guarantees   that   the  bar  cannot
  126.                                  overflow.
  127.             PB_BorderType        The   type   of  border  drawn  around  the
  128.                                  progress bar.  The available options are
  129.                   PBBT_NONE      No Border.
  130.                   PBBT_PLAIN     Plain Black Box  ( default ).
  131.                   PBBT_RECESSED  Recessed Box.
  132.                   PBBT_RAISED    Raised Box.
  133.                   PBBT_RIDGE     Raised Ridge.
  134.             PB_TextMode          The  mode used for rendering the text.  The
  135.                                  available options are
  136.                   PBTM_NONE      No Text  ( default ).
  137.                   PBTM_PERCENT   Display Value as a percentage, e.g. 50%.
  138.                   PBTM_VALUE     Display Value as "Value/Size", e.g. 67/153.
  139.             PB_TextPosition      The  position  you  want  the  text  to  be
  140.                                  displayed.  The available options are
  141.                   PBTP_BELOW     Text centred below the bar  ( default ).
  142.                   PBTP_ABOVE     Text centred above the bar.
  143.                   PBTP_LEFT      Text to the left of the bar.
  144.                   PBTP_RIGHT     Text to the right of the bar.
  145.                   PBTP_CENTRE    Text centred inside the bar.
  146.             PB_TextColour        The  pen  number  of  the text's foreground
  147.                                  colour.  The default is 1 (Black).
  148.             PB_TextBackColour    The  pen  number  of  the text's background
  149.                                  colour.   The  default  is  0 (Grey).  This
  150.                                  value  is  ignored  if the text  is centred
  151.                                  within   the   bar.    In   this  case  the
  152.                                  background will be the bar itself.
  153.             PB_TextFont          A  pointer to a TextAttr structure defining
  154.                                  the  font to be used for the text.  If this
  155.                                  value  is  NULL  the  window's font will be
  156.                                  used (default).
  157.  
  158. RESULT
  159.         None
  160.  
  161. BUGS
  162.         None known
  163.  
  164. SEE ALSO
  165.         CreateProgBar() FreeProgBar()
  166.  
  167.  
  168.  
  169. FreeProgBar()
  170. -------------
  171.  
  172. NAME
  173.         FreeProgBar -- Deletes  a  progress bar from the screen and releases
  174.                        all memory used by it.  (V1.0)
  175.  
  176. SYNOPSIS
  177.         FreeProgBar ( PBar )
  178.  
  179.         void FreeProgBar ( PBAR * )
  180.  
  181. FUNCTION
  182.         Releases all the memory used by the progress bar and removes it from
  183.         the screen.
  184.  
  185. INPUTS
  186.         PBar - A  pointer  to  the  progress  bar  to be freed.  This is the
  187.                pointer   returned   by   CreateProgBar().    After   calling
  188.                FreeProgBar() you should not use PBar again.
  189.  
  190. RESULT
  191.         None
  192.  
  193. BUGS
  194.         None known
  195.  
  196. SEE ALSO
  197.         CreateProgBar() SetProgBarAttrs() ClearProgBar()
  198.  
  199.  
  200.  
  201. RefreshProgBar()
  202. ----------------
  203.  
  204. NAME
  205.         RefreshProgBar -- Redraws a progress bar.  (V1.0)
  206.  
  207. SYNOPSIS
  208.         RefreshProgBar ( PBar )
  209.  
  210.         void RefreshProgBar ( PBAR * )
  211.  
  212. FUNCTION
  213.         Redraws   a  progress  bar  in  its  current  state.   It  does  not
  214.         recalculate any of the progress bar's internal values.
  215.  
  216. INPUTS
  217.         PBar - A  pointer  to  the  progress bar to be redrawn.  This is the
  218.                pointer returned by CreateProgBar().
  219.  
  220. RESULT
  221.         None
  222.  
  223. BUGS
  224.         None known
  225.  
  226. SEE ALSO
  227.         CreateProgBar() SetProgBarAttrs() FreeProgBar() UpdateProgBar()
  228.         ResetProgBar()
  229.  
  230.  
  231.  
  232. UpdateProgBar()
  233. ---------------
  234.  
  235. NAME
  236.         UpdateProgBar -- Change  the  current  value  of  a progress bar and
  237.                          redisplay its imagery.  (V1.0)
  238.  
  239. SYNOPSIS
  240.         UpdateProgBar ( PBar, Value )
  241.  
  242.         void UpdateProgBar ( PBAR *, UWORD )
  243.  
  244. FUNCTION
  245.         Updates  the  current  value  of  the progress bar, performs all the
  246.         necessary recalculations and redisplays the progress bar.
  247.  
  248. INPUTS
  249.         PBar  - A  pointer to the progress bar whose value is to be changed.
  250.                 This is the pointer returned by CreateProgBar().
  251.         Value - The new value for the progress bar.
  252.  
  253. NOTES
  254.         If  the  value  supplied  is  greater  than  the  size  of  the  bar
  255.         (PB_BarSize)  the  actual  value  stored  will  be PB_BarSize.  This
  256.         guarantees that the bar cannot overflow.
  257.  
  258.         If  the  bar's  value  is  to  be  changed at the same time as other
  259.         properties it is better to use SetProgBarAttrs().
  260.  
  261. RESULT
  262.         None
  263.  
  264. BUGS
  265.         None known
  266.  
  267. SEE ALSO
  268.         CreateProgBar() SetProgBarAttrs() FreeProgBar() RefreshProgBar()
  269.         ResetProgBar()
  270.  
  271.  
  272.  
  273. ResetProgBar()
  274. --------------
  275.  
  276. NAME
  277.         ResetProgBar -- Reset  the  current  value of a progress bar to zero
  278.                         and redisplay its imagery.  (V1.0)
  279.  
  280. SYNOPSIS
  281.         ResetProgBar ( PBar )
  282.  
  283.         void ResetProgBar ( PBAR * )
  284.  
  285. FUNCTION
  286.         Resets  the  current value of the progress bar to zero, performs all
  287.         the necessary recalculations and redisplays the progress bar.
  288.  
  289. INPUTS
  290.         PBar - A  pointer  to  the  progress bar whose value is to be reset.
  291.                This is the pointer returned by CreateProgBar().
  292.  
  293. NOTES
  294.         If  the  bar's  value  is  to  be  changed at the same time as other
  295.         properties it is better to use SetProgBarAttrs().
  296.  
  297.         This function is identical to "UpdateProgBar( PBar, 0 )".
  298.  
  299. RESULT
  300.         None
  301.  
  302. BUGS
  303.         None known
  304.  
  305. SEE ALSO
  306.         CreateProgBar() SetProgBarAttrs() FreeProgBar() RefreshProgBar()
  307.         UpdateProgBar()
  308.  
  309.  
  310.  
  311. ClearProgBar()
  312. --------------
  313.  
  314. NAME
  315.         ClearProgBar -- Removes a progress bar from the display.  (V1.0)
  316.  
  317. SYNOPSIS
  318.         ClearProgBar ( PBar )
  319.  
  320.         void ClearProgBar ( PBAR * )
  321.  
  322. FUNCTION
  323.         Removes  the  supplied  progress  bar from the display.  It does not
  324.         release  the  memory  used  by the progress bar.
  325.  
  326. INPUTS
  327.         PBar - A  pointer to the progress bar whose imagery is to be erased.
  328.                This is the pointer returned by CreateProgBar().
  329.  
  330. NOTES
  331.         If  your  progress bar does not have any text associated with it, it
  332.         will be marginally faster to call ClearBar() instead.
  333.  
  334.         If you only want to delete the progress bar's text then it is better
  335.         to call ClearText().
  336.  
  337. RESULT
  338.         None
  339.  
  340. BUGS
  341.         None known
  342.  
  343. SEE ALSO
  344.         CreateProgBar() SetProgBarAttrs() FreeProgBar() ClearBar()
  345.         ClearText()
  346.  
  347.  
  348.  
  349. ClearBar()
  350. ----------
  351.  
  352. NAME
  353.         ClearBar -- Removes  a  progress  bar from the display, but does not
  354.                     remove any text.  (V1.0)
  355.  
  356. SYNOPSIS
  357.         ClearBar ( PBar )
  358.  
  359.         void ClearBar ( PBAR * )
  360.  
  361. FUNCTION
  362.         Removes  the  supplied  progress  bar from the display, but does not
  363.         delete  the bar's text, if any.  It does not release the memory used
  364.         by the progress bar.
  365.  
  366. INPUTS
  367.         PBar - A  pointer to the progress bar whose imagery is to be erased.
  368.                This is the pointer returned by CreateProgBar().
  369.  
  370. RESULT
  371.         None
  372.  
  373. BUGS
  374.         None known
  375.  
  376. SEE ALSO
  377.         CreateProgBar() SetProgBarAttrs() FreeProgBar() ClearProgBar()
  378.         ClearText()
  379.  
  380.  
  381.  
  382. ClearText()
  383. -----------
  384.  
  385. NAME
  386.         ClearText -- Removes a progress bar's text from the display.  (V1.0)
  387.  
  388. SYNOPSIS
  389.         ClearText ( PBar )
  390.  
  391.         void ClearText ( PBAR * )
  392.  
  393. FUNCTION
  394.         Removes  the supplied progress bar's text from the display.  It does
  395.         not affect the image of the bar itself.
  396.  
  397. INPUTS
  398.         PBar - A  pointer  to  the  progress bar whose text is to be erased.
  399.                This is the pointer returned by CreateProgBar().
  400.  
  401. RESULT
  402.         None
  403.  
  404. BUGS
  405.         None known
  406.  
  407. SEE ALSO
  408.         CreateProgBar() SetProgBarAttrs() FreeProgBar() ClearProgBar()
  409.         ClearBar()
  410.