Control Commands



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.


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.


<Control Object Agent> ctlstring(label, value,
<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.


name = "BillyBob";
age = 18;
c1 = ctlstring("Your name?",name);
c2 = ctlinteger("Your age?",age);

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


length = .25;
// if selected default units are kilometers, then this
// edit field will initially be (.25 * 1k) == 250 meters
c1 = ctldistance("Length",length);

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.


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() 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,


label                    string; the label of the control.

text                     string or array; the text to be displayed.


c1Text[1] = "Text1 ";
c1Text[2] = "Text2 ";
c1Text[3] = "Text3 ";

c0 = ctltext("Text1 ", "Text2 ", "Text3 ");
c1 = ctltext("Text1 ", c1Text);

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).


c1 = ctlcolor("Color", 100);


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,

label                       string; the label of the control.

SurfName               string; the surface name.

fontIndex                integer; the index of the font.


c1 = ctlsurface("surface", "new surface");
c2 = ctlfont("font", 1);

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. 


choice[1] = "choice1";
choice[2] = "choice2";
choice[3] = "choice3";
c1 = ctlpopup("Popup, 1, choice);


c1 = ctlpopup("Popup", 1, @"choice1", "choice2",

Undocumented experimental feature of LS 2.5

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.


c1 = ctlpercent("Percent", 100);

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.


c1 = ctlangle("Angle", 180);

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.


c1 = ctlrgb("Color(rgb)", 10);
c1 = ctlrgb("Color(rgb)", <10, 10, 10>);

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,

label                   string; the label for the control.

hsv                    vector; the Hue Saturation and Value


c1 = ctlhsv("Color (hsv): ", <10, 30, 20>);

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).


c1 = ctlcheckbox("checkbox", true);

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.


@version 2.1
   reqbegin("State Control");
        c1 = ctlstate("Testing",true,100,"stateCallback");

stateCallback: val
   info(val); // 0 - off, 1 - on

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,


filename = ctlfilename("Open Object", "(none)",
70, 20);

This accepts two arguments, a string for the requester title, and a starting directory as a string.

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.


@version 2.1

        c1 = ctlbutton("Increment",50,"addcount","10,r1,r2");
        c2 = ctlinteger("Count",1);

   setvalue(c2,getvalue(c2) + 1);
   info(arg1," ",arg2," ",arg3);

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.


@version 2.2
   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);
   if(sel == nil)
        info("No selections were made");
        info("You have selected '",sel,"'!");
} lb_count
lb_name: index

lb_event: items
   // 'items' is an array of integer index values, or 'nil'
   if(items == nil)
        info("No items are selected");
        info("You have selected '",items,"'!");
   a = @1,3,5@;

In addition, the following script illustrates how button controls can manage and interact with the listbox contents:

@version 2.1


   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");

   // don’t use size() here because that counts
   // all elements, even if they have ‘nil’.

lb_name: index

   lb_items += "Item_" + (lb_items.size() + 1);

   sel = getvalue(c1);
   lb_items[sel] = nil;

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.


c1 = ctlslider("My value", 10, 0, 20);

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.


c1 = ctlminislider("My value", 10, 0, 20);

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>

column        integer, starting column.

width           integer, width of bar.


c1 = ctlsep();
c1 = ctlsep(10, 10)

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>

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.


// display the image at (0,0), 40% of its original
// width and 30% of its original height

// 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)


// display the image at (0,0) in its unaltered form

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>

tabNames           strings; a comma-separated list of names of tabs.
c3 = ctltab("Page 1","Page 2","Page 3");

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;


obj = ctlmeshitems("Objects in Scene:",mymesh);


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?


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


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

  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

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.



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             Control Object Agent; the group leader control.

controlId’s          Control Object Agents; a comma-separated list of

                         the follower controls.


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))
c0 = ctlcheckbox("Testing Number 1",true);
c1 = ctlcheckbox("Testing Number 2",false);
c2 = ctlcheckbox("Testing Number 3",true);
c3 = ctlcheckbox("Testing Number 4",false);
ctlposition(c1,0,20);        // <— relative to c0
ctlposition(c2,0,60);        // <— relative to c0
ctlposition(c3,0,20);       // <— relative to c2

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.


ctlposition(c1, 5, 5, 70, 20, 10);

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.


   x = 15;
   reqbegin("ctlactive test");
        c0 = ctlcheckbox("This controls the status of
   ctlstring", true);
        c1 = ctlstring("ctlstring"," ", 25);
        ctlactive(c0, "toggleOn", c1);
        c2 = ctlinteger("Disperal Range",x);
        c3 = ctlcheckbox("Testing Number 1",true);
        c4 = ctlchoice("Test",2,@"X","Y","Z"@);
        return if !reqpost();

toggleOn: value

over10: value
   return(value > 10); // turns ‘c3’ on or off

under10: value
   return(value <= 10); // turns ‘c4’ on or off

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);


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"@);


// stack visiblity-controlled controls atop each other

vis1: value
{ return(value == 1); }

vis2: value
{ return(value == 2); }

vis3: value
{ return(value == 3); }

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.


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

Offset values can also be negative.

ctlalign(c0,-5,20,c1,c2,c3);       // controls move 5 units
                                           // to the left of c0

Note: The LSIDE Interface Designer handles all such manual formatting in a more elegant fashion.

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.


counter = 2;


filenames = matchfiles("c:\\temp","*.*");
c0 = ctlchoice("Test",counter,@"X","Y","Z"@);
c1 = ctlstring("Filenames",filenames[counter]);

refresh: 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.

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.


@version 2.4

menu_items= @"New Session","Close Session","=====","Quit"@;

        c1 = ctlmenu("Sessions",menu_items,

menu_select: item
   info("You selected '",menu_items[item],"'");

menu_active: item
   return(item != 2);

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.


@version 2.4
@define MSG "This is cool!"

msg_x = 101;

         c1 = ctlinfo(100,30,"info_redraw");

   if(msg_x > 100)
        msg_x = -1 * drawtextwidth(MSG);
   drawtext(MSG,<0,0,0>,msg_x, integer((30 -
drawtextheight(MSG))/ 2));

   msg_x += 2;