Provided by: libmotif-dev_2.3.8-3_amd64 bug

NAME

       XmIconButton - The Icon Button widget

SYNOPSIS

       Documents the XmIconButton widget

DESCRIPTION

       The Icon Button widget is a selectable area of the screen that contains both a label and a
       string.  When  the  user  selects  this  button  with  the  OSF/Motif  select  button  its
       activateCallback  is  called. This widget can also be used as a Toggle button, although it
       will have no indicator. The placement of the icon relative to the text can be modified  by
       using the iconPlacement resource.

       Note: This widget takes a String as its label, not an XmString, so there is no need to use
       XmStringCreate to get a properly formatted string. Internationalized text is not currently
       supported.

Normal Resources

       Name                  Class             Type                  Initial Value
       activateCallback      Callback          Callback              NULL
       alignment             Alignment         Alignment             XmALIGNMENT_
                                                                      BEGINNING
       armColor              ArmColor          Pixel                 <dynamic>
       doubleClickCallback   Callback          Callback              NULL
       fontList              FontList          FontList              fixed
       horizontalMargin      Space             HorizontalDimension   2
       iconTextPadding       Space             VerticalDimension     2
       iconPlacement         IconPlacement     IconPlacement         XmIconTop
       label                 Label             String                Widget name
       labelString           LabelString       XmString              Widget name
       pixmap                Pixmap            Pixmap                None
       recomputeSize         Boolean           Boolean               True
       set                   Boolean           Boolean               False
       stringDirection       StringDirection   StringDirection       XmSTRING_
                                                                     DIRECTION_L_TO_R
       verticalMargin        Space             VerticalDimension     2

       All resource names begin with XmN and all resource class names begin with XmC.

activateCallback

       This  list  of  callback  routines is called whenever the icon button is clicked on by the
       user. The format of the callback routines is specified below.

armColor

       This is the pixel index that describes the color to fill the widget with when it is set.

doubleClickCallback

       This list of callback routines is called whenever the user double clicks on  this  widget.
       The format of the callback routines is specified below.

fontList

       The default font in this list is used to render the label string of the icon button.

horizontalMargin

verticalMargin

       The  amount  of  space  to  be  left between the edge of the shadow and the text or pixmap
       displayed. The vertical and horizontal spacing can be controlled independently.

iconTextPadding

       The amount of space to be left between the pixmap and the label string.

iconPlacement

       The location of the pixmap (icon) with respect to the displayed text.  This  resource  can
       take  one  of  the  following  values:  XmIconTop,  XmIconBottom, XmIconLeft, XmIconRight,
       XmIconNone, and XmIconOnly. A  type  converter  has  been  registered  that  converts  the
       following strings: "top", "bottom", "left", "right", "none", and "iconOnly".

       If  only a string is displayed in the Icon Button, this resource can be used to change the
       justification  of  the  label.   XmIconTop=bottom,   XmIconBottom=top,   XmIconRight=Left,
       XmIconLeft=Right,  XmIconNone=Center. In order to use these options, pixmap must be set to
       None.

