# iwidgets2.2.0 User Commands - labeledwidget

##

## NAME

         labeledwidget - Create and manipulate a labeled widget

## SYNOPSIS

         labeledwidget pathName ?options?

## INHERITANCE

         itk::Widget <- labeledwidget

## STANDARD OPTIONS

         background      cursor         foreground

         See the "options" manual entry for details on  the  standard
         options.

## WIDGET-SPECIFIC OPTIONS

         Name:           labelBitmap
         Class:          Bitmap
         Command-Line Switch:           -labelbitmap

              Specifies a bitmap to display in the widget, in any  of
              the  forms  acceptable  to  Tk_GetBitmap.   This option
              overrides the labeltext option.

         Name:           labelFont
         Class:          Font
         Command-Line Switch:           -labelfont

              Specifies the font to be used for the label.

         Name:           labelImage
         Class:          Image
         Command-Line Switch:           -labelimage

              Specifies a image to be used as the  label.  The  image
              may  be  any  of the values created by the image create
              command.  This option overrides  both  the  labelbitmap
              and labeletext options.

         Name:           labelMargin
         Class:          Margin
         Command-Line Switch:           -labelmargin

              Specifies the distance between the childsite and  label
              in  any  of  the forms acceptable to Tk_GetPixels.  The
              default is 1 pixel.

         Name:           labelPos
         Class:          Position
         Command-Line Switch:           -labelpos
              Specifies the position of the label along the  side  of
              the  childsite:  n,  ne,  e,  se, s, sw, w, or nw.  The
              default is w.

         Name:           labelText
         Class:          Text
         Command-Line Switch:           -labeltext

              Specifies the text of the label around the childsite.

         Name:           labelVariable
         Class:          Variable
         Command-Line Switch:           -labelvariable

              Specifies the text variable of  the  label  around  the
              childsite.

##

## DESCRIPTION

         The labeledwidget command creates  a  labeled  widget  which
         contains  a label and child site.  The child site is a frame
         which can filled with any widget  via  a  derived  class  or
         though  the  use  of  the  childsite method.  This class was
         designed to be a general purpose base class  for  supporting
         the  combination  of  label  widget  and  a  childsite.  The
         options include the ability to position the label around the
         childsite  widget,  modify  the font and margin, and control
         the display of the labels.

## METHODS

         The labeledwidget command creates a new  Tcl  command  whose
         name  is pathName.  This command may be used to invoke vari-
         ous operations on the widget.  It has the following  general
         form:

              pathName option ?arg arg ...?

         Option and the args determine the exact behavior of the com-
         mand.  The following commands are possible for labeledwidget
         widgets:

## WIDGET-SPECIFIC METHODS

         pathName childsite
              Return the path name of the child site.

         pathName cget option
              Returns the current value of the  configuration  option
              given  by  option.   Option  may have any of the values
              accepted by the labeledwidget command.

         pathName configure ?option? ?value option value ...?
              Query  or  modify  the  configuration  options  of  the
              widget.   If  no  option  is  specified, returns a list
              describing all of the available  options  for  pathName
              (see  Tk_ConfigureInfo for information on the format of
              this list).  If option is specified with no value, then
              the  command  returns  a  list describing the one named
              option (this list will be identical to the  correspond-
              ing  sublist  of  the  value  returned  if no option is
              specified).  If one or more  option - value  pairs  are
              specified,  then  the command modifies the given widget
              option(s) to have the given value(s);  in this case the
              command  returns  an empty string.  Option may have any
              of the values accepted by the labeledwidget command.

## STATIC METHODS

         Labeledwidget::alignlabels widget ?widget ...?
              The alignlabels  procedure  takes  a  list  of  widgets
              derived from the Labeledwidget class and uses the label
              margin to make each widget have the  same  total  space
              for  the  combination  of  label  and  margin.  The net
              effect is to left align the  labels.   Generally,  this
              method is only useful with a label position of w, which
              is the default.

## COMPONENTS

         Name:           label
         Class:          label

              The label component provides the label for the  labeled
              widget.   See  the  "label"  widget  manual  entry  for
              details on the label component item.

         Name:           lwchildsite
         Class:          frame

              The lwchildsite component is the user  child  site  for
              the  labeled  widget.   See  the  "frame" widget manual
              entry for details on the lwchildsite component item.

## EXAMPLE

              The labeledwidget was primarily  meant  to  be  a  base
              class.   The  ScrolledListBox  and  EntryField are good
              examples of derived classes of the labeledwidget class.
              In   order  to  provide  equal  support  for  composite
              classes, the 'childsite' methods also exists.  The fol-
              lowing is an example of 'childsite' method usage.

               labeledwidget .lw -labeltext "Canvas Widget" -labelpos s
               pack .lw -fill both -expand yes -padx 10 -pady 10

               set cw [canvas [.lw childsite].c -relief raised -width 200 -height 200]
               pack $cw -padx 10 -pady 10

## AUTHOR

         Mark L. Ulferts

## KEYWORDS

         labeledwidget, widget