7.6 Grid widget

local 
   Grid
   Desc=grid(label(text:"1") label(text:"2") label(text:"3") newline
             label(text:"4") empty           label(text:"6") newline
             label(text:"7") label(text:"8") label(text:"9")
             handle:Grid)
in 
   {{QTk.build td(Desc)} show}
   {Grid configure(label(text:"5") column:2 row:2)}
   {Grid configure(label(text:"0" bg:white)
                   column:1 columnspan:3 row:4 sticky:we)}
end

7.6.1 Description

A grid widget is a frame, ie a rectangular area of a window. It's primary purpose is to act as a grid container for placing widgets. Widgets are placed inside the grid at declaration time from left to right, newline skips to the beginning of the next line. As long as the window exists, a grid acts as a gridded placeholder widget: widgets can be placed and removed from anywhere inside the grid dynamically.

7.6.2 Parameter List

Specific Parameters

class colormap height n visual width

Non Specific Parameters

background borderwidth cursor feature glue handle highlightbackground highlightcolor highlightthickness look onCreation padx pady relief takefocus tooltips

7.6.3 Method List

'raise'

'raise'(1:W): If the W argument is omitted then the command raises the widget so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the 'raise' command will insert this widget into the stacking order just above W; this could end up either raising or lowering the widget.

bbox

bbox(?Column ?Row ?Column2 ?Row L): bind L to a list of 4 integers representing a bounding box: first two elements are the top left X and Y coordinate in pixels of the box, the third element the width and the height of the box. The bounding box and its origin depends on the number of arguments:

• if no other arguments are given: the origin depends on the master window of the grid widget, the width and height measure the size of the grid widget.

• if a single Column and Row is specified: returns the bounding of the cell of that particular coordinate in the grid widget.

• if both Column and Row arguments are specified: returns the bounding of the box spanning the rows and columns indicated.

bind

bind(event:E action:A args:LA append:AP): Specifies an action LA to execute when the event E is triggered.

• Actions can be specified either as a procedure, a pair Port#Message or a pair Object#Method (see Section 4.3.3).

• Events are strings (see Section 8.11.1).

• The list of arguments LA specifies supplementary information to pass to the action, like the key code of a keypress, or the mouse coordinates of a mouse button click (see Section 8.11.2). If LA if not specified, nil is assumed.

• The boolean append parameter specifies if the binding overrides the previous binding for this event, or adds a supplementary action. If not specified, false is assumed.

columnconfigure

columnconfigure(I ?minsize:MinSize ?weight:Weight ?pad:Pad): same as rowconfigure for configuring the columns of the grid.

configure

configure(Widget1 ... WidgetN ?column:Column ?columnspan:Columnspan ?ipadx:Ipadx ?ipady:Ipady ?padx:Padx ?pady:Pady ?row:Row ?rowspan:Rowspan ?sticky:Sticky): places one or several widgets inside the grid. WidgetX can be either a QTk description record or the handle widget that has already been placed inside the grid widget. The other parameters are:

• Column: an integer that specifies the number of the column of the grid to place the widget. Column numbers start with 0. If this option is not supplied, then the widget is arranged just to the right of previous widget specified on this call to grid, or column "0" if it is the first widget.

• Columnspan: an integer that specifies the number of columns the widget occupies in the grid. The default is one column.

• Ipadx: an integer specifying how much horizontal internal padding to leave on each side of the widget(s). The default is zero.

• Ipady: an integer specifying how much vertical internal padding to leave on the top and bottom sides of the widget(s). The default is zero.

• PadX: an integer specifying how much horizontal external padding to leave on each side of the widget(s). The default is zero.

• Pady: an integer specifying how much vertical external padding to leave on the top and bottom sides of the widget(s). The default is zero.

• Row: an integer that specifies the number of the row of the grid to place the widget. Row numbers start with 0. If this option is not supplied, then the widget is arranged in the same row of previous widget specified on this call to grid, or row "0" if it is the first widget.

• Rowspan: an integer that specifies the number of rows the widget occupies in the grid. The default is one row.

• Sticky: when using the configure method of a grid widget, the glue parameter of the contained widget isn't taken into account as it is with td and lr container widgets. The glue parameter (internal to the contained widget description) is replaced sticky parameter (external to this description). Sticky can be any format accepted by the glue parameter.

forget

forget(Widget1 ... WidgetN): removes Widget1 ... WidgetN from the grid widget permanently. These widgets can't be placed back into the grid by the configure any more.

get

get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.

getFocus

getFocus(force:B): if B is false (or by default): if the application currently has the input focus on the widget's display, this command resets the input focus for the widget's display to the widget. If the application doesn't currently have the input focus on the widget's display, the widget will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, it will be redirected it to the widget. If B is true: sets the focus of the widget's display to the widget, even if the application doesn't currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. B must be a boolean.

getGrabStatus

getGrabStatus(1:V): Binds V to the atom none if there is no grab on the widget, to the atom local if there is a local grab and to global if there is a global grab. V must be a free variable.

location

location(X Y O): given X and Y values in screen units relative to the master window, the column and row number at that X and Y location is bound to O. For locations that are above or to the left of the grid, -1 is returned.

lower

