<section ID="chapter.widgets.line">
  <TITLE>Tdline and lrline widgets</title>
<p>
<picture.extern to="line.gif" type=gif>

<<<local
   Desc=td(
	   lr(glue:nwe
	      tbbutton(glue:w
		       text:"tbbutton" )
	      tdline(glue:wns)
	      tbcheckbutton(glue:w
			    text:"tbcheckbutton")
	      tdspace(glue:w width:20)
	      tbradiobutton(glue:w
			    text:"tbradiobutton"
			    init:true
			    group:radio)
	      tbradiobutton(glue:w
			    text:"tbradiobutton"
			    group:radio)))
in
   {{QTk.build Desc} show}
end
>>>


<subsection> <TITLE>Description</TITLE>

<P>
These widgets skip spaces and draw a vertical or horizontal line inside. <<tdline>> skips vertical space while <<lrline>> skips horizontal space. They naturally only take one pixel of size in the opposite direction, so they are often glued to take all available space (<<tdline(glue:we)>> and <<lrline(glue:ns)>>.

<subsection> <title>Parameter List</title><p>

<subsubsection><title>Specific Parameters</title><p>
<ref to="chapter.widgets.line.width">width</ref>

<subsubsection><title>Non Specific Parameters</title><p>
<ref to="chapter.widgets.line.param_background">background</ref>
<ref to="chapter.widgets.line.param_feature">feature</ref>
<ref to="chapter.widgets.line.param_glue">glue</ref>
<ref to="chapter.widgets.line.param_handle">handle</ref>
<ref to="chapter.widgets.line.param_look">look</ref>
<ref to="chapter.widgets.line.param_onCreation">onCreation</ref>
<ref to="chapter.widgets.line.param_padx">padx</ref>
<ref to="chapter.widgets.line.param_pady">pady</ref>
<ref to="chapter.widgets.line.param_tooltips">tooltips</ref>

<subsection><title>Method List</title><p>

<para><title>'raise'</title><p><<'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.

<para><title>bind</title><p><<bind(event:E action:A args:LA append:AP)>>: Specifies an action <<LA>> to execute when the event <<E>> is triggered.
<list>
<item> Actions can be specified either as a procedure, a pair <<Port#Message>> or a pair <<Object#Method>> (see <ptr to="basics.otherevents">). 
<item> Events are strings (see <ptr to="misc.events.names">). 
<item> 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 <ptr to="misc.events.args">). If <<LA>> if not specified, <<nil>> is assumed.
<item> 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.
</LIST>

<para><title>get</title><p><<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.

<para><title>getFocus</title><p><<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.

<para><title>getGrabStatus</title><p><<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.

<para><title>lower</title><p><<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. 

<para><title>releaseGrab</title><p><<releaseGrab>>: Releases the grab on the widget if there is one, otherwise does nothing.

<para><title>set</title><p><<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.

<para><title>setGrab</title><p><<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.

<para><title>winfo</title><p><<winfo(parameter1:value1 ... parameterX:valueX)>>: This commands works like the <<get>> method, but for window-related information. For more details, see <ptr to="misc.winfo">.

<subsection><title>Detailed Parameters List</title><p>

<para id="chapter.widgets.line.param_background"><title>background</title><p><<background:C>>: or <<bg:C>>: Specifies the normal background color to use when displaying the widget. <<C>> must be a valid color (see <ptr to="misc.color">).

<para id="chapter.widgets.line.param_feature"><title>feature</title><p><<feature:A>>: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see <ptr to="basics.interaction">. <<A>> must be an atom.

<para id="chapter.widgets.line.param_glue"><title>glue</title><p><<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 <ptr to="basics.geometry">.

<para id="chapter.widgets.line.param_handle"><title>handle</title><p><<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 <ptr to="basics.interaction">. <<V>> must be a free variable.

<para id="chapter.widgets.line.param_look"><title>look</title><p><<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 <ptr to="misc.look"> for more details.

<para id="chapter.widgets.line.param_onCreation"><title>onCreation</title><p><<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).

<para id="chapter.widgets.line.param_padx"><title>padx</title><p><<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  <ptr to="misc.distance">)

<para id="chapter.widgets.line.param_pady"><title>pady</title><p><<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  <ptr to="misc.distance">)

<para id="chapter.widgets.line.param_tooltips"><title>tooltips</title><p><<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.

<para id="chapter.widgets.line.width"><title>width</title><p><<width:I>>: Specifies the amount of vertical or horizontal space to skip. <<I>> must be a valid screen distance (see <ptr to="misc.distance">).


</section>
