Controls
The following
control functions return a control identifier Object Agent upon their
creation. See the Object Agent reference section for a complete listing
of their Data Methods and Methods.
ctlstring
ctlinteger
ctlnumber
ctlvector
These functions
let you create edit controls for data types, namely character strings,
integers, floating point numeric values, and vectors (triples of floating
point numbers). ctlstring() takes an optional third parameter that determines
the width of the control.
ctlvector()
accepts a rather flexible format in its parameters. You can provide a
single vector data type, a single numeric value to populate all three
fields, or you can provide three individual numeric values to initialize
the individual edit fields.
prototypes:
<Control
Object Agent> ctlstring(label, value,
[width])
<Control Object Agent> ctlinteger(label, value)
<Control Object Agent> ctlnumber(label, value)
<Control Object Agent> ctlvector(label, value)
label
string; the label of the control.
value
(depends on the control); the default value of the control.
width
integer; the width of the control.
example:
name = "BillyBob";
age = 18;
c1 = ctlstring("Your name?",name);
c2 = ctlinteger("Your age?",age);
ctldistance
The ctldistance() function is similar to ctlnumber(), except the resulting
edit control displays and edits values based on Modeler’s current default
units of measurement.
prototype:
controlId
ctldistance(label, value)
label string;
the label of the control.
value number;
the default distance
example:
length = .25;
// if selected default units are kilometers, then this
// edit field will initially be (.25 * 1k) == 250 meters
c1 = ctldistance("Length",length);
ctlchoice
You create a push-button selection control with ctlchoice(); these enumerated
selection lists are displayed by the requester system as push buttons
grouped in the same location.
ctlchoice()
requires three parameters, and accepts an optional fourth. The first parameter,
as with all other controlcreation functions, is the control title. The
second is an integer value that specifies the initial push button that
is selected when the panel is posted. The third is either an array reference
containing the character strings for the button labels, or it can be an
initialization block placed directly into the function call that houses
the same data. Selection numbers begin at one (1).
You can provide
a (optional) fourth parameter to indicate the orientation of the selection
list. Selection lists can be grouped vertically or horizontally. This
fourth parameter selects a specific orientation by specifying a Boolean
true for vertical and false for horizontal. If this parameter is omitted,
lists are grouped horizontally by default.
prototype:
<Control
Object Agent> ctlchoice(label
,value,
choices,[orientation]
label string;
the label of the control.
value integer;
the index of the default choice.
choices string
or array; the list of choices.
orienation
boolean;
true = vertical and false = horizonal.
example:
booleans[1]
= "Yes";
booleans[2] = "No";
choice = 1;
// set "No" as initial selection
// create a
vertical selection list
c1 = ctlchoice("Quadrant?",choice,@"90","180","270"@,true);
ctltext
ctltext() adds static text to the requester dialog box. This static text
can give the user messages about special instructions or circumstances
for input values.
ctltext() accepts
a variable number of arguments, all of which should be text strings. As
with all control-creation functions, the first text string provided is
the control label. It will also accept an Array reference as either the
first (and only) argument, or the second (and final) from which text strings
will be extracted.
Like all other
control functions, ctltext() will return the control handle of the static
text control. However, because the control does not change, this handle
is of little value. It could be used by the setvalue() function to alter
the text before reposting the dialog box.
prototype:
<Control
Object Agent> ctltext(label,
text[..text...])
label string;
the label of the control.
text
string
or array; the text to be displayed.
examples:
c1Text[1] =
"Text1 ";
c1Text[2] = "Text2 ";
c1Text[3] = "Text3 ";
c0 = ctltext("Text1
", "Text2 ", "Text3 ");
c1 = ctltext("Text1 ", c1Text);
ctlcolor
ctlcolor() behaves similarly to ctlvector() in that it posts a control
that has three separate numeric editing fields. However, ctlcolor() allows
only integer values to be entered into its fields.
ctlcolor()
also accepts a combination of parameters and types. You can provide a
single vector data type, a single integer value that will populate all
three , or you can provide three individual integer values to initialize
the individual edit fields.
prototype:
ctlcolor(label,
colorVal)
label
string;
the label of the control.
colorVal int
or vector; the color value(s).
example:
c1 = ctlcolor("Color",
100);
or
c1 = ctlcolor("Color",
<100,100,100>);
ctlsurface,
ctlfont
The ctlsurface() and ctlfont() functions create controls for managing Modelers
surface and font attributes, respectively. The controls created often
have several other controls themselves, related to the particular features
of the control type.
As usual, both
functions use the first parameter as the control title. ctlsurface() assumes
that the second string parameter is the name of a surface that initializes
the surface control. The second parameter for ctlfont() must be an integer
value; the integer indicates the index of a currently-loaded font, and
it becomes the control’s initial value.
prototypes:
<Control
Object Agent>
ctlsurface(label,
surfName)
<Control
Object Agent> ctlfont(label,
fontIndex)
label
string;
the label of the control.
SurfName string;
the surface name.
fontIndex integer;
the index of the font.
example:
c1 = ctlsurface("surface",
"new surface");
c2 = ctlfont("font", 1);
ctlpopup
The ctrlpopup() command creates a pop-up control with the values provided.
A pop-up is a button-like control that displays a scrolling list of values
when it is selected with the mouse.
prototype:
<Control
Object Agent> ctlpopup(label,
value,
choices[])
label string;
the label of the control.
value integer;
the index of the default choice.
choices[] array or string UDF;
the list of items, or a UDF which returns a string or array of strings.
examples:
choice[1] =
"choice1";
choice[2] = "choice2";
choice[3] = "choice3";
c1 = ctlpopup("Popup, 1, choice);
or
c1 = ctlpopup("Popup",
1, @"choice1", "choice2",
"choice3"@);
ctledit
Undocumented experimental feature of LS 2.5
ctlpercent
ctrlpercent() creates a floating-point mini-slider field that displays
values as percentages. It returns a floating-point value with getvalue().
prototype:
<Control
Object Agent>
ctlpercent(label,
value)
label string;
the label of the control.
value number;
the default value.
example:
c1 = ctlpercent("Percent",
100);
ctlangle
ctlangle() is a floating-point mini-slider field that displays values as
angles (in degrees). It returns a floating-point value with getvalue().
Note: angle values are in radians. Use the
LScript rad() and deg() functions to convert between degrees and radians
if you wish to work in degrees.
prototype:
<Control
Object Agent> ctlangle(label, value)
label string;
the label of the control.
value number;
the default value.
example:
c1 = ctlangle("Angle",
180);
ctlrgb
The ctrlrgb() function creates a control that contains three numeric entry
fields where users can type in color components, and a preview area that
displays the combined values.
label is a
string value representing the label of the control, and rgb is a vector
value representing the Red, Green and Blue color components in the ‘x’,
‘y’, and ‘z’ positions. Each of these values is an integer number between
0 and 255. The rgb parameter can also be a single integer value that will
be used with all channels, or it can be three individual integer values
corresponding to each of the color channels.
prototype:
<Control
Object Agent> ctlrgb(label, rgb)
label
string;
the label of the control.
rgb
integer,
or vector; rgb values.
examples:
c1 = ctlrgb("Color(rgb)",
10);
c1 = ctlrgb("Color(rgb)", <10, 10, 10>);
ctlhsv
The ctrlhsv() function creates a control that contains three numeric entry
fields where users can type in color components, and a preview area that
displays the combined values.
hsv is a string
value representing the label of the control, and hsv is a vector value
representing the Hue, Saturation, and Value components in the ‘x’, ‘y’,
and ‘z’ positions. Each of these values is an integer number between 0
and 255. This parameter can also be a single integer value that will be
used with all channels, or it can be three individual integer values corresponding
to each of the color channels.
prototype:
<Control
Object Agent> ctlhsv(label,
hsv)
label string;
the label for the control.
hsv vector;
the Hue Saturation and Value
example:
c1 = ctlhsv("Color
(hsv): ", <10, 30, 20>);
ctlcheckbox
The ctlcheckbox() function creates a control that lets the user check on
or off states.
label is a
string value representing the label of the control. state is a Boolean
value that indicates the appearance of the checkbox. A logical ‘true’
will initially check the control, while a logical ‘false’ will leave it
unchecked.
prototype:
<Control
Object Agent>
ctlcheckbox(label,
state)
label string;
the controls label.
state boolean;
the value indicating the state of the
control
(true = checked, false = unchecked).
example:
c1 = ctlcheckbox("checkbox",
true);
ctlstate
ctlstate() is a boolean button, equivalent to a checkbox. Like ctlbutton(),
it triggers a pre-defined, user-defined function (action_udf) within the
script. Unlike ctlbutton(), the UDF takes a value that represents the
current state of the boolean control.
A false (0)
means it is off; a true (1) means it is on. Note that <width> is
expressed in pixels. The following script illustrates the setup use of
ctlstate():
prototype:
<Control
Object Agent> ctlstate(label,
value,
width,action_udf)
label string;
the label of the control.
value boolean;
the initial value of the control.
width integer;
the width of the control.
action_udf
string;
the udf to be called when the control’s state changes.
example:
@version 2.1
@warnings
generic
{
reqbegin("State
Control");
c1
= ctlstate("Testing",true,100,"stateCallback");
reqpost();
}
stateCallback:
val
{
info(val);
// 0 - off, 1 - on
}
ctlfilename
This ctlfilename() function creates a control that contains a text edit
field and a push button that will post a file-requester dialog box. The
selection returned from the file requester is placed in the text edit
field.
label is a
string value representing the label of the control. filename is a string
value representing the initial value of the filename edit field of the
control. dialog represents a Boolean value of 0 for a Save dialog, and
1 for Open.
prototype:
string
ctlfilename(label, filename
[,width,
[dialog]])
label string;
The title on the requester.
filename string;
the initial file value in the requester.
width integer;
width of the control.
height integer;
height of the control.
Dialog bool;
0 = Save dialog, 1 = Open dialog,
example:
filename =
ctlfilename("Open Object", "(none)",
70, 20);
ctlfoldername(Title,Dir)
This accepts two arguments, a string for the requester title, and a starting directory as a string.
ctlbutton
ctlbutton() is a "do-something-now" button that triggers a predefined,
user-defined function within the script. The width is expressed in
pixels.There is an optional argument list which is wrapped in quotation
marks (i.e., passed as a string), and contains one or more argument values each separated by a
comma.
prototype:
<Control
Object Agent> ctlbutton(label,
width,
action_udf,[argumentlist])
label
string;
the label of the control.
width
integer;
the width of the control.
action_udf
string;
the udf to be called when the button is pressed.
argumentlist string; argument list to be passed to udf, comma separated.
example:
@version 2.1
@warnings
c1..2;
r1=20;
generic
{
r2=10;
reqbegin("Testing");
c1
= ctlbutton("Increment",50,"addcount","10,r1,r2");
c2
= ctlinteger("Count",1);
reqpost();
}
addcount:arg1,arg2,arg3
{
setvalue(c2,getvalue(c2)
+ 1);
info(arg1," ",arg2," ",arg3);
}
ctllistbox
The ctllistbox() control displays a single-column collection of text entries.
Two user-defined functions must be defined within the script to return
the total number of items in the listbox: (count_udf) and the string value
at an indicated index offset in the listbox (name_udf). An optional event_udf
can be defined and specified that will receive control whenever an event
is triggered within the listbox (i.e., when an item is selected).
The count_udf
accepts no arguments, and returns the count of items as an integer. The
name_udf accepts the integer index value being queried, and returns a
single string value to be placed into that slot. The optional event_udf
accepts an array of index values of the selected items, and returns nothing.
The optional select_udf accepts the index of the element being selected,
and should return a Boolean true/false value to indicate if the element
can be selected.
prototype:
<Control Object Agent>
ctllistbox(label,width, height,count_udf,name_udf[, event_udf , [select_udf] ] )
label string;the label for the control.
width integer; the width of the control.
height integer; the height of the control.
count_udf string; a udf used by LScript to determine the count.
name_udf string; a udf used by LScript to retrieve a listbox item.
event_udf string; a udf used by LScript to detemine what happens when an item is selected.
select_udf string; a udf used to toggle a listbox item’s ability to be selected.
example:
@version 2.2
@warnings
c1;
lb_items;
generic
{
for(x = 1;x <= 5;x++)
lb_items += "Item_" + x;
reqbegin("Testing List Box");
c1 = ctllistbox("Items",300,300,"lb_count","lb_name","lb_event");
c2 = ctlbutton("Select",50,"button_event");
return if !reqpost();
sel = getvalue(c1);
reqend();
if(sel == nil)
info("No selections were made");
else
info("You have selected '",sel,"'!");
}
lb_count
{
return(lb_items.size());
}
lb_name: index
{
return(lb_items[index]);
}
lb_event: items
{
// 'items' is an array of integer index values, or 'nil'
if(items == nil)
info("No items are selected");
else
info("You have selected '",items,"'!");
}
button_event
{
a = @1,3,5@;
setvalue(c1,a);
}
In addition, the following script illustrates how button controls can manage and interact with the listbox contents:
@version 2.1
@warnings
c1..3;
lb_items;
main
{
for(x = 1;x <= 5;x++)
lb_items += "Item_" + x;
reqbegin("Testing List Box");
c1 = ctllistbox("Items",300,10,"lb_count","lb_name");
c2 = ctlbutton("Add",200,"add_button");
c3
= ctlbutton("Delete",200,"del_button");
reqpost();
}
lb_count
{
//
don’t use size() here because that counts
//
all elements, even if they have ‘nil’.
return(lb_items.count());
}
lb_name: index
{
return(lb_items[index]);
}
add_button
{
lb_items
+= "Item_" + (lb_items.size() + 1);
setvalue(c1,lb_items.count());
del_button
{
sel = getvalue(c1);
lb_items[sel] = nil;
lb_items.pack();
lb_items.trunc();
setvalue(c1,lb_items.count());
}
ctlslider
The ctlslider() function creates a scroll-bar slider with a specified range,
and includes a numeric input field.
prototype:
<Control
Object Agent> ctlslider(title, val, min, max[,width])
title
string;
label for the control.
val
number;
default value for the control.
min
number;
minimum value.
max number;
maximum value.
width absolute width of the control.
example:
c1 = ctlslider("My
value", 10, 0, 20);
ctlminislider
The ctlminislider function creates a numeric input field with a scroll
button to the immediate right.
prototype:
<Control
Object Agent>
ctlminislider(title,
val, min, max)
title
string;
label for the control.
val
number;
default value for the control.
min number;
minimum value.
max number;
maximum value.
example:
c1 = ctlminislider("My
value", 10, 0, 20);
ctlsep
Use ctlsep() to draw a 3D separator horizontally across your requester
panel. column is the starting column (pixel) of the separator, and width
is the number of columns (pixels) of the separator. If no parameters are
provided, then the separator will span the entire width of your panel.
A width of -1 will draw the separator to the right-most limit of your
panel.
prototype:
<Control
Object Agent>
ctlsep([column,width])
column integer,
starting column.
width integer,
width of bar.
examples:
ctlsep();
c1 = ctlsep();
c1 = ctlsep(10, 10)
ctlimage
The ctlimage() function allows you to embed Targa image files (type 2 and 10, top-down or bottom-up raster) anywhere on your Panels-based requester panel. ctlimage() takes one required and three optional parameters: the required parameter is the image file name. The optional parameters are the image’s X (horizontal) offset, the image’s Y (vertical) offset, and a color transparency mask—as a single integer or a vector—for simple color filtering (which can, in some cases, greatly increase display speed).
When you use the three optional parameters, you can also scale images. The fifth parameter (after the transparency vector) specifies the scaling factor or size of the image’s width. The sixth parameter specifies the scaling factor or size of the image’s height. The final parameter is a Boolean flag that instructs LScript to preserve the image’s aspect ratio. By default, the aspect ratio is not preserved.
LScript interprets the numeric values given for scaling width and height scaling by their type. If you provide an integer value for either component, then that value is considered an absolute width (in pixels) of the resulting image. On the other hand, if you pass a floating-point value in that position, then LScript considers it a percentage factor (where 1.0 equals 100%) and applies it to the image’s original width or height to get the final pixel width. Because this mechanism is not designed to enlarge images, anything that makes the resulting width or height exceed the image’s original dimensions is clamped to the image’s original dimension.
When images are loaded into Layout through the Image Editor, you can can display them using the ctlimage() function. Put the dollar sign character ($) before the image name, and LScript resolves the names by using any loaded image files instead of trying to locate an image file on disk. Names following the dollar sign metacharacter should exactly match the name that Layout displays for the image. The script ignores images referenced in this fashion when it compiles for run-time execution. This means that when the compiled script is executed, the image referenced must be available from Layout.
The ctlimage() function now returns a 'nil' value if the attempt to load an indicated image file
fails. This will usually be an indication that the required ImageLoader plug-in has not been
installed into the application (an error message will still be displayed to the user if the
indicated image file simply doesn't exist). Scripts using non-Targa image files should check
this return value to ensure that the control was properly created.
prototype:
<Control
Object Agent>
ctlimage(imageName,xOffset,yOffset,transMask,[scalingWidth,[scalingHeight,[aspectFlag]]])
imageName string;
The image name.
xOffset integer;
X (horizontal) coordinate offset.
yOffset integer;
Y (vertical) coordinate offset.
transMask single
integer or vector; simple color filtering.
scalingWidth If an integer, the absolute size in pixels
scalingHeight or if a float, a scaling value (1 being original size).
aspectFlag Boolean; Preserve the aspect ratio or not.
example:
…
// display
the image at (0,0), 40% of its original
// width and 30% of its original height
ctlimage("$ph_019.tga",0,0,,.4,.3);
…
// display
the image at (0,0), 100 pixels wide and
// 100 pixels tall, preserving its aspect ratio
// (which means it will probably not be exactly 100x100
// when displayed)
ctlimage("$ph_019.tga",0,0,,100,100);
…
// display the image at (0,0) in its unaltered form
ctlimage("$ph_019.tga",0,0);
ctlimage("$ph_019.tga",0,0);
ctltab
You can create tabs by using the ctltab() function, which takes a series
of character strings that title each tab. Like ctlimage(), tabs can be
positioned with ctlposition() without triggering LScript’s control position
release logic. Currently, only one tab control is allowed on the panel.
prototype:
<control
Object Agent>
ctltab(...tabNames...)
tabNames strings;
a comma-separated list of names of tabs.
example:
c3 = ctltab("Page 1","Page 2","Page 3");
ctlallitems
ctlmeshitems
ctlcameraitems
ctllightitems,
ctlboneitems
ctlimageitems(Layout Only)
These functions create controls that provide a drop-down list of the specified types of Layout objects currently available in the scene. The return value from each of these controls is an Object Agent that represents the LightWave object that was selected, or 'nil' if no object was selected.
prototypes:
<Object
Agent> ctlallitems(label[,itemOA])
<Object
Agent> ctlmeshitems(label[,itemOA]
<Object
Agent> ctlcameraitems(label[,itemOA]
<Object
Agent> ctllightitems(label[,itemOA]
<Object
Agent> ctlboneitems(label[,itemOA]
<Object
Agent> ctlimageitems(label[,itemOA]
label
string;
the label of the control.
itemOA
itemOA; selected item when
control is opened. This must be a valid OA reference, a name as displayed in layout or nil;
example:
obj = ctlmeshitems("Objects
in Scene:",mymesh);
ctlchannel()
prototype: ctlchannel(label,width,height[,channel[,channeleventUDF])
label
string; label of the control
width, height integer; size of the control
channel
channel OA of the current
selected channel.
channeleventUDF string; UDF called when a channel is modified?
ctlviewport()
A new control type called ctlviewport() is
available to script requesters. This control is similar to
ctlinfo(), however, it functions as a viewport into a larger canvass
area. The canvas can be much larger than the viewport window, and can
be navigated using included vertical and horizontal scroll bars.
The arguments to ctlviewport() are identical to
that of ctlinfo(), save for an additional callback that reports the
dimensions of the virtual canvass. This size function will always
be called immediately before the redraw function, so you can
dynamically resize the canvas to fit the situation.
c1 = ctlviewport(200,200,"vp_redraw","vp_size");
This size callback should return the width and
height of the canvass upon which the viewport (whose size is set in the
initial function call) will traverse. The size function could,
for instance, return a fixed size or it could calculate the bounding
area of objects positioned upon the canvass. It accepts the
control identifier to which the dimensions should apply.
vp_size: ctl
{
return(800,600);
}
Drawing on the canvass should be performed without regard to viewport
size. Your drawing function should behave as though the user can
see the entire canvass at once. It accepts the control identifier
for which drawing functions will apply.
vp_redraw: ctl
{
drawbox(<80,80,80>,0,0,800,600);
drawbox(<200,200,200>,50,50,20,20);
drawbox(<0,200,0>,750,450,20,20);
}
In addition, the Control Object Agent
class now exports two new data members called xoffset and
yoffset. These data members are currently a constant zero (0) for
all types except for the viewport control. The values in these
data members contain the current X (left) and Y (top) offsets of the
control's viewport. These values can be used to accurately
calculate things such as the virtual location of mouse events on the
canvass.
reqmousedown: mouse_x, mouse_y, ctrl
{
x = mouse_x - ctrl.x + ctrl.xoffset;
y = mouse_y - ctrl.y + ctrl.yoffset;
...
}
Or they can be assigned values to position the viewport at a
specific location on the virtual canvass. The range of allowable
values runs from zero (0) to (canvass_width - viewport_width) on the
horizontal, and zero (0) to (canvass_height - viewport_height) on the
vertical. LScript will automatically clamp assigned values to
these ranges if you exceed them.
Control Management
ctlpage
You can ‘place’ controls on tab pages with the ctlpage() command. This
command takes a page number, which corresponds to a defined tab, and one
or more control identifiers. When a control is placed on a tab page, it
appears only on the tab page when that tab is active. If a control is
not associated with a tab page, then it remains visible on the requester
panel at all times:
The cltpage()
function also accepts an array of Control Object Agents in addition to
a comma-separated list. The array reference must be the second and last
argument to the function.
prototype:
void
ctlpage(pageNum, … controlId’s…)
pageNum integer;
a number of a defined tab.
controlId’s
Control
Object Agent; a comma-separated list or array of Control Object Agents.
example:
ctlpage(1,c4,c5);
ctlpage(2,c6);
ctlpage(3,c7,c8,c9);
ctlgroup
When controls are grouped using the ctlgroup() function, all subordinate
controls are then positioned relative to the group leader. The first argument
is the control id of the group leader, while all subsequent arguments
are the controls that belong to the group.
Groupings should
be established PRIOR to setting control positions. For instance, the following
function "attaches" a separator to a tab control:
prototype:
void
ctlgroup(controlId, …
controlId’s…)
controlId Control
Object Agent; the group leader control.
controlId’s
Control
Object Agents; a comma-separated list of
the
follower controls.
example:
c0 = ctltab("Tab1","Tab2","Tab3");
c1 = ctlsep();
ctlgroup(c0,c1); //
<— c0 is group leader
ctlposition(c1,0,24); //
<— relative to c0
ctlposition(c0,0,10); //
<— group "leader" — c1 will follow
Groupings can
also be nested:
if(!reqbegin("Panels
Test",true))
return;
c0 = ctlcheckbox("Testing Number 1",true);
c1 = ctlcheckbox("Testing Number 2",false);
c2 = ctlcheckbox("Testing Number 3",true);
c3 = ctlcheckbox("Testing Number 4",false);
ctlgroup(c0,c1,c2);
ctlgroup(c2,c3);
ctlposition(c0,10,10);
ctlposition(c1,0,20); //
<— relative to c0
ctlposition(c2,0,60); //
<— relative to c0
ctlposition(c3,0,20); //
<— relative to c2
ctlposition
The ctlposition() command positions a control at the indicated column/row
coordinates on the requester panel. When you call this function, LScript
relinquishes all control on the formatting of your controls. Once you
call it, you must call it for ALL controls on the requester or they will
all default to (0,0) and stack one upon another.
The ctlposition()
function has three optional numeric arguments. These arguments give access
to requester controls that you can size in LScript. The third argument
indicates the width (in pixels) of the control. The fourth indicates the
height (also in pixels) of the control. The fifth argument indicates the
offset value for the control. An offset value can control the width of
the label field for controls with labels, or the distance a control is
shifted to the right from its left-most position for controls without
labels.
prototype:
void
ctlposition(controlId, column,
row,
[width],[height],[offset])
controlId Control
Object Agent; the control to be moved.
column integer;
X (horizontal) coordinate.
row integer,
Y (vertical) coordinate.
width integer;
width of the control.
height integer,
height of the control.
example:
ctlposition(c1,
5, 5, 70, 20, 10);
ctlactive
When you use the ctlactive() function, you can activate or deactivate one
or more requester controls based on the state of another control. This
mechanism is by far the most complex of those yet created for the LScript
requester. It has a parameter structure much like ctlgroup(), however
each call to ctlactive() must be accompanied by an LScript callback UDF.
The function
parameters consist of the "state" control identifier as the
first parameter (much like the group "leader" control forctlgroup()).The
second parameter in ctlactive() is a character string that identifies
a UDF in the current script. All remaining parameters in ctlactive() are
the identifiers of those controls whose state will be affected.
Active callbacks
must accept a single argument that will hold the value of the "state"
control at the time its state changed. Callback UDFs must return a Boolean
true or false to indicate the active state of all governed controls. A
Boolean true will cause governed controls to be active, while a false
value will render them inactive. The script must evaluate the data passed
to the callback UDF to determine the appropriate return value.
For instance,
if a state control is a checkbox, the value passed to our callback UDF
will be either true or false—the values that can be contained by the checkbox
control. So, if we wish our governed controls to be active when the checkbox
is "true," we would simply return the value passed to us. However,
if our state control was, for example, a choice, we might want to activate
our governed controls only when choice #2 was selected.
State controls
can be associated with up to ten callback functions. You can then perform
more specific activations on controls. However, unlike ctlgroup(), state
controllers CANNOT be cascaded—that is, you cannot include a state identifier
in the governed parameter list for another.
prototype:
void
ctlactive(controlId, active_udf, controlId)
controlId Control
Object Agent; the state control.
active_udf
string;
the callback UDF.
controlId control
identifier; the control (or array of control ids) to affect.
example:
generic
{
x
= 15;
reqbegin("ctlactive
test");
c0
= ctlcheckbox("This controls the status of
ctlstring",
true);
c1
= ctlstring("ctlstring"," ", 25);
ctlactive(c0,
"toggleOn", c1);
ctlsep();
c2
= ctlinteger("Disperal Range",x);
c3
= ctlcheckbox("Testing Number 1",true);
c4
= ctlchoice("Test",2,@"X","Y","Z"@);
ctlactive(c2,"over10",c3);
ctlactive(c2,"under10",c4);
return
if !reqpost();
reqend();
}
toggleOn: value
{
return(value);
}
over10: value
{
return(value
> 10); // turns ‘c3’ on or off
}
under10: value
{
return(value
<= 10); // turns ‘c4’ on or off
}
ctlvisible
The ctlvisible() function allows controls to be visible or invisible based
upon some condition. Its calling parameters and operational requirements
are identical to that of ctlactive(). ctlvisible() will also accept an
Array of Control identifiers as the third (and final) argument.
You can achieve
a pleasing and professional-looking effect by stacking controls that are
conditionally visible, allowing them all to occupy the same location/space
on the panel. In this way, the control itself appears to alter each time
the condition changes (see example #2).
Note: The LSIDE Interface Designer performs
implicit grouping, and using it, you don’t have to deal with the ctlgroup()
command.
prototype:
void
ctlvisible(controlId,
visible_udf,
…controlId’s…)
controlId control
identifier; the id of the controlling control.
Visible_udf
string;
the UDF that gets called.
controlId’s
array;
the controls that get affected.
example 1:
c0 = ctlchoice("Test",2,@"Checkbox","Integer"@);
c1 = ctlcheckbox("Testing Number 1",true);
c2 = ctlinteger("Disperal Range",x);
…
ctlvisible(c0,"showCheckBox",c1);
ctlvisible(c0,"showInteger",c2);
…
showCheckbox: value
{
return(value
== 1);
}
showInteger: value
{
return(value
== 2);
}
…
example 2:
c0 = ctlchoice("Test",2,@"X","Y","Z"@);
c1 = ctlinteger("Disperal Range",x);
c2 = ctlcheckbox("Testing Number 1",true);
c3 = ctlpopup("How ‘bout a pop-up?",2,@"Item 1","Item
2","Item 3"@);
ctlvisible(c0,"vis1",c1);
ctlvisible(c0,"vis2",c2);
ctlvisible(c0,"vis3",c3);
ctlposition(c0,10,10);
// stack visiblity-controlled controls atop each other
ctlposition(c1,0,30);
ctlposition(c2,0,30);
ctlposition(c3,0,30);
…
vis1: value
{ return(value == 1); }
vis2: value
{ return(value == 2); }
vis3: value
{ return(value == 3); }
…
ctlalign
ctlalign() allows controls to be aligned with a master control using incremental
offsets for the horizontal and vertical values. The first parameter is
the lead control whose position is the beginning offset. Next, come the
X and Y offset increments as integers that will be applied to successive
controls. All remaining parameters are the controls that will be aligned
relative to the master control and the increasing offsets.
prototype:
void
ctlalign(controlId, xOffset,
yOffset,
…controlIds…)
controlId control
Identifier; lead control.
XOffset integer;
X offset.
YOffset integer;
Y offset.
controlIds
Control
Object Agent; all controls that will be aligned.
example:
c0 = ctlchoice("Test",2,@"X","Y","Z"@);
c1 = ctlinteger("Disperal Range",x);
c2 = ctlcheckbox("Testing Number 1",true);
c3 = ctlpopup("How ‘bout a pop-up?",2,@"Item
1","Item2","Item 3"@);
// align c1/c2/c3
at an X offset of 0, and
// 20 successive units away from c0
ctlalign(c0,0,20,c1,c2,c3);
ctlposition(c0,10,10);
Offset values
can also be negative.
ctlalign(c0,-5,20,c1,c2,c3);
//
controls move 5 units
//
to the left of c0
ctlposition(c0,10,10);
Note: The LSIDE Interface Designer handles
all such manual formatting in a more elegant fashion.
ctlrefresh
A requester function called ctlrefresh() can make indicated controls act
as triggers to refresh the values of other controls on the panel. The
function takes a control identifier, and the name of a refresh callback
function. When the specified control is altered in any way by the user
(e.g., mouse clicks, keyboard entry, etc.), the refresh callback is invoked
with the current value of the control.
Unlike callbacks
used by other requester controls, the callback for ctlrefresh() should
not return a value. Instead, control refreshing takes place through the
setvalue() function.
prototype:
void
ctlrefresh(controlId, refresh_udf)
controlId
Control Object Agent; the trigger control.
refresh_udf
string;
the callback UDF that gets called when a refresh is detected.
example:
filenames;
counter = 2;
c1;
main
{
…
filenames =
matchfiles("c:\\temp","*.*");
c0 = ctlchoice("Test",counter,@"X","Y","Z"@);
c1 = ctlstring("Filenames",filenames[counter]);
ctlrefresh(c0,"refresh");
…
}
refresh: value
{
setvalue(c1,filenames[value]);
}
Note the global
values. Because the refresh callback alters the values of controls directly,
the control identifiers must be visible at a global level. In the example
above, the c1 variable is made global so that the refresh callback can
change its value directly.
ctlmenu
This control type consists of a button that displays a popup menu when
pressed. The first argument is the title of the button. Next, a list of
the items that will appear on the menu when displayed. As with ctlpopup(),
this list can be an array reference or an initialization block of values.
A required callback function is then defined to process any selections
made from the menu. A fourth optional argument will define a callback
used to enable/disable individual menu entries.
A special entry
value is recognized as a menu separator. An entry that begins with at
least two equal signs (=) will cause a separator to be added to the popup
menu at the indicated location.
The menu value
returned to either callback function corresponds directly to the linear
value of the entry in the original items. However, separator entries will
never be processed.
prototype:
<Control
Object Agent> ctlmenu(title,
itemList,selection_udf,
[enable_udf])
title string; text to be put on the label of listbox.
itemList array
of strings; list of items to be drawn in listbox.
selection_udf string; name of the callback UDF to be called if an item in the listbox is selected.
enable_udf string; name of the callback UDF to be called to determine if an item in the listbox
can be
selected.
example:
@version 2.4
@warnings
menu_items= @"New Session","Close Session","=====","Quit"@;
generic
{
reqbegin("Testing");
c1
= ctlmenu("Sessions",menu_items,
"menu_select","menu_active");
reqpost();
reqend();
}
menu_select:
item
{
info("You
selected '",menu_items[item],"'");
}
menu_active:
item
{
return(item
!= 2);
}
ctlinfo
The ctlinfo() function defines an area on the Requester panel into which
subsequent drawing will occur when a specified UDF callback is invoked.
All drawing into this area is clipped by LScript.
Three arguments
are required by the ctlinfo() function. The first two are integer values
that specify the width and height of the display area. The third argument
defines the UDF to be called when the informational area needs to be redrawn.
This UDF takes no arguments, and has access to all the Requester redraw
functions (drawtext(), drawpixel(), etc.).
prototype:
<Control
Object Agent> ctlinfo(width, height, draw_udf)
width integer;
width of the drawing area.
height integer,
height of the drawing area.
draw_udf string;
the name of the drawing callback UDF.
example:
@version 2.4
@warnings
@define MSG "This is cool!"
msg_x = 101;
generic
{
reqbegin("Testing");
c1
= ctlinfo(100,30,"info_redraw");
reqpost("marquee",50);
reqend();
}
info_redraw
{
drawbox(<132,130,132>,0,0,100,30);
if(msg_x
> 100)
msg_x
= -1 * drawtextwidth(MSG);
drawtext(MSG,<0,0,0>,msg_x,
integer((30 -
drawtextheight(MSG))/ 2));
drawborder(0,0,100,30,true);
}
marquee
{
msg_x
+= 2;
requpdate();
}
|