lower(1:W): If the W argument is omitted then the command lowers the widget so that it is below all of its siblings in the stacking order (it will be obscured by any siblings and will not obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the lower command will insert this widget into the stacking order just below W; this could end up either raising or lowering the widget.

propagate

propagate(B): B is a boolean that specifies if the propagation is enabled or not. The grid geometry manager normally computes how large a master must be to just exactly meet the needs of its slaves, and it sets the requested width and height of the master to these dimensions. This causes geometry information to propagate up through a window hierarchy to a top-level window so that the entire sub-tree sizes itself to fit the needs of the leaf windows. However, the grid propagate method may be used to turn off propagation for one or more masters. If propagation is disabled then grid will not set the requested width and height of the master window. This may be useful if, for example, you wish for a master window to have a fixed size that you specify.

releaseGrab

releaseGrab: Releases the grab on the widget if there is one, otherwise does nothing.

remove

remove(Widget1 ... WidgetN): removes Widget1 ... WidgetN from the grid widget temporarilly. These widgets can be placed back into the grid by the configure at any time.

rowconfigure

rowconfigure(I ?minsize:MinSize ?weight:Weight ?pad:Pad): set the I row properties of the grid.

• MinSize: sets the minimum size, in screen units, that will be permitted for this row.

• Weight: sets the relative weight (integer value) for apportioning any extra spaces among rows. A weight of zero (0) indicates the row will not deviate from its requested size. A row whose weight is two will grow at twice the rate as a row of weight one when extra space is allocated to the layout.

• Pad: specifies the number of screen units that will be added to the largest window contained completely in that row when the grid geometry manager requests a size from the containing window.

set

set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.

setGrab

setGrab(global:B): Sets a grab on the widget. If B is true then the grab is global, otherwise it is local (B false by default). If a grab was already in effect for this application then it is automatically released. If there is already a grab on the widget and it has the same global/local form as the requested grab, then the command does nothing. Local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either. Warning: whe a grab is set, it is define for the whole Oz process so that it will prevent the user to do input to other windows as well. Moreover a grab is still effective even if the window that contains the grabbed widgets is hidden. B must be a boolean.

size

size(S): binds S to the number of contained widgets in the grid.

slaves

slaves(L): binds L to the list of all widgets that have been placed in the grid. These widgets can be either visible in the grid or removed using the remove method. Widgets that where forgotten using the forget method are not in this list.

winfo

winfo(parameter1:value1 ... parameterX:valueX): This commands works like the get method, but for window-related information. For more details, see Section 8.9.

7.6.4 Detailed Parameters List

class:VS: Specifies a class for the window. This class will be used when querying the option database for the window's other options, and it will also be used later for other purposes such as bindings. This option can be specified at creation time only. VS must be a virtual string.

colormap:V: Specifies a colormap to use for the window. The value may be either the atom new, in which case a new colormap is created for the window and its children, or the handle of another window (which must be on the same screen and have the same visual as this widget), in which case the new window will use the colormap from the specified window. If the colormap option is not specified, the new window uses the same colormap as its parent. This option can be specified at creation time only.

height:P: Specifies the desired height for the window. If this option is less than or equal to zero then the window will not request any size at all. P must be a valid screen distance (see Section 8.6).

n:...: With n starting at 1 and going up one by one. Can take three different forms:

• n:R: Specifies a widget to place inside the grid. R must be a record describing a widget. Widgets are placed from left to right.

• n:newline: jumps to the next line so that all widgets placed on several lines are vertically aligned.

• n:empty: Leaves an empty blank space.

Note that newline and empty are not widgets and therefore can't be glued and don't have a handle. These parameters can be specified at creation time only. Once the widget is created and as long as it exists inside the window, new widgets can be placed at any position in the grid using the configure method (see below).

background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).

borderwidth:P: Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the relief option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. P must be a valid screen distance (see Section 8.6).

cursor:A: Specifies the mouse cursor to be used for the widget. A must be a valid cursor (see Section 8.7)

feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.

glue:A: Specifies how a widget must fit in its own available place. A must be an atom that is any combination of n, s, w and e. If a direction is specified, the corresponding border is glued to its neighbor or border of the frame if there is no neighbor. If a direction is not specified, the corresponding border if such that the widget takes just the width or height it needs to draw itself. If none of opposite directions is specified, the widget is centered. For more details, see Section 4.1.

handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.

highlightbackground:C: Specifies the color to display in the traversal highlight region when the widget does not have the input focus. C must be a valid color (see Section 8.2)

highlightcolor:C: Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. C must be a valid color (see Section 8.2)

highlightthickness:P: 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. If the value is zero, no focus highlight is drawn around the widget. P must be a valid screen distance (see Section 8.6).

look:L: Specifies a look to use for the widget. A look specifies default values for the parameters of widgets. This parameter can be specified at creation time only. Moreover changing a look will not change the appearance of widgets that are already displayed with that look. See Section 5.1 for more details.

onCreation:P: When a widget is created, for example by QTk.build, this parameter specifies an action to execute right after the widget has been created, but before returning from the build instruction. It is usefull if one needs the handle of the widget to initialize it in ways not permitted by its description record (for example binding the Enter or Leave mouse events).

padx:P: Specifies how much horizontal external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

pady:P: Specifies how much vertical external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

relief:A: Specifies the 3-D effect desired for the widget. Must be one of these atoms: raised, sunken, flat, ridge, solid or groove. The value indicates how the interior of the widget should appear relative to its exterior; for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.

takefocus:B: Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal mechanims consult the value of the takeFocus option. A value of false means that the widget should be skipped entirely during keyboard traversal. true means that the widget should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). B must be a boolean.

tooltips:VS: Specifies a tooltip for the widget. A tooltip is a small message that appears when the mouse cursor if left still over the widget for a while. If VS is set to nil, no tooltip will appear at all. VS must be a virtual string.

visual:A: Specifies visual information for the new window. A must be one of the following atoms: directcolor, grayscale, greyscale, pseudocolor, staticcolor, staticgray, staticgrey, or truecolor. If this option is not specified, the new window will use the same visual as its parent. This option can be specified at creation time only.

width:P: Specifies the desired width for the window. If this option is less than or equal to zero then the window will not request any size at all. P must be a valid screen distance (see Section 8.6).