![[Contents]](../images/toc_d.gif)
![[Index]](../images/index_d.gif)
![[Help]](../images/help_d.gif)
![[Retrace]](../images/retrace_d.gif)
![[Browse <]](../images/prev.gif)
![[Browse >]](../images/next.gif)
NAME
button_gc -- create button BOOPSI objects
SUPERCLASS
gadgetclass
REQUIRES
bevel.image, glyph.image
DESCRIPTION
The button gadget class is used to create action buttons that are
momentary, toggle and sticky. This class also supports relativity
and placement within the window border.
Advantages that this class provides:
> Centered images.
> Centered pen-sensitive glyphs.
> Multi-frame images animation ability (NEW V42)
> Ability to change the text and background colors for normal
and selected buttons.
> Supports window relativity.
> Supports OS 3.0 BOOPSI Gadget HelpTest.
METHODS
OM_NEW -- Passed to superclass, defaults set, then OM_SET.
OM_SET -- Passed to superclass, custom tags set.
OM_GET -- Custom tag returned or passed to superclass.
OM_UPDATE -- Passed to superclass, options set then rendered.
OM_NOTIFY -- Tag set then passed to superclass.
OM_DISPOSE -- MemPool memory freed, then Passed to superclass.
GM_RENDER -- Passed to superclass, then button is rendered.
GM_HITTEST -- Overrides supperclass, returns GMR_HITTEST.
GM_GOACTIVE -- Passed to superclass, button activated.
GM_HANDLEINPUT -- Overrides supperclass, all input processed.
GM_GOINACTIVE -- Passed to superclass, button deactivated.
GM_DOMAIN -- Returns GDOMAIN_MINIMUM and GDOMAIN_MAXIMUM dimensions.
GM_KEYACTIVE -- Private method for keyboard control.
GM_KEYINACTIVE -- Private method for keyboard control.
ATTRIBUTES
GA_ID (WORD)
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET, OM_NOTIFY)
GA_Selected (BOOL)
Determines whether the button is selected or not.
Changing selection state will invoke GM_RENDER.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_GET, OM_NOTIFY)
GA_Disabled (BOOL)
Determines whether the button is disabled or
not. Changing disable state will invoke GM_RENDER. A disabled
button's border and label are all rendered in SHADOWPEN and then
dusted in a ghosting pattern.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_UPDATE, OM_GET, OM_NOTIFY)
GA_Text (STRPTR)
Used to specify the NULL terminated string to use as the text
for the gadget. The Text() function is used to draw the text.
NULL is valid input. Changing the label will invoke GM_RENDER.
Text string is clipped to fit inside the button via the
TextLength() function. The text string may contain varargs
format specifiers compatible to RawDoFmt() if the varargs data
is supplied via BUTTON_VarArgs.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
GA_Image (struct Image *)
Used to specify the image to use for the label of the gadget.
The DrawImageState() function is used to draw the image.
Changing the label will invoke GM_RENDER.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
GA_SelectImage (struct Image *)
Used to specify the image to use for the label of the gadget
in the selected state. The DrawImageState() function is used
to draw the image. Changing the label will invoke GM_RENDER
if the gadget is currently selected.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
GA_TextAttr (struct TextAttr *)
Text attribute for the font to use for the text labels.
Defaults to RPort->Font, which is often the screen or
window preferences font.
Applicability is (OM_NEW, OM_SET)
GA_ReadOnly (BOOL)
Read-only gadgets ignore activation attempts.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_AutoButton (UWORD)
Used to create automatic button with one of the selected
scaled image glyphs. Accepted settings are;
BAG_POPFILE - popup file selection glyph
BAG_POPDRAWER - popup drawer selection glyph
BAG_POPFONT - popup font selection glyph
BAG_CHECKBOX - checkmark glyph (same as checkbox.gadget)
BAG_CANCELBOX - NOT IMPLEMENETED!
BAG_UPARROW - up arrow
BAG_DNARROW - down arrow
BAG_RTARROW - right arrow
BAG_LFARROW - left arrow
BAG_POPTIME - popup time glyph
BAG_POPSCREEN - popup screen mode glyph
Defaults to 0.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_PushButton (BOOL)
Used to indicate that the button stays pressed in when the
user selects it with the mouse. The button may
programmatically be deselected using {GA_Selected, FALSE}.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_TextPen (LONG)
Indicate the pen number used to render the IDS_NORMAL text.
If ~0 is specified, then TEXTPEN is used.
Defaults to ~0.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_BackgroundPen (LONG)
Indicate the pen number used to render the IDS_NORMAL
background. If ~0 is specified, then BACKGROUNDPEN
is used.
Defaults to ~0.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_FillTextPen (LONG)
Indicate the pen number used to render the IDS_SELECTED text.
If ~0 is specified, then FILLTEXTPEN is used.
Defaults to ~0.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_FillPen (LONG)
Indicate the pen number used to render the IDS_SELECTED
background. If ~0 is specified, then FILLPEN is used.
Defaults to ~0.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_BevelStyle (WORD)
Button bevel box rendering style, passed to bevel.image.
Supports:
BVS_NONE
BVS_THIN
BVS_BUTTON
BVS_GROUP
Defaults to BVS_BUTTON.
Applicability is (OM_NEW, OM_SET)
BUTTON_Transparent (BOOL)
Make button background rendering transparent.
EraseRect() is used rather than RectFill() so that
custom backfill rendering hooks maybe utilized.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET)
BUTTON_Justification (WORD)
Justification mode of button text label.
Supports:
BCJ_LEFT
BCJ_CENTER
BCJ_RIGHT
Defaults to BJ_CENTER.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_SoftStyle (WORD)
Set the GA_TextAttr font's softstyle, ie BOLD, ITALICS, etc.
See <graphics/text.h> SoftStyle definitions.
Defaults to 0.
Applicability is (OM_NEW, OM_SET)
BUTTON_VarArgs (APTR)
Varargs data array to supply data for RawDoFmt() when
format specifiers are to be used in GA_Text text strings.
The internal VarArgs result buffer is presently fixed at
a maximum of 128 bytes, take care not to exceed this buffer.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
BUTTON_DomainString (STRPTR)
Used to specify the NULL terminated string to use as the text
to domain the gadgets minimum size. This string is NEVER
rendered on screen. This is useful when you need to create
a button with a empty ("") or NULL string, but want to enforce
minimum size in a layout group based on some initializing
string and the current preferenced font, rather some fixed
pixel or weighted minimum. Added by request.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
BUTTON_Integer (int) (V42)
Set an integer value to display a numeric string. Highly useful
for interconnect notifications from sliders, scrollers, etc.
Added by request.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_BitMap (struct BitMap *) (V42)
Specify a BitMap to render in button, rather than image or
text. Added by request, but use of bitmap.image is highly
recommended for AmigaOS V39 and later.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
BUTTON_AnimButton (BOOL) (V42)
Is button animatable? Use to turn animating on or off.
Defaults to FALSE.
Applicability is (OM_NEW, OM_SET)
BUTTON_AnimImages (struct Image *) (V42)
Sets an array of struct Images for animation
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
BUTTON_SelAnimImages (struct Image *) (V42)
Sets an array of alternate images for a selected state
if used, must contain an equal number of images as the
array used for BUTTON_AnimImages. It's wise to use the
same sized images too
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
BUTTON_MaxAnimImages (LONG) (V42)
Number of images available in the arrays
Defaults to 0.
Applicability is (OM_NEW, OM_SET)
BUTTON_AnimImageNumber (LONG) (V42)
Current image number in the array(s) to use the range of
available frames is 0 .. MaxAnimImages-1
Defaults to 0.
Applicability is (OM_NEW, OM_SET)
BUTTON_AddAnimImageNumber (ULONG) (V42)
Value to be added to the current image number counter
the counter will wrap around at MaxAnimImages
Applicability is (OM_SET, OM_UPDATE)
BUTTON_SubAnimImageNumber (ULONG) (V42)
Value to be subtracted from the current image number counter
the counter will wrap around when less than 0
Applicability is (OM_SET, OM_UPDATE)
BUGS
Unfortunetly, this class shares the same filename and tag range
as the button gadget released by David Junod of C=, released in
the GI1.lha V42 beta archive on BIX, and later the AT DevCD.
We admit it, we screwed up... but its not a majorly serious issue
as this class is atleast 90% compatible.
A few rarely, possibly never, used tags of the original are NOT
currently supported. The usage of BUTTON_PushButton in ReAction is
not totally compatible to Junod's. Ours acts like GA_ToggleSelect
of Junod's.
Please report any incompatibilities immediatly.