diff options
Diffstat (limited to 'blt/man/container.mann')
| -rw-r--r-- | blt/man/container.mann | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/blt/man/container.mann b/blt/man/container.mann new file mode 100644 index 00000000000..682fff36dcc --- /dev/null +++ b/blt/man/container.mann @@ -0,0 +1,303 @@ +'\" +'\" Copyright 1998 by Bell Labs Innovations for Lucent Technologies. +'\" +'\" Permission to use, copy, modify, and distribute this software and its +'\" documentation for any purpose and without fee is hereby granted, provided +'\" that the above copyright notice appear in all copies and that both that the +'\" copyright notice and warranty disclaimer appear in supporting documentation, +'\" and that the names of Lucent Technologies any of their entities not be used +'\" in advertising or publicity pertaining to distribution of the software +'\" without specific, written prior permission. +'\" +'\" Lucent Technologies disclaims all warranties with regard to this software, +'\" including all implied warranties of merchantability and fitness. In no event +'\" shall Lucent Technologies be liable for any special, indirect or +'\" consequential damages or any damages whatsoever resulting from loss of use, +'\" data or profits, whether in an action of contract, negligence or other +'\" tortuous action, arising out of or in connection with the use or performance +'\" of this software. +'\" +'\" Container widget created by George Howlett. +'\" +.so man.macros.in +.TH container n BLT_VERSION BLT "BLT Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +container \- Widget to contain a foreign window. +.BE +.SH SYNOPSIS +\fBcontainer\fR \fIpathName \fR?\fIoptions\fR? +.SH DESCRIPTION +The \fBcontainer\fR widget lets you 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. +.SH 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 \fBframe\fR because +they are too large. The other alternative is to pack the graphs into +several \fBtoplevel\fR 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. +.PP +The \fBcontainer\fR 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 \fBcontainer\fR 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. +.PP +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. +.SH EXAMPLE +You create a container widget with the \fBcontainer\fR command. +.CS +# Create a new container +container .c +.CE +A new Tcl command \f(CW.c\fR 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 \fBconfigure\fR operation. +.CS +# Change the default font. +\&.c configure \-borderwidth 2 +.CE +You can then add folders using the \fBinsert\fR operation. +.CS +# Create a new folder "f1" +\&.c coinsert 0 "f1" +.CE +This inserts the new tab named "f1" into the container. The index +\f(CW0\fR indicates location to insert the new tab. You can also use +the index \f(CWend\fR 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 \fB\-text\fR option. +.CS +# Change the label of "f1" +\&.ts tab configure "f1" -label "Tab #1" +.CE +The \fBinsert\fR operation lets you add one or more folders at a time. +.CS +\&.ts insert end "f2" -label "Tab #2" "f3" "f4" +.CE +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 \fBtab +configure\fR operation. +.CS +# 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 +.CE +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 \fB\-window\fR 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. +.CS +graph .ts.graph +\&.ts tab configure "f1" -window ".ts.graph" \\ + -fill both -padx 0.25i -pady 0.25i +.CE +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 \fB\-pagewidth\fR and \fB\-pageheight\fR options override this. +.PP +Other options control how the widget appears in the folder. The +\fB\-fill\fR option says that you wish to have the widget stretch to +fill the available space in the folder. +.CS +\&.ts tab configure "f1" -fill both -padx 0.25i -pady 0.25i +.CE +.PP +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. +.PP +If you want to share a page between two different folders, the +\fB\-command\fR option lets you specify a Tcl command to be invoked +whenever the folder is selected. You can reset the \fB\-window\fR +option for the tab whenever it's clicked. +.CS +\&.ts tab configure "f2" -command { + \&.ts tab configure "f2" -window ".ts.graph" +} +\&.ts tab configure "f1" -command { + \&.ts tab configure "f1" -window ".ts.graph" +} +.CE +If you have many folders, you may wish to stack tabs in multiple +tiers. The container's \fB\-tiers\fR option requests a maximum +number of tiers. The default is one tier. +.CS +\&.ts configure -tiers 2 +.CE +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. +.CS +\&.ts configure -scrollcommand { .sbar set } -scrollincrement 20 +\&.sbar configure -orient horizontal -command { .ts view } +.CE +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 \fB\-side\fR +option. +.CS +# Arrange tabs along the right side of the container. +\&.ts configure -side right -rotate 270 +.CE +.SH SYNTAX +The \fBcontainer\fR command creates a new window using the \fIpathName\fR +argument and makes it into a container widget. +.CS +\fBcontainer \fIpathName \fR?\fIoption value\fR?... +.CE +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 \fBcontainer\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, there +must not exist a window named \fIpathName\fR, but \fIpathName\fR's +parent must exist. +.PP +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 \fB\-scrollcommand\fR +option. They also support scanning (see the \fBscan\fR operation). +Tabs may be arranged along any side of the container window using the +\fB\-side\fR option. +.PP +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 detemined solely by the size of the tabs. +.PP +You can override either dimension with the container's \fB\-width\fR +and \fB\-height\fR options. +.SH "CONTAINER OPERATIONS" +All \fBcontainer\fR operations are invoked by specifying the widget's +pathname, the operation, and any arguments that pertain to that +operation. The general form is: +.sp +.CS + \fIpathName operation \fR?\fIarg arg ...\fR? +.CE +.sp +\fIOperation\fR and the \fIarg\fRs determine the exact behavior of the +command. The following operations are available for container widgets: +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \fBconfigure\fR +operation described below. +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list describing all +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, 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 \fIoption\fR is specified). If +one or more \fIoption\-value\fR 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. +\fIOption\fR and \fIvalue\fR are described below: +.RS +.TP +\fB\-background \fIcolor\fR +Sets the border color of the container. +.TP +\fB\-borderwidth \fIpixels\fR +Sets the width of the 3\-D border around the outside edge of the widget. The +\fB\-relief\fR option determines how the border is to be drawn. The +default is \f(CW2\fR. +.TP +\fB\-command \fIpattern\fR +Specifies to search for a window whose \f(CWWM_COMMAND\fR property matches +the given pattern. If no windows, or more than one window, matches +the pattern, an error is generated. If \fIpattern\fR is the empty +string, then no command search is performed. +The default is \f(CW""\fR. +.TP +\fB\-cursor \fIcursor\fR +Specifies the widget's cursor. The default cursor is \f(CW""\fR. +.TP +\fB\-height \fIpixels\fR +Specifies the requested height of widget. If \fIpixels\fR is +0, then the height is height the embedded window plus the specified +borderwidth. The default is \f(CW0\fR. +.TP +\fB\-highlightbackground \fIcolor\fR +Sets the color to display in the traversal highlight region when +the container does not have the input focus. +.TP +\fB\-highlightcolor \fIcolor\fR +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 \f(CWblack\fR. +.TP +\fB\-highlightthickness \fIpixels\fR +Sets the width of the highlight rectangle to draw around the outside of +the widget when it has the input focus. \fIPixels\fR is a non-negative +value and may have any of the forms acceptable to \fBTk_GetPixels\fR. +If the value is zero, no focus highlight is drawn around the widget. +The default is \f(CW2\fR. +.TP +\fB\-name \fIpattern\fR +Specifies to search for a window whose \f(CWWM_NAME\fR property matches +the given pattern. If no windows, or more than one window, matches +the pattern, an error is generated. If \fIpattern\fR is the empty +string, then no name search is performed. +The default is \f(CW""\fR. +.TP +\fB\-relief \fIrelief\fR +Specifies the 3-D effect for the container widget. \fIRelief\fR +specifies how the container should appear relative to widget that +it is packed into; for example, \f(CWraised\fR means the container should +appear to protrude. The default is \f(CWsunken\fR. +.TP +\fB\-takefocus\fR \fIfocus\fR +Provides information used when moving the focus from window to window +via keyboard traversal (e.g., Tab and Shift-Tab). If \fIfocus\fR is +\f(CW0\fR, this means that this window should be skipped entirely during +keyboard traversal. \f(CW1\fR 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 \f(CW1\fR. +.TP +\fB\-width \fIpixels\fR +Specifies the requested width of the widget. If \fIpixels\fR is 0, +then the width is the width the embedded window and the specified +borderwidth. The default is \f(CW0\fR. +.TP +\fB\-window \fIid\fR +Specifies the foreign embedded using its X window id. +.RE +.TP +\fIpathName \fBfind \fB\-command\fR|\fB\-name\fR \fIpattern\fR +Searches for all windows that match the given pattern. If the +\fB\-command\fR switch is given, all windows whose \fCWWM_COMMAND\fR +property match \fIpattern\fR are returned in a list. If the +\fB\-name\fR switch is given, all windows whose \fCWWM_NAME\fR +property match \fIpattern\fR are returned in a list. The list +returned will contains pairs of the window id and the matching property. +.SH KEYWORDS +container, widget |