1iwidgets::tabnotebook − create and manipulate tabnotebook widgets

iwidgets::tabnotebook pathName? options? itk::Widget <‐ iwid‐

3gets::Tabnotebook

background disabledForeground foreground scrollCommand

cursor font height width

6See  the  "options"  manual entry for details on the standard op‐
7tions.
8Name:           angle
9Class:          Angle
10Command‐Line Switch:           ‐angle
11Specifes the angle of slope from the inner edge to the outer edge
12of  the  tab.   An angle of 0 specifies square tabs. Valid ranges
13are 0 to 45 degrees inclusive. Default is 15 degrees.  If  tabPos
14is e or w, this option is ignored.
15Name:           auto
16Class:          Auto
17Command‐Line Switch:           ‐auto
18Specifies  whether  to  use the automatic packing/unpacking algo‐
19rithm of the notebook. A value of true indicates that page frames
20will  be unpacked and packed acoording to the algorithm described
21in the select command. A value of false leaves the  current  page
22packed  and subsequent selects, next, or previous commands do not
23switch pages automatically. In either case the page’s  associated
24command (see the add command’s description of the command option)
25is invoked. The value may have any of the forms accepted  by  the

Tcl_GetBoolean, such as true, false, 0, 1, yes, or no.

27Name:           backdrop
28Class:          Backdrop
29Command‐Line Switch:           ‐backdrop
30Specifies  a background color to use when filling in the backdrop
31area behind the tabs.
32Name:           background
33Class:          Background
34Command‐Line Switch:           ‐background
35Specifies a background color to use for displaying a page and its
36associated  tab. This can be thought of as the selected tab back‐
37ground color, since the tab associated with the selected page  is
38the selected tab.
39Name:           bevelAmount
40Class:          BevelAmount
41Command‐Line Switch:           ‐bevelamount
42Specifes  the size of tab corners. A value of 0 with angle set to
430 results in square tabs. A bevelAmount of 4, means that the  tab
44will  be  drawn with angled corners that cut in 4 pixels from the
45edge of the tab. The default is 0.
46Name:           borderWidth
47Class:          BorderWidth
48Command‐Line Switch:           ‐borderwidth
49Specifies the width of shadowed border to place around the  note‐
50book area of the tabnotebook. The default value is 2.
51Name:           disabledForeground
52Class:          DisabledForeground
53Command‐Line Switch:           ‐disabledforeground
54Specifies  a foreground color to use for displaying a tab’s label
55when its state is disabled.
56Name:           equalTabs
57Class:          EqualTabs
58Command‐Line Switch:           ‐equaltabs
59Specifies whether to force tabs to be equal sized or not. A value
60of  true means constrain tabs to be equal sized. A value of false
61allows each tab to size based on the text label size.  The  value
62may have any of the forms accepted by the Tcl_GetBoolean, such as

true, false, 0, 1, yes, or no. For horizontally positioned tabs

64(tabpos is either s or n), true forces all tabs to be equal width
65(the width being equal to the longest label plus any padX  speci‐
66fied). Horizontal tabs are always equal in height.  For vertical‐
67ly positioned tabs (tabpos is either w or  e),  true  forces  all
68tabs  to be equal height (the height being equal to the height of
69the label with the largest font). Vertically  oriented  tabs  are
70always equal in width.
71Name:           foreground
72Class:          Foreground
73Command‐Line Switch:           ‐foreground
74Specifies a foreground color to use for displaying a page and its
75associated tab label. This can be thought of as the selected  tab
76background color, since the tab associated with the selected page
77is the selected tab.
78Name:           gap
79Class:          Gap
80Command‐Line Switch:           ‐gap
81Specifies the amount of pixel space to place  between  each  tab.
82Value  may be any pixel offset value. In addition, a special key‐
83word overlap can be used as the value to achieve a standard over‐
84lap  of  tabs. This value may have any of the forms acceptable to

Tk_GetPixels.

