DwtToggleButton(3Dwt) DwtToggleButton(3Dwt)
Name
DwtToggleButton, DwtToggleButtonCreate - Creates a toggle button widget for the application to display screen settable switches for the
user.
Syntax
Widget DwtToggleButton(parent_widget, name, x, y,
label, value, callback, help_callback)
Widget parent_widget;
char *name;
Position x, y;
DwtCompString label;
Boolean value;
DwtCallbackPtr callback;
DwtCallbackPtr help_callback;
Widget DwtToggleButtonCreate (parent_widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char *name;
ArgList override_arglist;
int override_argcount;
Arguments
parent_widget
Specifies the parent widget ID.
name Specifies the name of the created widget.
x Specifies the placement, in pixels, of the left side of the widget window relative to the inner upper left corner of the parent
window. This argument sets the DwtNx core widget attribute.
y Specifies, in pixels, the placement of the upper left corner of the widget window relative to the inner upper left corner of the
parent window. This argument sets the DwtNy core widget attribute.
label Specifies the text in the toggle button label/indicator. This argument sets the DwtNlabel attribute associated with DwtLabelCre-
ate.
value Specifies a boolean value that, when False, indicates the button state is off. If True, the button state is on. This argument
sets the DwtNvalue attribute associated with DwtToggleButtonCreate.
callback Specifies the callback function or functions called back when the value of the toggle button changes. This argument sets the
DwtNarmCallback, DwtNdisarmCallback, and DwtNvalueChangedCallback attributes associated with DwtToggleButtonCreate.
help_callback
Specifies the callback function or functions called when a help request is made. This argument sets the DwtNhelpCallback common
widget attribute.
override_arglist
Specifies the application override argument list.
override_argcount
Specifies the number of attributes in the application override argument list (override_arglist).
Description
The DwtToggleButton and DwtToggleButtonCreate functions create an instance of a toggle button widget and return its associated widget ID.
When calling DwtToggleButton, you set the common toggle button widget attributes presented in the formal parameter list. For DwtToggleBut-
tonCreate, however, you specify a list of attribute name/value pairs that represent all the possible toggle button widget attributes.
The toggle button widget consists of either a label and indicator button combination or simply a pixmap (icon). Toggle buttons imply an on
or off state. These functions use their attributes to configure the visual representation, ``looks,'' and the user interface syntax
``feel,'' for the application. Note that the callback data structure includes a value member, which allows the callback data function to
pass the status of the toggle switch back to the application.
The sizing is affected by spacing, font (affects indicator), and label. See the description for DwtLabel and DwtLabelCreate.
The sizing is affected by these attributes: DwtNspacing, DwtNfont (text label), and DwtNlabel. For more information, see DwtLabel and Dwt-
LabelCreate.
The DwtNindicator size is based on the height of the toggle button minus twice the margin height. The DwtNindicator width is equal to the
indicator height.
The default margin height is four pixels. The default margin width is five pixels.
Inherited Attributes
------------------------------------------------------------------
Attribute Name Data Type Default
------------------------------------------------------------------
Core Attributes
DwtNx Position Determined by the geome-
try manager
DwtNy Position Determined by the geome-
try manager
DwtNwidth Dimension Width of the label or
pixmap, plus three times
DwtNmarginWidth, plus
the width of DwtNindica-
tor
DwtNheight Dimension The height of the label
or pixmap, plus two
times DwtNmarginHeight
DwtNborderWidth Dimension zero pixels
DwtNborder Pixel Default foreground color
DwtNborderPixmap Pixmap NULL
DwtNbackground Pixel Default background color
DwtNbackgroundPixmap Pixmap NULL
DwtNcolormap Colormap Default color map
DwtNsensitive Boolean True
DwtNancestorSensitive Boolean The bitwise AND of the
parent widget's DwtNsen-
sitive and DwtNances-
torSensitive attributes
DwtNaccelerators XtTranslations NULL
DwtNdepth int Depth of the parent win-
dow
DwtNtranslations XtTranslations NULL
DwtNmappedWhenManaged Boolean True
DwtNscreen Screen * The parent screen
DwtNdestroyCallback DwtCallbackPtr NULL
Common Attributes
DwtNforeground Pixel Default foreground color
DwtNhighlight Pixel Default foreground color
DwtNhighlightPixmap Pixmap NULL
DwtNuserData Opaque * NULL
DwtNdirectionRToL unsigned char DwtDirectionRightDown
DwtNfont DwtFontList The default XUI Toolkit
font
DwtNhelpCallback DwtCallbackPtr NULL
Label Attributes
DwtNlabelType unsigned char DwtCString
DwtNlabel DwtCompString Widget name
DwtNmarginWidth Dimension Two pixels for text
Zero pixels for pixmap
DwtNmarginHeight Dimension Two pixels for text
Zero pixels for pixmap
DwtNalignment unsigned char DwtAlignmentCenter
DwtNpixmap Pixmap NULL
DwtNmarginLeft Dimension Zero
DwtNmarginRight Dimension Zero
DwtNmarginTop Dimension Zero
DwtNmarginBottom Dimension Zero
DwtNconformToText Boolean True, if the widget is
created with a width and
height of zero
False, if the widget is
created with a non-zero
width and height
------------------------------------------------------------------
Widget-Specific Attributes
You can set the following widget-specific attributes in the override_arglist:
------------------------------------------------------------
Attribute Name Data Type Default
------------------------------------------------------------
DwtNshape unsigned char DwtRectangular
DwtNvisibleWhenOff Boolean True
DwtNspacing short 4 pixels
DwtNpixmapOn Pixmap NULL
DwtNpixmapOff Pixmap NULL
DwtNvalue Boolean False
DwtNarmCallback DwtCallbackPtr NULL
DwtNdisarmCallback DwtCallbackPtr NULL
DwtNvalueChangedCallback DwtCallbackPtr NULL
DwtNindicator Boolean True when the
label is DwtC-
String
False when the
label is Dwt-
Pixmap
DwtNacceleratorText DwtCompString NULL
DwtNbuttonAccelerator char * NULL
DwtNinsensitivePixmapOn Pixmap NULL
DwtNinsensitivePixmapOff Pixmap NULL
------------------------------------------------------------
DwtNshape Specifies the toggle button indicator shape. You can pass DwtRectangular or DwtOval.
DwtNvisibleWhenOff
Specifies a boolean value that, when True, indicates that the toggle button is visible when in the off state.
DwtNspacing Specifies the number of pixels between the label and the button if DwtNlabelType is DwtCompString.
DwtNpixmapOn Specifies the pixmap to be used as the button label if DwtNlabelType is DwtPixmap and the toggle button is in the on state.
DwtNpixmapOff Specifies the pixmap to be used as the button label if DwtNlabelType is DwtPixmap and the toggle button is in the off state.
DwtNvalue Specifies a boolean value that, when False, indicates the button state is off. If True, the button state is on.
DwtNarmCallback
Specifies the callback function or functions called when the toggle button is armed. The toggle button is armed when the
user presses and releases MB1 while the pointer is inside the toggle button widget. For this callback, the reason is
DwtCRArm.
DwtNdisarmCallback
Specifies the callback function or functions called when the button is disarmed. The button is disarmed when the user
presses MB1 while the pointer is inside the toggle button widget, but moves the pointer outside the toggle button before
releasing MB1. For this callback, the reason is DwtCRDisarm.
DwtNvalueChangedCallback
Specifies the callback function or functions called when the toggle button value was changed. For this callback, the reason
is DwtCRValueChanged.
DwtNindicator Specifies a boolean value that, when True, signifies that the indicator is present in the toggle button. If False, signi-
fies that the indicator is not present in the toggle button.
DwtNacceleratorText
Specifies the compound-string text displayed for the accelerator.
DwtNbuttonAccelerator
Sets an accelerator on a toggle button widget.
DwtNinsensitivePixmapOn
Specifies the pixmap used when the toggle button is on and is insensitive. This attribute applies only if the toggle button
label is specified as a pixmap.
DwtNinsensitivePixmapOff
Specifies the pixmap used when the toggle button is off and is insensitive. This attribute applies only if the toggle but-
ton label is specified as a pixmap.
Return Values
These functions return the ID of the created widget.
Callback Information
The following structure is returned to your callback:
typedef struct {
int reason;
XEvent *event;
int value;
} DwtToggleButtonCallbackStruct;
The reason member is set to a constant that represents the reason why this callback was invoked. For this callback, the reason member can
be set to:
DwtCRValueChanged The user activated the
toggle button to change
state.
DwtCRArm The user armed the toggle
button by pressing MB1
while the pointer was
inside the toggle button
widget.
DwtCRDisarm The user disarmed the
toggle button by pressing
MB1 while the pointer was
inside the toggle button
widget, but did not
release it until after
moving the pointer out-
side the toggle button
widget.
DwtCRHelpRequested The user selected Help.
The event member is a pointer to the Xlib structure XEvent, which describes the event that generated this callback. This structure is a
union of the individual structures declared for each event type. For information on XEvent and event processing, see the Guide to the Xlib
Library: C Language Binding.
The value member is set to the toggle button's current state when the callback occurred, either True (on) or False (off).
See Also
DwtToggleButtonGetState(3Dwt), DwtToggleButtonSetState(3Dwt)
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding
DwtToggleButton(3Dwt)