button.gadget Reference¶
Comprehensive function reference for button.gadget, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/button).
This page documents 2 functions of button.gadget. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.
Function index¶
button_gc()¶
**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 (since V42).
> Ability to change the text and background colors for normal
and selected buttons.
> Supports window relativity.
> Supports OS 3.0 BOOPSI gadget help test.
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)
Unique ID number for the gadget.
Defaults to 0.
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
BAG_POPUP - generic popup glyph
BAG_POPDATE - popup date glyph (V47)
BAG_POPCOLOR - popup colour glyph (V47)
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 may be 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 BCJ_CENTER.
Applicability is (OM_NEW, OM_SET, OM_UPDATE)
BUTTON_SoftStyle (WORD)
Set the GA_TextAttr font's soft style, ie. BOLD, ITALIC, etc.
See <graphics/text.h> soft style 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 gadget's minimum size. This string is NEVER
rendered on screen. This is useful when you need to create
a button with an empty ("") or NULL string, but want to enforce
minimum size in a layout group based on some initializing
string and the current preferences font, rather than some fixed
pixel or weighted minimum. Added by request.
Defaults to NULL.
Applicability is (OM_NEW, OM_SET)
BUTTON_TextPadding (BOOL) (V47)
If TRUE, add some horizontal padding around the button's text
label for aesthetic reasons. The extra space is (currently)
twice the nominal width of the button's text font.
Defaults to FALSE.
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 size for the 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
Unfortunately, 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 it's 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 immediately.
BUTTON_GetClass()¶
BUTTON_GetClass -- Gets the pointer to the button class.
Synopsis
button_class = BUTTON_GetClass();
D0
Class * BUTTON_GetClass(VOID);
Function
This function is only available in runtime linked version of the
class, and is not in the compiler linker library button_gc.lib.
Obtains the pointer to the Button gadget class for use with
NewObject(). This function always returns a valid pointer so
you do not need to check it. The reason is that if the library
opens fine, then the pointer returned is already setup. (Of course
this implies that if opening the library fails, you shouldn't be
calling this.)
Note that this function does not create the class, that is done
when the class library is opened.
Inputs
Nothing.
RESULT
button_class - Pointer to the Button gadget class.