86Name:           margin
87Class:          Margin
88Command‐Line Switch:           ‐Bmargin
89Specifies the amount of space to place between the  outside  edge
90of the tabnotebook and the outside edge of its tabs. If tabPos is

s, this is the amount of space between the bottom edge of the

92tabnotebook  and the bottom edge of the set of tabs. If tabPos is

n, this is the amount of space between the top edge of the tab‐

94notebook  and  the  top  edge of the set of tabs. If tabPos is e,
95this is the amount of space between the right edge  of  the  tab‐
96notebook  and  the right edge of the set of tabs. If tabPos is w,
97this is the amount of space between the left edge of the tabnote‐
98book  and  the  left edge of the set of tabs. This value may have
99any of the forms acceptable to Tk_GetPixels.
100Name:           padX
101Class:          PadX
102Command‐Line Switch:           ‐padx
103Specifies a non‐negative value indicating how much extra space to
104request  for a tab around its label in the X‐direction. When com‐
105puting how large a window it needs, the tab will add this  amount
106to  the width it would normally need The tab will end up with ex‐
107tra internal space to the left and right of its text label.  This
108value may have any of the forms acceptable to Tk_GetPixels.
109Name:           padY
110Class:          PadY
111Command‐Line Switch:           ‐pady
112Specifies a non‐negative value indicating how much extra space to
113request for a tab around its label in the Y‐direction. When  com‐
114puting  how large a window it needs, the tab will add this amount
115to the height it would normally need The tab will end up with ex‐
116tra  internal space to the top and bottom of its text label. This
117value may have any of the forms acceptable to Tk_GetPixels.
118Name:           raiseSelect
119Class:          RaiseSelect
120Command‐Line Switch:           ‐raiseselect
121Specifes whether to slightly raise the selected tab from the rest
122of  the  tabs.  The  selected tab is drawn 2 pixels closer to the
123outside of the tabnotebook than the unselected tabs. A  value  of

true says to raise selected tabs, a value of false turns this

125feature off. The default is false. The value may have any of  the
126forms  accepted by the Tcl_GetBoolean, such as true, false, 0, 1,

yes, or no.

128Name:           start
129Class:          Start
130Command‐Line Switch:           ‐start
131Specifies the amount of space to place between the  left  or  top
132edge  of  the  tabnotebook and the starting edge of its tabs. For
133horizontally positioned tabs, this is the amount of space between
134the left edge of the notebook and the left edge of the first tab.
135For vertically positioned tabs, this is the amount of  space  be‐
136tween  the top of the notebook and the top of the first tab. This
137value may change if the user performs a MButton‐2 scroll  on  the
138tabs.  This value may have any of the forms acceptable to Tk_Get‐

Pixels.

140Name:           state
141Class:          State
142Command‐Line Switch:           ‐state
143Sets the active state of the tabnotebook. Specifying  normal  al‐
144lows all pages to be selectable. Specifying disabled disables the
145notebook causing all page tabs to be drawn in  the  disabledFore‐

ground color.

147Name:           tabBackground
148Class:          TabBackground
149Command‐Line Switch:           ‐tabbackground
150Specifies  a  background  color  to  use for displaying tab back‐
151grounds when they are in their  unselected  state.  This  is  the
152background  associated  with tabs on all pages other than the se‐
153lected page.
154Name:           tabBorders
155Class:          TabBorders
156Command‐Line Switch:           ‐tabborders
157Specifies whether to draw the borders of tabs that  are  not  se‐
158lected.  Specifying true (the default) draws these borders, spec‐
159ifying false draws only the border around the selected  tab.  The
160value  may  have any of the forms accepted by the Tcl_GetBoolean,
161such as true, false, 0, 1, yes, or no.
162Name:           tabForeground
163Class:          TabForeground
164Command‐Line Switch:           ‐tabforeground
165Specifies a foreground color to use  for  displaying  tab  labels
166when  they  are in their unselected state. This is the foreground
167associated with tabs on all pages other than the selected page.
168Name:           tabPos
169Class:          TabPos
170Command‐Line Switch:           ‐tabpos
171Specifies the location of the set of  tabs  in  relation  to  the
172notebook  area.  Must be n, s, e, or w. Defaults to s.  The iwid‐