label

       The string to display in this button. This string can only have one font, but can  be  any
       number  of  lines long. Use the NEW_LINE character ( '0 ) to separate lines. This resource
       has been superseded by labelString,  but  is  included  for  backwards  compatibility.  If
       XmNlabelString is set , XmNlabel is ignored

labelString

       Specifies  the  compound  string to be displayed in the button. If this value is NULL, the
       value of XmNlabel is used. If both are NULL, labelString is initialized by converting  the
       name  of  the  widget  to  a  compound  string.  Refer  to  XmString(3X)  in the OSD/Motif
       Programmers' Reference for more information on the  creation  and  structure  of  compound
       strings.

pixmap

       The  pixmap  to  display. This pixmap may either be of depth one (1), or the same depth as
       the screen this widget is being  displayed  on.  If  the  pixmap  is  of  depth  one  then
       XCopyPlane  is  used  to render the pixmap in the foreground and background colors. If the
       pixmap is not of depth one then XCopyArea is used and  all  the  original  colors  of  the
       pixmap  are  preserved.  Unlike  the  Motif  PushButton widget the pixmap is automatically
       stippled when the Icon Button becomes insensitive.

recomputeSize

       If this Boolean value is True then the icon button will ask its parent to resize it to  be
       just  large  enough to contain the pixmap, label and shadows. If it is False then the icon
       button will not attempt a resize.

set

       This Boolean value represents the current state of the icon button. If this value is  True
       then  the  icon  button  is set and is rendered as depressed. Otherwise it is unset and is
       rendered normally.

stringDirection

       Specifies the direction in which the string is to be drawn. XmNSTRING_DIRECTION_L_TO_R  is
       drawn  left to right, while XmNSTRING_DIRECTION_R_TO_L is drawn right to left. The default
       for this resource is determined at creation time.  If  no  value  is  specified  for  this
       resource  and  the  widget's  parent is a manager, the value is inherited from the parent;
       otherwise, it defaults to XmNSTRING_DIRECTION_L_TO_R.

Callback Routines

       Whenever the user selects the icon button the activate callbacks  will  be  called.  When-
       ever the user double clicks on this widget the first click will call the activateCallback,
       and if the second occurs within MultiClickTime  it  will  call  the  doubleClickCallback..
       These callbacks have the following parameters:

       void (activate_callback)(Widget w, XtPointer client_data, XtPointer call_data)

       w              the Icon Button widget

       client_data    the client data specified by the application

       call_data      a pointer to an XmIconButtonCallbackInfo structure

       void (double_click_callback)(Widget w, XtPointer client_data, XtPointer call_data)

       w              the Icon Button widget

       client_data    the client data specified by the application

       call_data      a pointer to an XmIconButtonCallbackInfo structure

       All  procedures  on  the Icon Button's activateCallback and doubleClickCallback lists will
       have a pointer to an IconButtonCallbackInfo structure passed  to  them  in  the  call_data
       field.  This  structure  is  defined  in  the  Icon  Button widget's public header file as
       follows:

       typedef struct _XmIconButtonCallbackInfo {

            Boolean state;   /* The current state of the icon button.*/

            XEvent * event;  /* The event that caused this action.*/

       } XmIconButtonCallbackInfo;

       state          the current state of the icon button. When this is used as  a  push  button
                      (the default) the state variable will always be True.

       event          the X Event that caused this action, see Translations and Actions below for
                      details on the events that can cause these callbacks to be called.

Convenience Routine


XmCreateIconButton - Widget creation convenience routine

       Widget XmCreateIconButton(
                      Widget parent,/* Widget id of parent for IconButton */
                      String name, /* Name of the created widget */
                      ArgList args,/* argument list */
                      Cardinal num_args/* number of items in argument list */
                      )

       Translations and Actions:

       The following are the default translation bindings used by the icon button:

       <Btn1Down>,<Btn1Up>:   XmToggle() XmNotify()
       <Btn1Down>(2):         XmDoubleNotify()
       <Btn1Down>:            XmGetFocus() XmToggle()
       <Key>osfSelect:        XmArmAndActivate()
       <Key>osfActivate:      XmArmAndActivate()
       None<Key>space:        XmArmAndActivate()
       None<Key>Return:       XmArmAndActivate()
       <Btn1Down>,<Leave>     XmToggle()

       The following actions are supported by the icon button:

       XmToggle()     Toggles the state of the icon button.

       XmNotify()     Calls all routines on activateCallback list.

       XmDoubleNotify()Calls all routines on the doubleClickCallback list.

       XmArmAndActivated()This action will arm the button, call the actions on the activateCallback
                      list, wait a fraction of a second and then disarm the button.

       To use this button as a toggle button rather than a push button, replace the default
       translation table with the following table.

       <Btn1Down>:         XmToggle() XmNotify()

       <Btn1Up>(2):        XmDoubleNotify()
       <Key>osfSelect:     XmToggle() XmNotify()
       <Key>osfActivate:   XmToggle() XmNotify()
       None<Key>space:     XmToggle() XmNotify()
       None<Key>Return:    XmToggle() XmNotify()

COPYRIGHT

       Copyright (c) 1992 by Integrated Computer Solutions, Inc.

                                           15 July 1992                           XmIconButton(3)