/usr/share/doc/blt-dev/html/container.html

                     <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->

<HTML>
<HEAD>
<TITLE>container(n) manual page</TITLE>
</HEAD>
<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
<A HREF="#toc">Table of Contents</A><P>
 
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
container - Widget to contain a foreign window.

<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<B>container</B> <I>pathName </I>?<I>options</I>? 
<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
The <B>container</B> 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. 
<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
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 <B>frame</B> because they are too large.  The other alternative is
to pack the graphs into several <B>toplevel</B> 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. <P>
The <B>container</B> 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 <B>container</B> 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. <P>
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.  
<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
You
create a container widget with the <B>container</B> command. <BR>
<CODE># Create a new container<BR>
container .c<BR>
</CODE><P>A new Tcl command <I>.c</I> 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 <B>configure</B> operation. <BR>
<CODE># Change the default font.<BR>
.c configure -borderwidth 2<BR>
</CODE><P>You can then add folders using the <B>insert</B> operation. <BR>
<CODE># Create a new folder "f1"<BR>
.c coinsert 0 "f1"<BR>
</CODE><P>This inserts the new tab named "f1" into the container.  The index <I>0</I> indicates
location to insert the new tab.  You can also use the index <I>end</I> 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 <B>-text</B> option. <BR>
<CODE># Change the label of "f1"<BR>
.ts tab configure "f1" -label "Tab #1" <BR>
</CODE><P>The <B>insert</B> operation lets you add one or more folders at a time. <BR>
<CODE>.ts insert end "f2" -label "Tab #2" "f3" "f4" <BR>
</CODE><P>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 <B>tab configure</B> operation. <BR>
<CODE># Add an image to the label of "f1"<BR>
set image [image create photo -file stopsign.gif]<BR>
.ts tab configure "f1" -image $image<BR>
.ts tab configure "f2" -rotate 90<BR>
</CODE><P>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
<B>-window</B> 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. <BR>
<CODE>graph .ts.graph<BR>
.ts tab configure "f1" -window ".ts.graph" \<BR>
    -fill both -padx 0.25i -pady 0.25i<BR>
</CODE><P>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 <B>-pagewidth</B>
and <B>-pageheight</B> options override this. <P>
Other options control how the widget
appears in the folder.  The <B>-fill</B> option says that you wish to have the widget
stretch to fill the available space in the folder. <BR>
<CODE>.ts tab configure "f1" -fill both -padx 0.25i -pady 0.25i<BR>
<P>
</CODE><P>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. <P>
If you want to share a page between two different
folders, the <B>-command</B> option lets you specify a Tcl command to be invoked
whenever the folder is selected.  You can reset the <B>-window</B> option for the
tab whenever it's clicked. <BR>
<CODE>.ts tab configure "f2" -command { <BR>
    .ts tab configure "f2" -window ".ts.graph"<BR>
}<BR>
.ts tab configure "f1" -command { <BR>
    .ts tab configure "f1" -window ".ts.graph"<BR>
}<BR>
</CODE><P>If you have many folders, you may wish to stack tabs in multiple tiers.
 The container's <B>-tiers</B> option requests a maximum number of tiers.   The default
is one tier.   <BR>
<CODE>.ts configure -tiers 2<BR>
</CODE><P>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. <BR>
<CODE>.ts configure -scrollcommand { .sbar set }  -scrollincrement 20<BR>
.sbar configure -orient horizontal -command { .ts view }<BR>
</CODE><P>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 <B>-side</B> option.
<BR>
<CODE># Arrange tabs along the right side of the container. <BR>
.ts configure -side right -rotate 270<BR>

<H2><A NAME="sect5" HREF="#toc5"></CODE><P>Syntax</A></H2>
The <B>container</B> command creates a new window using the <I>pathName</I> argument
and makes it into a container widget. <BR>
<CODE><B>container <I>pathName </I></B>?<I>option value</I>?...<BR>
</CODE><P>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 <B>container</B> command returns its <I>pathName</I> argument. 
At the time this command is invoked, there must not exist a window named
<I>pathName</I>, but <I>pathName</I>'s parent must exist. <P>
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 <B>-scrollcommand</B>
option.  They also support scanning (see the <B>scan</B> operation). Tabs may be
arranged along any side of the container window using the <B>-side</B> option. <P>
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.   <P>
You can override either dimension with the container's
<B>-width</B> and <B>-height</B> options. 
<H2><A NAME="sect6" HREF="#toc6">Container Operations</A></H2>
All <B>container</B> operations are
invoked by specifying the widget's pathname, the operation, and any arguments
that pertain to that operation.  The general form is: <P>
<BR>
<CODE><tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;<I>pathName operation </I>?<I>arg arg ...</I>?<BR>
<P>
</CODE><P><I>Operation</I> and the <I>arg</I>s determine the exact behavior of the command.  The
following operations are available for container widgets: 
<DL>