gets::tabnotebook command creates a new window (given by the

174pathName  argument) and makes it into a tabnotebook widget. Addi‐
175tional options, described above may be specified on  the  command
176line  or  in the option database to configure aspects of the tab‐
177notebook such as its colors, font, and text.  The  iwidgets::tab‐
178notebook  command returns its pathName argument. At the time this
179command is invoked, there must not exist a window named pathName,
180but pathName’s parent must exist.  A tabnotebook is a widget that
181contains a set of tabbed pages. It displays one page from the set
182as  the  selected  page. A Tab displays the label for the page to
183which it is attached and serves as a page selector. When a page’s
184tab  is  selected,  the page’s contents are displayed in the page
185area. The selected tab has a three‐dimensional effect to make  it
186appear to float above the other tabs. The tabs are displayed as a
187group along either the left, top, right,  or  bottom  edge.  When
188first  created  a tabnotebook has no pages. Pages may be added or
189deleted using widget commands described below.  A special  option
190may  be  provided  to the tabnotebook. The ‐auto option specifies
191whether the tabnotebook will automatically handle  the  unpacking
192and  packing  of  pages  when pages are selected. A value of true
193signifies that the notebook will automatically manage it. This is
194the  default  value. A value of false signifies the notebook will
195not perform automatic switching of pages.  A tabnotebook’s  pages
196area  contains a single child site frame. When a new page is cre‐
197ated it is a child of this frame. The  page’s  child  site  frame
198serves  as  a geometry container for applications to pack widgets
199into. It is this frame that is automatically unpacked  or  packed
200when the auto option is true. This creates the effect of one page
201being visible at a time. When a new page is selected, the  previ‐
202ously  selected page’s child site frame is automatically unpacked
203from the tabnotebook’s child site frame and  the  newly  selected
204page’s  child  site  is  packed into the tabnotebook’s child site
205frame.  However, sometimes it is desirable to handle page changes
206in  a  different  manner. By specifying the auto option as false,
207child site packing can be disabled and done differently. For  ex‐
208ample,  all  widgets  might be packed into the first page’s child
209site frame. Then when a new page is selected, the application can
210reconfigure the widgets and give the appearance that the page was
211flipped.  In both cases the command option for a page specifies a
212Tcl  Command to execute when the page is selected. In the case of

auto being true, it is between the unpacking of the previously

214selected  page and the packing of the newly selected page.  Note‐
215book pages can also be controlled with scroll bars or other  wid‐
216gets  that obey the scrollcommand protocol. By giving a scrollbar
217a ‐command to call the tabnotebook’s select method, the  tabnote‐
218book  can  be  controlled with a scrollbar.  The notebook area is
219implemented with the notebook mega widget.  Tabs appear along the
220edge  of  the notebook area. Tabs are drawn to appear attached to
221their associated page. When a tab is clicked on,  the  associated
222page  is  selected and the tab is drawn as raised above all other
223tabs and as a seamless part of its notebook  page.  Tabs  can  be
224controlled in their location along the edges, the angle tab sides
225are drawn with, gap between tabs, starting margin of tabs, inter‐
226nal padding around text labels in a tab, the font, and its label.
227The Tab area is implemented with the  tabset  mega  widget.   See

tabset(1). Tabs may be oriented along either the north, south,

