home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / bgui.lzx / bgui / docs / bgui.doc < prev    next >
Encoding:
Text File  |  1995-08-08  |  9.1 KB  |  323 lines
  1.  
  2.            File: bgui.doc
  3.     Description: bgui.library documentation.
  4.       Copyright: (C) Copyright 1994-1995 Jaba Development.
  5.              (C) Copyright 1994-1995 Jan van den Baard.
  6.              All Rights Reserved.
  7.  
  8. -------------------------------------------------------------------------------
  9.  
  10. TABLE OF CONTENTS
  11.  
  12. bgui.library/BGUI_GetClassPtr
  13. bgui.library/BGUI_NewObjectA
  14. bgui.library/BGUI_RequestA
  15. bgui.library/BGUI_Help
  16. bgui.library/BGUI_LockWindow
  17. bgui.library/BGUI_UnlockWindow
  18. bgui.library/BGUI_DoGadgetMethodA
  19.  
  20. bgui.library/BGUI_GetClassPtr               bgui.library/BGUI_GetClassPtr
  21.  
  22.     NAME
  23.     BGUI_GetClassPtr -- Obtain a pointer to a BGUI class.
  24.  
  25.     SYNOPSIS
  26.     class = BGUI_GetClassPtr( classID )
  27.     D0              D0
  28.  
  29.     Class *BGUI_GetClassPtr( ULONG );
  30.  
  31.     FUNCTION
  32.     This function is ment to provide class writers an  easy way  to obtain a
  33.     pointer to one of the bgui.library classes. The pointer returned by this
  34.     routine may _only_ be used to subclass or to obtain objects from. Either
  35.     reading from or writing to the class structure is not allowed.
  36.  
  37.     INPUTS
  38.     classID         - The numeric ID of the class you need.
  39.  
  40.     RESULT
  41.     A pointer to the requested class or NULL if the call was  unsuccessfull.
  42.  
  43.     BUGS
  44.     None known.
  45.  
  46.     SEE ALSO
  47.     libraries/bgui.h
  48.  
  49. bgui.library/BGUI_NewObjectA                bgui.library/BGUI_NewObjectA
  50.  
  51.     NAME
  52.     BGUI_NewObjectA -- Get an object from a class.
  53.     BGUI_NewObject -- Varargs version.
  54.  
  55.     SYNOPSIS
  56.     object = BGUI_NewObjectA( classID, tags )
  57.     D0              D0       A0
  58.  
  59.     Object *BGUI_NewObjectA( ULONG, struct TagItem * )
  60.  
  61.     object = BGUI_NewObject( classID, tag1, ... )
  62.  
  63.     Object *BGUI_NewObject( ULONG, Tag, ... )
  64.  
  65.     FUNCTION
  66.     This routine is a replacement routine for intuition's NewObjectA() call.
  67.     It is an easy way to obtain an object from any of the  BGUI classes. You
  68.     pass it a classID and some create time attributes  and the  routine will
  69.     return you a pointer to the created object.
  70.  
  71.     INPUTS
  72.     classID - The numeric ID of the class.
  73.  
  74.     tags    - A set of create-time attributes  which will be passed onto the
  75.           class of which the object is created.
  76.  
  77.     RESULT
  78.     A pointer to the created object or NULL if an error occured.
  79.  
  80.     BUGS
  81.     None known.
  82.  
  83.     SEE ALSO
  84.     intuition.library/NewObjectA(), libraries/bgui.h
  85.  
  86. bgui.library/BGUI_RequestA                  bgui.library/BGUI_RequestA
  87.  
  88.     NAME
  89.     BGUI_RequestA -- Put up a requester.
  90.     BGUI_Request -- Varargs version.
  91.  
  92.     SYNOPSIS
  93.     gadid = BGUI_RequestA( win, req, args )
  94.     D0               A0   A1     A2
  95.  
  96.     ULONG BGUI_RequestA( struct Window *, struct bguiRequest *, ULONG * )
  97.  
  98.     gadid = BGUI_Request( win, req, arg1, ... )
  99.  
  100.     ULONG BGUI_Request( struct Window *, struct bguiRequest *, ULONG, ... )
  101.  
  102.     FUNCTION
  103.     To  put  up  a    requester.   It  is typically the  same  as  intuition's
  104.     EasyRequestArgs() only this routine allows you to put in InfoClass style
  105.     command sequences in the body text.
  106.  
  107.     INPUTS
  108.     win    - A pointer to the window on which the requester will open. This
  109.           may be NULL.
  110.  
  111.     req    - A pointer to    an  initialized  bguiRequest  structure.    This
  112.           structure is    simular  to  intuition's  EasyStruct  structure.
  113.           It is used to control the  general  look of the requester. The
  114.           structure is    initialized  with the following data:
  115.  
  116.           br_Flags      - This  field can contain any of the following
  117.                     flags:
  118.  
  119.                     BREQF_CENTERWINDOW
  120.                     This  will center the requester over the
  121.                     window 'win' if a  valid  pointer  to  a
  122.                     window is passed.
  123.  
  124.                     BREQF_LOCKWINDOW
  125.                     This will  disable  the window    on which
  126.                     the requester appears from receiving any
  127.                     IDCMP messages.   Also a busy pointer is
  128.                     set on that window.   NOTE: ' win'  must
  129.                     point to a window for this to work.
  130.  
  131.                     BREQF_NO_PATTERN
  132.                     This will suppress the backfill pattern.
  133.  
  134.                     BREQF_XEN_BUTTONS
  135.                     When set this flag will make the buttons
  136.                     framing appear as XEN style framing.
  137.  
  138.                     BREQF_AUTO_ASPECT
  139.                     When set all  the  requester  will  make
  140.                     some aspect  ratio dependant  changes to
  141.                     the GUI like thin/thick frames etc.
  142.  
  143.                     BREQF_FAST_KEYS
  144.                     This flag tells BGUI to  use  the Return
  145.                     and Esc key as default positive/negative
  146.                     responce to the  requester.  Please note
  147.                     that  no  visual  confirmation    is given
  148.                     at this time when the key is pressed.
  149.  
  150.           br_Title      - A pointer to the title of the requester.  If
  151.                     this is NULL the title of the window is used
  152.                     if one is present.    In the    last  case "BGUI
  153.                     Request"  or  it's  localized  equivalent is
  154.                     used.
  155.  
  156.  
  157.           br_GadgetFormat - A  pointer to the gadget label string.   The
  158.                     gadget  labels   are   truncated  by  a  '|'
  159.                     character. I.E "OK|Cancel" will give  you  a
  160.                     "OK" and a "Cancel" gadget.
  161.  
  162.                     When you precede the gadget label with a '*'
  163.                     sign the label  of    the  gadget  in question
  164.                     is printed in bold.  Also  this  gadget will
  165.                     automatically be the default responce of the
  166.                     Return key when the BREQF_FAST_KEYS  flag is
  167.                     set (see above).
  168.  
  169.           br_TextFormat   - A printf-style formatting  string which  may
  170.                     also   contain   InfoClass     style     command
  171.                     sequences.
  172.  
  173.           br_ReqPos      - The  position  at which   the requester will
  174.                     be opened.     There are three possibilities:
  175.  
  176.                     POS_CENTERSCREEN
  177.                     POS_CENTERMOUSE
  178.                     POS_TOPLEFT
  179.  
  180.                     It should be obvious what  they mean.  NOTE:
  181.                     The  BREQF_CENTERWINDOW  flag  will override
  182.                     this setting.
  183.  
  184.           br_Underscore   - With this field you  can  set the  character
  185.                     which preceedes the character  to underline.
  186.                     The  underlined  character    will  be the key
  187.                     which activates the gadget.
  188.  
  189.           br_Reserved0      - These fields  are  for  future expansion and
  190.                     _must_ be zero'd.
  191.  
  192.           br_Screen      - Here you can optionally  specify the  Screen
  193.                     on    which  the  requester  must  appear.  By
  194.                     default  the Window it's Screen is used if a
  195.                     valid Window pointer is given.  If no Window
  196.                     is given then this Screen is used.    If  this
  197.                     field is NULL the  default Public  Screen is
  198.                     used.
  199.  
  200.           br_Reserved1      - These fields  are  for  future expansion and
  201.                     _must_ be zero'd.
  202.  
  203.     args    - A pointer to an array of arguments for the  C-style formatting
  204.           codes.
  205.  
  206.     RESULT
  207.     1, 2, 3, 4 ....., 0 You will be returned a value ranging  from    0 to the
  208.     amount of gadgets minus one.     NOTE: The right most gadget will always
  209.     return 0.
  210.  
  211.     BUGS
  212.     This routine  really  should support underscored characters and keyboard
  213.     short cuts.
  214.  
  215.     SEE ALSO
  216.     intuition.library/EasyRequestArgs(), intuition/intuition.h,
  217.     libraries/bgui.h, infoclass.doc
  218.  
  219. bgui.library/BGUI_Help                      bgui.library/BGUI_Help
  220.  
  221.     NAME
  222.     BGUI_Help -- Put up a simple synchronus amigaguide help file.
  223.  
  224.     SYNOPSIS
  225.     success = BGUI_Help( win, file, node, line )
  226.     D0             A0   A1    A2    D0
  227.  
  228.     BOOL BGUI_Help( struct Window *, UBYTE *, UBYTE *, ULONG )
  229.  
  230.     FUNCTION
  231.     To show additional online-help using the amigaguide system.
  232.  
  233.     INPUTS
  234.     win    - A pointer to the window which shows the help.
  235.  
  236.     name    - A pointer to the full path name of the amigaguide file.
  237.  
  238.     node    - A pointer to the node name to display.
  239.  
  240.     line    - The line number to display.
  241.  
  242.     RESULT
  243.     TRUE uppon success and FALSE if something went wrong.
  244.  
  245.     BUGS
  246.     None known.
  247.  
  248.     SEE ALSO
  249.     amigaguide.library/OpenAmigaGuideA()
  250.  
  251. bgui.library/BGUI_LockWindow                bgui.library/BGUI_LockWindow
  252.  
  253.     NAME
  254.     BGUI_LockWindow -- Disable a window from receiving IDCMP.
  255.  
  256.     SYNOPSIS
  257.     lock = BGUI_LockWindow( win )
  258.     D0            A0
  259.  
  260.     APTR BGUI_LockWindow( struct Window * )
  261.  
  262.     FUNCTION
  263.     To disable a window from receiving IDCMP messages on  it's message port.
  264.     This is done by putting  up an    invisible  requester and a  busy pointer
  265.     same as the workbench uses. The only thing possible with  locked windows
  266.     is moving it with the dragbar and depth gadget.
  267.  
  268.     INPUTS
  269.     win    - A pointer to the window to lock.
  270.  
  271.     RESULT
  272.     lock will point to some private data if successfull or NULL if not.
  273.  
  274.     BUGS
  275.     None know.
  276.  
  277.     SEE ALSO
  278.     bgui.library/BGUI_UnlockWindow()
  279.  
  280. bgui.library/BGUI_UnlockWindow              bgui.library/BGUI_UnlockWindow
  281.  
  282.     NAME
  283.     BGUI_UnlockWindow -- Enable a window from receiving IDCMP.
  284.  
  285.     SYNOPSIS
  286.     BGUI_UnlockWindow( lock )
  287.                A0
  288.  
  289.     VOID BGUI_UnlockWindow( APTR )
  290.  
  291.     FUNCTION
  292.     To enable a window to receive IDCMP messages on  it's message port. This
  293.     routine must be used to 'unlock' windows locked with BGUI_LockWindow().
  294.  
  295.     INPUTS
  296.     lock    - A pointer to the data returned by BGUI_LockWindow().    This may
  297.           be NULL.
  298.  
  299.     RESULT
  300.     The window will be unlocked.
  301.  
  302.     BUGS
  303.     None know.
  304.  
  305.     SEE ALSO
  306.     bgui.library/BGUI_LockWindow()
  307.  
  308. bgui.library/BGUI_DoGadgetMethodA         bgui.library/BGUI_DoGadgetMethodA
  309.  
  310.     **************************************************************************
  311.     This routine is the same as intuition's DoGadgetMethod() routine  with the
  312.     exception  that  this call is _simulated_ on systems running lower than OS
  313.     3.0.   I  have  not  yet  experienced problems with this routine  on these
  314.     systems but please keep in mind that it is basically a hack under 2.04.
  315.     **************************************************************************
  316.  
  317.     BUGS
  318.     This call is simulated on systems running lower than OS 3.0.  There is
  319.     no way to avoid this...
  320.  
  321.     SEE ALSO
  322.     intuition.library/DoGadgetMethod()
  323.