Matrix Programming

This page describes various actions that can be performed by a Matrix Object, including scrolling, and finding out the dimensions of elements within the list.

### Matrix Object Identifier

All 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 its 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 Matrix object that you’ve given the name Airport List. You could force this matrix to scroll to the top with this code:

    objectaction "Airport List","matrixscroll",1

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

The objectaction statement also allows the object to be specified by its 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 have a form with one matrix object, but you’re not sure what the object name of the Matrix object is, or if it even has a name. You can still find out what the object ID number is and scroll the Matrix object with code like this:

    let targetObjects = objectinfoarray(
        {str(objectinfo("id"))},
        {objectinfo("class")="TextListObject"})
    if linecount(targetObjects)=1
        let targetObjectID = val(targetObjects)
        objectaction targetObjectID,"matrixscroll",1
    else
        beep
    endif

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

### Matrix Scrolling

Use the `"matrixscroll"` action to scroll a matrix to make a specified row visible. The topmost row is row 1. For example, this code will scroll to the 27th row.

    objectaction "Airport List","scrolltorow",27

If the Matrix object is displaying an array, you can use the arraysearch( function to find out the row number. This example assumes that there is a list of airports in the variable Airports, it scrolls the list to make sure SFO is visible.

    let airportRow = arraysearch(Airports,"SFO",1,cr())
    if airportRow>0
        objectaction "Airport List","matrixscroll",airportRow
    endif

Another way to scroll is with the `"autoscroll"` action. This action will scroll the matrix to make the 27th row. However, the 27th row may not be the topmost visible row, it’s only guaranteed to be visible somewhere.

    objectaction "Airport List","autoscroll",27

### Position and Size of Rows, Columns and Cells

The `"cellrectangle"` action allow code to determine the physical location and size (i.e. rectangle) of any cell in the matrix. For example this code determines the location and size of the twelfth cell.

    local cellRectangle
    objectaction "Airport List","cellrectangle",12, cellRectangle

The rectangle that is returned by this action is in window relative co-ordinates. You can change this to screen or form relative co-ordinates using the xytoxy( function. For example if you wanted to use this rectangle with the draggraybox statement you would need to convert it to screen relative co-ordinates.

### Converting a Point to a Cell Number

Use the `"pointtocell"` action to find out what cell contains a specified point. Typically this is used to find out what cell the mouse is over.

    local cellNumber
    let mouseSpot = xytoxy(info("mouse"),"s","f")
    objectaction "Airport List","pointtocell", mouseSpot, cellNumber

### Converting Frame Relative Coordinates to Form Relative Coordinates

Panorama displays a matrix by taking the contents of the matrix frame and mapping it onto the matrix area. This is done over and over again for each cell (see Matrix Geometry and Matrix Object Frame). The `"xytoxy"` action gives your code access to this mapping logic. This action converts a rectangle within the matrix frame object into a rectangle within an individual cell in the matrix. The intended use for this command is allow a procedure to test whether the mouse is over a specific object within the cell, or to pop-up a text editor over a specific section of the cell. The Cell parameter should be a number from 1 to the maximum number of cells in the matrix. The Rectangle parameter should be a rectangle inside the frame rectangle. This action is often used in combination with the `"hitobject"` action, as shown in this example.

    local clickedObjectName,clickedObjectRectangle
    let mouseClick = xytoxy(info("click"),"screen","form")
    objectaction "Airport List","hitobject",
        info("matrixcell"), mouseClick, clickedObjectName
    objectaction "Airport List","xytoxy",info("matrixcell"),clickedObjectRectangle

This code is intended to be attached to the Matrix object so that it will run when the matrix is clicked. It will figure out the position and size of the object within the frame that was clicked on. For example, it could be used to open a dialog window precisely over the clicked object.

### Identifying the Clicked Object Within the Frame

When a Matrix object is clicked, the code attached to the object can use various info( functions to find out what cell was clicked (see Matrix Clicking). You can also use the info(“matrixclickedobjectid”) function to find out exactly what object was clicked within the frame.

There’s also another, obsolete, way to find out what object was clicked within the frame, the `"hitobject"` action. This action only works when the objects within the frame have object names. You can use this action to find out the name of the object that was clicked. The previous example shows how this code can be used. However, for new code, we recommend that you skip the `"hitobject"` action – it’s much simpler and it works even if the objects within the frame don’t have names.

### Converting a Cell Number to a Row and Column

If a Matrix object has multiple columns (see Matrix Geometry) you can use the `"celltoxy"` action to convert a cell number into the corresponding row and column. The example below displays what row and column were clicked on. For example if you’ve created a calendar with a matrix, you could use this code to find out what day of the week was clicked on.

    local calendarRow,calendarColumn
    objectaction "Calendar",
        "CellToXY",info("matrixcell"), calendarRow,calendarColumn
    let dayOfWeek = array("Sun,Mon,Tue,Wed,Thu,Fri,Sat",calendarColumn,",")

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.
- 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 Display Programming -- programming a Text Display Object.
- 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.0 | New | New in this version.