Home  /  Autodocs

button.gadget

create button BOOPSI objects

FUNCTIONS

BUTTON_GetClass

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:

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)
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) (V47)

BUTTON_Integer (int)
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) (V42)

BUTTON_BitMap (struct BitMap *)
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) (V42)

BUTTON_AnimButton (BOOL)
Is button animatable? Use to turn animating on or off.

Defaults to FALSE.

Applicability is (OM_NEW, OM_SET)

BUTTON_AnimImages (struct Image *)
Sets an array of struct Images for animation

Defaults to NULL.

Applicability is (OM_NEW, OM_SET) (V42)

BUTTON_SelAnimImages (struct Image *)
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) (V42)

BUTTON_MaxAnimImages (LONG)
Number of images available in the arrays.

Defaults to 0.

Applicability is (OM_NEW, OM_SET) (V42)

BUTTON_AnimImageNumber (LONG)
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) (V42)

BUTTON_AddAnimImageNumber (ULONG)
Value to be added to the current image number counter. The counter will wrap around at MaxAnimImages.

Applicability is (OM_SET, OM_UPDATE) (V42)

BUTTON_SubAnimImageNumber (ULONG)
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) (V42)

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.