manpagez: man pages & more
man XmIconButton(3)
Home | html | info | man
XmIconButton(3)                                              XmIconButton(3)




NAME

       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  speci-
       fied 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, XmIcon-
       Bottom, 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, XmI-
       conBottom=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 superceded by label-
       String, 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,  label-
       String  is  initialized  by converting the name of the widget to a com-
       pound string. Refer to XmString(3X) in the OSD/Motif Programmers'  Ref-
       erence  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 automati-
       cally 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. XmN-
       STRING_DIRECTION_L_TO_R is drawn left to right, while  XmNSTRING_DIREC-
       TION_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  doubleClick-
       Callback  lists will have a pointer to an IconButtonCallbackInfo struc-
       ture 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)

openMotif 2.3.1 - Generated Sun Nov 30 16:52:51 CST 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.