229east, or west sides with the tabPos option. North and south  tabs
230may appear as angled, square, or bevelled. West and east tabs may
231appear as square or bevelled. By changing tab gaps,  tab  angles,
232bevelling, orientations, colors, fonts, start locations, and mar‐
233gins; tabs may appear in a wide variety of styles.  For  example,
234it is possible to implement Microsoft‐style tabs, Borland proper‐
235ty tab styles, or Borland Delphi style tabs  all  with  the  same
236tabnotebook.  The iwidgets::tabnotebook command creates a new Tcl
237command whose name is pathName. This command may be used  to  in‐
238voke  various operations on the widget. It has the following gen‐
239eral form: pathName option ?arg arg ...?  option and the args de‐
240termine  the  exact  behavior of the command.  Many of the widget
241commands for a notebook take as  one  argument  an  indicator  of
242which  page  of  the notebook to operate on. These indicators are
243called indexes and may be  specified  in  any  of  the  following
244forms: number Specifies the page numerically, where 0 corresponds
245to the first page in the notebook, 1 to the second,  and  so  on.

select Specifies the currently selected page’s index. If no page

247is currently selected, the value ‐1 is  returned.   end  Specifes
248the last page in the tabnotebook’s index. If the notebook is emp‐
249ty this will return ‐1.  pattern If the index doesn’t satisfy any
250of  the  above forms, then this form is used. Pattern is pattern‐
251matched against the label of each page in the notebook, in  order
252from the first to the last page, until a matching entry is found.
253The rules of Tcl_StringMatch are used.   The  following  commands
254are  possible for tabnotebook widgets: pathName add ?option value

option value ...? Add a new page at the end of the tabnotebook.

256A  new  child site frame is created. Returns the child site path‐
257Name. If additional arguments are present, they  specify  any  of
258the  following  options: ‐angle value Specifes the angle of slope
259from the inner edge to the outer edge of the tab. An angle  of  0
260specifies  square  tabs.  Valid ranges are 0 to 45 degrees inclu‐
261sive. Default is 15 degrees. If this option is  specified  as  an
262empty string (the default), then the angle option for the overall
263tabnotebook is used. This is generally only set at  the  tabnote‐
264book  level. Tabs normally will want to share the same angle val‐
265ue.  ‐background value Specifies a background color  to  use  for
266displaying  tabs  when  they  are selected and for displaying the
267current page. If this option is specified as an empty string (the
268default),  then the background option for the overall tabnotebook
269is used.  ‐bevelamount value Specifes the size of tab corners.  A
270value of 0 with angle set to 0 results in square tabs. A bevelAm‐
271ount of 4, means that the tab will be drawn with  angled  corners
272that cut in 4 pixels from the edge of the tab.  The default is 0.
273This is generally only set at the tabnotebook level.   Tabs  nor‐
274mally  will want to share the same bevelAmount.  ‐bitmap value If
275label is a non‐empty string, specifies a  bitmap  to  display  in
276this  page’s  tab.  Bitmap may be of any of the forms accepted by
277Tk_GetPixmap.  ‐command value Specifies a Tcl command to be  exe‐
278cuted  when  this  page is selected. This allows the programmer a
279hook to reconfigure this page’s widgets or any other page’s  wid‐
280gets.  If the tabnotebook has the auto option set to true, when a
281page is selected this command will be  called  immediately  after
282the  previously  selected page is unpacked and immediately before
283this page is selected. The index value  select  is  valid  during
284this  Tcl  command.  ‘index  select’ will return this page’s page
285number.  If the auto option is set to false, when a page  is  se‐
286lected  the  unpack and pack calls are bypassed. This Tcl command
287is still called.  ‐disabledforeground  value  Specifies  a  fore‐
288ground  color  to  use for displaying tab labels when tabs are in
289their disable state. If this option  is  specified  as  an  empty
290string  (the default), then the disabledforeground option for the
291overall tabnotebook is used.  ‐font value Specifies the  font  to
292use  when  drawing  a text label on a page tab. If this option is
293specified as an empty string then the font option for the overall
294tabnotebook  is  used..  ‐foreground value Specifies a foreground
295color to use for displaying tab labels when they are selected. If
296this  option  is specified as an empty string (the default), then
297the foreground option for the overall tabnotebook is used.   ‐la‐

bel value Specifies a string to display as an identifying label

