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 function 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


History

VersionStatusNotes
10.0NewNew in this version.