home *** CD-ROM | disk | FTP | other *** search
/ The AGA Experience 2 / agavol2.iso / software / utilities / icon_tools / iconian296 / sources / docs / popupgadget.doc
Text File  |  1995-09-18  |  5KB  |  137 lines
  1. Class:            popup.gadget
  2. Superclass:       gadgetclass
  3.  
  4. Very configurable popup-menu gadget.
  5.  
  6. New Methods:
  7.  
  8. None.
  9.  
  10.  
  11. Changed Methods:
  12.  
  13. OM_SET - Any attribute that would result in a visual change will cause
  14. the  gadget  to  re-render  itself,  even if a popup window is opened.
  15. Weird visual stuff may happen if the popup window is open.
  16.  
  17.  
  18. Attributes:
  19.  
  20. GA_LEFT,  GA_TOP  (IS)  -  Same  as  for gadgetclass.  Any change will
  21. result in the gadget moving itself.
  22.  
  23. GA_WIDTH, GA_HEIGHT (IS) - Only used if PUA_AUTOGADGETRESIZE is set to
  24. FALSE.
  25.  
  26. GA_IMAGE,  GA_SELECTRENDER  (IS) - If set, will determine the gadget's
  27. imagery.   Otherwise, the image is taken from the active item's image.
  28. If  GA_IMAGE  is  present,  but  GA_SELECTRENDER  is  absent,  then  a
  29. IDS_SELECTED state will be sent to the GA_IMAGE image.
  30.  
  31. GA_RELVERIFY  (I)  (New  for  2.0) - If set, only a final notification
  32. will be sent, after the selection is made or canceled.
  33.  
  34. PUA_ACTIVE (ISGU) - The currently selected item.
  35.  
  36. PUA_OBJECTS  (I)  - A list of linked objects.  This is the meat of the
  37. gadget.   The  objectnode  structure's  documentation is at the end of
  38. this file.
  39.  
  40. PUA_ROWS,  PUA_COLUMNS  (ISGU)  -  Determines  the  size  of the popup
  41. window.
  42.  
  43. PUA_POPUPARROW  (ISU)  -  Selects  the visual imagery.  PUARROW_NONE,
  44. PUARROW_TINY, or PUARROW_POPUP.
  45.  
  46. PUA_GADGETBORDER  (ISU)  -  Selects the visual imagery of the gadget's
  47. border.   -1  for  no  border.   Otherwise any FRAME_* type supported by
  48. frameiclass is legal.
  49.  
  50. PUA_WINDOWBORDER  (ISU)  - Same as PUA_GADGETBORDER, but for the frame
  51. around the window.
  52.  
  53. PUA_WINDOWSPACING,  PUA_IMAGESPACING  (ISU)  -  If  TRUE, a few pixels
  54. around each item.  Otherwise, a bestfit is used.
  55.  
  56. PUA_NUMBEROFOBJECTS (G) - Number of objects found in the object list.
  57.  
  58. PUA_AUTOGADGETRESIZE  (ISU)  -  If  TRUE,  the  gadget will attempt to
  59. resize  itself  based  on it's imagery.  This can be useful if you are
  60. unsure how the gadget will look.  Just create the gadget, and then use
  61. gadget->width/gadget->height to determine it's size.
  62.  
  63. PUA_AUTOWINDOWLAYOUT - UNUSED for now.
  64.  
  65. PUA_CENTERIMAGES  (ISU) - If TRUE, each image will be centered in it's
  66. box.
  67.  
  68. PUA_CENTERGADGETIMAGE  (ISU)  - If TRUE, the GA_IMAGE will be centered
  69. in the gadget.
  70.  
  71.  
  72. Additional functions in library:
  73.  
  74. Class *InitPopUpClass (void)
  75.   Initializes the class and returns a pointer to it.
  76.  
  77. BOOL FreePopUpClass (Class *cl)
  78.   Frees the class.
  79.  
  80. struct objectnode AddObjectToList(List *list, Object *object, long frameType, Object *selobject, long selFrameType, long selFillColor)
  81.   Allocates  an object node and fills in the appropriate fields.  Pass
  82. this node through the DisposeObjectNodes!
  83.  
  84. struct objectnode AddTextToList(List *list, STRPTR text, textAttr ta, struct DrawInfo *drawInfo)
  85.   Opens  the  font  specified  by  ta.   (If it fails, topaz.8 will be
  86. opened.   uk!) An objectnode will be allocated.  Then, two itexticlass
  87. objects  will  be  inserted.   The  objectnode will be returned.  This
  88. objectnode   MUST   be   passed   thru   the   DisposeObjects()  *and*
  89. DiposeObjectNodes() routine.
  90.  
  91. void DisposeObjectNodes (List *list)
  92.   Frees  a list of objectsnodes.  Does not dispose any objects, so use
  93. DisposeObjects  before  hand  if  needed.  This routine is intelligent
  94. enough  to  dispose  only  those nodes allocated by other popup.gadget
  95. routines.
  96.  
  97. void DisposeObjects (List *list)
  98.   Walks  a  list  or  objectnodes  and  DisposeObject() all object and
  99. selobjects  encountered.   Also  correctly  frees objects created with
  100. AddTextToList().
  101.  
  102. List  *BuildPalette (long firstcolor, long lastcolor, long width, long height)
  103.   Allocates,  and  creates  a  "palette"  object  list consisting of a
  104. number  of fillrectclass rectangles.  You MUST use DisposePalette() to
  105. free  the  list.  objectnode.frametype and objectnode.selframetype for
  106. individual  nodes  may be modified as needed.  All other variables are
  107. off-limits.
  108.  
  109. void DisposePalette (List *list)
  110.   Frees a palette list.
  111.  
  112.  
  113. NOTICE:
  114.  
  115. I'm  not very proficent in writing C stuff (just reading it).  So some
  116. of  the  above  calls might have wrong variable types.  Take a look at
  117. testpu.e for examples.
  118.  
  119.  
  120. HISTORY:
  121.  
  122. ---v2.0---
  123. Added  MENUUP  and SELECTDOWN to end/cancel the popup-window.  You can
  124. now use ActivateGadget() to bringup window inside a menu-button verify
  125. cancel  (right  mouse  button).   This  effect  can be seen in Iconian
  126. 2.94b.
  127.  
  128. Added  support  for  GA_RELVERIFY.   If  set, the gadget does not send
  129. PUA_ACTIVE  messages  until  the  gadget  is done.  (Although, a final
  130. message  will  still  be  sent  if the window is canceled...this might
  131. change in the future.)
  132.  
  133.  
  134. ---v1.0---
  135. Original release
  136.  
  137.