299for a notebook page. This label serves as an additional identifi‐
300er used to reference the page. This label may be used for the in‐
301dex value in widget commands.  ‐tabbackground value  Specifies  a
302background  color  to  use  for  displaying  a tab when it is not
303elected. If this option is specified as an empty string (the  de‐
304fault), then the tabBackground option for the overall tabnotebook
305is used.  ‐tabforeground value Specifies a  foreground  color  to
306use  for displaying the tab’s text label when it is not selected.
307If this option is specified as an  empty  string  (the  default),
308then  the  tabForeground  option  for  the overall tabnotebook is
309used.  ‐padx value Specifies a non‐negative value indicating  how
310much  extra space to request for a tab around its label in the X‐
311direction. When computing how large a window it  needs,  the  tab
312will  add this amount to the width it would normally need The tab
313will end up with extra internal space to the left  and  right  of
314its  text  label. This value may have any of the forms acceptable
315to Tk_GetPixels. If this option is specified as an  empty  string
316(the  default),  then the padX option for the overall tabnotebook
317is used ‐pady value Specifies a non‐negative value indicating how
318much  extra space to request for a tab around its label in the Y‐
319direction. When computing how large a window it  needs,  the  tab
320will add this amount to the height it would normally need The tab
321will end up with extra internal space to the top  and  bottom  of
322its  text  label. This value may have any of the forms acceptable
323to Tk_GetPixels. If this option is specified as an  empty  string
324(the  default),  then the padY option for the overall tabnotebook
325is used ‐state value Specifies one of two states  for  the  page:
326normal or disabled. In normal state unselected tabs are displayed
327using the tabforeground and tabbackground option  from  the  tab‐
328notebook or the page. Selected tabs and pages are displayed using
329the foreground and background option from the tabnotebook or  the
330page.  The  disabled state means that the page and its tab is in‐
331sensitive: it doesn’t respond to mouse button presses or  releas‐
332es.  In  this  state the entry is displayed according to its dis‐
333abledForeground  option  for  the  tabnotebook  and   the   back‐
334ground/tabbackground  option  from  the  page or the tabnotebook.

pathName childSite ?index? If passed no arguments, returns a

336list  of  pathNames  for all the pages in the tabnotebook. If the
337tab notebook is empty, an empty list  is  returned  If  index  is
338passed,  it  returns the pathName for the page’s child site frame
339specified by index. Widgets that are created with  this  pathName
340will  be displayed when the associated page is selected. If index
341is not a valid index, an empty string is returned.  pathName con‐

figure ?option? ?value option value ...? Query or modify the

343configuration options of the widget. If no option  is  specified,
344returns  a list describing all of the available options for path‐

Name (see Tk_ConfigureInfo for information on the format of this

346list). If option is specified with no value, then the command re‐
347turns a list describing the one named option (this list  will  be
348identical  to  the corresponding sublist of the value returned if
349no option is specified). If one or more  option‐value  pairs  are
350specified,  then  the command modifies the given widget option(s)
351to have the given value(s); in this case the command  returns  an
352empty  string.  Option may have any of the values accepted by the
353iwidgets::tabnotebook command.  pathName delete  index1  ?index2?
354Delete  all of the pages between index1 and index2 inclusive.  If

index2 is omitted then it defaults to index1. Returns an empty

356string.   pathName index index Returns the numerical index corre‐
357sponding to index.  pathName insert index  ?option  value  option

value ...? Insert a new page in the tabnotebook before the page

359specified by index. A new child site frame is created. The  addi‐
360tional arguments are the same as for the add command. Returns the
361child site pathName.  pathName next Advances the selected page to
362the  next  page  (order is determined by insertion order). If the
363currently selected page is the last page in the notebook, the se‐
364lection  wraps  around  to the first page in the notebook. It be‐
365haves as if the user selected the new page.  For  notebooks  with

auto set to true the current page’s child site is unpacked from