<DT><I>pathName <B>cget</B></I>
<I>option</I> </DT>
<DD>Returns the current value of the configuration option given by <I>option</I>.
<I>Option</I> may have any of the values accepted by the <B>configure</B> operation described
below. </DD>

<DT><I>pathName <B>configure</B></I> ?<I>option</I>? ?<I>value option value ...</I>? </DT>
<DD>Query or modify
the configuration options of the widget. If no <I>option</I> is specified, returns
a list describing all  the available options for <I>pathName</I> (see <B>Tk_ConfigureInfo</B>
for information on the format of this list).  If <I>option</I> is specified with
no <I>value</I>, 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 <I>option</I> is specified).  If one or more <I>option-value</I> 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. <I>Option</I>
and <I>value</I> are described below: <blockquote></DD>

<DT><B>-background <I>color</I></B> </DT>
<DD>Sets the border color of
the container.   </DD>

<DT><B>-borderwidth <I>pixels</I></B> </DT>
<DD>Sets the width of the 3-D border around
the outside edge of the widget.  The <B>-relief</B> option determines how the border
is to be drawn.  The default is <I>2</I>. </DD>

<DT><B>-command <I>pattern</I></B> </DT>
<DD>Specifies to search for
a window whose <I>WM_COMMAND</I> property matches the given pattern (X11 only).  If no windows,
or more than one window, matches the pattern, an error is generated.  If
<I>pattern</I> is the empty string, then no command search is performed. The default
is <I>""</I>. </DD>

<DT><B>-cursor <I>cursor</I></B> </DT>
<DD>Specifies the widget's cursor.  The default cursor is
<I>""</I>. </DD>

<DT><B>-height <I>pixels</I></B> </DT>
<DD>Specifies the requested height of widget.  If <I>pixels</I> is
0, then the height is height the embedded window plus the specified  borderwidth.
The default is <I>0</I>. </DD>

<DT><B>-highlightbackground  <I>color</I></B> </DT>
<DD>Sets the color to display in
the traversal highlight region when the container does not have the input
focus.   </DD>

<DT><B>-highlightcolor <I>color</I></B> </DT>
<DD>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 <I>black</I>. </DD>

<DT><B>-highlightthickness <I>pixels</I></B> </DT>
<DD>Sets the width of the highlight
rectangle to draw around the outside of  the widget when it has the input
focus. <I>Pixels</I> is a non-negative  value and may have any of the forms acceptable
to <B>Tk_GetPixels</B>. If the value is zero, no focus highlight is drawn around
the widget. The default is <I>2</I>. </DD>

<DT><B>-name <I>pattern</I></B> </DT>
<DD>Specifies to search for a window
whose <I>WM_NAME</I> property matches the given pattern (X11 only).  If no windows, or more
than one window, matches the pattern, an error is generated.  If <I>pattern</I>
is the empty string, then no name search is performed. The default is <I>""</I>.
</DD>

<DT><B>-relief <I>relief</I></B> </DT>
<DD>Specifies the 3-D effect for the container widget.  <I>Relief</I>
specifies how the container should appear relative to widget that it is
packed into; for example, <I>raised</I> means the container should appear to protrude.
 The default is <I>sunken</I>. </DD>

<DT><B>-takefocus</B> <I>focus</I>  </DT>
<DD>Provides information used when
moving the focus from window to window via keyboard traversal (e.g., Tab
and Shift-Tab).  If <I>focus</I> is <I>0</I>, this means that this window should be skipped
entirely during keyboard traversal.  <I>1</I> 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 <I>1</I>. </DD>

<DT><B>-width <I>pixels</I></B>
 </DT>
<DD>Specifies the requested width of the widget.  If <I>pixels</I> is 0, then the
width is the width the embedded window and the specified borderwidth.  The
default is <I>0</I>. </DD>

<DT><B>-window <I>id</I></B> </DT>
<DD>Specifies the foreign embedded using its path or X window
id.   </DD>
</DL>
</blockquote>

<DL>

<DT><I>pathName <B>find <B>-command</B></B></I>|<B>-name</B> <I>pattern</I> </DT>
<DD>Searches for all windows that match
the given pattern.  If the <B>-command</B> switch is given, all windows whose WWM_COMMAND
property match <I>pattern</I> are returned in a list (X11 only).  If the <B>-name</B> switch is given,
all windows whose WWM_NAME property match <I>pattern</I> are returned in a list.
 The list returned will contains pairs of the window id and the matching
property. </DD>
</DL>

<H2><A NAME="sect7" HREF="#toc7">Keywords</A></H2>
container, widget <P>

<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Syntax</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Container Operations</A></LI>
<LI><A NAME="toc7" HREF="#sect7">Keywords</A></LI>
</UL>
</BODY></HTML>
blt-dev 2.5.3+dfsg-1 / usr / share / doc / blt-dev / html / container.html
