Text Display Programming

This page describes how to program a Text Display Object, including how to scroll, how to access and change the current selection, and how to access the text being displayed.

### Text Display Object Identifier

Most of the features described below are accessed by using the objectaction statement. This statement performs actions on a specified object. Usually the object is specified by it’s name, which means that the object must have a name. To learn how to assign a name to an object, see Object Names.

For example, suppose the current form has a Text Display object that you’ve given the name Notes Display. You could cause this object to scroll to the bottom with this code:

    objectaction "Notes Display","scroll",-1

But remember, this will only work if you’ve set the object name to Notes Display.

The objectaction statement also allows the object to be specified by it’s ID value. You can use the objectinfoarray( function to find out the ID you need based on particular criteria, for example the field name. Suppose you want to start editing the field Body, but you’re not sure what the object name of the Text Editor object is, or if it even has a name. You can still find out what the object ID number is and open the Text Editor object with code like this:

    let targetField = "Notes"
    let targetObjects = objectinfoarray(
        {str(objectinfo("id"))},
        {objectinfo("Formula")=targetField and objectinfo("class")="TextDisplayObject"})
    if linecount(targetObjects)=1
        let targetObjectID = val(targetObjects)
        objectaction targetObjectID,"scroll",-1
    else
        beep
    endif

In this example, the objectinfoarray( function scans all of the objects in the current form.

    let targetObjects = objectinfoarray(
        {str(objectinfo("id"))},
        {objectinfo("formula")=targetField and objectinfo("class")="TextDisplayObject"})

If it finds a Text Display object that is associated with the Notes field, the ID of that object is placed into the targetObjects array. (This formula checks to make sure that the object is a TextDisplayObject because we want to skip over other types of objects that could be associated with the Notes field, like text editors, data buttons, popup menus, or text lists.)

The if statment checks to make sure that we found one, and only one object.

    if linecount(targetObjects)=1

If we did find one object, we need to convert the ID value from text into a number.

    let targetObjectID = val(targetObjects)

With this ID number we can now perform actions on this object.

    objectaction targetObjectID,"scroll",-1

If the form doesn’t contain an text display object for Notes, or if contains two or more such objects, this code will beep.

Now that we know how to identify the Text Editor object that is the intended target of an action, the rest of this page will discuss the various actions that be peformed.

### Scrolling the Text

If the vertical scroll bar is enabled, the text in the Text Display object can be scrolled up and down. Usually this is done manually by clicking and dragging on the scroll bar, but this can be automated. For example, this code will scroll the Notes text display object to the top.

    objectaction "Notes","scroll",0

The 0 in this case tells the Panorama what character to scroll to, in this case 0 is the very first character being displayed (the top). You can also specify the position as a negative number, which indicates the position from the end of the text instead of from the beginning. So this code will scroll the Notes to the bottom.

    objectaction "Notes","scroll",-1

You can also scroll to any position in between.

Note: If the Auto Scroll to Bottom option is enabled, the text will automatically scroll to the bottom whenever the text is modified. Suppose your Notes object is linked to a variable named myNotes. You could add a new line to the notes with today’s date like this:

    let myNotes = sandwich("",myNotes,cr())+datepattern(today(),"Month ddnth:")
    showvariables myNotes

If you wanted the text display object to show this new line, you could modify this code like this:

    let myNotes = sandwich("",myNotes,cr())+datepattern(today(),"Month ddnth:")
    showvariables myNotes
    objectaction "Notes","scroll",-1

However, if the Auto Scroll to Bottom option is enabled, this extra line is not necessary. Simply using showvariables will cause the text to scroll.

Note: If the Text Display object allows text to be selected, scrolling the text via code will cancel any text selection. If necessary, you could save the selection, scroll, then re-set the selection (using the techniques described in the next section).

### Working With the Selection Range

If the Allow Text Selection option is enabled, the user can click on, select, and copy the select text that is being displayed. You can also manipulate the selection with code.

To find out what the current selection range is, use the `"getselection"` action. This must be followed by two variables that will receive the start and end points of the selection. This code will display the number of characters currently selected.

    local start,end
    objectaction "Notes","getselection",start,end
    if start=end
        message "Insertion point"
    else
        message pattern(end-start,"# character~")+" selected"
    endif

Note: The selection range values start at zero, not one. So if the first five characters are selelected, the start of the selection will be 0 and the end of the selection will be 4.

To change the current selection range, use the `"setselection"` action. This must be followed by two values for the start and end positions of the range. This code selects the first character of the text.

    objectaction "Notes","setselection",0,1

If you specify negative values, they will be counted from the end of the text. This code will select the last character of the text.

    objectaction "Notes","setselection",-2,-1

To select all of the text, use:

    objectaction "Notes","setselection",0,-1

It’s ok to specify a number past the end of the text. This code will probably select all of the text, even if there are only ten characters. (But to make sure, it’s better to use -1, which will work even if there are a million characters.)

    objectaction "Notes","setselection",0,9999

### Working With the Displayed Text

Since the text being displayed is generated by a formula, you can usually simply use the same formula in your code to find out what the text is. But sometimes that’s inconvenient. To find out the what the text is currently is right this moment, use the `"gettext"` action.

    local dtext
    objectaction "Notes","gettext",dtext

To find out what the currently selected text is, use the `"getselectedtext"` action.

    local dtext
    objectaction "Notes","getselectedtext", dtext

To copy the currently selected text into the clipboard, you could do this:

    local dtext
    objectaction "Notes","getselectedtext", dtext
    clipboard = dtext

Of course the user could also simply press Command-C for the same effect!

See Also

- activeobjectaction -- allows a procedure to communicate with the object on the current form that is currently being edited (if any).
- changeobject -- modifies the properties of one object in a form.
- changeobjects -- modifies the properties of one or more objects in a form.
- cloneform -- copies all of the objects in a form (optionally, with modifications) into the active form.
- cloneobjects -- duplicates objects in a form (with modifications).
- closeactiveobject -- closes any object whose text is currently being edited.
- datamode -- switches a form from graphics mode into data mode.
- deleteobject -- deletes the specified object from the current form.
- deleteselectedobjects -- deletes selected objects from a form.
- draggraybox -- facilitates dragging something around in a form window.
- dragtext -- starts drag-and-drop of text.
- formcleanview -- cleans up extraneous NSView objects in the current form.
- formxy -- programmatically scrolls a form to a new position.
- graphicsmode -- switches a form into graphics mode.
- info("activeobject") -- returns the name of the currently active text editor or word processor object (if any).
- info("activeobjectid") -- returns the object ID of the currently active text editor or text list object, if any.
- info("activesuperobject") -- returns the name of the currently active text editor or word processor object, if any.
- info("click") -- returns the location of the last mouse click in screen relative coordinates.
- info("clickedobjectid") -- returns the object ID of the clicked object.
- info("focusobject") -- returns the name of the currently active text editor or word processor object, if any.
- info("focusobjectid") -- returns the object ID of the currently active text editor or text list object, if any.
- info("scrollpoint") -- returns the distance the current form is scrolled horizontally and vertically.
- magicformwindow -- designates an open window as the temporary active window for the purposes of info( functions and graphic statements.
- magicwindow -- designates an open window as the temporary active window for the purposes of info( functions and graphic statements.
- magnification -- changes the magnification of a form.
- Matrix Programming -- programming a Matrix object.
- Modifiable Object Properties -- describes the properties of graphic objects that can be modified by a program (dimensions, color, font, title, etc.).
- newformobject -- creates a new graphic object in a form.
- object -- selects an object (based on the object name).
- objectaction -- allows a procedure to communicate with an object on the current form.
- objectid -- selects one graphic object in the current form based on an ID number.
- objectinfo( -- returns information about a graphic object: its location, size, color, font, etc.
- objectinfoarray( -- builds a text array of form object properties
- objectnumber -- identifies one graphic object from a set of selected graphic objects in the current form.
- openasyncprogresswindow -- opens a floating progress window for asynchronous operations (urltask(, timers).
- progressalert -- displays a progress alert if an operation is going to take a long time.
- progressbar -- updates a progress bar on the current form.
- selectallobjects -- selects all the graphic objects in the current form.
- selectnoobjects -- unselects all the graphic objects in the current form.
- selectobjects -- uses a formula to select one or more objects in the current form.
- startgraphicschange -- adds undo support to a procedure.
- Text Editor Programming -- programming a Text Editor Object.
- Text List Programming -- programming a Text List Object.
- textlisttableoptions -- sets up text list table options
- Web Browser Programming -- programming a Web Browser Object (including JavaScript).
- xytoxy( -- converts a point or rectangle from one co-ordinate system to another.

History

Version | Status | Notes
10.2 | New | New in this version.