367the notebook’s child site frame. Then the next page’s child  site
368is  packed  into the notebook’s child site frame. The Tcl command
369given with the command option will be invoked between  these  two
370operations.  For notebooks with auto set to false the Tcl command
371given with the command option will be invoked.  pathName pagecon‐

figure index ?option? ?value option value ...? This command is

373similar to the configure command, except that it applies  to  the
374options  for an individual page, whereas configure applies to the
375options for the tabnotebook as a whole. Options may have  any  of
376the  values  accepted  by  the add widget command. If options are
377specified, options are modified as indicated in the  command  and
378the command returns an empty string. If no options are specified,
379returns a list describing the current options for page index (see

Tk_ConfigureInfo for information on the format of this list).

pathName prev Moves the selected page to the previous page (order

382is determined by insertion order). If the currently selected page
383is the first page in the notebook, the selection wraps around  to
384the last page in the notebook. It behaves as if the user selected
385the new page.  For notebooks with auto set to  true  the  current
386page’s  child  site  is  unpacked  from the notebook’s child site

frame. Then the previous page’s child site is packed into the

388notebook’s child site frame.  The Tcl command given with the com‐
389mand option will be invoked between these  two  operations.   For
390notebooks  with  auto set to false the Tcl command given with the
391command option will be invoked.  pathName  select  index  Selects
392the  page  specified by index as the currently selected page.  It
393behaves as if the user selected the new page.  For notebooks with

auto set to true the current page’s child site is unpacked from

395the notebook’s child site frame. Then the index page’s child site
396is  packed  into the notebook’s child site frame. The Tcl command
397given with the command option will be invoked between  these  two
398operations.  For notebooks with auto set to false the Tcl command
399given with the command option will be invoked.  pathName view Re‐
400turns  the  currently selected page. This command is for compati‐
401bility with the scrollbar widget.  pathName  view  index  Selects
402the page specified by index as the currently selected page.  This
403command is for compatibility with the scrollbar widget.  pathName

view moveto fraction Uses the fraction value to determine the

405corresponding page to move to.  This command is for compatibility
406with  the  scrollbar  widget.  pathName view scroll num what Uses
407the num value to determine how many  pages  to  move  forward  or
408backward  (num can be negative or positive). The what argument is
409ignored. This command is for  compatibility  with  the  scrollbar
410widget.   Generally all behavior of the internal components, tab‐

set and notebook are controlled via the pageconfigure method.

412The following section documents these two components.
413Name:   tabset
414Class:  Tabset
415This is the tabset component. It implements the tabs that are as‐
416sociated with the notebook component.  See  the  "Tabset"  widget
417manual entry for details on the tabset component item.
418Name:   notebook
419Class:  Notebook
420This  is  the notebook component. It implements the notebook that
421contains the pages of the tabnotebook.  See the "Notebook" widget
422manual entry for details on the notebook component item.
423Following  is  an  example  that  creates  a tabnotebook with two
424pages.
425package require Iwidgets 4.0
426# Create the tabnotebook widget and pack it.
427  iwidgets::tabnotebook .tn ‐width 100 ‐height 100
428  pack .tn \
429        ‐anchor nw \
430        ‐fill both \
431        ‐expand yes \
432        ‐side left \
433        ‐padx 10 \
434        ‐pady 10
435# Add two pages to the tabnotebook,
436# labelled "Page One" and "Page Two"
437  .tn add ‐label "Page One"
438  .tn add ‐label "Page Two"
439# Get the child site frames of these two pages.
440  set page1CS [.tn childsite 0]
441  set page2CS [.tn childsite "Page Two"]
442# Create buttons on each page of the tabnotebook.
443  button $page1CS.b ‐text "Button One"
444  pack $page1CS.b
445  button $page2CS.b ‐text "Button Two"
446  pack $page2CS.b
447# Select the first page of the tabnotebook.
448  .tn select 0
449Bill W. Scott tab tabset notebook tabnotebook page
450
451
452
453
454
455
456
457
458
459
460
461
462
Impressum