# iwidgets2.2.0 User Commands - shell

##

## NAME

         shell - Create and manipulate a shell widget

## SYNOPSIS

         shell pathName ?options?

## INHERITANCE

         itk::Toplevel <- shell

## STANDARD OPTIONS

         background      cursor         foreground

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

## WIDGET-SPECIFIC OPTIONS

         Name:           master
         Class:          Window
         Command-Line Switch:           -master

              Defines the shell as being a transient window with  the
              master  window  given by the master option.  The master
              window should be either another existing toplevel  win-
              dow  or {} for no master.  The default is {} for shells
              and "." for dialogs.

         Name:           modality
         Class:          Modality
         Command-Line Switch:           -modality

              Allows the shell to grab control of the screen  in  one
              of three different ways:  application, system, or none.
              Application modal prevents any other  toplevel  windows
              within the application which are direct children of '.'
              from gaining focus.  System modal locks the screen  and
              prevents  all  windows from gaining focus regardless of
              application.  A modality of none performs no  grabs  at
              all.  The default is none.

         Name:           padX
         Class:          Pad
         Command-Line Switch:           -padx

              Specifies a padding distance for the childsite  in  the
              X-direction   in   any   of  the  forms  acceptable  to
              Tk_GetPixels.  The default is 10.

         Name:           padY
         Class:          Pad
         Command-Line Switch:           -pady
              Specifies a padding distance for the childsite  in  the
              Y-direction   in   any   of  the  forms  acceptable  to
              Tk_GetPixels.  The default is 10.

         Name:           title
         Class:          Title
         Command-Line Switch:           -title

              String to be displayed in the title window decoration.

##

## DESCRIPTION

         The shell command creates a  shell  which  is  a  top  level
         widget which supports modal operation.

## METHODS

         The shell command create a new Tcl  command  whose  name  is
         pathName.  This command may be used to invoke various opera-
         tions 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 shell widg-
         ets:

## WIDGET-SPECIFIC METHODS

         pathName activate
              Display the shell and wait based on the modality.   For
              application  and  system  modal  activations, perform a
              grab operation, and wait for the  result.   The  result
              may  be  returned  via  an  argument  to the deactivate
              method.

         pathName center ?widget?
              Centers the shell with respect to another widget.   The
              widget argument is optional.  If provided, it should be
              the path of another widget with  to  center  upon.   If
              absent,  then  the shell will be centered on the screen
              as a whole.

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

         pathName childsite
              Returns the pathname of the child site widget.

         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 shell command.

         pathName deactivate ?arg?
              Deactivate the display of the shell.  The method  takes
              an  optional  argument  to  be  passed  to the activate
              method which returns the value.  The optional  argument
              is only effective for application and system modal dia-
              logs.

## COMPONENTS

         Name:           shellchildsite
         Class:          frame

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

## EXAMPLE

               shell .sh -modality application -padx 20 -pady 20 -title Shell

               pack [label [.sh childsite].l -text SHELL]

               .sh center
               .sh activate

## AUTHOR

         Mark L. Ulferts

         Kris Raney

## KEYWORDS

         shell, widget