NAME¶
container - Widget to contain a foreign window.
SYNOPSIS¶
container pathName ?
options?
DESCRIPTION¶
The
container widget lets you swallow another X11/Win32 toplevel or embed
an X11 window from a foreign application into your Tk application. The foreign
window is reparented inside of the widget. You can then place and arrange the
container just as you would any Tk widget.
INTRODUCTION¶
Notebooks are a popular graphical paradigm. They allow you to organize many
windows in a single widget. For example, you might have an application the
displays several X-Y graphs at the same time. Typically, you can't pack the
graphs into the same
frame because they are too large. The other
alternative is to pack the graphs into several
toplevel widgets,
allowing them to overlap on the screen. The problem is that all the different
toplevel windows clutter the screen and are difficult to manage.
The
container widget lets organize your application by displaying each
graph as a page in a folder of a notebook. Only one page is visible at a time.
When you click on a tab, the folder (graph) corresponding to the tab is
displayed in the
container widget. The container also lets you
temporarily tear pages out of the notebook into a separate toplevel widget,
and put them back in the container later. For example, you could compare two
graphs side-by-side by tearing them out, and then replace them when you are
finished.
A container may contain an unlimited number of folders. If there are too many
tabs to view, you can arrange them as multiple tiers or scroll the tabs. The
container uses the conventional Tk scrollbar syntax, so you can attach a
scrollbar too.
EXAMPLE¶
You create a container widget with the
container command.
# Create a new container
container .c
A new Tcl command
.c is also created. This command can be used to query
and modify the container. For example, to change the default borderwidth, you
use the new command and the container's
configure operation.
# Change the default font.
.c configure -borderwidth 2
You can then add folders using the
insert operation.
# Create a new folder "f1"
.c coinsert 0 "f1"
This inserts the new tab named "f1" into the container. The index
0 indicates location to insert the new tab. You can also use the index
end to append a tab to the end of the container. By default, the text
of the tab is the name of the tab. You can change this by configuring the
-text option.
# Change the label of "f1"
.ts tab configure "f1" -label "Tab #1"
The
insert operation lets you add one or more folders at a time.
.ts insert end "f2" -label "Tab #2" "f3" "f4"
The tab on each folder contains a label. A label may display both an image and a
text string. You can reconfigure the tab's attributes (foreground/background
colors, font, rotation, etc) using the
tab configure operation.
# Add an image to the label of "f1"
set image [image create photo -file stopsign.gif]
.ts tab configure "f1" -image $image
.ts tab configure "f2" -rotate 90
Each folder may contain an embedded widget to represent its contents. The widget
to be embedded must be a child of the container widget. Using the
-window option, you specify the name of widget to be embedded. But
don't pack the widget, the container takes care of placing and arranging the
widget for you.
graph .ts.graph
.ts tab configure "f1" -window ".ts.graph" \
-fill both -padx 0.25i -pady 0.25i
The size of the folder is determined the sizes of the Tk widgets embedded inside
each folder. The folder will be as wide as the widest widget in any folder.
The tallest determines the height. You can use the tab's
-pagewidth and
-pageheight options override this.
Other options control how the widget appears in the folder. The
-fill
option says that you wish to have the widget stretch to fill the available
space in the folder.
.ts tab configure "f1" -fill both -padx 0.25i -pady 0.25i
Now when you click the left mouse button on "f1", the graph will be
displayed in the folder. It will be automatically hidden when another folder
is selected. If you click on the right mouse button, the embedded widget will
be moved into a toplevel widget of its own. Clicking again on the right mouse
button puts it back into the folder.
If you want to share a page between two different folders, the
-command
option lets you specify a Tcl command to be invoked whenever the folder is
selected. You can reset the
-window option for the tab whenever it's
clicked.
.ts tab configure "f2" -command {
.ts tab configure "f2" -window ".ts.graph"
}
.ts tab configure "f1" -command {
.ts tab configure "f1" -window ".ts.graph"
}
If you have many folders, you may wish to stack tabs in multiple tiers. The
container's
-tiers option requests a maximum number of tiers. The
default is one tier.
If the tabs can fit in less tiers, the widget will use that many. Whenever there
are more tabs than can be displayed in the maximum number of tiers, the
container will automatically let you scroll the tabs. You can even attach a
scrollbar to the container.
.ts configure -scrollcommand { .sbar set } -scrollincrement 20
.sbar configure -orient horizontal -command { .ts view }
By default tabs are along the top of the container from left to right. But tabs
can be placed on any side of the container using the
-side option.
# Arrange tabs along the right side of the container.
.ts configure -side right -rotate 270
SYNTAX¶
The
container command creates a new window using the
pathName
argument and makes it into a container widget.
container pathName ?option value?...
Additional options may be specified on the command line or in the option
database to configure aspects of the container such as its colors, font, text,
and relief. The
container command returns its
pathName argument.
At the time this command is invoked, there must not exist a window named
pathName, but
pathName's parent must exist.
When first created, a new container contains no tabs. Tabs are added or deleted
using widget operations described below. It is not necessary for all the tabs
to be displayed in the container window at once; commands described below may
be used to change the view in the window. Containers allow scrolling of tabs
using the
-scrollcommand option. They also support scanning (see the
scan operation). Tabs may be arranged along any side of the container
window using the
-side option.
The size of the container window is determined the number of tiers of tabs and
the sizes of the Tk widgets embedded inside each folder. The widest widget
determines the width of the folder. The tallest determines the height. If no
folders contain an embedded widget, the size is determined solely by the size
of the tabs.
You can override either dimension with the container's
-width and
-height options.
CONTAINER OPERATIONS¶
All
container operations are invoked by specifying the widget's pathname,
the operation, and any arguments that pertain to that operation. The general
form is:
pathName operation ?arg arg ...?
Operation and the
args determine the exact behavior of the
command. The following operations are available for container widgets:
- pathName cget option
- Returns the current value of the configuration option given by
option. Option may have any of the values accepted by the
configure operation described below.
- 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 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 corresponding 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 and value are
described below:
- -background color
- Sets the border color of the container.
- -borderwidth pixels
- Sets the width of the 3-D border around the outside edge of the widget.
The -relief option determines how the border is to be drawn. The
default is 2.
- -command pattern
- Specifies to search for a window whose WM_COMMAND property matches
the given pattern (X11 only). If no windows, or more than one window,
matches the pattern, an error is generated. If pattern is the empty
string, then no command search is performed. The default is
"".
- -cursor cursor
- Specifies the widget's cursor. The default cursor is
"".
- -height pixels
- Specifies the requested height of widget. If pixels is 0, then the
height is height the embedded window plus the specified borderwidth. The
default is 0.
- -highlightbackground color
- Sets the color to display in the traversal highlight region when the
container does not have the input focus.
- -highlightcolor color
- Sets the color to use for the traversal highlight rectangle that is drawn
around the widget when it has the input focus. The default is
black.
- -highlightthickness pixels
- Sets the width of the highlight rectangle to draw around the outside of
the widget when it has the input focus. Pixels is a non-negative
value and may have any of the forms acceptable to Tk_GetPixels. If
the value is zero, no focus highlight is drawn around the widget. The
default is 2.
- -name pattern
- Specifies to search for a window whose WM_NAME property matches the
given pattern (X11 only). If no windows, or more than one window, matches
the pattern, an error is generated. If pattern is the empty string,
then no name search is performed. The default is "".
- -relief relief
- Specifies the 3-D effect for the container widget. Relief specifies
how the container should appear relative to widget that it is packed into;
for example, raised means the container should appear to protrude.
The default is sunken.
- -takefocus focus
- Provides information used when moving the focus from window to window via
keyboard traversal (e.g., Tab and Shift-Tab). If focus is 0,
this means that this window should be skipped entirely during keyboard
traversal. 1 means that the this window should always receive the
input focus. An empty value means that the traversal scripts decide
whether to focus on the window. The default is 1.
- -width pixels
- Specifies the requested width of the widget. If pixels is 0, then
the width is the width the embedded window and the specified borderwidth.
The default is 0.
- -window id
- Specifies the foreign embedded using its path or X window id.
- pathName find -command|-name
pattern
- Searches for all windows that match the given pattern. If the
-command switch is given, all windows whose WWM_COMMAND property
match pattern are returned in a list (X11 only). If the
-name switch is given, all windows whose WWM_NAME property match
pattern are returned in a list. The list returned will contains
pairs of the window id and the matching property.
KEYWORDS¶
container, widget