home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Workbench / Libs / GADUTIL.LHA / GadUtil / Docs / AutoDocs / 01.GU_PreliminaryDocs < prev    next >
Encoding:
Text File  |  1995-10-10  |  21.0 KB  |  532 lines
  1.                                 GadUtil tags
  2.                                ~~~~~~~~~~~~~~
  3. Tags to use for the yet undocumented function GU_LayoutGadgetsA().
  4.  
  5. Tags to use in the tag lists for each gadget to create. Note that
  6. you do not have to specify any tags that not change from gadget to
  7. gadget.
  8.  
  9. GU_GadgetKind (ULONG)
  10.     Can be any of the standard GadTools gadget kinds, or one of the
  11.     extensions provided by GadUtil. Currently extended types are:
  12.  
  13.     IMAGE_KIND
  14.         A gadget that uses an Intuition Image structure for its
  15.         contents. Selected and unselected states can use different
  16.         images. The images are centered automatically.
  17.  
  18.         Extra tags for IMAGE_KIND:
  19.  
  20.             GUIM_Image (struct Image *)
  21.                 Image for the gadget in its unselected state. This is
  22.                 the only required (extra) tag for IMAGE_KIND gadgets.
  23.  
  24.             GUIM_SelectImg (struct Image *)
  25.                 Image for the gadget in its selected state. If this tag
  26.                 is omitted, the selected image will be the same as the
  27.                 unselected, and only the border and the background color
  28.                 will change (depending on the GUIM_BOOPSILook tag).
  29.  
  30.             GUIM_ReadOnly (BOOL)
  31.                 TRUE to create a read-only image gadget.
  32.  
  33.             GUIM_BOOPSILook (BOOL)
  34.                 This tag will allow the programmer to select how the
  35.                 secondary image should be shown, if only one image is
  36.                 used for the gadget. Defaults to TRUE, which means that
  37.                 the background color will change when the user selects
  38.                 the gadget.
  39.  
  40.     DRAWER_KIND
  41.         A "select drawer" image button. This can be used to select
  42.         a path, but is often used to select files.
  43.  
  44.     FILE_KIND
  45.         A "select file" image button. This can be used to allow the
  46.         user to select a file. Most programs uses the DRAWER_KIND
  47.         for both file and path selection.
  48.  
  49.     BEVELBOX_KIND
  50.         A GadTools bevelbox. Use this to avoid the use of absolute
  51.         sizing of bevelboxes. All bevel box kinds from OS3.0 is
  52.         supported, even if the computer only has OS2.0.
  53.  
  54.         Extra tags for BEVELBOX_KIND:
  55.  
  56.             GUBB_Recessed (BOOL)
  57.                 Create a recessed ("pushed in") bevel box. Differs from
  58.                 the GadTools tag GTBB_Recessed, in that it works with
  59.                 both TRUE and FALSE as parameter. GadTools creates a
  60.                 recessed box independent from the given value.
  61.  
  62.                 Defaults to FALSE.
  63.  
  64.             GUBB_FrameType (ULONG)
  65.                 Determines what kind of box this function renders. The
  66.                 current available alternatives are:
  67.  
  68.                     BFT_BUTTON - Generates a box like what is used around
  69.                                  a GadTools BUTTON_KIND gadget.
  70.  
  71.                     BFT_RIDGE - Generates a box like what is used around
  72.                                 a GadTools STRING_KIND gadget.
  73.  
  74.                     BFT_DROPBOX - Generates a box suitable for a standard
  75.                                   icon drop box imagery.
  76.  
  77.                     BFT_HORIZBAR - Generates a horizontal shadowed line.
  78.                                    Can also be used to draw a normal line,
  79.                                    using 1 for the line's height.
  80.  
  81.                     BFT_VERTBAR - Generates a vertical shadowed line. Can
  82.                                   also be used to draw a normal line, using
  83.                                   1 for the line's width.
  84.  
  85.                 Defaults to BFT_BUTTON.
  86.  
  87.             GUBB_TextColor (ULONG)
  88.                 Selects which color to print the title text in. Only useful
  89.                 for a bevelbox with a title. Defaults to the color of the
  90.                 TEXTPEN.
  91.  
  92.             GUBB_TextPen (ULONG)
  93.                 Selects which pen to print the title text in. Only
  94.                 useful for a bevelbox with a title. Defaults to TEXTPEN.
  95.                 This tag overrides the GUBB_TextColor tag.
  96.  
  97.             GUBB_Flags (ULONG)
  98.                 Currently, only text placement flags are defined. These are:
  99.  
  100.                 Y-pos flags
  101.                 ~~~~~~~~~~~
  102.                     BB_TEXT_ABOVE - Places the bevel box text above the upper
  103.                                     border of the box           ___Example___
  104.  
  105.                     BB_TEXT_IN    - Places the bevel box text at the upper
  106.                                     border of the box           ---Example---
  107.  
  108.                     BB_TEXT_BELOW - Places the bevel box text below the upper
  109.                                     border of the box           ___       ___
  110.                                                                    Example
  111.                 X-pos flags
  112.                 ~~~~~~~~~~~
  113.                     BB_TEXT_CENTER - Places the bevel box text in the middle
  114.                                      of the upper border        ---Example---
  115.  
  116.                     BB_TEXT_LEFT   - Places the bevel box text 8 pixels from
  117.                                      the left edge of the box   -Example-----
  118.  
  119.                     BB_TEXT_RIGHT  - Places the bevel box text 8 pixels from
  120.                                      the right edge of the box  -----Example-
  121.  
  122.                 Combined flags
  123.                 ~~~~~~~~~~~~~~
  124.                     BB_TEXT_ABOVE_CENTER - BB_TEXT_ABOVE + BB_TEXT_CENTER
  125.                     BB_TEXT_ABOVE_LEFT   - BB_TEXT_ABOVE + BB_TEXT_LEFT
  126.                     BB_TEXT_ABOVE_RIGHT  - BB_TEXT_ABOVE + BB_TEXT_RIGHT
  127.  
  128.                     BB_TEXT_IN_CENTER    - BB_TEXT_IN + BB_TEXT_CENTER
  129.                     BB_TEXT_IN_LEFT      - BB_TEXT_IN + BB_TEXT_LEFT
  130.                     BB_TEXT_IN_RIGHT     - BB_TEXT_IN + BB_TEXT_RIGHT
  131.  
  132.                     BB_TEXT_BELOW_CENTER - BB_TEXT_BELOW + BB_TEXT_CENTER
  133.                     BB_TEXT_BELOW_LEFT   - BB_TEXT_BELOW + BB_TEXT_LEFT
  134.                     BB_TEXT_BELOW_RIGHT  - BB_TEXT_BELOW + BB_TEXT_RIGHT
  135.  
  136.                 Default if BB_TEXT_ABOVE|BB_TEXT_CENTER. Combine the x and y
  137.                 position flags by OR:ing them together. Don't combine two X
  138.                 or two Y flags together.
  139.                 
  140.                 Shadow placement flags
  141.                 ~~~~~~~~~~~~~~~~~~~~~~
  142.                     BB_SHADOW_DR - Places the bevel box text shadow one pixel
  143.                                    below and to the right of the text. 
  144.  
  145.                     BB_SHADOW_UR - Places the bevel box text shadow one pixel
  146.                                    above and to the right of the text. 
  147.  
  148.                     BB_SHADOW_DL - Places the bevel box text shadow one pixel
  149.                                    below and to the left of the text. 
  150.  
  151.                     BB_SHADOW_UL - Places the bevel box text shadow one pixel
  152.                                    above and to the left of the text. 
  153.  
  154.                     BB_SUNAT_UL  - Another name for BB_SHADOW_DR
  155.                     BB_SUNAT_DL  - Another name for BB_SHADOW_UR
  156.                     BB_SUNAT_UR  - Another name for BB_SHADOW_DL
  157.                     BB_SUNAT_DR  - Another name for BB_SHADOW_UL
  158.  
  159.                 Default if BB_SHADOW_DR (BB_SUNAT_UL).
  160.  
  161.             GUBB_3DText (BOOL)
  162.                 Enables the shadow on the bevel box text. This tag must be
  163.                 used if GUBB_ShadowColor or GUBB_ShadowPen isn't used.
  164.  
  165.             GUBB_ShadowColor (ULONG)
  166.                 Selects which color to print the shadow text in. Only useful
  167.                 for a bevelbox with a title. Defaults to the color of the
  168.                 SHADOWPEN.
  169.  
  170.             GUBB_ShadowPen (ULONG)
  171.                 Selects which pen to print the shadow text in. Only useful
  172.                 for a bevelbox with a title. Defaults to SHADOWPEN.
  173.                 This tag overrides the GUBB_ShadowColor tag.
  174.  
  175.     PROGRESS_KIND:
  176.         Gadget used to display a value out of a total. Can be used to
  177.         display the progress of a search, a diskcopy or anything else.
  178.  
  179.         Extra tags for PROGRESS_KIND:
  180.  
  181.             GUPR_FillColor (ULONG)
  182.                 Selects which color to use to paint the current value of
  183.                 the progress requester with. Defaults to the color of the
  184.                 FILLPEN.
  185.  
  186.             GUPR_FillPen (ULONG)
  187.                 Selects which pen to use to paint the current value of
  188.                 the progress requester with. Defaults to the FILLPEN.
  189.                 This tag overrides the GUPR_FillColor tag.
  190.  
  191.             GUPR_BackColor (ULONG)
  192.                 Selects which color to fill the background of the progress
  193.                 requester with. Defaults to the color of the BACKGROUNDPEN.
  194.  
  195.             GUPR_BackPen (ULONG)
  196.                 Selects which pen to fill the background of the progress
  197.                 requester with. Defaults to the BACKGROUNDPEN.
  198.                 This tag overrides the GUPR_BackColor tag.
  199.  
  200.             GUPR_Current (ULONG)
  201.                 The initial current value of the progress requester. The
  202.                 gadget's current value may be changed later by directly
  203.                 modifying the pg_Current field of the ProgressGad structure.
  204.                 Use GU_UpdateProgress to redraw the progress requester with
  205.                 the new value. The pg_Current field must not be larger than
  206.                 4.294.967.295 / the width of the progress gadget. A "normal"
  207.                 width of 410 pixels allows a current value of 10.737.418.
  208.         Defaults to 0.
  209.  
  210.             GUPR_Total (ULONG)
  211.                 The initial total value of the progress requester. The
  212.                 gadget's total value may be changed later by directly
  213.                 modifying the pg_Total field of the ProgressGad structure.
  214.                 Use GU_UpdateProgress to redraw the progress requester with
  215.                 the new value. The total value can be as large as a longword
  216.                 allows (4.294.967.295), but you can't display a current value
  217.                 larger than 4.294.967.295 / the width of the progress gadget.
  218.         Defaults to 100.
  219.  
  220.     Changed tags, and additions to GadTools:
  221.  
  222.     LISTVIEW_KIND:
  223.  
  224.         GTLV_ShowSelected (UWORD id)
  225.  
  226.             This tag was changed, so that you don't have to create the
  227.             string gadget before all other gadgets. The difference from
  228.             this tag in GadTools, is that we now have to give the ID of
  229.             the string gadget to use to show the selected item.
  230.  
  231.             An example of a valid (and probably most useful) gadget to
  232.             use for GTLV_ShowSelected:
  233.  
  234.             ShowSelGad:
  235.                 dc.l    GU_GadgetKind,  STRING_KIND,    GU_AutoHeight,  4
  236.                 dc.l    GU_DupeWidth,   GAD_LISTVIEW,   GU_GadgetText,  NULL
  237.                 dc.l    TAG_DONE
  238.  
  239.             This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
  240.             array.
  241.  
  242.             Special:
  243.  
  244.             ti_Data = -1    Creates a read-only gadget below the listview,
  245.                             same as for GTLV_ShowSelected, 0  for GadTools.
  246.  
  247.             ti_Data =  x    Gadget ID for the gadget that the selected item
  248.                             should be displayed in. Same as GadTools reaction
  249.                             on a gadget pointer in ti_Data.
  250.  
  251.             This gadget's ti_Data field will be changed during the creation
  252.             of the gadget, but will be changed back before GU_LayoutGadgets
  253.             returns.
  254.  
  255.     MX_KIND:
  256.  
  257.         The gng_GadgetText field in the NewGadget structure can be used even
  258.         with MX_KIND gadgets. This should have been included in GadTools.
  259.         The gadget text will always be placed ABOVE the gadget, on the same
  260.         side as the other texts for the gadget. Positions are checked against
  261.         WBPattern & SerialPrefs to get them "right". The GU_GadgetText and
  262.         GU_LocaleText tags are used to access this field.
  263.  
  264. Tags for all gadget kinds:
  265.  
  266. Gadget width control:
  267.  
  268.     GU_Width (UWORD wid)
  269.         Absolute width of the gadget. Not recommended to use for other
  270.         gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  271.  
  272.     GU_DupeWidth (UWORD id)
  273.         Duplicate the width of another gadget.
  274.  
  275.     GU_AutoWidth (WORD add)
  276.         Width = length of text label + ti_Data. For CYCLE_KIND gadgets,
  277.     the gadget width will be calculated by checking the length of
  278.     all alternatives and using the one that is widest + 26 as width.
  279.  
  280.     GU_Columns (UWORD numcols)
  281.         Set the gadget width so that approximately ti_Data columns of
  282.         text will fit.
  283.  
  284.     GU_AddWidth (WORD add)
  285.         Add ti_Data to the total width calculation.
  286.  
  287.     GU_MinWidth (UWORD wid)
  288.         Make the gadget at least ti_Data pixels wide.
  289.  
  290.     GU_MaxWidth (UWORD wid)
  291.         Make the gadget at most ti_Data pixels wide.
  292.  
  293.     GU_AddWidChar (WORD chars)
  294.         Add the length of ti_Data characters to the total width calculation.
  295.  
  296. Gadget height control:
  297.  
  298.     GU_Height (UWORD hei)
  299.         Absolute height of the gadget. Not recommended to use for other
  300.         gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  301.         
  302.     GU_DupeHeight (UWORD id)
  303.         Duplicate the height of another gadget.
  304.  
  305.     GU_AutoHeight (WORD add)
  306.         Height = height of the gadget's font + ti_Data. This tag doesn't
  307.         work as it should with MX_KIND gadgets. Will be fixed later.
  308.         Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
  309.  
  310.     GU_HeightFactor (UWORD numlines)
  311.         Set the gadget height to approximately ti_Data lines.
  312.  
  313.     GU_AddHeight (WORD add)
  314.         Add ti_Data to the total height calculation.
  315.  
  316.     GU_MinHeight (UWORD wid)
  317.         Make the gadget at least ti_Data pixels high.
  318.  
  319.     GU_MaxHeight (UWORD wid)
  320.         Make the gadget at most ti_Data pixels high.
  321.  
  322.     GU_AddHeiLines (WORD numlines)
  323.         Add the height of ti_Data/2 lines to the final height calculation.
  324.         The numlines argument is given in units of 1/2 lines to get
  325.         better resolution (ti_Data of 4 means that the height of 2
  326.         lines should be added).
  327.  
  328. Gadget top edge control:
  329.  
  330.     GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
  331.     allows any bottom edge control tag to adjust the height, so that both
  332.     top and bottom edges will be correct.
  333.  
  334.     GU_Top (UWORD ypos)
  335.         Absolute top edge of the gadget. Not recommended to use for other
  336.         gadgets than the top-most gadgets.
  337.  
  338.     GU_TopRel (UWORD id)
  339.         Make the top edge relative to another gadgets bottom edge. This
  340.         gadget will be placed BELOW the given gadget.
  341.  
  342.     GU_AddTop (WORD add)
  343.         Add ti_Data to the final top edge calculation.
  344.  
  345.     GU_AlignTop (UWORD id)
  346.         Align the top edge of the gadget with another gadgets top edge.
  347.  
  348.     GU_AdjustTop (WORD add)
  349.         Add the height of the text font + ti_Data to the top edge.
  350.  
  351.     GU_AddTopLines (WORD numlines)
  352.         Add the height of ti_Data/2 lines to the final top edge. The
  353.         numlines argument is given in units of 1/2 lines to get better
  354.         resolution (ti_Data of 4 means that the height of 2 lines
  355.         should be added).
  356.  
  357. Gadget bottom edge control:
  358.  
  359.     GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
  360.     gadget, and allows any top edge control tag to adjust the height, so that
  361.     both top and bottom edges will be correct.
  362.  
  363.     GU_Bottom (UWORD ypos)
  364.         Absolute bottom edge of the gadget. Not recommended to use for other
  365.         gadgets than the bottom-most gadgets. Should not be necessary to use
  366.         at all.
  367.  
  368.     GU_BottomRel (UWORD id)
  369.         Make the bottom edge relative to another gadgets top edge. This
  370.         gadget will be placed ABOVE the given gadget.
  371.  
  372.     GU_AddBottom (WORD add)
  373.         Add ti_Data to the final bottom edge calculation.
  374.  
  375.     GU_AlignBottom (UWORD id)
  376.         Align the bottom edge of the gadget with another gadgets bottom edge.
  377.  
  378.     GU_AdjustBottom (WORD add)
  379.         Subtract the height of the gadget's font + ti_Data from the top edge.
  380.         This will move the gadget UPWARDS (ti_Data + font height) pixels.
  381.  
  382. Gadget left edge control:
  383.  
  384.     GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
  385.     and allows any right edge control tag to adjust the width, so that both
  386.     left and right edges will be correct.
  387.  
  388.     GU_Left (UWORD xpos)
  389.         Absoulute left edge of the gadget. Not recommended to use for other
  390.         gadgets than the left-most gadgets.
  391.  
  392.     GU_LeftRel (UWORD id)
  393.         Make the left edge relative to another gadgets right edge. This
  394.         gadget will be placed TO THE RIGHT of the given gadget.
  395.  
  396.     GU_AddLeft (WORD add)
  397.         Add ti_Data to the final left edge calculation.
  398.  
  399.     GU_AlignLeft (UWORD id)
  400.         Align the left edge of the gadget with another gadgets left edge.
  401.  
  402.     GU_AdjustLeft (WORD add)
  403.         Add the width of the gadget label + ti_Data to the left edge.
  404.  
  405.     GU_AddLeftChar (WORD chars)
  406.         Add the length of ti_Data characters to the left edge.
  407.  
  408. Gadget right edge control:
  409.  
  410.     GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
  411.     gadget, and allows any left edge control tag to adjust the width, so
  412.     that both left and right edges will be correct.
  413.  
  414.     GU_Right (UWORD xpos)
  415.         Absoulute right edge of the gadget. Not recommended to use for other
  416.         gadgets than the right-most gadgets. Should not be necessary to use
  417.         at all.
  418.  
  419.     GU_RightRel (UWORD id)
  420.         Make the right edge relative to another gadgets left edge. This
  421.         gadget will be placed TO THE LEFT of the given gadget.
  422.  
  423.     GU_AddRight (WORD add)
  424.         Add ti_Data to the final right edge calculation.
  425.  
  426.     GU_AlignRight (UWORD id)
  427.         Align the right edge of the gadget with another gadgets right edge.
  428.  
  429.     GU_AdjustRight (WORD add)
  430.         Add the width of the gadget label + ti_Data to the left edge.
  431.  
  432. Other tags:
  433.  
  434.     GU_ToggleSelect (BOOL)
  435.         Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
  436.         gadgets.
  437.  
  438.     GU_Selected (BOOL)
  439.         Set the initial value of a toggle select gadget.
  440.  
  441.     GU_Hotkey (CHAR)
  442.         Hotkey that should simulate a press (release) of a gadget.
  443.  
  444.     GU_HotkeyCase (BOOL)
  445.         Make the hotkey case-sensitive. Default is not case sensitive.
  446.  
  447.     GU_LabelHotkey (BOOL)
  448.         Get the hotkey directly from the gadget's label. The hotkey can
  449.         be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
  450.  
  451.     GU_RawKey (BYTE)
  452.         Use a rawkey as a gadget hotkey. May not be case-sensitive.
  453.         
  454. Tags that gives access to other fields in the NewGadget structure:
  455.  
  456.     GU_GadgetText (UBYTE *)
  457.         A pointer to the gadget's label. Will be copied directly into the
  458.         gng_GadgetText field of the NewGadget structure.
  459.  
  460.     GU_TextAttr (struct TextAttr *)
  461.         A pointer to an initialized TextAttr structure (to select the font).
  462.         Will be copied directly into the gng_TextAttr field of the NewGadget
  463.         structure.
  464.  
  465.     GU_Flags (ULONG)
  466.         Gadget flags. Currently available flags are as for GadTools, but
  467.         here is a short list of them:
  468.  
  469.         PLACETEXT_LEFT - Place the gadget label right aligned on the left
  470.                          side of the gadget.
  471.  
  472.         PLACETEXT_RIGHT - Place the gadget label left aligned on the right
  473.                           side of the gadget.
  474.  
  475.         PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
  476.  
  477.         PLACETEXT_BELOW - Place the gadget label centered below the gadget.
  478.  
  479.         PLACETEXT_IN - Place the gadget label centered inside the gadget.
  480.  
  481.         NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
  482.  
  483.     GU_UserData (APTR)
  484.         Storage for your own data. Will probably be removed, since GadUtil
  485.         uses this filed for an internal structure (with some external
  486.         available fields).
  487.  
  488.     GU_LocaleText (ULONG stringid)
  489.         Get gadget label from a catalog. This allows easy localization of
  490.         all new programs.
  491.  
  492. Tags that should be passed directly to GU_LayoutGadgetsA():
  493.  
  494.     GU_RightExtreme (ULONG *)
  495.         A pointer to a longword that is used to store the rightmost point
  496.         that a gadget will exist in.
  497.  
  498.     GU_LowerExtreme (ULONG *)
  499.         A pointer to a longword that is used to store the lowermost point
  500.         that a gadget woll exist in.
  501.  
  502.     GU_Catalog (struct Catalog *)
  503.         A pointer to the programs translation catalog. NULL indicates that
  504.         the program should use the internal strings. You must open the
  505.         catalog by yourself (use GU_OpenCatalog() or locale/OpenCatalog).
  506.         The GU_AppStrings tag MUST be used together with this tag.
  507.  
  508.     GU_DefTextAttr (struct TextAttr *)
  509.         Specifies the default font to use with all gadgets. Can be over-
  510.         ridden with GU_TextAttr tag for each gadget.
  511.  
  512.     GU_AppStrings (struct AppString *)
  513.         A pointer to an array of AppString structures. These strutures
  514.         contains the programs internal strings.
  515.         This tag must be used together with the GU_Catalog tag.
  516.  
  517.     GU_BorderLeft (ULONG)
  518.         Size of the window's left border.
  519.  
  520.     GU_BorderTop (ULONG)
  521.         Size of the window's top border.
  522.  
  523.     GU_NoCreate (BOOL)
  524.         Don't create any gadgets. Useful to determine if the window will
  525.         fit on the screen etc.
  526.  
  527.     GU_MinimumIDCMP (ULONG *)
  528.         A pointer to a longword that is used to store the minimum required
  529.         IDCMP flags, so that all gadgets will work. The longword can already
  530.         be initialized, and any new needed IDCMP flags will be appended to
  531.         that longword.
  532.