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.

nameSpecifies the name of the created widget. 

xSpecifies 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. 

ySpecifies, 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. 

labelSpecifies the text in the toggle button label/indicator.  This argument sets the DwtNlabel attribute associated with DwtLabelCreate. 

valueSpecifies 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. 

callbackSpecifies 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_callbackSpecifies 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 DwtToggleButtonCreate, 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 DwtLabelCreate. 

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

Widget-Specific Attributes

You can set the following widget-specifc attributes in the override_arglist:

DwtNshapeSpecifies 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. 

DwtNspacingSpecifies the number of pixels between the label and the button if DwtNlabelType is DwtCompString. 

DwtNpixmapOnSpecifies the pixmap to be used as the button label if DwtNlabelType is DwtPixmap and the toggle button is in the on state. 

DwtNpixmapOffSpecifies the pixmap to be used as the button label if DwtNlabelType is DwtPixmap and the toggle button is in the off state. 

DwtNvalueSpecifies 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. 

DwtNindicatorSpecifies a boolean value that, when True, signifies that the indicator is present in the toggle button.  If False, signifies 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 button label is specified as a pixmap.

Return Value

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:

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

Subroutines