NAME
GU_LayoutGadgetsA -- Formats an array of GadTools gadgets.
SYNOPSIS
gad_info = GU_LayoutGadgetsA(gad_list, gadgets, screen, taglist)
D0,A0 A0 A1 A2 A3
APTR GU_LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
struct Screen *, struct TagItem *);
FUNCTION
Creates a laid-out gadget list from a LayoutGadget array, which
describes each gadget you want to create. Gadgets you create can
be any of the gadget kinds supported by GadTools, as well as any
of the extended gadget kinds provided by GadUtil.
The gadgets created by this routine, can easily be defined so that
they adjust their sizes and positions to accomodate fonts of any
size, and also adapt to different locale strings.
INPUTS
gad_list - a pointer to the gadget list pointer. This will be
ready to pass to OpenWindowTagList() or AddGList().
gadgets - an array of LayoutGadget structures. Each element in
the array describes one of the gadgets that you will
be creating. Each LayoutGadget structure in the array
should be initialized as follows:
lg_GadgetID - the ID for this gadget. An ID of -1
terminates the array. Don't use gadget ID's
in the range 65000(-536) to 65535 (-1). These
may be used internally in later versions of
GadUtil.
lg_LayoutTags - tags that describes each gadget to
create. These tags is used to calculate
positions, sizes and other attributes
of the created gadgets.
lg_GadToolsTags - additional tags for GadTools gadgets.
This would be the same set of tags that
you might pass to CreateGadgetA() if
you were using GadTools directly.
lg_Gadget - the pointer to the Gadget structure created
for this gadget will be placed here. You
should initialize this field to NULL. The
gadget structure created should be considered
READ ONLY! This field will contain a pointer
to a struct BBoxData, if the created gadget
kind is a BEVELBOX_KIND or a LABEL_KIND.
PROGRESS_KIND gadgets will store a pointer to
a ProgressGad structure here.
Assembly language programmers can use the macro GADGET:
GADGET GadgetID, Gad_LayoutTags, Gad_GadToolsTags
screen - a pointer to the screen that the gadgets will be created
for. This is required, so that the layuot routines can
get display info about the screen where the rendering
will be done. Use LockPubScreen() to use a public screen,
or OpenScreenTagList(), if you want to use your own screen.
taglist - pointer to an array of tags providing optional extra
parameters, or NULL.
These tags can be used here:
GU_RightExtreme (ULONG *)
A pointer to a longword that is used to store the
rightmost point that a gadget will exist in.
GU_LowerExtreme (ULONG *)
A pointer to a longword that is used to store the
lowermost point that a gadget woll exist in.
GU_Catalog (struct Catalog *)
A pointer to the programs translation catalog. NULL
indicates that the program should use the internal
strings. You must open the catalog by yourself (use
GU_OpenCatalog() or locale/OpenCatalog). The
GU_AppStrings tag MUST be used together with this tag.
GU_DefTextAttr (struct TextAttr *)
Specifies the default font to use with all gadgets. Can
be overridden with GU_TextAttr tag for each gadget.
GU_AppStrings (struct AppString *)
A pointer to an array of AppString structures. These
strutures contains the programs internal strings. This
tag must be used together with the GU_Catalog tag.
GU_BorderLeft (ULONG)
Size of the window's left border.
GU_BorderTop (ULONG)
Size of the window's top border.
GU_NoCreate (BOOL)
Don't create any gadgets. Useful to determine if the
window will fit on the screen etc. As of version 37.10 this
tag is also available in the gadget tags, making only one
gadget invisible at the time.
GU_MinimumIDCMP (ULONG *)
A pointer to a longword that is used to store the
minimum required IDCMP flags, so that all gadgets will
work. The longword can already be initialized, and any
new needed IDCMP flags will be appended to that
longword.
GU_DefWTitle (UBYTE *)
The text to show in the window title when the mouse pointer
is outside all objects (gadgets, strings, bevelboxes etc.)
that have a help string.
GU_DefLocWTitle (ULONG stringid)
Localized version of GU_DefWTitle. The ti_Data is a string ID
to be read from the locale catalog.
GU_DefSTitle (UBYTE *)
The text to show in the window's active screen title when the
mouse pointer is outside all objects that have a help string.
GU_DefLocSTitle (ULONG stringid)
Localized version of GU_DefSTitle. The ti_Data is a string ID
to be read from the locale catalog.
GU_DefHelpText (UBYTE *)
The text to show in the rest of the help display objects when
the mouse pointer is outside all objects that have a help
string.
GU_DefLocHelpText (ULONG stringid)
Localized version of GU_DefHelpText. The ti_Data is a string
ID to be read from the locale catalog.
TAGS
Tags for the gadgets lg_LayoutTags taglist. The other tags can be found in
the autodoc to gadtools.library/CreateGadgetA().
GU_GadgetKind (ULONG)
Can be any of the standard GadTools gadget kinds, or one of the
extensions provided by GadUtil. Currently extended types are:
IMAGE_KIND
A gadget that uses an Intuition Image structure for its
contents. Selected and unselected states can use different
images. The images are centered automatically.
The value in the LayoutGadget's lg_Gadget field is a pointer to
a Gadget structure.
Extra tags for IMAGE_KIND:
GUIM_Image (struct Image *)
Image for the gadget in its unselected state. This is
the only required (extra) tag for IMAGE_KIND gadgets.
GUIM_SelectImg (struct Image *)
Image for the gadget in its selected state. If this tag
is omitted, the selected image will be the same as the
unselected, and only the border and the background color
will change (depending on the GUIM_BOOPSILook tag).
GUIM_ReadOnly (BOOL)
TRUE to create a read-only image gadget.
GUIM_BOOPSILook (BOOL)
This tag will allow the programmer to select how the
secondary image should be shown, if only one image is
used for the gadget. Defaults to TRUE, which means that
the background color will change when the user selects
the gadget.
DRAWER_KIND
A "select drawer" image button. This can be used to select
a path, but is often used to select files.
The value in the LayoutGadget's lg_Gadget field is a pointer to
a Gadget structure.
FILE_KIND
A "select file" image button. This can be used to allow the
user to select a file. Most programs uses the DRAWER_KIND
for both file and path selection.
The value in the LayoutGadget's lg_Gadget field is a pointer to
a Gadget structure.
BEVELBOX_KIND
A GadTools bevelbox. Use this to avoid the use of absolute
sizing of bevelboxes. All bevel box kinds from OS3.0 is
supported, even if the computer only has OS2.0.
The function GU_RefreshBoxes() can be used to redraw all
bevelboxes.
The value in the LayoutGadget's lg_Gadget field is a pointer to
a BBoxData structure.
Extra tags for BEVELBOX_KIND:
GUBB_Recessed (BOOL)
Create a recessed ("pushed in") bevel box. Differs from
the GadTools tag GTBB_Recessed, in that it works with
both TRUE and FALSE as parameter. GadTools creates a
recessed box independent from the given value.
Defaults to FALSE.
GUBB_FrameType (ULONG)
Determines what kind of box this function renders. The
current available alternatives are:
BFT_BUTTON - Generates a box like what is used around
a GadTools BUTTON_KIND gadget.
BFT_RIDGE - Generates a box like what is used around
a GadTools STRING_KIND gadget.
BFT_DROPBOX - Generates a box suitable for a standard
icon drop box imagery.
BFT_HORIZBAR - Generates a horizontal shadowed line.
Can also be used to draw a normal line,
using 1 for the line's height.
BFT_VERTBAR - Generates a vertical shadowed line. Can
also be used to draw a normal line, using
1 for the line's width.
Defaults to BFT_BUTTON.
GUBB_TextColor (ULONG)
Selects which color to print the title text in. Only useful
for a bevelbox with a title. Defaults to the color of the
TEXTPEN.
GUBB_TextPen (ULONG)
Selects which pen to print the title text in. Only
useful for a bevelbox with a title. Defaults to TEXTPEN.
This tag overrides the GUBB_TextColor tag.
GUBB_Flags (ULONG)
Flags for text placement, text shadowing and 3D text:
Y-pos flags
~~~~~~~~~~~
BB_TEXT_ABOVE - Places the bevel box text above the upper
border of the box ___Example___
BB_TEXT_IN - Places the bevel box text at the upper
border of the box ---Example---
BB_TEXT_BELOW - Places the bevel box text below the upper
border of the box ___ ___
Example
X-pos flags
~~~~~~~~~~~
BB_TEXT_CENTER - Places the bevel box text in the middle
of the upper border ---Example---
BB_TEXT_LEFT - Places the bevel box text 8 pixels from
the left edge of the box -Example-----
BB_TEXT_RIGHT - Places the bevel box text 8 pixels from
the right edge of the box -----Example-
Combined flags
~~~~~~~~~~~~~~
BB_TEXT_ABOVE_CENTER - BB_TEXT_ABOVE + BB_TEXT_CENTER
BB_TEXT_ABOVE_LEFT - BB_TEXT_ABOVE + BB_TEXT_LEFT
BB_TEXT_ABOVE_RIGHT - BB_TEXT_ABOVE + BB_TEXT_RIGHT
BB_TEXT_IN_CENTER - BB_TEXT_IN + BB_TEXT_CENTER
BB_TEXT_IN_LEFT - BB_TEXT_IN + BB_TEXT_LEFT
BB_TEXT_IN_RIGHT - BB_TEXT_IN + BB_TEXT_RIGHT
BB_TEXT_BELOW_CENTER - BB_TEXT_BELOW + BB_TEXT_CENTER
BB_TEXT_BELOW_LEFT - BB_TEXT_BELOW + BB_TEXT_LEFT
BB_TEXT_BELOW_RIGHT - BB_TEXT_BELOW + BB_TEXT_RIGHT
Default is BB_TEXT_ABOVE|BB_TEXT_CENTER. Combine the x and y
position flags by OR:ing them together. Don't combine two X
or two Y flags together.
Shadow placement flags
~~~~~~~~~~~~~~~~~~~~~~
BB_SHADOW_DR - Places the bevel box text shadow one pixel
below and to the right of the text.
BB_SHADOW_UR - Places the bevel box text shadow one pixel
above and to the right of the text.
BB_SHADOW_DL - Places the bevel box text shadow one pixel
below and to the left of the text.
BB_SHADOW_UL - Places the bevel box text shadow one pixel
above and to the left of the text.
BB_SUNAT_UL - Another name for BB_SHADOW_DR
BB_SUNAT_DL - Another name for BB_SHADOW_UR
BB_SUNAT_UR - Another name for BB_SHADOW_DL
BB_SUNAT_DR - Another name for BB_SHADOW_UL
Default is BB_SHADOW_DR (BB_SUNAT_UL).
BB_3DTEXT - This flag can be used in place of the tag
GUBB_3DText, TRUE
GUBB_3DText (BOOL)
Enables the shadow on the bevel box text. This tag must be
used if GUBB_ShadowColor or GUBB_ShadowPen isn't used.
Another way to enable 3D text is to set the flag BB_3DTEXT
in the GUBB_Flags tag.
GUBB_ShadowColor (ULONG)
Selects which color to print the shadow text in. Only useful
for a bevelbox with a title. Defaults to the color of the
SHADOWPEN.
GUBB_ShadowPen (ULONG)
Selects which pen to print the shadow text in. Only useful
for a bevelbox with a title. Defaults to SHADOWPEN.
This tag overrides the GUBB_ShadowColor tag.
PROGRESS_KIND
Gadget used to display a value out of a total. Can be used to
display the progress of a search, a diskcopy or anything else.
The value in the LayoutGadget's lg_Gadget field is a pointer to
a ProgressGad structure.
Extra tags for PROGRESS_KIND:
GUPR_FillColor (ULONG)
Selects which color to use to paint the current value of
the progress requester with. Defaults to the color of the
FILLPEN.
GUPR_FillPen (ULONG)
Selects which pen to use to paint the current value of
the progress requester with. Defaults to the FILLPEN.
This tag overrides the GUPR_FillColor tag.
GUPR_BackColor (ULONG)
Selects which color to fill the background of the progress
requester with. Defaults to the color of the BACKGROUNDPEN.
GUPR_BackPen (ULONG)
Selects which pen to fill the background of the progress
requester with. Defaults to the BACKGROUNDPEN.
This tag overrides the GUPR_BackColor tag.
GUPR_Current (ULONG)
The initial current value of the progress requester. The
gadget's current value may be changed later by directly
modifying the pg_Current field of the ProgressGad structure.
Use GU_UpdateProgress to redraw the progress requester with
the new value. The pg_Current field must not be larger than
4.294.967.295 / the width of the progress gadget. A "normal"
width of 410 pixels allows a current value of 10.737.418.
Defaults to 0.
GUPR_Total (ULONG)
The initial total value of the progress requester. The
gadget's total value may be changed later by directly
modifying the pg_Total field of the ProgressGad structure.
Use GU_UpdateProgress() to redraw the progress requester with
the new value. The total value can be as large as a longword
allows (4.294.967.295), but you can't display a current value
larger than 4.294.967.295 / the width of the progress gadget.
Defaults to 100.
LABEL_KIND
A text label. Use this to avoid the use of absolute placement
of text that you print into the window. Supports the most of
the text placement and shadow flags for the BEVELBOX_KIND.
The function GU_RefreshBoxes() can be used to redraw all
text created by LABEL_KIND gadgets.
The value in the LayoutGadget's lg_Gadget field is a pointer to
a BBoxData structure.
Extra tags for LABEL_KIND:
GULB_TextColor (ULONG)
Selects which color to print the text in. Defaults to the
color of the TEXTPEN.
GULB_TextPen (ULONG)
Selects which pen to print the text in. Defaults to TEXTPEN.
This tag overrides the GULB_TextColor tag.
GULB_Flags (ULONG)
Flags for text placement, text shadowing and 3D text:
___1_____2_____3___
|_____|_____|_____| A
|_____|_____|_____| B
|_____|_____|_____| C
Y-pos flags
~~~~~~~~~~~
LB_TEXT_TOP - Places the topmost point of the text below
the upper border of the box (row A)
LB_TEXT_MIDDLE - Places the text centered in the box, not
counting in the part of the text that is
below the font's baseline (row B)
LB_TEXT_BOTTOM - Places the text at the bottom of the box.
Any part of the text that is below the
baseline will be below the box (row C)
X-pos flags
~~~~~~~~~~~
LB_TEXT_CENTER - Places the text centered on the width of
the box (column 2).
LB_TEXT_LEFT - Places the text left adjusted in the box
(column 1)
LB_TEXT_RIGHT - Places the text right adjusted in the box
(column 3)
Combined flags
~~~~~~~~~~~~~~
LB_TEXT_TOP_CENTER - LB_TEXT_TOP + LB_TEXT_CENTER
LB_TEXT_TOP_LEFT - LB_TEXT_TOP + LB_TEXT_LEFT
LB_TEXT_TOP_RIGHT - LB_TEXT_TOP + LB_TEXT_RIGHT
LB_TEXT_MIDDLE_CENTER - LB_TEXT_MIDDLE + LB_TEXT_CENTER
LB_TEXT_MIDDLE_LEFT - LB_TEXT_MIDDLE + LB_TEXT_LEFT
LB_TEXT_MIDDLE_RIGHT - LB_TEXT_MIDDLE + LB_TEXT_RIGHT
LB_TEXT_BOTTOM_CENTER - LB_TEXT_BOTTOM + LB_TEXT_CENTER
LB_TEXT_BOTTOM_LEFT - LB_TEXT_BOTTOM + LB_TEXT_LEFT
LB_TEXT_BOTTOM_RIGHT - LB_TEXT_BOTTOM + LB_TEXT_RIGHT
Default is LB_TEXT_TOP|LB_TEXT_CENTER. Combine the x and y
position flags by OR:ing them together. Don't combine two X
or two Y flags together.
Shadow placement flags
~~~~~~~~~~~~~~~~~~~~~~
LB_SHADOW_DR - Places the bevel box text shadow one pixel
below and to the right of the text.
LB_SHADOW_UR - Places the bevel box text shadow one pixel
above and to the right of the text.
LB_SHADOW_DL - Places the bevel box text shadow one pixel
below and to the left of the text.
LB_SHADOW_UL - Places the bevel box text shadow one pixel
above and to the left of the text.
LB_SUNAT_UL - Another name for LB_SHADOW_DR
LB_SUNAT_DL - Another name for LB_SHADOW_UR
LB_SUNAT_UR - Another name for LB_SHADOW_DL
LB_SUNAT_DR - Another name for LB_SHADOW_UL
Default is LB_SHADOW_DR (LB_SUNAT_UL).
LB_3DTEXT - This flag can be used in place of the tag
GULB_3DText, TRUE
GULB_3DText (BOOL)
Enables the shadow on the text. This tag must be used if
GULB_ShadowColor or GULB_ShadowPen isn't used. Another
way to enable 3D text is to set the flag LB_3DTEXT in the
GULB_Flags tag.
GULB_ShadowColor (ULONG)
Selects which color to print the shadow text in. Defaults to
the color of the SHADOWPEN.
GULB_ShadowPen (ULONG)
Selects which pen to print the shadow text in. Defaults to
SHADOWPEN. This tag overrides the GULB_ShadowColor tag.
Changed tags, and additions to GadTools:
LISTVIEW_KIND
GTLV_ShowSelected (UWORD id)
This tag was changed, so that you don't have to create the
string gadget before all other gadgets. The difference from
this tag in GadTools, is that we now have to give the ID of
the string gadget to use to show the selected item.
An example of a valid (and probably most useful) gadget to
use for GTLV_ShowSelected:
ShowSelGad:
dc.l GU_GadgetKind, STRING_KIND, GU_AutoHeight, 4
dc.l GU_DupeWidth, GAD_LISTVIEW, GU_GadgetText, NULL
dc.l TAG_DONE
This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
array.
Special:
ti_Data = -1 Creates a read-only gadget below the listview,
same as for GTLV_ShowSelected, 0 for GadTools.
ti_Data = x Gadget ID for the gadget that the selected item
should be displayed in. Same as GadTools reaction
on a gadget pointer in ti_Data.
This gadget's ti_Data field will be changed during the creation
of the gadget, but will be changed back before GU_LayoutGadgets
returns.
MX_KIND
The gng_GadgetText field in the NewGadget structure can be used
even with MX_KIND gadgets. This should have been included in
GadTools. The gadget text will always be placed ABOVE the gadget,
on the same side as the other texts for the gadget. Positions are
checked against WBPattern & SerialPrefs to get them "right". The
GU_GadgetText and GU_LocaleText tags are used to access this field.
Tags for all gadget kinds:
Gadget width control:
GU_Width (UWORD wid)
Absolute width of the gadget. Not recommended to use for other
gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
GU_DupeWidth (UWORD id)
Duplicate the width of another gadget.
GU_AutoWidth (WORD add)
Width = length of text label + ti_Data. For CYCLE_KIND gadgets,
the gadget width will be calculated by checking the length of
all alternatives and using the one that is widest + 26 as width.
GU_Columns (UWORD numcols)
Set the gadget width so that approximately ti_Data columns of
text will fit.
GU_AddWidth (WORD add)
Add ti_Data to the total width calculation.
GU_MinWidth (UWORD wid)
Make the gadget at least ti_Data pixels wide.
GU_MaxWidth (UWORD wid)
Make the gadget at most ti_Data pixels wide.
GU_AddWidChar (WORD chars)
Add the length of ti_Data characters to the total width calculation.
GU_FractWidth (LONG parts)
Divide or multiply the gadget's width with ti_Data. A positive
value divides the gadget's width by the ti_Data, a negative ti_Data
multiplies the gadget's width with ti_Data.
Gadget height control:
GU_Height (UWORD hei)
Absolute height of the gadget. Not recommended to use for other
gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
GU_DupeHeight (UWORD id)
Duplicate the height of another gadget.
GU_AutoHeight (WORD add)
Height = height of the gadget's font + ti_Data. This tag doesn't
work as it should with MX_KIND gadgets. Will be fixed later.
Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
GU_HeightFactor (UWORD numlines)
Set the gadget height to approximately ti_Data lines.
GU_AddHeight (WORD add)
Add ti_Data to the total height calculation.
GU_MinHeight (UWORD wid)
Make the gadget at least ti_Data pixels high.
GU_MaxHeight (UWORD wid)
Make the gadget at most ti_Data pixels high.
GU_AddHeiLines (WORD numlines)
Add the height of ti_Data/2 lines to the final height calculation.
The numlines argument is given in units of 1/2 lines to get
better resolution (ti_Data of 4 means that the height of 2
lines should be added).
GU_FractHeight (LONG parts)
Divide or multiply the gadget's height with ti_Data. A positive
value divides the gadget's height by the ti_Data, a negative ti_Data
multiplies the gadget's height with ti_Data.
Gadget top edge control:
GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
allows any bottom edge control tag to adjust the height, so that both
top and bottom edges will be correct.
GU_Top (UWORD ypos)
Absolute top edge of the gadget. Not recommended to use for other
gadgets than the top-most gadgets.
GU_TopRel (UWORD id)
Make the top edge relative to another gadgets bottom edge. This
gadget will be placed BELOW the given gadget.
GU_AddTop (WORD add)
Add ti_Data to the final top edge calculation.
GU_AlignTop (UWORD id)
Align the top edge of the gadget with another gadgets top edge.
GU_AdjustTop (WORD add)
Add the height of the text font + ti_Data to the top edge.
GU_AddTopLines (WORD numlines)
Add the height of ti_Data/2 lines to the final top edge. The
numlines argument is given in units of 1/2 lines to get better
resolution (ti_Data of 4 means that the height of 2 lines
should be added).
Gadget bottom edge control:
GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
gadget, and allows any top edge control tag to adjust the height, so that
both top and bottom edges will be correct.
GU_Bottom (UWORD ypos)
Absolute bottom edge of the gadget. Not recommended to use for other
gadgets than the bottom-most gadgets. Should not be necessary to use
at all.
GU_BottomRel (UWORD id)
Make the bottom edge relative to another gadgets top edge. This
gadget will be placed ABOVE the given gadget.
GU_AddBottom (WORD add)
Add ti_Data to the final bottom edge calculation.
GU_AlignBottom (UWORD id)
Align the bottom edge of the gadget with another gadgets bottom edge.
GU_AdjustBottom (WORD add)
Subtract the height of the gadget's font + ti_Data from the top edge.
This will move the gadget UPWARDS (ti_Data + font height) pixels.
Gadget left edge control:
GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
and allows any right edge control tag to adjust the width, so that both
left and right edges will be correct.
GU_Left (UWORD xpos)
Absoulute left edge of the gadget. Not recommended to use for other
gadgets than the left-most gadgets.
GU_LeftRel (UWORD id)
Make the left edge relative to another gadgets right edge. This
gadget will be placed TO THE RIGHT of the given gadget.
GU_AddLeft (WORD add)
Add ti_Data to the final left edge calculation.
GU_AlignLeft (UWORD id)
Align the left edge of the gadget with another gadgets left edge.
GU_AdjustLeft (WORD add)
Add the width of the gadget label + ti_Data to the left edge.
GU_AddLeftChar (WORD chars)
Add the length of ti_Data characters to the left edge.
Gadget right edge control:
GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
gadget, and allows any left edge control tag to adjust the width, so
that both left and right edges will be correct.
GU_Right (UWORD xpos)
Absoulute right edge of the gadget. Not recommended to use for other
gadgets than the right-most gadgets. Should not be necessary to use
at all.
GU_RightRel (UWORD id)
Make the right edge relative to another gadgets left edge. This
gadget will be placed TO THE LEFT of the given gadget.
GU_AddRight (WORD add)
Add ti_Data to the final right edge calculation.
GU_AlignRight (UWORD id)
Align the right edge of the gadget with another gadgets right edge.
GU_AdjustRight (WORD add)
Add the width of the gadget label + ti_Data to the left edge.
Other tags:
GU_ToggleSelect (BOOL)
Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
gadgets.
GU_Selected (BOOL)
Set the initial value of a toggle select gadget.
GU_Hotkey (CHAR)
Hotkey that should simulate a press (release) of a gadget.
GU_HotkeyCase (BOOL)
Make the hotkey case-sensitive. Default is not case sensitive.
GU_LabelHotkey (BOOL)
Get the hotkey directly from the gadget's label. The hotkey can
be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
GU_RawKey (BOOL)
Use a rawkey as a gadget hotkey. May not be case-sensitive.
GU_HelpGadget (ULONG)
GadgetID of the TEXT_KIND or the STRING_KIND to show the gadget's
help text in. There exists two "special" GadgetID's that can be
used with this tag:
WINTITLE_HELP - shows the help text in the windows's titlebar.
SCRTITLE_HELP - shows the help text in the screen's titlebar.
These tags won't work if your window doesn't use the WFLG_REPORTMOUSE
(or the tag WA_ReportMouse, TRUE). The IDCMP is handled automatically
if you use the layout tag GU_MinimumIDCMP, otherwise you'll have to
use IDCMP_MOUSEMOVE in your IDCMP mask.
Beginning with v37.9 of GadUtil, it is possible to set default strings
for the help display objects. See the explanation of the tags passed to
this function (the taglist parameter) for more info about the default
strings.
GU_HelpText (UBYTE *)
The text that is shown in the help gadget (GU_HelpGadget) when the
mouse pointer is placed on the gadget.
GU_LocaleHelp (ULONG stringid)
Get gadget help text from a catalog. This makes it easy to create
localized help strings in the program.
GU_NoCreate (BOOL)
Don't create this gadget. Useful if you need invisible objects in
the window for layout purposes.
GU_StoreLeft (UWORD *)
Store the gadget's calculated left edge in the word that ti_Data
points to.
GU_StoreTop (UWORD *)
Store the gadget's calculated top edge in the word that ti_Data
points to.
GU_StoreWidth (UWORD *)
Store the gadget's calculated width in the word that ti_Data
points to.
GU_StoreHeight (UWORD *)
Store the gadget's calculated height in the word that ti_Data
points to.
GU_StoreRight (UWORD *)
Store the gadget's calculated right edge in the word that ti_Data
points to.
GU_StoreBottom (UWORD *)
Store the gadget's calculated bottom edge in the word that ti_Data
points to.
Tags that gives access to other fields in the NewGadget structure:
GU_GadgetText (UBYTE *)
A pointer to the gadget's label. Will be copied directly into the
gng_GadgetText field of the NewGadget structure.
GU_TextAttr (struct TextAttr *)
A pointer to an initialized TextAttr structure (to select the font).
Will be copied directly into the gng_TextAttr field of the NewGadget
structure.
GU_Flags (ULONG)
Gadget flags. Currently available flags are as for GadTools, but
here is a short list of them:
PLACETEXT_LEFT - Place the gadget label right aligned on the left
side of the gadget.
PLACETEXT_RIGHT - Place the gadget label left aligned on the right
side of the gadget.
PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
PLACETEXT_BELOW - Place the gadget label centered below the gadget.
PLACETEXT_IN - Place the gadget label centered inside the gadget.
NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
*** GU_UserData (APTR) *** REMOVED in v37.7 ***
GU_LocaleText (ULONG stringid)
Get gadget label from a catalog. This allows easy localization of
all new programs.
RESULT
gad_info - a pointer to a private structure. You must keep this
value and pass it to GU_FreeLayoutGadgets() later on
in order to free up all resources used by your gadgets.
This pointer is also used in a lot of other functions
in this library.
The UserData pointer of all created gadgets will contain a pointer
to a GU_Public structure. You can use this structure to obtain some
info about the gadget, such as current, max and minimum values.
The gu_MaxVal, gu_MinVal, and gu_Active fields are kind specific:
MX_KIND: gu_Active = the selected entry (GTMX_Active)
gu_MaxVal = number of choices - 1
gu_MinVal = 0
SLIDER_KIND: gu_Active = the selected value (GTSL_Level)
gu_MaxVal = maximum allowed value (GTSL_Max)
gu_MinVal = minimum allowed value (GTSL_Min)
CYCLE_KIND: gu_Active = the selected entry (GTCY_Active)
gu_MaxVal = number of choices - 1
gu_MinVal = 0
SCROLLER_KIND: gu_Active = the top value (GTSC_Top)
gu_MaxVal = the total value (GTSC_Total)
gu_MinVal = number visible in scroller (GTSC_Visible)
LISTVIEW_KIND: gu_Active = the selected entry (GTLV_Selected)
gu_MaxVal = number of nodes in list - 1
gu_MinVal = number of visible entries
PALETTE_KIND: gu_Active = the selected color (GTPA_Color)
gu_MaxVal = the maximum color number that can be
selected (GTPA_NumColors, GTPA_Depth^2-1)
gu_MinVal = 0
STRING_KIND: gu_Active = pointer to the string buffer
TEXT_KIND: gu_Active = pointer to the displayed string
INTEGER_KIND: gu_Active = the current displayed/editable number. This
value is _not_ updated if the gadget is
deactivated by clicking outside it.
NUMBER_KIND: gu_Active = the current displayed number
These values are initialized upon creation of the gadget, and updated
automatically when using GU_GetIMsg and GU_SetGadgetAttrsA.
NOTES
You must be careful with the taglist in the lg_LayoutTags field.
Tags are processed sequentally in the order you give them in, and
if a tag references another gadget (eg. the GU_TopRel tag), then
processing of the current gadget halts while the referenced gadget
is processed (if it has not already been processed). Problems can
occur if this gadget refers back to the original gadget that
referenced if, if it is referring to a field that has not yet been
processed in that gadget.
Also note that you do not have to specify any tags that do not
change from gadget to gadget. Just be sure that you know in which
order the gadgets are processed (eg. relatives etc).
Another thing to note, is that we have tried to make the processing
of position and width / height tags as usable as possible, what I
mean with this, is that if you eg first define the left edge and
then define the right edge, the width will change. BUT, there are
special cases when this isn't true. This is because we have tried
out this and decided that this was the best way to do it.
Here comes some examples of the special cases;
dc.l GU_AlignLeft, GAD_1 ; Left edge aligned with GAD_1's left.
dc.l GU_AlignRight, GAD_2 ; This stretches the gadget, so that
; both the left and right edges are
; positioned as defined.
; Then, if we want to move the right edge 2 pixels right, and the left
; edge two pixels right, we might try this:
dc.l GU_AddLeft, -2 ; This works as we want, it moves the
; left edge to the right place, but it
; also moves the whole gadget two
; pixels left..
dc.l GU_AddRight, 2 ; <- This is a common mistake. This
; moves the whole gadget to the right.
; Ie. it is moved back to the old
; position, not as we wanted...
; But if we replace the previous line with the following;
dc.l GU_AddWith,4 ; This works just as we wanted it to.
; Now the gadget should be 4 pixels
; wider, two to the left and two to
; the right.
The same goes for GU_AddHeight and GU_AddBottom etc.
This is actually a feature. Sometimes you might want to move the whole
button, so we made it work this way.
SEE ALSO
GU_FreeLayoutGadgets(), GU_CreateGadgetA(), gadtools/CreateGadgetA()
GU_RefreshWindow(), GU_RefreshBoxes(), GU_UpdateProgress()
Converted on 19 Jul 1996 with RexxDoesAmigaGuide2HTML by Michael Ranner.