GNU/Linux man pages
Livre :
Expressions régulières,
Syntaxe et mise en oeuvre :
GNU/Linux |
RedHat 6.2(Zoot) |
|
 |
hierbox(n) |
 |
______________________________________________________________________________
hierbox − Create and manipulate hierarchical listbox widgets ______________________________________________________________________________
hierbox pathName ?options?
The hierbox widget that displays a hierarchy of entries, drawn one per line. The hierarchy is a general ordered tree of entries. Each entry contains a list of subentries which in turn can contain their own lists of subentries. The lists of subentries can be opened (shown) or closed (hidden). Individual entries can be selected.
The hierbox command creates a new window (given by the pathName argument) and makes it into a hierbox widget. hierbox pathName ?option value?... Additional options, described above, may be specified on the command line or in the option database to configure aspects of the hierbox such as its colors, font, text, and relief. The hierbox 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.
An entry an icon (image), text label, and optionally a data field.
When first created, a new hierbox has no elements. Elements may be added or deleted using widget operations described below. one or more elements may be selected as described below.
When entries are inserted, they are given a name which can used to specify them later.
It is not necessary for all the elements to be displayed in the hierbox window at once; commands described below may be used to change the view in the window. Hierboxes allow scrolling in both directions using the standard xScrollCommand and yScrollCommand options. They also support scanning, as described below.
Many of the operations for hierbox widgets take one or more indices as arguments. The indices refer to individual nodes in the hierarchy. An index may take one of several forms:
|
number |
Each entry in the widget has a serial number that uniquely identifies it. The number doesn’t indicate the location or position an entry (for example, you can’t determine the order of two entries from their node numbers), but if an entry is moved, the node ID will still refer to it. Node "0" is always the root of the hierarchy. | ||
|
active |
Entry where the mouse pointer is currently located. The label is drawn using its active colors (see the −activebackground and −activeforeground options). The active index is typically changed by moving the mouse pointer over a entry or using the widget’s activate operation. There can be only one active entry at a time. | ||
|
anchor |
Indicates the anchor point for the selection. The anchor point is set by the selection anchor operation. | ||
|
focus |
Indicates the entry that currently has focus. This entry is displayed with a dashed line around its label. You can change this using the focus operation. | ||
|
root |
Indicates the root entry which is displayed as the first entry of the hierbox. You can also use the node "0" to describe the root. | ||
|
end |
Indicates the last entry which is displayed at the bottom of the hierbox. This is the last open entry. | ||
|
up |
Entry immediately above the entry that has focus. If the focus is at root, then up is also root. | ||
|
down |
Entry immediately below the entry that has focus. If the focus is the last entry of the hierbox, then down is the same. | ||
|
prev |
Entry above the entry with focus. Unlike up, if the focus is at root, prev wraps around to the bottom entry currently displayed in the widget. | ||
|
next |
Entry below the entry with focus. Unlike down, if the focus is on the bottom-most entry displayed in the hierbox, next wraps up to the root node. | ||
|
parent |
Parent of the entry with focus. The parent of the root is also the root. | ||
|
sibling |
Next sibling of the parent. | ||
|
view.top |
First partially visible entry in the hierbox window. | ||
|
view.bottom |
Last partially visible entry in the hierbox window. | ||
|
path |
Absolute path of an entry. Path names refer to the node name, not their entry labels. Paths don’t have to start with a separator (see the −separator configuration option), but component names must be separated by the designated separator. | ||
|
@x,y |
Indicates the element that covers the point in the hierbox window specified by x and y (in pixel coordinates). If no element covers that point, then the closest element to that point is used. |
The hierbox operations have the 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 operation are available for hierbox
widgets:
pathName activate index
Sets the active entry to the one indicated by index. The active entry is drawn with a black outline around its label and its index may be retrieved with the index active.
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 close ?−recurse? index...
Closes the level of each entry specified by index. The Tcl script specified by the −closecommand option is also invoked. If the −recurse flag is set, then each subnode is recursively closed also. If the entry is already closed, this command has no effect.
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 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 background color the hierbox. The default is white.
−borderwidth pixels
Sets the width of the 3−D border around the outside edge of the widget. The −relief option determines if the border is to be drawn. The default is 2.
−closecommand string
Specifies a Tcl script to be invoked when an entry is closed. Individual entries may override this with their own −closecommand option. The default is "".
−closerelief relief
Specifies the 3-D effect for gadgets of closed entries. Relief specifies how the gadget should appear relative to entry; for example, raised means the gadget should appear to protrude. The default is raised.
−cursor cursor
Specifies the widget’s cursor. The default cursor is "".
−dashes number
Sets the dash style of the horizontal and vertical lines drawn connecting entries. Number is the length in pixels which represents the lengths of the dashes and gaps. If number is 0, solid lines will be drawn. The default is 1.
−exportselection boolean
Indicates if the selection is exported. If a hierbox is exporting its selection then it will observe the standard X11 protocols for handling the selection. Selections are available as type STRING; the value of the selection will be the text of the selected elements, with newlines separating the elements. The default is no.
−font fontName
Specifies the font for entry labels. Individual entries may override this with their own −font option. The default is *-Helvetica-Bold-R-Normal-*-12-120-*.
−foreground color
Specifies the color of entry labels. Individual entries may override this with their own −foreground option. The default is black.
−gadgetactivebackground color
Specifies the background color non-image gadgets when the pointer is placed over it.
−gadgetactiveforeground color
Specifies the foreground color non-image gadgets when the pointer is placed over it.
−gadgetbackground color
Specifies the background color of gadgets. The default is black.
−gadgetborderwidth pixels
Specifies a non-negative value indicating the width of the 3-D border to draw around the gadgets. The default is 1.
−gadgetforeground color
Specifies the foreground color of gadgets. The default is black.
−gadgets imageList
Specifies the gadget images for open and closed entries. If imageList contains the name of two Tk images, that first image will be displayed with the entry is closed, and the second when entry is opened. If imageList contains only one image, the same image will be drawn regardless the entry is opened or closed. If imageList is the empty string, the default (+/-) symbols will be drawn for gadgets. The default is "".
−height pixels
Specifies the requested height of widget. The default is 400.
−highlightbackground color
Specifies the color to display in the traversal highlight region when the hierbox does not have the input focus.
−highlightcolor color
Specifies 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
Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. The value 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.
−linecolor color
Sets the color of lines drawn connecting entries. The default is black.
−linespacing pixels
Sets the number of pixels spacing between entries. The default is 0.
−linewidth pixels
Set the width of the lines drawn connecting entries. If pixels is 0, no lines are drawn. The default is 1.
−opencommand string
Specifies a Tcl script to be invoked when an entry is open. For example, this may be used to populate the hierarchy as it is traversed. Individual entries may override this with their own −opencommand option. The default is "".
−openrelief relief
Specifies the 3-D effect for gadgets of open entries. Relief specifies how the gadget should appear relative to entry; for example, raised means the gadget should appear to protrude. The default is sunken.
−relief relief
Specifies the 3-D effect for the hierbox widget. Relief specifies how the hierbox should appear relative to widget it is packed into; for example, raised means the hierbox should appear to protrude. The default is sunken.
−scrolltile boolean
Indicates if the tile should appear to scroll when the widget is scrolled.
−selectbackground color
Specifies the color to use when displaying background of selected entries. The default is lightblue2.
−selectborderwidth pixels
Specifies a non-negative value indicating the width of the raised 3-D border to draw around the labels of selected entries. The default is 1.
−selectforeground color
Specifies the color to use when drawing the labels of selected entries. The default is black.
−separator string
Specifies the path separator of components of entries. The separator may several characters (such as "::"). This string is used to parse entry pathnames. The default is "".
−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 make the decision whether to focus on the window. The default is "1".
−tile image
Specifies a tiled background for the widget. If image isn’t "", the background is tiled using image. Otherwise, the normal background color is drawn (see the −background option). Image must be an image created using the Tk image command. The default is "".
−trimleft string
Specifies leading characters to trim from entry pathnames.
−width pixels
Specifies the requested width of the widget. The default is 200.
−xscrollcommand string
Specifies the prefix for a command used to communicate with horizontal scrollbars. Whenever the horizontal view in the widget’s window changes, the widget will generate a Tcl command by concatenating the scroll command and two numbers. If this option is not specified, then no command will be executed.
−yscrollcommand string
Specifies the prefix for a command used to communicate with vertical scrollbars. Whenever the vertical view in the widget’s window changes, the widget will generate a Tcl command by concatenating the scroll command and two numbers. If this option is not specified, then no command will be executed.
pathName curselection
Returns a list containing the numerical indices of all of the elements in the hierbox that are currently selected. If there are no elements selected in the hierbox then an empty string is returned.
pathName delete first ?last?
Deletes one or more elements of the hierbox. First and last are indices specifying the first and last elements in the range to delete. If last isn’t specified it defaults to first, i.e. a single element is deleted.
pathName entry operation ?args?
See the ENTRY OPERATIONS section.
pathName get ?−full? index...
Returns a list of the names for the indices specified. If the −full flag is set, then the full pathnames for the elements are returned.
pathName index ?−at index? index
Returns the node index of the entry specified by index. Several forms of indices return an index relative to currently active entry (they are describe in the section HIERBOX INDICES ). The −at flag lets you get an index for some entry other than the active one.
pathName insert ?−at index? position name... ?option value?...
Inserts zero or more new elements in an hierarchy list just before the entry given by position. Position is a number indicating where in the list, new elements should be added. If position is end then the new elements are added to the end of the list. Returns a list containing the indices of the new entries.
pathName nearest x y ?varName?
Returns the index of the entry closest to the given X-Y screen coordinate. The optional argument varName is the name of variable which is set to a string over what parts of the entry the coordinate lies. The part names are gadget and select. If the coordinate is not directly over any entry, then varName will contain the empty string.
pathName open ?−recurse? index...
Displays the lists of subentries for each entry specified by index. If an entry is not already open, the Tcl script specified by the −opencommand option is also invoked. If the −recurse flag is set, then each subentry is recursively opened too.
pathName scan option args
This command is used to
implement scanning on hierboxes. It has two forms, depending
on option:
pathName scan mark x y
Records x and y and the current view in the hierbox window; used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string.
pathName scan dragto x y.
This command computes the difference between its x and y arguments and the x and y arguments to the last scan mark command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string.
pathName see index
Adjust the view in the hierbox so that the entry given by index is visible in the middle of the hierbox.
pathName selection option arg
This command is used to adjust
the selection within a hierbox. It has several forms,
depending on option:
pathName selection anchor index
Sets the selection anchor to the element given by index. │ If index refers to a non-existent element, then the │ closest element is used. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse. The index anchor may be used to refer to the anchor element.
pathName selection clear first ?last?
If any of the elements between first and last (inclusive) are selected, they are deselected. The selection state is not changed for elements outside this range.
pathName selection includes index
Returns 1 if the element indicated by index is currently selected, 0 if it isn’t.
pathName selection set first ?last?
Selects all of the elements in the range between first and last, inclusive, without affecting the selection state of elements outside that range.
pathName xview args
This command is used to query
and change the horizontal position of the information in the
widget’s window. It can take any of the following
forms:
pathName xview
Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the hierbox’s text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the −xscrollcommand option.
pathName xview index
Adjusts the view in the window so that the character position given by index is displayed at the left edge of the window. Character positions are defined by the width of the character 0.
pathName xview moveto fraction
Adjusts the view in the window so that fraction of the total width of the hierbox text is off-screen to the left. fraction must be a fraction between 0 and 1.
pathName xview scroll number what
This command shifts the view in the window left or right according to number and what. Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units, the view adjusts left or right by number character units (the width of the 0 character) on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.
pathName yview ?args?
This command is used to query
and change the vertical position of the text in the
widget’s window. It can take any of the following
forms:
pathName yview
Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the hierbox element at the top of the window, relative to the hierbox as a whole (0.5 means it is halfway through the hierbox, for example). The second element gives the position of the hierbox element just after the last one in the window, relative to the hierbox as a whole. These are the same values passed to scrollbars via the −yscrollcommand option.
pathName yview index
Adjusts the view in the window so that the element given by index is displayed at the top of the window.
pathName yview moveto fraction
Adjusts the view in the window so that the element given by fraction appears at the top of the window. Fraction is a fraction between 0 and 1; 0 indicates the first element in the hierbox, 0.33 indicates the element one-third the way through the hierbox, and so on.
pathName yview scroll number what
This command adjusts the view in the window up or down according to number and what. Number must be an integer. What must be either units or pages. If what is units, the view adjusts up or down by number lines; if it is pages then the view adjusts by number screenfuls. If number is negative then earlier elements become visible; if it is positive then later elements become visible.
pathName entry bbox index
Returns a list of four numbers describing the bounding box of the text in the entry given by index. The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the entry (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the entry given by index is visible on the screen then the result is an empty string. If the element is partially visible, the result gives the full area of the element, including any parts that are not visible.
pathName entry 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 entry children index ?first? ?last?
Returns the list of nodes of the subentries at index. By default, all subentries listed in index are returned. If a rst argument is present, then the node index of the subentry at that numeric position is returned. If both first and last arguments are given, then the nodes of the subentries in that range are returned.
pathName entry 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 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:
pathName entry hidden index
Returns 1 if the entry is currently hidden and 0 otherwise. An entry is not hidden if all of its ancestor entries are open.
pathName entry open index
Returns 1 if the entry is currently open and 0 otherwise.
pathName entry size −recurse index
Returns the number of subentries at index. If the −recurse flag is set, then each the number of all subentries under index is returned.
pathName entry configure −recurse index
Returns the number of subentries at index. If the −recurse flag is set, then each the number of all subentries under index is returned.
Tk automatically creates class bindings for hierboxes that give them Motif-like behavior. Much of the behavior of a hierbox is determined by its selectMode option, which selects one of four ways of dealing with the selection.
If the selection mode is single or browse, at most one element can be selected in the hierbox at once. In both modes, clicking button 1 on an element selects it and deselects any other selected item. In browse mode it is also possible to drag the selection with button 1.
If the selection mode is multiple or extended, any number of elements may be selected at once, including discontiguous ranges. In multiple mode, clicking button 1 on an element toggles its selection state without affecting any other elements. In extended mode, pressing button 1 on an element selects it, deselects everything else, and sets the anchor to the element under the mouse; dragging the mouse with button 1 down extends the selection to include all the elements between the anchor and the element under the mouse, inclusive.
Most people will probably want to use browse mode for single selections and extended mode for multiple selections; the other modes appear to be useful only in special situations.
In addition to the above behavior, the following additional behavior is defined by the default bindings:
|
[1] |
In extended mode, the selected range can be adjusted by pressing button 1 with the Shift key down: this modifies the selection to consist of the elements between the anchor and the element under the mouse, inclusive. The un-anchored end of this new selection can also be dragged with the button down. | ||
|
[2] |
In extended mode, pressing button 1 with the Control key down starts a toggle operation: the anchor is set to the element under the mouse, and its selection state is reversed. The selection state of other elements isn’t changed. If the mouse is dragged with button 1 down, then the selection state of all elements between the anchor and the element under the mouse is set to match that of the anchor element; the selection state of all other elements remains what it was before the toggle operation began. | ||
|
[3] |
If the mouse leaves the hierbox window with button 1 down, the window scrolls away from the mouse, making information visible that used to be off-screen on the side of the mouse. The scrolling continues until the mouse re-enters the window, the button is released, or the end of the hierbox is reached. | ||
|
[4] |
Mouse button 2 may be used for scanning. If it is pressed and dragged over the hierbox, the contents of the hierbox drag at high speed in the direction the mouse moves. | ||
|
[5] |
If the Up or Down key is pressed, the location cursor (active element) moves up or down one element. If the selection mode is browse or extended then the new active element is also selected and all other elements are deselected. In extended mode the new active element becomes the selection anchor. | ||
|
[6] |
In extended mode, Shift-Up and Shift-Down move the location cursor (active element) up or down one element and also extend the selection to that element in a fashion similar to dragging with mouse button 1. | ||
|
[7] |
The Left and Right keys scroll the hierbox view left and right by the width of the character 0. Control-Left and Control-Right scroll the hierbox view left and right by the width of the window. Control-Prior and Control-Next also scroll left and right by the width of the window. | ||
|
[8] |
The Prior and Next keys scroll the hierbox view up and down by one page (the height of the window). | ||
|
[9] |
The Home and End keys scroll the hierbox horizontally to the left and right edges, respectively. | ||
|
[10] |
Control-Home sets the location cursor to the the first element in the hierbox, selects that element, and deselects everything else in the hierbox. | ||
|
[11] |
Control-End sets the location cursor to the the last element in the hierbox, selects that element, and deselects everything else in the hierbox. | ||
|
[12] |
In extended mode, Control-Shift-Home extends the selection to the first element in the hierbox and Control-Shift-End extends the selection to the last element. | ||
|
[13] |
In multiple mode, Control-Shift-Home moves the location cursor to the first element in the hierbox and Control-Shift-End moves the location cursor to the last element. | ||
|
[14] |
The space and Select keys make a selection at the location cursor (active element) just as if mouse button 1 had been pressed over this element. | ||
|
[15] |
In extended mode, Control-Shift-space and Shift-Select extend the selection to the active element just as if button 1 had been pressed with the Shift key down. | ||
|
[16] |
In extended mode, the Escape key cancels the most recent selection and restores all the elements in the selected range to their previous selection state. | ||
|
[17] |
Control-slash selects everything in the widget, except in single and browse modes, in which case it selects the active element and deselects everything else. | ||
|
[18] |
Control-backslash deselects everything in the widget, except in browse mode where it has no effect. | ||
|
[19] |
The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. |
The behavior of hierboxes can be changed by defining new bindings for individual widgets or by redefining the class bindings.
hierbox, widget
If a hierbox is exporting its selection (see exportSelection option), then it will observe the standard X11 protocols for handling the selection. Hierbox selections are available as type STRING; the value of the selection will be the text of the selected elements, with newlines separating the elements.
|
hierbox(n) | |