RunRevPlanetGrid

The RunRevPlanet Grid is a flexible spreadsheet style grid with per cell formatting and virtual or stored data modes. The control is 100% LiveCode and does not use any platform specific libraries. Add powerful grids to your cross platform LiveCode applications for Linux, Mac or Windows.

Guide andReference

RunRevPlanetGrid

Guide and Reference

Copyright (c) 2010 Scott McDonald PC ServicesAll rights reserved.

November 2010 Edition

Address: Scott McDonald PC ServicesPO Box 139, Newtown, 2042New South Wales, AustraliaFacsimile: +612-9564-2347

Website: http://www.runrevplanet.comEmail: runrevplanet@smpcs.server101.com

1

Built with LiveCode from RunRev Ltd.

Table of Contents

Introduction............................................................................3Installation & Requirements...................................................5Conventions............................................................................6Licensing Agreement..............................................................7Simple Grid Demo..................................................................9Advanced Grid Demo TINAS..............................................17Common Grid Actions..........................................................26Callback Functions and Messages........................................38Virtual Mode Grid................................................................40Deploying Your Own Application........................................43Error messages......................................................................46Handler Reference................................................................47

About the Cover Image

The image on the cover of this RunRevPlanet Grid Guide and Reference is a public domain image from the NSSDC (National Space Science Data Center) Photo Gallery. Many thanks to NASA and the NSSDC for making this image, and many more images, available to the public.

Three images were taken on August 12, 2009 by the robotic explorer Cassini, using the red, green and blue spectral filters of the wide angle camera and were combined to create this natural color view. The images were obtained at a distance of approximately 847,000 kilometers from Saturn. This view looks toward the northern side of the rings from about 20 degrees above the ring plane. The original image PIA11667.jpg can be found at: http://photojournal.jpl.nasa.gov/catalog/PIA11667

About RunRevPlanet.com

The RunRevPlanet.com website is an initiative of Scott McDonald PC Services. Our goal is to make RunRevPlanet.com one of the top websites dedicated to LiveCode and an invaluable source of components, stacks, tools and resources for LiveCode developers. Visit us at:http://www.runrevplanet.com

RunRevPlanet.com is not officially affiliated with RunRev Ltd.

2

IntroductionThe RunRevPlanet Grid is a general purpose spreadsheet style unbound grid for your LiveCode applications. The RRP Grid is written in 100% LiveCode script and does not use any platform specific libraries. This means you can add a powerful and flexible grid to your cross platform application for Linux, Mac or Windows.

The RRP Grid is simple to use and requires only a few lines of script to add a powerful grid to your LiveCode application. By using RRP Grid (RRPG) you are free to focus on the unique features of your application and not be concerned with the low-level details of implementing fast and flexible grids to your application.

The RRPG offers two ways to work with your data. With the first method you pass the data to the grid with a single handler call, and the grid stores all the cells that the user can interact with by scrolling, editing and otherwise working with the data. After the user has finished with the data, another handler is called to retrieve the data from the grid. This method of operation requires only a small amount of scripting to add a grid to your application, while giving the users a sophisticated but familiar way of working with rows and columns of data.

The second method of operation that the RRPG supports is virtual mode. In virtual mode the grid does not store the data, but instead uses messages to request the contents of the cells as needed. This method of operation requires you to add handlers to your stack to supply the data as the user interacts by scrolling, editing and otherwise works with the data. For a user, the grid is identical to the storage mode, but as a developer you have more flexibility and the ability to present much larger grids with up to 1,000,000,000,000 cells.

3

Figure 1: A flexible grid component

With the RRPG you can use either method to your application, depending on what is most appropriate for your requirements.

To simplify the addition of a grid to your application and to minimize the scripts required in your application, the RRPG can be copied and pasted from the RunRevPlanet Palette stack into your application while in the LiveCode Edit (Browse) mode. You can freely customize the properties of the grid from the Custom Properties pane of the Property Inspector without having to write a single line of script. This is all possible without having to install a plug-in into the LiveCode IDE.

Features of the RRPG are:

● Flexible spreadsheet style grid● Handles thousands of rows and hundreds of column in the internal storage

mode● Virtual mode handles up to 1,000,000,000,000 cells (one million rows

by one million columns) with fast scrolling● Shading of alternate rows● Highlighting of cursor row and column labels● Selection and arbitrary range of cells● Click and drag selection of cells● Printing of all or selected cells● Every cell can have own alignment● Every cell can have own color● Every cell can have own text style● Editing of cells● Frozen rows● Frozen columns● Messages for detecting changes such as edited cells, and scrolling● Simple input and output of tab delimited plain text or HTML● Uses HTML <table> tags for formatted input and output● Insertion and deletion of rows● Dynamic resizing of grid size● Simple runtime changing of the number of rows and columns● 100% LiveCode script

4

Figure 2: Not just spreadsheets

Installation & RequirementsTo use the RRPG you must have the following:

● Revolution 3.0, or newer, in the Studio or Enterprise edition.● LiveCode 4.5, or newer.

The RRPG may run with earlier versions of Revolution and LiveCode, but version 3.0 or higher is recommended. The RRPG is distributed as a single ZIP archive containing these files:

rrpGrid.revrrpGrid-Guide-Reference.pdfReadme.txtLicense.txt/Demos/Demo-Grid-Simple.rev/Demos/Demo-Grid-TINAS.rev/Demos/planets-data

Also included are three folders:

/DemoTINAS/Linux/DemoTINAS/MacOSX/DemoTINAS/Windows

These contain executable bundles of the Demo-Grid-TINAS application, which is a simple application to illustrate some of the features of the RRPG.

Installation

To install RRPG unzip the files above into a folder of your choice.

M Do not unzip the files into your LiveCode program folder, instead put them into a convenient folder where you work in documents.

After unzipping the files, each time you start a new LiveCode application that uses the Grid you can either:

i. make a copy of the rrpGrid.rev file in the same folder as your application main stack, or

ii. make the rrpGrid.rev file a substack your application main stack.

5

ConventionsThe terms "rrpGrid stack", "rrpGrid.rev" and "RRPG" may be used interchangeably in this guide depending on the context. Each of these names refers to the RunRevPlanet Grid.

Handlers in LiveCode come in different types. There are event handlers, commands, functions and property handlers. For the sake of brevity where the specific type is not important, throughout this guide these terms may be used interchangeably. The generic term handler may refer to commands, functions and property handlers.

The word LiveCode refers to the LiveCode IDE (Integrated Development Environment) and may be used interchangeably with the term IDE.

LiveCode script is shown in a fixed width font with the same formatting shown in the IDE Script Editor. An example of a script is shown below.

command SaveFile if sFileName is empty then SaveAsFile else put rrpGridGetPropsAsText() & return & rrpGridGetDataAsHTML(true) into URL("file:" & sFileName) end ifend SaveFile

The symbol is used to indicate single lines of script that are too long to fit in the width here, and so are broken over two or more lines, but can be entered as a single line in the Script Editor. Scripts that are entered in the Message Box are also shown with a fixed width font but without any formatting such as below.

answer the cVersionNumber of stack "rrpGrid"

M A paragraph with this symbol highlights a point that could be unexpected behavior, or a potential problem that may not be obvious at first.

6

Licensing AgreementThe RRP Grid software and accompanying files and documentation are protected by Australian copyright law and also by international treaty provisions. Any use of this software in violation of copyright law or against the spirit of the terms of this agreement will be prosecuted.

RRP Grid is Copyright (c) 2010 Scott McDonald PC Services, all rights reserved.

Scott McDonald PC services authorizes you to make archival copies of the software for the sole purpose of backup and protecting your investment from loss. Under no circumstances may you copy the software and documentation for the purpose of distribution to others. Under no conditions may you remove the copyright notices from the software or documentation.

You may use an unlicensed copy of the RRP Grid to evaluate the RRP Grid for an unlimited time. You may not build or distribute a standalone application that uses the RRP Grid without first purchasing a License Key from Scott McDonald PC Services at the RunRevPlanet website, or without first purchasing an Unlock Code from an approved vendor.

You may distribute, without run-time fees or further licenses, your own executable applications based on the RRP Grid and the demonstration files after you have purchased a License Key or Unlock Code. You may not distribute applications that use the RRP Grid with your License Key or Unlock Code in an unencrypted stack file.

When distributing your own executable applications based on the RRP Grid you must encrypt with a secure password any stack that includes your License Name and Key or Unlock Code. You may not distribute your License Key or Unlock Code in a separate file with your application, or through other media such as Internet, email or print.

The previous restrictions do not prohibit you from distributing your own source code or stacks that depend on the RRP Grid. However others who receive your scripts need to download their own copy of the RRP Grid and purchase a License Key or Unlock Code in order to write programs that use your own code.

The RRP Grid may be used by one person on as many computer systems that person uses. We expect that group programming projects making use of the software will purchase a license for each member of the group. In such cases, volume discounts may apply to site licensing agreements.

7

The RRP Grid will perform substantially in accordance with the accompanying documentation, and technical support by Scott McDonald PC Services will make commercially reasonable efforts to solve any problems associated with the RRP Grid. If you encounter a bug or deficiency, we will require a problem report detailed enough to allow us to find and fix the problem.

In no event will Scott McDonald PC Services or anyone else who has been involved in the creation, development, production, or delivery of the RRP Grid be liable for any direct, incidental or consequential damages, such as, but not limited to, loss of anticipated profits, benefits, use, or data resulting from the use of this software, or arising out of any breach of warranty.

By using this software you agree to the terms of this Licensing Agreement. If you do not agree, you should immediately erase all your copies of the RRP Grid and apply for a refund if you have purchased a Licensing Key or Unlock Code. Scott McDonald PC Services provides web-based and email support for the RRP Grid on an "as available" basis at no extra charge. When you send an email to technical support we will try to answer your support question within 48 hours.

Built with LiveCode. Portions (c)2000-2010 RunRev Ltd, All Rights Reserved Worldwide. You should review the License Agreement in your copy of LiveCode when building your own applications with LiveCode and the RRP Grid.

All names of products and companies used in this Licensing Agreement, the RRP Grid, or the documentation may be trademarks of their corresponding owners. Their use in this Licensing Agreement is intended to be in compliance with the respective guidelines and licenses.

8

Simple Grid DemoThe RRPG is a self contained stack that you use to add a grid to any LiveCode application. This chapter explains the process of adding a grid to a simple stack. While this demo does not do anything useful, it is important to understand how a grid is added to a stack. It only takes a few minutes to do, and there is a completed copy of the stack named Demo-Grid-Simple.rev in the Demos folder.

It is recommended that you carefully follow these steps the first time you use the grid. Once you understand the process you can then add grids to your own applications.

First you need an open stack to add the grid to. Choose the New Mainstack command in the File menu. The grid is a group of objects that you copy and paste onto a stack. To simplify this, the RunRevPlanet Palette stack is used as a source for the grid objects. Depending on the version of your grid, this palette may include additional RunRevPlanet components

Choose the Open Stack command in the File menu. The RunRevPlanet Palette stack is named rrpPalette.rev . For this tutorial it helps if both the rrpPalette.rev and the rrpGrid.rev stacks are in the same folder as the demo application. Select rrpPalette.rev and choose the Open button.

9

Figure 3: The RunRevPlanet Palette

The RunRevPlanet Palette has the title of RRP which you can see in Figure 3 and the grid is the first object on the palette. To copy the grid, you first need to select it. It is important for the Edit (Pointer) tool to be active to allow you to do this. First check that this is the case in the LiveCode Tools, or you can press control-0 (command-0) to select the Edit tool.

Select the grid by clicking on the background of the RunRevPlanet Palette just above the top left corner of the grid component. Keep the mouse button pressed and click and drag to the bottom right corner of the grid component as in Figure 4. A selection rectangle is drawn around the grid. When the selection handles appear you can release the mouse button.

With the grid object selected you are ready to copy it onto the stack. Right click in the middle of the selected grid object and from the contextual menu choose the Copy command shown in Figure 5.

10

Figure 4: Selecting the grid component

Figure 5: Copying the grid component

Then in the new empty main stack, right click and choose the Paste Objects command from the contextual menu in Figure 6.

This adds the grid to your stack in Figure 7. The grid is bounded by a rectangle which this documentation calls the grid frame. This grid frame is actually a graphic object that holds all of the objects that make up the grid.

It is important not to delete the grid frame or any of the objects in it, unless you actually want to delete the grid from the stack.

M To delete a grid, select the grid frame by doing a small click and drag in the bottom right corner and then press the Delete key. Deleting a grid in this way ensures that all of the objects are properly removed from the stack.

11

Figure 6: Pasting the grid component

Figure 7: The grid on a stack

The grid frame allows you to move and resize the grid. Click and drag on the bottom right corner selection handles of the grid frame like in Figure 8. The grid resizes to fill the new size of the frame when the mouse is released.

The grid is moved with a click and drag inside the selected grid frame. When moving the grid frame you must click in the blank area near the bottom right corner (not on the selection handle) and then move the grid frame as shown in Figure 9. As with resizing the grid frame, the grid is drawn in the new position after releasing the mouse.

Before proceeding right click on a blank area of the new stack and choose the Property Inspector command in the contextual menu. Enter Demo Grid Simple for the name and then choose the Save command in the File menu. It is recommended that you navigate to the same folder as the rrpPalette.rev and rrpGrid.rev files when saving.

12

Figure 8: Resizing the grid

Figure 9: Moving the grid

Now with a grid on the Demo Grid Simple stack, you can examine the custom properties of the grid frame object to see some of the flexibility of the grid. If it is not still selected, select the grid frame by doing the small click and drag in the bottom right corner. Then right click and choose the Property Inspector command in the contextual menu, or use your favorite method for showing the Inspector.

The grid frame is given a name that includes the ID. The ID number is important to know if you later make an application with more than one grid in a stack. This ID is also required if you want the grid to automatically resize itself if the stack is resized. Making the grid resize itself will be covered later in this chapter, but first you can examine the custom properties as shown in Figure 10.

The custom properties of the grid frame object specify the visible appearance and behavior of the grid. Properties that can be changed in the Property Inspector (or from a script in your application) begin with a lowercase letter c.

Scrolling down the list there are more custom properties, that begin with the letters pv which means “private”. These properties in Figure 11 are essential for the operation of the grid they must not be changed in the Property Inspector or from your scripts.

M The values of the properties that begin with pv are maintained by the grid itself and must not be altered.

13

Figure 10: The grid custom properties

Figure 11: Private properties

Next a handler is added to the stack script to allow the grid to resize itself when the stack is resized. Right click in any blank area of the Demo Grid Simple stack and choose the Edit Stack Script command from the contextual menu.

Here in the Script Editor two handlers have been added in Figure 12. The first handler makes the grid resize itself when the stack is resized, with the actual script below

on resizeStack pNewWidth, pNewHeight pvGridStackResize 1003, pNewWidth, pNewHeight pass resizeStackend resizeStack

This is where the ID of the grid frame object is important because if you copy and paste the script from this chapter into your stack, you need to edit the first parameter of the call to pvGridStackResize handler so that it has the same ID as your grid frame object.

M On some platforms, you need to add an additional handler to ensure correct resizing of the grid. To keep this demo as simple as possible, the additional handler is omitted here, but please refer to the Resizing a grid section of the Common Grid Actions chapter for more details.

Another handler that is important for a stack with a grid is the openStack handler. The grid in this demo stack works correctly because rrpPalette.rev was first opened which puts the rrpGrid.rev stack in the message path.

14

Figure 12: Two important handlers

But in a finished application, the RunRevPlanet Palette would not be open and so you need your application to insert the rrpGrid into the message path. So this second handler is required to make the grid works correctly the next time you open the Demo Grid Simple stack.

on openStack try start using "rrpGrid.rev" catch tError answer "Cannot find: rrpGrid.rev" end tryend openStack

To keep the openStack handler simple for this demo, making rrpGrid.rev a substack of the main stack is best so you do not need to worry about the folder where the rrpGrid.rev file is located.

M It is not necessary to make rrpGrid.rev a substack when using the RRPG in your own applications, but if you don't your openStack handler will need to be more sophisticated than the one here.

Choose the Open command in the File menu and open the rrpGrid.rev stack. After loading, right click on it and show the Property Inspector for it. In the Basic Properties pane select Demo Grid Simple in the Main stack list to make rrpGrid a substack as in Figure 13. After making a stack a substack is a good time to save so choose the Save command in the File menu again.

15

Figure 13: Making the grid a substack

Now the grid is ready to go. Click on the IDE Run (Browse) tool to make the grid active so you can interact with it and enter text. Click on a cell to move the cursor, or with a click and drag action select a region of cells like in Figure 14. Then edit the contents of a cell by pressing the Enter (Return) key. Lastly try the scrollbars to move around the grid.

Conclusion

Here is a summary of what you have learned in this chapter.

● How to open the RunRevPlanet Palette● How to select and copy the grid object from the palette onto your own

stack● How to select, move and resize the grid on your stack● How the custom properties in the Property Inspector control the look and

behavior of the grid● Found out that the custom properties that begin with pv are “private” and

should not be changed● How to add a resizeStack handler to your stack to make the grid resize

with the stack● How to add an openStack handler to ensure the grid handlers are in the

message path

In the next chapter a more sophisticated demo is examined to learn more about the features of the grid.

M The Demo Grid Simple stack made in this chapter is the simplest grid with a minimum of scripting. This means it does not properly handle being open at the same time as another grid in the IDE, so it should be closed and removed from memory before examining the demo in the next chapter.

16

Figure 14: The completed demo

Advanced Grid Demo TINASThe second demo stack is ready-made and the process of making it is not covered here. Instead this demo stack illustrates some of the more commonly used handlers. The demo mimics some of the features of a spreadsheet and also uses a second grid for setting the preferences of the main grid.

M The demo in this chapter is also called TINAS which means “this is not a spreadsheet”. It is important to understand that the RunRevPlanet Grid is not a complete spreadsheet engine and also is not limited to a spreadsheet type of application.

For this demo, the spreadsheet metaphor is used as a way of illustrating some of the features of the grid in a way that is familiar to many users. But as shown in the Preferences command in the Edit menu, the grid is suitable for other purposes,

Open the Demo-Grid-TINAS.rev stack from the Demos folder. Before examining the scripts you can experiment with the grid by selecting the Run (Browse) tool in the IDE and then choose the Open command in the File menu of the Demo Grid TINAS stack. Select The planets-data file and click on the Open button.

This opens a file of data shown in Figure 15 that has been previously prepared in the demo and saved. First feature to note is the different styles and alignments used in some of the cells.

17

Figure 15: This is not a spreadsheet demo

A second feature to note, by scrolling down and across a few rows and columns, is the different coloring possible for each cell in Figure 16.

Next choose the Preferences command in the Edit menu of the demo. This displays the following dialogue box in Figure 17 so you can change the properties of the grid in the main stack. The preferences are displayed with another instance of a RunRevPlanet grid.

The spreadsheet style grid in the main stack and the grid in the preferences dialogue are just two examples of the possibilities with RRPG.

18

Figure 16: Different cell colors and attributes

Figure 17: Main stack properties

You can experiment with the properties in the Preferences dialogue, each time choosing the OK button to effect the changes.

M If you want to return to the original appearance of the main grid, just open the planets-data file again – without first saving the file.

The Grid menu in the main stack allows you to set some of the more commonly used properties in a more user-friendly way. While the Edit, Inserts and Grid menus have commands for you to interact and change the data in the cells of the grid.

Choose the Application Browser in the Tools command of the IDE and you can see that rrpGrid is a substack in Figure 18. This is for the convenience of this demo to make sure it works from any folder without having to be concerned with the path to the rrpGrid.rev file. In your own applications the grid can be a substack, or it can be kept as a separate stack file, depending on what is most convenient for your deployment.

In the Application Browser, select the Demo-Grid-TINAS stack and right click to choose the Edit Script command in the contextual menu. The first three handlers shown in Figure 19 are important to put the grid in the message path, and to make the grid resize itself when the stack is resized.

M Refer to the Resizing a grid section of the Common Grid Actions chapter for more details of the two handlers that resize the grid.

19

Figure 18: Edit the stack script

Scrolling through the stack script shows that many of the commands from the main menu items of the demo simply call the relevant handler in the RRPG. This allows you to add a lot of functionality for very little effort.

The two handlers that save and open the demo data are one example of getting data in and out of a grid. To save the contents of the grid as a file, the properties and data from the grid are returned by these two functions which are then stored in a file.

put rrpGridGetPropsAsText() & return & rrpGridGetDataAsHTML(true) into URL("file:" & sFileName)

Reading the data back requires a more complicated script because the saved file is split into two sections before restoring the properties and data.

put URL("file:" & it) into tDataput offset("<table", tData) into tIndexif tIndex > 0 then put it into sFileName put char 1 to tIndex - 1 of tData into tProps delete char 1 to tIndex - 1 of tData rrpGridSetPropsFromText tProps rrpGridRefresh rrpGridSetDataFromHTML tDataend if

Here a test is done to check that the file has a HTML table in it. If there is, the lines before the table are assumed to be grid properties. If you like, you can open in the

20

Figure 19: Three important stack handlers

planets-data file in any text editor to examine the format of the data. This simple format is just for the demo.

The next script examined relates to the use of a second grid for the Preferences dialogue box.

command EditPreferences set the cPreferences of stack "Demo-Grid-Pref" to rrpGridGetPropsAsText(true) go stack "Demo-Grid-Pref" as modal rrpGridSetActiveAuto rrpGridSetPropsFromText the cPreferences of stack "Demo-Grid-Pref" rrpGridRefreshend EditPreferences

Here the properties of the grid are stored as text in the cPreferences custom property of the Demo-Grid-Pref stack. This is done to pass the properties to the Preferences dialogue before it is shown modally.

Then after the modal stack is closed, the rrpGridSetActiveAuto handler is called. This is necessary because this demo application has more than one grid. When there is more than one grid in an application, RRPG needs to know the active grid so the grid handlers work on the correct grid.

The rrpGridSetActiveAuto handler makes the grid on the current stack the active one. This works when there is only one grid on a stack because there is no ambiguity about which grid must be made active, so you don't need to specify the ID or name of the grid frame.

M For an application with more than one grid on a stack the rrpGridSetActiveByID or rrpGridSetActiveByName handler must be used to set the active stack. Refer to the refer to the Multiple grids section of the Common Grid Actions chapter for more details.

Lastly in the EditPreferences handler, the properties of the grid are set and the grid refreshed to show any changes made to the properties. Next examine the scripts in the Demo-Grid-Pref stack. Use the Application Browser to edit the stack script. The first handler is below.

on openStack rrpGridSetActiveAuto rrpGridSetColLabels "Property,Value" rrpGridSetDataFromText the cPreferences of this stack rrpGridSetRowCount the number of lines in the cPreferences of this stack rrpGridSetMessageMode trueend openStack

21

The openStack handler sets up the grid that is used for the preferences. As mentioned above, because there is more than one stack in this application rrpGridSetActiveAuto is called to make the grid in this stack the active one.

Then rrpGridSetColLabels is called to change the labels for the columns, since the default column names of A and B are not appropriate they instead are set to Property and Value.

The cells of the grid are now set with the contents of the cPreferences custom property, that was set before the stack was modally called. The preferences are a simple tab delimited list of pairs with the property name and value on each line. Since there is no formatting in this list, rrpGridSetDataFromText puts the data in the grid.

To make the grid show the same number of rows as there is in the data, rrpGridSetRowCount is called, and lastly rrpGridSetMessageMode is called with true as the parameter so messages are sent as the user interacts with the grid.

By default, a grid does not send messages as the user interacts with it. In this demo messages are used to simplify the setting of any cell that specifies a color. You can read more about the messages the grid sends in the Callback Functions and Messages chapter.

In this demo only one message is being handled, which is the one when the user double clicks on a cell. This message is handled so the user does not need to manually enter a color, but can instead select it from a dialogue box.

Here is the handler that in the Demo-Grid-Pref stack script that handles the message sent from the grid.

on rrpGridCellDoubleClickM pRow, pCol, pID local tValue if (pCol = 2) and rrpGridGetCellAt(pRow, 1) ends with "color") then put rrpGridGetCellAt(pRow, 2) into tValue answer color with tValue if it is not empty then put rrpGridConvertColor(it) into tValue rrpGridSetCellAt pRow, 2, tValue end if end ifend rrpGridCellDoubleClickM

The rrpGridCellDoubleClickM message is sent when the user double clicks on a cell. First this script checks that the user has double-clicked a cell in the second column and that the text in the first cell of that row ends with “color”. If these two

22

conditions are true, the clicked cell we want to handle by showing the answer color dialogue box shown in Figure 20.

In that case the contents of the clicked cell is passed to the answer color dialogue. If the user does not choose the Cancel button the selected color is put back into the cell. An extra detail is that the RRPG requires colors in the HTML style, so the rrpGridConvertColor function of the RRPG converts the RGB value of the answer color dialogue into a HTML style color.

The only other script of interest in Demo-Grid-Pref stack is for the OK button, which is:

on mouseUp set the cPreferences of this stack to rrpGridGetDataAsText() close this stackend mouseUp

This gets the data from the grid puts it back into the cPreferences custom property ready for the modal stack to return control to EditPreferences handler in the main stack. With this substack you can see that using and interacting with the RRPG is straightforward and only requires a few lines of script to build a relatively sophisticated interface.

Returning now to the script of the main stack, the last handler examined in this chapter is PrintFile. Other than setting the margins for the printer, this script does

23

Figure 20: Handling a double mouse click with a message handler

not perform any special set up of the printer and so here the pages will be sent to the default attached printer.

command PrintFile set the printMargins to 28,28,28,28 rrpGridPrint trueend PrintFile

With the rrpGridPrint command, the grid is sent to the printer with all formatting. The true parameter means that empty rows and columns towards the bottom and right of the grid are trimmed (i.e. left off) the print out. The rrpGridPrint command handles any pagination if the grid cannot fit on a single page. Figure 21 shows the first page of the printout.

24

Figure 21: The printed grid

Conclusion

Here is a summary of the handlers you have learned about in this chapter.

rrpGridConvertColorrrpGridGetCellAtrrpGridGetDataAsHTMLrrpGridGetDataAsTextrrpGridGetPropsAsTextrrpGridPrintrrpGridRefreshrrpGridSetActiveAutorrpGridSetCellAtrrpGridSetColLabelsrrpGridSetDataFromHTMLrrpGridSetDataFromTextrrpGridSetMessageModerrpGridSetPropsFromTextrrpGridSetRowCount

You have also learned the basics of:

● How to handle more than one grid in an application● How to use the message mode● How to get data in and out of a grid in the HTML and text formats● How to access individual cells in a grid● How to change the column labels● How to print a grid

25

Common Grid ActionsThis chapter lists some common actions that you may need to add to your application that uses the RRPG. This chapter does not include a detailed description of the handlers listed, but instead organizes them into functional groups. For more details of individual handlers you can refer to the Handler Reference chapter.

Start using

After adding a grid to your stack, one of the first scripts you should add to your application is in the openStack handler to ensure that the RRPG is in the message path. This sample script below is very simple and assumes that the grid stack is a substack of your application. As a substack you do not need to be concerned with folders and paths in the start using statement.

on openStack try start using "rrpGrid" catch tError answer "Cannot find: rrpGrid.rev" end tryend openStack

If rrpGrid is not a substack, you will need a more complicated script that uses the path of your application stack, or some other method, to determine where rrpGrid.rev is located.

Changing appearance and behavior

The grid has many custom properties so you can customize the appearance and behavior of the grid. Each custom property has a corresponding handler so you can easily set these custom properties without having to use the property syntax. So instead a line like:

set the cRowCount of stack "rrpGrid" to 10

You can instead write the shorter line here.

rrpGridRowCount 10

At design time, changing a custom property in the Custom Properties pane of the Property Inspector for the graphic frame allows you to see the immediate affect on the grid.

26

M The value of all the custom properties is a single line of text. When changing these properties it may be tempting to press the Enter (Return) key to make the change, but this adds a second line to the property and doesn't work. Instead after changing a property, click on the property name to effect the change.

The Custom Properties pane is useful at design time to make changes to the appearance and behavior of the grid, but at runtime less script is required to instead use the rrpGrid handlers. Below is a list of each custom property and the associated handler.

cAlternateRowColor rrpGridSetAlternateRowColorcCacheVirtual rrpGridSetCacheVirtualcCellBorderColor rrpGridSetCellBorderColorcCellColor rrpGridSetCellColorcCellHeight rrpGridSetCellHeightcCellWidth rrpGridSetCellWidthcColCount rrpGridSetColCountcColLabelOffset rrpGridSetColLabelOffsetcColLabels rrpGridSetColLabelscCursorColor rrpGridSetCursorColorcCursorRowColColor rrpGridSetCursorRowColColorcEditColor rrpGridSetEditColorcFrameVisible rrpGridSetFrameVisiblecFrozenColCount rrpGridSetFrozenColCountcFrozenColor rrpGridSetFrozenColorcFrozenRowCount rrpGridSetFrozenRowCountcHiliteCursorLabels rrpGridSetHiliteCursorLabelscHScrollVisible rrpGridSetHScrollVisiblecLabelHeight rrpGridSetLabelHeightcLabelWidth rrpGridSetLabelWidthcPrintFooter rrpGridSetPrintFootercPrintLabelColor rrpGridSetPrintLabelColorcPrintLabelTextColor rrpGridSetPrintLabelTextColorcRowCount rrpGridSetRowCountcRowLabels rrpGridSetRowLabelscSelectionColor rrpGridSetSelectionColorcShadeAlternateRows rrpGridSetShadeAlternateRowscShadeCursorCol rrpGridSetShadeCursorColcShadeCursorRow rrpGridSetShadeCursorRowcVScrollVisible rrpGridSetVScrollVisible

In every case, the handler name is the same as the custom property name (except the initial c) but begins with rrpGridSet.

In most cases there is no corresponding handler to get the value of the custom property. Generally, it is assumed that the values of these properties are set from a value stored elsewhere in your application and so don't need to be read from the grid.

27

If you did need to get the value of one of these properties from the grid you can use a script like this one.

get the cPrintFooter of graphic ID 1003

The last item in the script is the ID of the grid frame. The 1003 shown here is just an example, the ID will almost certainly be different in your stack.

Resizing a grid

The grid fills the grid frame object on your stack and if you resize the grid frame at design time while the Edit (Pointer) tool is active, the grid resizes itself to fill the grid frame.

To make the grid resize itself when the stack is resized, you need to add this resizeStack handler to the stack script. The first parameter of the call to pvGridStackResize is the ID of the grid frame.

on resizeStack pNewWidth, pNewHeight pvGridStackResize 1003, pNewWidth, pNewHeight pass resizeStackend resizeStack

M On some platforms, the grid may not properly resize itself after you define this handler of your stack. To prevent potential resizing problems you should also add the handler below to your stack.

on rrpGridResizeHelperM pvGridStackResizeHelper 1003, the width of me, the height of meend rrpGridResizeHelperM

Again the first parameter of the call to pvGridStackResizeHelper is the ID of the grid frame.

When the stack is resized, these two handlers determined how the grid is resized.

rrpGridSetWidthCanStretchrrpGridSetHeightCanStretch

If both of these are set to true, the grid is resized so the right and bottom edges of the grid remain the same distance from the right and bottom edges of the grid. By setting either of these to false, either the width or the height remains fixed when the stack is resized. Also if you do not have a resizeStack handler with the script above, then the size of the grid remains unchanged.

28

M Using the Geometry Manager to resize the grid frame object will not resize the grid.

To change the size of the grid from a script, call this handler.

rrpGridSetRectangle

This allows you to set the position of the left, top, right and bottom edges of the grid.

Putting data into a grid

Once the grid on your stack looks and works the way that you want, the next step is putting data into the grid. The two main handlers for doing this are:

rrpGridSetDataFromHTMLrrpGridSetDataFromText

The first requires data as a HTML table, while the second accepts lines of tab delimited plain text. Both of these handlers replace all of the data in the grid with the specified data.

To change the cells in only a part of the grid, use one of these handlers.

rrpGridSetCellAtrrpGridSetDataAt

Lastly, this next handler copies data from the clipboard, which can be in either the HTML format, or as plain text. The data is put into the grid starting from the position of the cursor cell.

rrpGridPasteAtCursor

Setting the cell attributes

Cells can be selected in the grid by the user doing a click and drag action over the cells, or cells can be selected with this handler.

rrpGridSetSelectedCells

The selected cells can then be set with different attributes with these handlers.

rrpGridSetSelectedAlignmentrrpGridSetSelectedColorrrpGridSetSelectedStylerrpGridSetSelectedWrap

29

The alignment is whether the cell text is left or right justified, or centered. The color is as you expect, but needs to be coded in the HTML style that begins with a # followed by 6 hexadecimal digits.

M To convert a color from the RGB to the HTML format, use the rrpGridConvertColor function.

The cell style can be either bold, italic or a combination of those, and if no style is set the content has the plain style.

The rrpGridSetSelectedWrap handler sets whether the selected cells wrap content that is greater than the width of the cell. Setting this property is useful when the rows have a greater height than the default and cells have long text in them. The wrapping occurs on word breaks, in other words, where there is a space in the text.

M If no cells are selected when calling the handlers in this section, the attributes are applied to the cursor cell.

The cursor position

The cursor cell is shaded with the color from the cCursorColor property and is the cell edited if the Enter (Return) key is pressed. The position of the cursor cell is specified by a row and column pair of values and is read and set with these handlers.

rrpGridGetCursorrrpGridSetCursor

When setting the cursor, if the row or column parameter is outside the range of the grid the cursor remains unchanged. If the position of the cursor is within the grid, but outside of the currently visible cells, the grid is scrolled to make the cursor cell visible.

If you only need the row or column of the cursor position, to avoid the overhead of getting the first or second item from the rrpGridGetCursor function, use either of these handlers.

rrpGridGetCursorRowrrpGridGetCursorCol

Similarly, change only the row or column by calling one of these handlers while keeping the other position unchanged.

rrpGridSetCursorRowrrpGridSetCursorCol

30

Frozen cells

Frozen cells are cells that do not scroll off the left or top edge of the grid when the grid is scrolled. Frozen cells are useful as headings and other information that must remain constant while the user scrolls around the grid.

You specify the frozen cells by setting how many rows or columns need to be frozen. This means, for example, if the frozen row count is set to 1, all the cells in the first row remain visible at the top of the grid even when you scroll downwards. Similarly, you can set the frozen column count to keep cells at the left edge of the grid visible. Set the frozen cells with these two handlers.

rrpGridSetFrozenColCountrrpGridSetFrozenRowCount

The number of frozen rows or columns must be less than the number of visible rows or columns in the grid. To remove frozen rows or columns so the cells scroll normally you set the count to 0. You can have both rows and columns frozen at the same time.

M If a grid is resized and the number of frozen rows or columns is more than the visible number of rows and columns, the number of frozen cells are reduced to ensure there is always at least one whole cell that is not frozen.

Inserting and deleting cells

There are several handlers for inserting and deleting rows and columns in the grid . Inserting shifts the data in the cells downwards and to the right “to make room” for the inserted row or column. These two handlers insert a new empty column into the grid.

rrpGridInsertAfterColrrpGridInsertBeforeCol

The first handler puts the new column after the specified column, while the second handler puts the new column before the specified column. The next two handlers are similar, but insert a row into the grid.

rrpGridInsertAfterRowrrpGridInsertBeforeRow

For convenience, because often rows and columns are inserted at the cursor position, there are these four additional handlers, which work as you expect.

rrpGridInsertColAfterCursorrrpGridInsertColBeforeCursor

31

rrpGridInsertRowAfterCursorrrpGridInsertRowBeforeCursor

M When rows and columns are inserted into the grid, by default the number of rows and columns in the grid is unchanged so cells at the edge of the grid that are not empty are lost from the grid.

Set the cExpandMode Property to true if you want the number of rows and columns in the grid to increase so no data is lost when you insert a row or column.

The row or column at the cursor is deleted with these handlers.

rrpGridDeleteColAtCursorrrpGridDeleteRowAtCursor

When deleting a row or column, the cells below or to the right of the deleted row or column are shifted to fill in the gap of the deleted row or column.

To delete multiple rows or columns, or to delete a cells from a specific position, use these two handlers.

rrpGridDeleteColRegionrrpGridDeleteRowRegion

If only a single parameter is specified then the cells in that row or column are deleted. With two parameters, all the cells between those two positions are deleted from the grid.

When deleting rows or columns the size of the grid does not change. The data in the cells is shifted up or to the left to fill the space of the deleted cells. The cells at the edge of the grid are set to empty.

M Inserting and deleting and rows and columns can require shifting the contents of many cells in the grid. In a large grid, or a grid in virtual mode, this may take a significant amount of time and can result in an application not responding to messages. If your application uses a large grid, especially in virtual mode, you may need to avoid or be careful about using the handlers in this section.

Getting data out of a grid

These two handlers return the entire contents of the grid. The HTML handler returns the contents of the grid as a HTML table that preserves all of the attributes of the cells in the grid. While the second handler returns the text of each cell as tab delimited columns with one row per line.

32

rrpGridGetDataAsHTMLrrpGridGetDataAsText

The next group of handlers returns either a specific region that you specify, or the selected cells in the grid. In each case you have the option of getting the cells as a HTML table or as plain text.

rrpGridGetRegionAsHTMLrrpGridGetRegionAsTextrrpGridGetSelectedAsHTMLrrpGridGetSelectedAsText

To copy cells to the clipboard use the next two handlers. These copy the selected cells and are typically used for an Edit Copy type of command in your application.

rrpGridCopySelectedAsHTMLrrpGridCopySelectedAsText

The last group of handlers in this section access a single cell anywhere in the grid to return the contents or attributes.

rrpGridGetCellAtrrpGridGetAlignmentAtrrpGridGetColorAtrrpGridGetStyleAt

Multiple grids

If your application has a single grid, the handlers in this section are not necessary. When you create a grid the RRPG attaches the objects of the grid to the appropriate handlers in rrpGrid.rev.

When your application has more than a single grid you need to make sure that your scripts sets the active grid before you access it with the handlers. If your application has more than one grid, but each grid is on its own stack then this handler can be called to activate the grid on the stack.

rrpGridSetActiveAuto

M As with all the grid handlers, this handler needs to be called from the same stack or card that contains the grid.

This handler searches for a grid frame object on the stack, and if one is found it is made active. If there is more than one grid frame on a stack, for example on different cards in the same stack, the above handler cannot determine which grid you intend as the active one. In those cases, the two handlers below are required.

33

rrpGridSetActiveByIDrrpGridSetActiveByName

These handlers take a parameter of either the ID or name of the grid frame, and assuming a grid frame is found that matches the ID or name, it is made active.

M It is important with applications that have more than one grid, that each grid have a unique name set for the grid frame object in the Property Inspector.

If you have separate applications that share a single copy of rrpGrid.rev, i.e. it is not a substack, then every grid frame object that shares the RRPG must have a unique name.

For applications with multiple grids on multiple stacks, where the stack with the focus may change, the script below ensures the RRPG keeps track of the active grid as each stack is made active.

local sLastActiveGridNameon suspendStack put rrpGridGetActiveName() into sLastActiveGridName pass suspendStackend suspendStackon resumeStack rrpGridSetActiveByName sLastActiveGridName pass resumeStackend resumeStack

The script above is not needed in simpler applications that do not have more than one grid, or do not have modeless stack windows.

M Calling rrpGridSetActiveByName does nothing if the stack is already active, so there little penalty if it is called just to be sure the correct grid is active.

If called repeatedly, the rrpGridSetActiveByName handler is slightly more efficient than calling the rrpGridSetActiveByID handler when the application has multiple grids.

Virtual Mode

In virtual mode you do not put data into the grid where it is viewed or edited and then later get the data back from the grid. Instead in virtual mode the grid sends messages to your stack requesting the contents of each cell as it is displayed, and a message is sent when the contents of a cell changes. Virtual mode is set and read with these handlers.

34

RrpGridSetVirtualModerrpGridGetVirtualMode

Depending on the type of user interaction with your grid, virtual mode can be slower than the normal method of operation. This is a trade-off because of the extra messages required to allow a significantly larger number of cells in the grid.

To speed up virtual mode, calling this handler with a parameter of true enables a cache for the virtual grid.

rrpGridSetCacheVirtual

The cache provides temporary storage for frequently accessed cells to speed up the operation of the grid, for example, when scrolling. When the cache is enabled, the grid does not need to send a message every time a cell is re-drawn.

There may be times when you need to clear the cache to ensure that the grid is displaying the latest data. To do this call the following handler.

rrpGridEmptyCache

M The cache is automatically cleared each time you make a different grid active in an application.

For more details of working in virtual mode, refer to the Virtual Mode Grids chapter.

35

Callback Functions and MessagesThe RRPG optionally sends messages when the user interacts with the grid. The messages can be intercepted by handlers in your stack. These are commonly named callback handlers. Defining a callback handler in your stack allows you to do actions in response to user interaction with the grid.

M RRPG only sends these messages when the cSendMessages property is set to true. By default this property is false, so set it to true if your application defines callback functions.

The messages sent by RRPG and when they occur are:

● rrpGridCellClickM called when there is a mouse click on a cell● rrpGridCellDoubleClickM called when there is a mouse double click

on a cell● rrpGridColChangeM called when the column of the cursor

changes● rrpGridColLabelClickM called when there is a mouse click on a

column label● rrpGridColumnResizeM called when the user resizes the widths of

the columns● rrpGridCornerClickM called when there is a mouse click in the

top left corner button● rrpGridCursorChangeM called when the cursor changes● rrpGridEditBeginM called when the user starts to edit a cell● rrpGridEditCancelM called when the user cancels the editing

of a cell● rrpGridEditEndM called when the user finishes editing a cell● rrpGridEditPreM called before the editing of a cell begins● rrpGridEditReadOnlyM called when the user tries to edit a cell that

is read only● rrpGridResizeHelperM called when the grid is being resized● rrpGridRowChangeM called when the row of the cursor changes● rrpGridRowLabelClickM called when there is a mouse click on a

row label● rrpGridSelectionChangeM called when the cell selection in the grid

changes● rrpGridTopLeftChangeM called when the grid is scrolled so the cell

in the top left corner changes

36

In each case the message ends with the letter M as a reminder that these are not handlers that you can call, but are instead messages that your own application can handle.

These messages are sent to the stack that contains the grid.

The handlers that you can put in you stack to respond to the messages are not documented in the Handler Reference and instead listed here.

on rrpGridCellClickM pRow, pCol, pID -- called when there is a mouse click on one of the cells -- pRow is the row of the clicked cell -- pCol is the column of the clicked cell -- pID is the ID of grid frameend rrpGridCellClickMon rrpGridColChangeM pCol, pID -- called when the column of the cursor changes -- pCol is the current cursor column -- pID is the ID of grid frameend rrpGridColChangeMon rrpGridColLabelClickM pCol, pID -- called when there is a mouse click on one of the column labels -- pCol is the column that is clicked on -- pID is the ID of grid frameend rrpGridColLabelClickMon rrpGridColumnResizeM pCellWidth, pID -- called when the user resizes the widths of the columns -- pCellWidth is the cell width -- pID is the ID of grid frameend rrpGridColumnResizeMon rrpGridCornerClickM pID -- called when there is a mouse click in the top left –- corner button -- pID is the ID of grid frameend rrpGridCornerClickMon rrpGridCursorChangeM pRow, pCol, pID -- called when the cursor changes -- pRow and pCol is the current cursor position -- pID is the ID of grid frameend rrpGridCursorChangeMon rrpGridEditBeginM pRow, pCol, pText, pID -- called when the user starts to edit a cell -- pRow is the row of the edited cell -- pCol is the column of the edited cell -- pText is the text in the cell before any changes are made -- pID is the ID of grid frameend rrpGridEditBeginM

37

on rrpGridEditCancelM pRow, pCol, pText, pID -- called when the user cancels the editing of a cell -- pRow is the row of the edited cell -- pCol is the column of the edited cell -- pText is the text in the cell without any changes -- pID is the ID of grid frameend rrpGridEditCancelMon rrpGridEditEndM pRow, pCol, pText, pID -- called when the user finishes editing a cell, can -- optionally return a value that changes the text seen -- in the cell after the edit ends -- pRow is the row of the edited cell -- pCol is the column of the edited cell -- pText is the text in the cell after the changes are made -- pID is the ID of grid frameend rrpGridEditEndMon rrpGridEditPreM pRow, pCol, pText, pID -- called when the user starts to edit a cell, but before the -- editing is started, can optionally return a value that -- changes the text seen in the cell when the edit begins -- pRow is the row of the edited cell -- pCol is the column of the edited cell -- pText is the text in the cell before any changes are made -- pID is the ID of grid frameend rrpGridEditPreMon rrpGridEditReadOnlyM pRow, pCol, pText, pID -- called when the user tries to start to editing a cell -- that is read only, this message is not sent if the -- when the cReadOnly property is set to true -- pRow is the row of the edited cell -- pCol is the column of the edited cell -- pText is the text in the cell before any changes are made -- pID is the ID of grid frameend rrpGridEditReadOnlyMon rrpGridResizeHelperM pID, pWidth, pHeight -- see "Resizing a grid" in the "Common Grid Actions" chapter -- for more details -- pID is the ID of grid frame -- pWidth is the width of the stack with the grid -- pHeight is the height of the stack with the gridend rrpGridResizeHelperMon rrpGridRowChangeM pRow, pID -- called when the row of the cursor changes -- pRow is the current cursor row -- pID is the ID of grid frameend rrpGridRowChangeM

38

on rrpGridRowLabelClickM pRow, pID -- called when there is a mouse click on one of the row labels -- pRow is the row that is clicked on -- pID is the ID of grid frameend rrpGridRowLabelClickMon rrpGridSelectionChangeM pCursorRow, pCursorCol, pSelectRow, pSelectCol, pID -- called when the selection in the grid changes -- pCursorRow, pCursorCol is position of the cell at –- top left corner of the selected region -- pSelectRow, pSelectCol is position of the cell at bottom –- right corner of the selected region -- pID is the ID of grid frameend rrpGridSelectionChangeMon rrpGridTopLeftChangeM pLeft, pTop, pID -- called when the grid is scrolled so the cell in the –- top left corner has changed -- when the cell A1 is visible in the top left corner, pLeft –- and pTop is 0, 0 -- pLeft is the number of columns that have scrolled off the –- left edge and are not visible -- pTop is the number of rows that have scrolled off the top –- edge and are not visible -- pID is the ID of grid frameend rrpGridTopLeftChangeM

You only need to include in your script handlers for the messages that you specifically are interested in. In RRPG messages that are not handled are simply ignored.

M You can ignore the pID parameter if a stack has only one grid.

39

Virtual Mode GridUsing a grid in virtual mode allows you to have many more rows and columns than is possible when the grid stores the contents of each cell. The RRPG normally stores the data for the cells in the grid. In the normal mode, you typically send the data to the grid with either rrpGridSetDataFromHTML or rrpGridSetDataFromText where the data is stored in a data structure maintained by rrpGrid.rev.

In the normal mode, your application can react to changes made in the grid with the callback handlers from the previous chapter, or the application calls a handler like rrpGridGetDataAsHTML after all the changes are made. This flow of data to and from the grid is easy to script, but there is a practical limit to the size of the internal data structure that the grid can maintain.

M While multi-gigabyte systems with 32 bit and 64 bit processors allow for large data structures in LiveCode, there are practical limits after which the speed of the grid deteriorates significantly. The limit varies with the type of data in the grid and the resources of your system.

To remove such a limitation a virtual mode grid does not store the contents of all the cells. Instead in virtual mode, the grid sends two messages to your stack when a cell is displayed. One message gets the contents of the cell as plain text, and the other message to get the attributes. Messages are only sent for the visible cells.

What this means, for example, is that if a grid has 1,000,000,000 rows but only 50 rows are visible at a time, then only the visible rows require messages to be sent. If the user moves the cursor to the last row, the intervening 999999900 rows are not loaded and the grid only sends messages to request the contents of the cells in the last 50 rows.

This virtual mode allows very large grids, but there is an overhead for each message sent for each visible cell. So there is a trade-off, virtual mode allows more cells, but the grid will operate slower than a smaller grid that stores all the data.

M The RRPG sends the messages below when the cVirtualMode property is set to true. Unlike the callback functions in the previous chapter all four of these handlers must be defined in your stack, otherwise an error occurs when using virtual mode.

40

The virtual mode messages sent by the RRPG and when they occur are:

● rrpGridGetCellM called when in virtual mode to get the text ofa cell

● rrpGridGetFormatM called when in virtual mode to get the attributes of a cell

● rrpGridSetCellM called when in virtual mode to store the textof a cell after it has been edited

● rrpGridSetFormatM called when in virtual mode to store the attributes of a cell after it has been changed

In each case the message ends with the letter M as a reminder that these are not handlers that you can call, but are instead messages that your own application must respond to.

These messages are sent to the same stack that contains the grid. The actual handlers that you can put in your stack to respond to the messages are not documented in the Handler Reference because they are not called in the RRPG and are instead listed here showing how they should be scripted and the parameters they accept.

on rrpGridGetCellM pRow, pCol, pID /* called when in virtual mode to get the text of a cell pRow is the row of the required cell pCol is the column of the required cell pID is the ID of grid frame must end with the return control structure to return text in the cell, replace the line below with your own */ return pRow && "," && pColend rrpGridGetCellMon rrpGridGetFormatM pRow, pCol, pID /* called when in virtual mode to get the formatting of a cell if the cell is not formatted, must return empty pRow is the row of the required cell pCol is the column of the required cell pID is the ID of grid frame must end with the return control structure to return formatting of the cell, replace the line below with your own */ return emptyend rrpGridGetFormatMon rrpGridSetCellM pRow, pCol, pText, pID /* called when in virtual mode to store the text of a cell after it has been edited pRow is the row of the required cell pCol is the column of the required cell pText is the new text of the cell pID is the ID of grid frame */end rrpGridSetCellM

41

on rrpGridSetFormatM pRow, pCol, pFormat, pID /* called when in virtual mode to store the formatting of a cell after it has been changed pRow is the row of the required cell pCol is the column of the required cell pFormat is the new format of the cell pID is the ID of grid frame */end rrpGridSetFormatM

M Remember, these handlers must be in the script of the stack that contains the grid.

Inserting or deleting rows or columns

When a grid is in virtual mode, handlers that insert or delete rows or columns will result in many messages being sent to the stack containing the grid, if the grid is large. The handlers listed below should be avoided if you have a virtual grid with many rows or columns. By many, grids with more than tens of thousands of rows or columns may be a problem.

rrpGridInsertAfterColrrpGridInsertBeforeColrrpGridInsertAfterRowrrpGridInsertBeforeRowrrpGridInsertColAfterCursorrrpGridInsertColBeforeCursorrrpGridInsertRowAfterCursorrrpGridInsertRowBeforeCursorrrpGridDeleteColAtCursorrrpGridDeleteRowAtCursorrrpGridDeleteColRegionrrpGridDeleteRowRegion

M If you have large virtual mode grid and need to use the handlers it is recommended that you carefully test the parts of your application that use these handlers to determine whether the performance is satisfactory.

42

Deploying Your Own ApplicationTo deploy or distribute your own application with the RRPG you must first purchase a License Key or Unlock Code. This can be done from the RunRevPlanet.com website, or from other approved vendors. You can visit the RunRevPlanet website for full details, but in summary, a License Key can be purchased with a credit card and the key is emailed to you.

If purchasing from another vendor, the process may be slightly different and you may have an Unlock Code but the end result is the same, you can deploy or distribute your own application with the RRPG.

M Without a valid key you are not entitled to distribute standalone applications that use rrpGrid.rev and an application without a valid key will not work correctly.

Depending on whether you have a license name and key or an unlock code, follow the appropriate section next to find out how to use them in your standalone applications.

Setting the unlock code

If you have purchased a developer's license from another vendor you will have a single unlock code that allows RRPG to function fully in a standalone application, one extra line must be added your scripts. This line is normally where you initialize your application and may be in the openStack handler. Below is a sample of the line.

set the cUnlockCode of stack "rrpGrid" to "XXX-XXX-XXX-XXX-XXX-XXX-XXX-XXX"

Here the unlock property is set. The cUnlockCode property is set to a special character code that is unique and made available to you after the purchase is complete.

With this line in your applications that have a grid, you can make use of the RRPG without any further payments or royalties.

M The Unlock Code is for your use only and must not be made public or shared with others. This means that the script containing the code must be encrypted with a password. This requires setting the password property of the stack that sets these properties.

43

Setting this property needs to be done only in the initialization of your application.

Setting the license name and key

If you have purchased a License Key direct from RunRevPlanet, for the RRPG to function fully in a standalone application, two extra lines must be added your scripts. These lines are normally where you initialize your application and may be in the openStack handler. Below is a sample of these two lines.

set the cLicenseName of stack "rrpGrid" to "Scott McDonald"set the cLicenseKey of stack "rrpGrid" to "XXX-XXX-XXX-XXX-XXX-XXX"

Here the two licensing properties are set. The first, cLicenseName is the name that is registered when you purchase the License Key. The cLicenseKey property is a special character code that is unique and emailed to you after the purchase is completed.

With these two lines in your applications that have a grid, you can make use of the RRPG without any further payments or royalties.

M The License Key is for your use only and must not be made public or shared with others. This means that the script containing the key must be encrypted with a password. This requires setting the password property of the stack that sets these properties.

Setting these properties needs to be done only in the initialization of your application.

M When setting the cLicenceKey or cUnlockCode properties the code must be entered exactly as sent to you. For example, the hyphens are significant and must be included.

Acknowledgement

While not required, acknowledgement of the use of the “RunRevPlanet Grid” in the Readme file or the About box of your application is welcome.

44

Grid as a Substack

The RRPG can be distributed with your standalone application as a separate stack, rrpGrid.rev, or as a substack of your application. If included as a substack it becomes part of your mainstack file which is can be convenient, but when making the standalone application you may get an error message.

When choosing the Save as Standalone Application command in the File menu the message shown in Figure 22 may appear.

M To prevent this message in the General section of the Standalone Application Settings in the File menu, in the Advanced section the Select inclusions for the standalone application option must be selected. The stacks or script libraries required by your application must be selected manually.

In addition to any libraries that you application requires it is important to also include Cursors and Printing in your Standalone Application Settings as inFigure 23.

M After building a standalone, the stacks in the message path are cleared which means your stack with a grid will stop functioning correctly. Either close and open your stack to reset it, or manually start using rrpGrid in the Message Box.

45

Figure 22: Message when creating a standalone

Figure 23: Set Cursors as an inclusion

Error MessagesThe handlers in the RRPG can fail and report an error messages if the active grid cannot be determined when a handler is called. This can happen in applications with more than one grid.

M If there is only one grid on each stack, the RRPG automatically finds the grid on the stack when you call the handlers, but applications with more than one stack must call one of these handlers when switching stacks.

rrpGridSetActiveByIDrrpGridSetActiveByName

These handlers take a parameter of either the ID or name of the grid frame, and assuming a grid frame is found that matches the ID or name, it is made active.

If the ID or Name does not match a grid frame object on the stack, then one of these error messages is shown.

● Cannot find a grid frame object with the ID.● Cannot find a grid frame object with the Name.● Cannot find a grid frame object to initialize. The rrpGrid handlers must be

called from the stack that contains the grid.● When there is more than one rrpGrid on stack, rrpGridSetActiveByID or

rrpGridSetActiveByName must be called before using the grid handlers.

If this occurs, refer to the Multiple grids section of the Common Grid Actions chapter for more details of suggested scripts and handlers to prevent these error messages.

M It is important for every grid frame object in your application that shares a single copy of rrpGrid.rev to have a unique name.

If you build a standalone and do not turn on the Cursors inclusion, this error message is shown when the mouse pointer is moved over the column labels in your application.

● Cannot find cursor. Please make sure Cursors is an inclusion in the Standalone Application Settings.

Refer to the Deploying your Own Application chapter for more details on this error message.

46

Handler ReferenceThis chapter documents all the public handlers in the rrpGrid stack. Each entry begins with the name of the handler and on the right whether it is a command, function or property. Next is the declaration of the handler as found in the rrpGrid.rev stack. Properties do not show the declaration, only the name.

This is followed by a short description of the action of the handler, and if there are any parameters a list of them. Lastly, general comments about the handler are included.

M There are other handlers in the rrpGrid.rev stack, but these are “private” handlers, which while necessary for the operation of RRPG are only for internal use and should not be called from your own scripts. Calls to some of these private handlers may be examined with the Application Browser, but they should not be altered.

___________________________________________________________________cAlternateRowColor property

cAlternateRowColor

Set this property to change the color used when alternate rows are shaded.

Value: any color encoded in the HTML style that begins with a #Default: #F9F9FC

CommentThis property is only used when the cShadeAlternateRows property is set to true.

47

___________________________________________________________________cCacheVirtual property

cCacheVirtual

Set this property to true to speed up the operation of the grid when the virtual mode is turned on.

Value: true or falseDefault: false

CommentWhen this property is set to true, the contents of the visible cells are stored in a cache to speed up the the grid when scrolling. If the underlying data of your grid changes and this property is set to true, you can call the rrpGridEmptyCache command to refresh the visible cells. When using the grid in virtual mode, setting this property to true can significantly reduce the number of messages sent to the virtual callback handlers.

___________________________________________________________________cCellBorderColor property

cCellBorderColor

Set this property to change the color of the cell borders in the grid.

Value: any color encoded in the HTML style that begins with a #Default: #C0C0C0

CommentThis property sets the cell border color. Setting this property to the same color as the cCellColor property makes the borders invisible.

48

___________________________________________________________________cCellColor property

cCellColor

Set this property to change the background color of the cells that are not selected or at the cursor.

Value: any color encoded in the HTML style that begins with a #Default: #FFFFFF

CommentThis property sets the normal cell background color.

___________________________________________________________________cCellHeight property

cCellHeight

Set this property to change the height of the cells in the grid.

Value: an integer greater than or equal to 8 and less than half of the height of the gridDefault: 24

CommentChanging the cell height does not affect the size of the grid. For example, increasing the cell height reduces the number of visible rows in the grid. Partial rows cannot be displayed in the grid, so if the cell height is not an integer divisor of the height of the grid there will be a blank area at the bottom of the grid frame.

___________________________________________________________________cCellTextFont property

cCellTextFont

Set this property to change the font of the text in the cells in the grid.

Value: empty, or a valid font nameDefault: empty

CommentBy default this property is empty which means the font of the text in the cells is the same as the default font of the card.

49

___________________________________________________________________cCellTextSize property

cCellTextSize

Set this property to change the size of the text in the cells in the grid.

Value: empty or an integer specifying the text size in pointsDefault: empty

CommentChanging the text size does not affect the height of the cells. By default this property is empty which means the size of the text in the cells is the same as the stack text size.___________________________________________________________________cCellWidth property

cCellWidth

Set this property to change the width of the cells in the grid.

Value: an integer greater than or equal to 24 and less than half of the width of the gridDefault: 80

CommentChanging the cell width does not affect the size of the grid. For example, decreasing the cell width increases the number of visible columns in the grid. ___________________________________________________________________cColCount property

cColCount

Set this property to change the number of columns in the grid.

Value: an integer between than 1 and 1,000,000 inclusive.Default: 26

CommentThe column count is the total number of columns in the grid, which can be larger than the visible number of columns. If the number of columns is more than can be displayed in the grid, the horizontal scroll bar allows you to change the visible columns. For a grid with more than 1,000 columns the virtual mode may be required to ensure satisfactory speeds when scrolling.

50

___________________________________________________________________cColLabelAlignment property

cColLabelAlignment

Set this property to change the alignment of the column labels.

Value: a string of “left”, “center” or “right”Default: center

CommentBy default this property is center so the text in the column labels are centered

___________________________________________________________________cColLabelOffset property

cColLabelOffset

Set this property to fine tune the positioning of the column labels.

Value: four integers separated by commasDefault: 0,0,0,0

CommentNormally this property does not need to be changed, but if you need to adjust the position in of the column labels by a small amount you can do so with this property. The first two numbers affect the left and top location of the label respectively. For example if the first two numbers are -1and 1the column labels are moved to the left 1 pixel and down by 1 pixel. The third and fourth numbers affect the width and height of the column labels. For example if the third number is -1 the width of the labels is reduced by 1pixel.

51

___________________________________________________________________cColLabels property

cColLabels

Set this property to change the text shown on the column labels.

Value: a comma delimited list of labelsDefault: empty

CommentWhen this property is empty the grid uses alphabetical labels starting from A followed by B, and so on, like in a typical spreadsheet. Setting this property allows you to change the labels shown to different text. If the number of items in this property is less than the number of columns in the grid, the labels for the remaining columns will be the typical alphabetical labels.

___________________________________________________________________cColorMode property

cColorMode

Set in this property to change whether cells can be set to display individual colors.

Value: true or falseDefault: true

CommentBy default this property is true which means that cells can be set with individual colors with the rrpGridSetSelectionColor command. For a grid that has many visible rows and columns, allowing cells to be colored may reduce the speed of the grid when scrolling. If setting the color of the cells is not required, it is recommended that this property be set to false.

52

___________________________________________________________________cCursorBorderColor property

cCursorBorderColor

Set this property to change the color of the cell border at the cursor.

Value: any color encoded in the HTML style that begins with a #Default: #C0C0C0

CommentThis property sets the cursor cell border color.

___________________________________________________________________cCursorColor property

cCursorColor

Set this property to change the color of the cell at the cursor.

Value: any color encoded in the HTML style that begins with a #Default: #FFC06F

CommentThis property sets the cursor cell background color.

___________________________________________________________________cCursorRowColColor property

cCursorRowColColor

Set this property to change the color used when the cursor row or column is shaded.

Value: any color encoded in the HTML style that begins with a #Default: #FFF3E5

CommentThis property is only used when the cShadeCursorRow or cShadeCursorCol properties are set to true.

53

___________________________________________________________________cEditColor property

cEditColor

Set this property to change the color of the cell that is being edited.

Value: any color encoded in the HTML style that begins with a #Default: #FFFFFF

CommentThis property sets the cursor cell background color when the contents are being edited.

___________________________________________________________________cEditOnDoubleClick property

cEditOnDoubleClick

Set this property to true to allow a double click on a cell to start editing the cell.

Value: true or falseDefault: true

CommentBy default this property is true, but if you have a grid from an earlier version of rrpGrid explicitly setting this property to true may be necessary if you want double click editing to be enabled.

___________________________________________________________________cEditOnF2 property

cEditOnF2

Set this property to true to allow pressing of the F2 function key to start editing the cell.

Value: true or falseDefault: true

CommentBy default this property is true, but if you have a grid from an earlier version of rrpGrid explicitly setting this property to true may be necessary if you want F2 editing to be enabled.

54

___________________________________________________________________cEditOnKeyPress property

cEditOnKeyPress

Set this property to true to allow pressing of any key to start editing the cell.

Value: true or falseDefault: true

CommentIf this property is true and the cells in the grid have the focus, pressing any key with a normal character is entered into the current cell. If this property is false you must first press either the Return key, F2, or double click on a cell to start editing. By default this property is true, but if you have a grid from an earlier version of rrpGrid explicitly setting this property to true may be necessary if you want any key press to start the editing.

___________________________________________________________________cExpandMode property

cExpandMode

Set this property to true to allow the number of rows and columns in the grid to increase to fit the data

Value: true or falseDefault: false

CommentBy default this property is false, which means for example if you insert an empty row into the grid all of the rows below the inserted Row are moved down one row,but the number of rows in the grid does not increase which means that the last row of data is lost. As another example, if you paste data into the grid and the size of the grid is not large enough to contain all of the data, then the extra data that does not fit will not be pasted into the grid. By setting this property to true, in these cases the number of rows and columns in the grid automatically expands to fit the required data.

55

___________________________________________________________________cFrameVisible property

cFrameVisible

Set this property to false to hide the grid frame.

Value: falseDefault: true

CommentThe grid is contained within the bounds of a rectangle graphic on your stack. This is called the grid frame. Normally during design time it is useful for this frame to be visible to simplify resizing and selection of the grid. In a finished application you would normally sets this property to false.

___________________________________________________________________cFrozenColCount property

cFrozenColCount

Set this property to change the number of frozen columns in the grid.

Value: an integer less than the number of visible columns in the gridDefault: 0

CommentFrozen columns are columns in the grid that are in a fixed position and do not scroll off the left edge of the grid when scrolling to the right. Frozen columns are also displayed with a different color that is set with the cFrozenColor property.

___________________________________________________________________cFrozenColor property

cFrozenColor

Set this property to change the color of any frozen rows or columns

Value: any color encoded in the HTML style that begins with a #Default: #FFFFFF

CommentThis property sets the background color of any frozen cells. This property is only used when the cFrozenRowCount or cFrozenColCount properties are greater than zero.

56

___________________________________________________________________cFrozenColTextSize property

cFrozenColTextSize

Set this property to change the size of the text in the frozen column cells in the grid.

Value: empty or an integer specifying the text size in pointsDefault: empty

CommentChanging the text size does not affect the height of the frozen column cells. By default this property is empty which means the size of the text in the frozen column cells is the same as the stack text size.___________________________________________________________________cFrozenColWidths property

cFrozenColWidths

Set this property to change the widths of the frozen column cells in the grid.

Value: empty or comma delimited list of widths, For example, if there are three frozen columns this property could be set to 10,80,40 to make the cells in the first three columns be 10, 80 and 40 pixels wide respectively.Default: empty

CommentBy default this property is empty which means the widths of the frozen column cells are the same as the other cells in the grid. If there are no frozen columns this property has no effect. If there are less items in the list than the number of frozen columns, the remaining frozen column cells are the same as the cCellWidth.

57

___________________________________________________________________cFrozenRowCount property

cFrozenRowCount

Set this property to change the number of frozen rows in the grid.

Value: an integer less than the number of visible rows in the gridDefault: 0

CommentFrozen rows are rows in the grid that are in a fixed position and do not scroll off the top edge of the grid when scrolling downwards. Frozen rows are also displayed with a different color that is set with the cFrozenColor property.

___________________________________________________________________cFrozenRowHeights property

cFrozenRowHeights

Set this property to change the heights of the frozen row cells in the grid.

Value: empty or comma delimited list of heights, For example, if there are two frozen rows this property could be set to 40,40 to make the cells in the first two rows be 40 pixels high.Default: empty

CommentBy default this property is empty which means the heights of the frozen row cells are the same as the other cells in the grid. If there are no frozen rows this property has no effect. If there are less items in the list than the number of frozen rows, the remaining frozen row cells are the same as the cCellHeight.

58

___________________________________________________________________cFrozenRowTextSize property

cFrozenRowTextSize

Set this property to change the size of the text in the frozen row cells in the grid.

Value: empty or an integer specifying the text size in pointsDefault: empty

CommentChanging the text size does not affect the height of the frozen row cells. By default this property is empty which means the size of the text in the frozen row cells is the same as the stack text size.

___________________________________________________________________cHeightCanStretch property

cHeightCanStretch

Set this property to change whether the height of the grid can change when the size of the stack changes.

Value: true or falseDefault: true

CommentBy default this property is true which means the grid will resize its height if the stack is resized. For this property to have an effect there must be a resizeStack handler in your stack that calls the pvGridStackResize command. Refer to the Resizing a grid section of the Common Grid Actions chapter for more details.

59

___________________________________________________________________cHiliteCursorLabels property

cHiliteCursorLabels

Set this property to true to make the background color of the row and column labels change to indicate the position of the cursor.

Value: true or falseDefault: false

CommentThe background color of the row and column labels is the same color as the cCursorColor property.

___________________________________________________________________cHScrollVisible property

cHScrollVisible

Set this property to change whether the horizontal scroll bar is visible along the bottom edge of the grid

Value: true or falseDefault: true

CommentDepending on the height of the cells, setting this property to false may allow for an additional visible row. When the horizontal scroll bar is not visible, the grid can still be scrolled by using the left and right arrow keys.

___________________________________________________________________cLabelHeight property

cLabelHeight

Set this property to change the height (or hide) of the column labels.

Value: an integer between than 0 and half the height of the grid, inclusive.Default: 24

CommentSetting the height to 0 removes the column labels from the grid.

60

___________________________________________________________________cLabelStyle property

cLabelStyle

Set this property to change the style of the row and column labels.

Value: a valid button styleDefault: rectangle

CommentThe row and column labels are button objects. The default style of rectangle makes the grid look most like a typical spreadsheet, but you can change the style to change the look. This property does not check whether the value is valid, so be careful to only set it to a valid button style.

___________________________________________________________________cLabelTextSize property

cLabelTextSize

Set this property to change the size of the text in the labels in the grid.

Value: empty or an integer specifying the text size in pointsDefault: empty

CommentChanging the text size does not affect the height of the labels. By default this property is empty which means the size of the text in the labels is the same as the stack text size.

___________________________________________________________________cLabelWidth property

cLabelWidth

Set this property to change the width (or hide) of the row labels.

Value: an integer between than 0 and half the width of the grid, inclusive.Default: 40

CommentSetting the width to 0 removes the row labels from the grid.

61

___________________________________________________________________cLicenseKey property

cLicenseKey

Set this property with a valid key to use the RRPG in a standalone application.

Default: empty

CommentThe cLicenseKey property must be set to a valid key, otherwise the grid will not work in a standalone application and an error message is shown. This property must be a key that is associated with the cLicenseName property. Refer to the Deploying Your Own Application chapter for more details.

___________________________________________________________________cLicenseName property

cLicenseName

Set this property with the name used when the License Key was purchased to use the RRPG in a standalone application.

Default: empty

CommentThe cLicenseName property must be set to the name associated with the key in the cLicenseKey property, otherwise the grid will not work in a standalone application and an error message is shown.

___________________________________________________________________cMessageMode property

cMessageMode

Set this property to true to make the grid send messages when the user interacts with the grid.

Value: true or falseDefault: false

CommentOnly set this property to true if you have defined callback functions in your stack, because this mode may reduce the speed of the grid. Refer to the Callback Functions and Messages chapter for more details.

62

___________________________________________________________________cNoCursorColCount property

cNoCursorColCount

Set this property to change the number of columns in the grid that the cursor cannot move to which prevents the cells from being edited.

Value: an integer less than or equal to the number of frozen columns in the gridDefault: 0 or cFrozenColCount

CommentBy default this property is the same value as cFrozenColCount because normally the cells in the frozen columns cannot be edited. By setting this property to less than cFrozenColCount, the cells in the frozen columns can be edited.

___________________________________________________________________cNoCursorRowCount property

cNoCursorRowCount

Set this property to change the number of rows in the grid that the cursor cannot move to which prevents the cells from being edited.

Value: an integer less than or equal to the number of frozen rows in the gridDefault: 0 or cFrozenRowCount

CommentBy default this property is the same value as cFrozenRowCount because normally the cells in the frozen rows cannot be edited. By setting this property to less than cFrozenRowCount, the cells in the frozen rows can be edited.

63

___________________________________________________________________cPrintFooter property

cPrintFooter

Set this property to change the footer shown at the bottom of the page when printing the grid.

Value: empty or a string of textDefault: Page # of #

CommentThe # symbol is used as a “placeholder” for the two values. The first # has the page number substituted into it, and the second is the total number of pages. The footer does not require these symbols and can be any text that fits on a single line of a page.

___________________________________________________________________cPrintLabelColor property

cPrintLabelColor

Set this property to change the color of the row and column labels when printing the grid.

Value: any color encoded in the HTML style that begins with a #Default: #070707

CommentThe default background color is a shade of grey, but can be changed to make it lighter or darker or in color.

64

___________________________________________________________________cPrintLabelTextColor property

cPrintLabelTextColor

Set this property to change the color of the row and column label text when printing the grid.

Value: any color encoded in the HTML style that begins with a #Default: #000000

CommentThe default text color is black, but can be changed to make it contrast better if the cPrintLabelColor is changed.

___________________________________________________________________cReadOnly property

cReadOnly

Set this property to true to make the grid read only so that the cells cannot be edited.

Value: true or falseDefault: false

CommentThis property can be changed while the grid is active to change whether the cells can be edited. The data in a read only grid can still be changed with the rrpGridSet commands, this property only affects stops the users from editing the data with the keyboard.

65

___________________________________________________________________cReturnMovesCursor property

cReturnMovesCursor

Set this property to true to make pressing the return key move to the cell in the next row below when editing the grid.

Value: true or falseDefault: false

CommentThe default action when this property is false when pressing the return key is to end the editing and not move the cursor.

___________________________________________________________________cRowCount property

cRowCount

Set this property to change the number of rows in the grid.

Value: an integer between than 1 and 1,000,000 inclusive.Default: 100

CommentThe row count is the total number of rows in the grid, which can be larger than the visible number of rows. If the number of rows is more than can be displayed in the grid, the vertical scroll bar allows you to change the visible rows. For a grid with more than 100,000 rows the virtual mode may be required to ensure satisfactory speeds when scrolling.

66

___________________________________________________________________cRowLabelAlignment property

cRowLabelAlignment

Set this property to change the alignment of the row labels.

Value: a string of “left”, “center” or “right”Default: center

CommentBy default this property is center so the text in the row labels are centered

___________________________________________________________________cRowLabelOffset property

cRowLabelOffset

Set this property to fine tune the positioning of the row labels.

Value: four integers separated by commasDefault: 0,0,0,0

CommentNormally this property does not need to be changed, but if you need to adjust the position in of the row labels by a small amount you can do so with this property. The first two numbers affect the left and top location of the label respectively. For example if the first two numbers are 1and 1the column labels are moved to the right 1 pixel and down by 1 pixel. The third and fourth numbers affect the width and height of the column labels. For example if the fourth number is 2 the height of the labels is increased by 2 pixels.

67

___________________________________________________________________cRowLabels property

cRowLabels

Set this property to change the text shown on the row labels.

Value: a comma delimited list of labelsDefault: empty

CommentWhen this property is empty the grid uses numerical row labels starting from 1 followed by 2, and so on, like in a typical spreadsheet. Setting this property allows you to change the labels shown to different text. If the number of items in this property is less than the number of rows in the grid, the labels for the remaining rows will be the numbered labels.

___________________________________________________________________cScrollAutoVisible property

cScrollAutoVisible

Set this property to true to make either scrollbar hide itself when it is not needed

Value: true or falseDefault: false

CommentWhen this property is set to true, the scrollbars are only shown if there are rows or columns that are no visible because the size of the data is larger than the visible number of rows or columns.

68

___________________________________________________________________cScrollWidth property

cScrollWidth

Set this property to change the width of the horizontal and vertical scroll bars

Value: an integer between than 10 and 100 inclusive.Default: 20

CommentThe default value of 20 produces scrollbars of a typical size. Setting this property to 0 is not the recommended way to hide the scroll bars. Instead the cHScrollVisible and cVScrollVisible properties should be used to hide the scrollbars. This property does not check whether the value is sensible, so be careful to only set it to a reasonable value.

___________________________________________________________________cSelectionColor property

cSelectionColor

Set this property to change the color of the selected cells

Value: any color encoded in the HTML style that begins with a #Default: #E4E4E8

CommentThis property sets the selected cell background color.

___________________________________________________________________cShadeAlternateRows property

cShadeAlternateRows

Set this property to change whether the alternate rows are shaded.

Value: true or falseDefault: true

CommentThe background color of the shaded rows is the color set in the cAlternateRowCol property.

69

___________________________________________________________________cShadeCursorCol property

cShadeCursorCol

Set this property to change whether the column with the cursor is shaded.

Value: true or falseDefault: false

CommentThe background color of the cursor column is the color set in the cCursorRowColColor property.

___________________________________________________________________cShadeCursorRow property

cShadeCursorRow

Set this property to change whether the row with the cursor is shaded.

Value: true or falseDefault: false

CommentThe background color of the cursor row is the color set in the cCursorRowColColor property.

___________________________________________________________________cUnlockCode property

cUnlockCode

Set this property with a valid code to use the RRPG in a standalone application.

Default: empty

CommentThe cUnlockCode property must be set to a valid code, otherwise the grid will not work in a standalone application and an error message is shown. Refer to the Deploying Your Own Application chapter for more details. This property is an alternative to using the cLicenseKey and cLicenseName properties.

70

___________________________________________________________________cVirtualMode property

cVirtualMode

Set this property to true to enable the virtual mode.

Value: true or falseDefault: false

CommentIn virtual mode the grid does not store the data of the grid, instead you define a set of callback functions in your stack that the grid calls each time it needs to get or set data in the grid. A grid in virtual mode is able to display up to 1,000,000,000,000 cells but at the expense of more complex scripting in your stack and possibly lower performance. Refer to the Virtual Mode Grids chapter for more details.

___________________________________________________________________cVScrollVisible property

cVScrollVisible

Set this property to change whether the vertical scroll bar is visible along the right edge of the grid

Value: true or falseDefault: true

CommentDepending on the width of the cells, setting this property to false may allow for an additional visible column. When the vertical scroll bar is not visible, the grid can still be scrolled by using the up and down arrow keys.

71

___________________________________________________________________cWidthCanStretch property

cWidthCanStretch

Set this property to change whether the width of the grid can change when the size of the stack changes.

Value: true or falseDefault: true

CommentBy default this property is true which means the grid will resize its width if the stack is resized. For this property to have an effect there must be a resizeStack handler in your stack that calls the pvGridStackResize command. Refer to the Resizing a grid section of the Common Grid Actions chapter for more details.

___________________________________________________________________cWrapCursorCol property

cWrapCursorCol

Set this property to change whether the cursor will “wrap around” to the next row when the cursor reaches the first or last column of the grid.

Value: true or falseDefault: false

CommentBy default this property is false which means that the cursor does not wrap.

___________________________________________________________________cWrapCursorRow property

cWrapCursorRow

Set this property to change whether the cursor will “wrap around” to the next column when the cursor reaches the first or last row of the grid.

Value: true or falseDefault: false

CommentBy default this property is false which means that the cursor does not wrap.

72

___________________________________________________________________rrpGridBeginEdit command

command rrpGridBeginEditPuts the current cell into the edit mode

CommentThis has the same effect as pressing the return key or double clicking on the cell so the text cursor appears to allow editing.

___________________________________________________________________rrpGridCancelEdit command

command rrpGridCancelEditCancels the editing of a cell.

CommentThis cancels the editing of the cell and has the same effect as pressing the escape key where any changes to the cell are ignored and the contents of the cell revert to what it was before the edit began.

___________________________________________________________________rrpGridCancelPendingCursor command

command rrpGridCancelPendingCursorCancels any changes to the cursor position.

CommentWhen there are multiple changes to the position of the cursor within a handler, the changes in position may be cached to increase performance. In some cases, this may mean that an earlier setting of the cursor will be the last one set. To prevent this, calling this command before the last call to one of the rrpGridSetCursor commands remove all the pending cursor positions, and only the last will be set.

73

___________________________________________________________________rrpGridClearRegion command

command rrpGridClearRegion pRow1, pCol1, pRow2, pCol2Clears the text and formatting in the cells defined by the region specified in the parameters.

ParameterspRow1: the row that specifies the top left corner of the regionpCol1: the column that specifies the top left corner of the regionpRow2: the row that specifies the bottom right corner of the regionpCol2: the column that specifies the bottom right corner of the region

CommentThis command clears the contents of the cells without affecting the position of the cursor.___________________________________________________________________rrpGridClearSelected command

command rrpGridClearSelectedClears the text and formatting in the selected cells.

CommentThis command clears the cursor cell if there is no region of cells selected.

___________________________________________________________________rrpGridConvertColor function

function rrpGridConvertColor pColorReturnsa color encoded in the HTML style that begins with from a color made up of three integers which are RGB values

ParameterspColor: the RGB color as three comma-separated integers between zero and 255

CommentThis function is useful when setting the color properties if the color is not already in the HTML style

74

___________________________________________________________________rrpGridCopyAsText command

command rrpGridCopyAsText pIncludeLabelsCopies only the text of the entire to the clipboard with the option of including the row and column labels

ParameterspIncludeLabels: true or false, true means the labels are included in the text

CommentThis command copies only the text of the grid to the clipboard and so loses any formatting applied to those cells. These cells are copied as one line per row with the tab character delimiting the columns. If the rrpGridSetDataAt, rrpGridSetDataFromText or rrpGridPasteAtCursor handler has been previously called with comma delimited data, then the comma character is used as the column delimiter.

___________________________________________________________________rrpGridCopySelectedAsHTML command

command rrpGridCopySelectedAsHTMLCopies the text and formatting of the selected cells to the clipboard.

CommentThis command uses standard HTML tags such as <table> to copy the selected cells to the clipboard without any loss of information.

___________________________________________________________________rrpGridCopySelectedAsText command

command rrpGridCopySelectedAsTextCopies only the text of the selected cells to the clipboard.

CommentThis command copies only the text of the selected cells to the clipboard and so loses any formatting applied to those cells. These cells are copied as one line per row with the tab character delimiting the columns. If the rrpGridSetDataAt, rrpGridSetDataFromText or rrpGridPasteAtCursor handler has been previously called with comma delimited data, then the comma character is used as the column delimiter.

75

___________________________________________________________________rrpGridDeleteColAtCursor command

command rrpGridDeleteColAtCursorDeletes the column of cells that the cursor is in.

CommentThe deleted cells are removed from the grid and the contents of the grid to the right of the cursor are shifted to the left to fill the deleted column.

___________________________________________________________________rrpGridDeleteColRegion command

command rrpGridDeleteColRegion pCol1, pCol2Deletes one or more columns of cells as specified by the parameters.

ParameterspCol1: the column that specifies the first column of the regionpCol2: the column that specifies the last column of the region

CommentThe deleted columns are removed from the grid and the contents of the grid to the right of the deleted region is shifted to the left to fill the deleted columns. The region includes all of the rows in the grid. The pCol2 parameter is optional, and if omitted is only the column at pCol1 is deleted.

___________________________________________________________________rrpGridDeleteRowAtCursor command

command rrpGridDeleteRowAtCursorDeletes the row of cells that the cursor is in.

CommentThe deleted cells are removed from the grid and the contents of the grid below the cursor are shifted up to fill the deleted row.

76

___________________________________________________________________rrpGridDeleteRowRegion command

command rrpGridDeleteRowRegion pRow1, pRow2Deletes one or more rows of cells as specified by the parameters.

ParameterspRow1: the row that specifies the first row of the regionpRow2: the row that specifies the last row of the region

CommentThe deleted rows are removed from the grid and the contents of the grid below the deleted region is shifted up to fill the deleted rows. The region includes all of the columns in the grid. The pRow2 parameter is optional, and if omitted is only the column at pRow1 is deleted.

___________________________________________________________________rrpGridEmptyCache command

command rrpGridEmptyCacheEmpties the contents of the cache when the grid is in virtual mode.

CommentThis command can be used when the grid is running in virtual mode and you want all of these cells to be refreshed. This is useful if the underlying data has changed. This command has no effect when the grid is not in virtual mode.

___________________________________________________________________rrpGridGetActiveID function

function rrpGridGetActiveIDReturnsthe ID of the active grid frame

CommentEvery grid is attached to a graphic object called the grid frame, this function is useful if you have more than one grid in a stack and need to determine which one is currently controlled by the RRPG commands. Refer to the refer to the Multiple grids section of the Common Grid Actions chapter for more details.

77

___________________________________________________________________rrpGridGetActiveName function

function rrpGridGetActiveNameReturnsthe Name of the active grid frame

CommentEvery grid is attached to a graphic object called the grid frame, this function is useful if you have more than one grid in a stack and need to determine which one is currently controlled by the RRPG commands. Refer to the refer to the Multiple grids section of the Common Grid Actions chapter for more details.

___________________________________________________________________rrpGridGetAlignmentAt function

function rrpGridGetAlignmentAt pRow, pColReturnsthe alignment of the text in cell specified by the parameters as a string of “left”, “center” or “right”

ParameterspRow: the row of the cellpCol: the column of the cell

CommentIf the cell has no formatting “left” is returned. If the cell specified is outside the bounds of the grid, empty is returned.

___________________________________________________________________rrpGridGetCellAt function

function rrpGridGetCellAt pRow, pColReturnsthe text of the cell specified by the parameters

ParameterspRow: the row of the cellpCol: the column of the cell

CommentIf the cell specified is outside the bounds of the grid, empty is returned.

78

___________________________________________________________________rrpGridGetCellWidth function

function rrpGridGetCellWidthReturnsthe width of the cells in the grid in pixel units

CommentIn RRPG all cells have the same width.

___________________________________________________________________rrpGridGetColCount function

function rrpGridGetColCountReturnsthe number of columns in the grid

CommentThis function is a convenience for accessing the property of the grid frame object. The column count is the total number of columns in the grid, which can be larger than the visible number of columns. If the number of columns is more than can be displayed in the grid, the horizontal scroll bar allows you to change the visible columns. For a grid with more than 1,000 columns the virtual mode may be required to ensure satisfactory speeds when scrolling.

___________________________________________________________________rrpGridGetColLabels function

function rrpGridGetColLabelsReturnsempty or a comma delimited list of labels

CommentThis function is a convenience for accessing the property of the grid frame object. If the labels are empty, column labels of A, B and so on are used in the grid.

79

___________________________________________________________________rrpGridGetColorAt function

function rrpGridGetColorAt pRow, pColReturnsthe color of the cell specified by the parameters

ParameterspRow: the row of the cellpCol: the column of the cell

CommentIf the cell specified has no color or is outside the bounds of the grid, empty is returned.

___________________________________________________________________rrpGridGetCursor function

function rrpGridGetCursorReturnsthe position of the cursor as two comma-separated integers specifying the row and column

CommentThe numbering of the cells starts from 1,1 in the top left corner. If only the row or column of the cursor is required, use the rrpGridGetCursorRow or rrpGridGetCursorCol functions instead.

___________________________________________________________________rrpGridGetCursorCol function

function rrpGridGetCursorColReturnsthe column of the cursor as an integer

CommentThe first column is numbered 1.

80

___________________________________________________________________rrpGridGetCursorRow function

function rrpGridGetCursorRowReturnsthe row of the cursor as an integer

CommentThe first row is numbered 1.

___________________________________________________________________rrpGridGetDataAsHTML function

function rrpGridGetDataAsHTML pTrimReturnsthe contents of the entire grid as standard HTML tags such as <table> without any loss of information.

ParameterspTrim: true to remove empty rows and columns from the end of the data

CommentThe pTrim parameter can be omitted if the data is not to be trimmed.

___________________________________________________________________rrpGridGetDataAsText function

function rrpGridGetDataAsTextReturnsonly the text contents of the entire grid as lines of tab delimited text

ParameterspTrim: specify whether to remove empty rows and columns from the end of the data

CommentThe pTrim parameter can be omitted if the data is not to be trimmed. If the rrpGridSetDataAt, rrpGridSetDataFromText or rrpGridPasteAtCursor handler has been previously called with comma delimited data, then the comma character is used as the column delimiter.

81

___________________________________________________________________rrpGridGetDataSize function

function rrpGridGetDataSizeReturnsThe number of rows and columns in the grid as a comma delimited pair

CommentThe size of the grid is the number of data rows and columns which may be larger than the number of visible rows and columns. This function is the same as rrpGridGetSize.

___________________________________________________________________rrpGridGetEditing function

function rrpGridGetEditingReturnstrue if a cell is currently being edited

CommentThis function returns false unless a cell has the edit cursor in it to allow editing of the cell.

___________________________________________________________________rrpGridGetFormatAt function

function rrpGridGetFormatAt pRow, pColReturnsthe encoded format of the cell specified by the parameters

ParameterspRow: the row of the cellpCol: the column of the cell

CommentThe format of a cell is stored as an encoded string. To get the format in a more readable way use the rrpGridGetAlignmentAt, rrpGridGetColorAt and rrpGridGetStyleAt functions. If the cell specified has no formatting or is outside the bounds of the grid, empty is returned.

82

___________________________________________________________________rrpGridGetFrozenColCount function

function rrpGridGetFrozenColCountReturnsthe number of frozen columns in the grid

CommentThis function is a convenience for accessing the property of the grid frame object. The frozen column count is the number of frozen columns in the grid, which must be less than the visible number of columns.

___________________________________________________________________rrpGridGetFrozenRowCount function

function rrpGridGetFrozenRowCountReturnsthe number of frozen rows in the grid

CommentThis function is a convenience for accessing the property of the grid frame object. The frozen row count is the number of frozen rows in the grid, which must be less than the visible number of rows.

___________________________________________________________________rrpGridGetHiliteCursorLabels function

function rrpGridGetHiliteCursorLabelsReturnsthe state of the cHiliteCursorLabels property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

83

___________________________________________________________________rrpGridGetHScrollVisible function

function rrpGridGetHScrollVisibleReturnsthe state of the cHScrollVisible property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

___________________________________________________________________rrpGridGetModified function

function rrpGridGetModifiedReturnsthe state of the cModified property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

___________________________________________________________________rrpGridGetNoCursorColCount function

function rrpGridGetNoCursorColCountReturnsthe state of the cNoCursorColCount property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

___________________________________________________________________rrpGridGetNoCursorRowCount function

function rrpGridGetNoCursorRowCountReturnsthe state of the cNoCursorRowCount property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

84

___________________________________________________________________rrpGridGetPropsAsText function

function rrpGridGetPropsAsText pOnlyPublicReturnsa list of the grid properties and the value of each value

ParameterspOnlyPublic: true if only the public properties are to be returned

CommentThe function is useful for streaming and storing the state of the grid in a file or for in a property inspector. The format of the list can be read by the rrpGridSetPropsFromText command.

___________________________________________________________________rrpGridGetRectangle function

function rrpGridGetRectangleReturnsthe rectangle of the actual grid inside the grid frame

CommentThe function is returns the rectangle of the actual labels, cells and scrollbars of the grid. This may be smaller than the rectangle of the grid frame object because only whole rows are part of the grid, which means there may be a blank area between the last row and the bottom of the grid frame object.

85

___________________________________________________________________rrpGridGetRegionAsHTML function

function rrpGridGetRegionAsHTML pRow1, pCol1, pRow2, pCol2

Returnsthe region of cells as standard HTML tags such as <table> without any loss of information

ParameterspRow1: the row that specifies the top left corner of the regionpCol1: the column that specifies the top left corner of the regionpRow2: the row that specifies the bottom right corner of the regionpCol2: the column that specifies the bottom right corner of the region

CommentIf the region specified is larger than the grid then the entire grid is returned.

___________________________________________________________________rrpGridGetRegionAsText function

function rrpGridGetRegionAsText pRow1, pCol1, pRow2, pCol2

Returnsonly the text contents of the region of cells as as lines of tab delimited text

ParameterspRow1: the row that specifies the top left corner of the regionpCol1: the column that specifies the top left corner of the regionpRow2: the row that specifies the bottom right corner of the regionpCol2: the column that specifies the bottom right corner of the region

CommentIf the region specified is larger than the grid then the entire grid is returned.

86

___________________________________________________________________rrpGridGetRowCount function

function rrpGridGetRowCountReturnsthe number of rows in the grid

CommentThis function is a convenience for accessing the property of the grid frame object. The row count is the total number of rows in the grid, which can be larger than the visible number of rows. If the number of rows is more than can be displayed in the grid, the vertical scroll bar allows you to change the visible rows. For a grid with more than 100,000 rows the virtual mode may be required to ensure satisfactory speeds when scrolling.

___________________________________________________________________rrpGridGetRowLabels function

function rrpGridGetRowLabelsReturnsempty or a comma delimited list of labels

CommentThis function is a convenience for accessing the property of the grid frame object. If the labels are empty, row labels of 1, 2 and so on are used in the grid.

___________________________________________________________________rrpGridGetSelectedAsHTML function

function rrpGridGetSelectedAsHTML pIncludeFrozenReturnsthe selected cells as standard HTML tags such as <table> without any loss of information

ParameterspIncludeFrozen: true if frozen rows or columns are to be included in the returned HTML

CommentIf the frozen rows or columns are to be included the selected cells must be immediately adjacent to the frozen cells.

87

___________________________________________________________________rrpGridGetSelectedAsText function

function rrpGridGetSelectedAsText pIncludeFrozenReturnsonly the text contents of the selected cells as as lines of tab delimited text

ParameterspIncludeFrozen: true if frozen rows or columns are to be included in the returned HTML

CommentIf the frozen rows or columns are to be included the selected cells must be immediately adjacent to the frozen cells.

___________________________________________________________________rrpGridGetSelectedRegion function

function rrpGridGetSelectedRegionReturnsa list of 4 items row1, col1, row2, col2, which are the top left and bottom right corners of the selected region.

CommentThe first pair of numbers in the list are the top left corner, and the last pair of numbers are the bottom right corner.

___________________________________________________________________rrpGridGetShadeAlternateRows function

function rrpGridGetShadeAlternateRowsReturnsthe state of the cShadeAlternateRows property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

88

___________________________________________________________________rrpGridGetShadeCursorCol function

function rrpGridGetShadeCursorColReturnsthe state of the cShadeCursorCol property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

___________________________________________________________________rrpGridGetShadeCursorRow function

function rrpGridGetShadeCursorRowReturnsthe state of the cShadeCursorRow property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

___________________________________________________________________rrpGridGetSize function

function rrpGridGetSizeReturnsThe number of rows and columns in the grid as a comma delimited pair

CommentThe size of the grid is the number of data rows and columns which may be larger than the number of visible rows and columns.

89

___________________________________________________________________rrpGridGetStyleAt function

function rrpGridGetStyleAt pRow, pColReturnsthe style of the text in cell specified by the parameters as a string with “plain”, “bold” or “italic”

ParameterspRow: the row of the cellpCol: the column of the cell

CommentIf the cell specified is outside the bounds of the grid, empty is returned.

___________________________________________________________________rrpGridGetTopLeft function

function rrpGridGetTopLeftReturnsa list of 2 items which are the row and column of the cell in the top left corner of the grid

CommentThe first number in the list is the row and the second the column.

___________________________________________________________________rrpGridGetVirtualMode function

function rrpGridGetVirtualModeReturnsthe state of the cVirtualMode property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

90

___________________________________________________________________rrpGridGetVScrollVisible function

function rrpGridGetVScrollVisibleReturnsthe state of the cVScrollVisible property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

___________________________________________________________________rrpGridGetWrapAt function

function rrpGridGetWrapAt pRow, pColReturnstrue if the cell specified by the parameters can wrap the text of the cell over more than one line

ParameterspRow: the row of the cellpCol: the column of the cell

CommentBy default a cell shows its contents as a single line of text. If the length of the text is too long for the cell, the text that does not fit is truncated and not shown. If the cell is set to wrap, The text is wrapped onto a new line at the word breaks, i.e. where there is a space.

___________________________________________________________________rrpGridGetWrapCursorCol function

function rrpGridGetWrapCursorColReturnsthe state of the cWrapCursorCol property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

91

___________________________________________________________________rrpGridGetWrapCursorRow function

function rrpGridGetWrapCursorRowReturnsthe state of the cWrapCursorRow property of the grid

CommentThis function is a convenience for accessing the property of the grid frame object.

___________________________________________________________________rrpGridGetHasSelection function

function rrpGridGetHasSelectionReturnstrue if the there are selected cells in the grid

CommentIf there is no selection this function returns false. Selected cells are those that are highlighted either by the user do a click and drag or from the grid commands.

___________________________________________________________________rrpGridInsertAfterCol command

command rrpGridInsertAfterCol pColAdds a new column to the grid after the column specified in the parameter.

ParameterspCol: the column that the new column is inserted after

CommentThe contents of the grid to the right of the column is shifted across to make room for the inserted column. If the cExpandMode property is set to true, the number of columns in the grid is increased by one.

92

___________________________________________________________________rrpGridInsertAfterRow command

command rrpGridInsertAfterRow pRowAdds a new row to the grid after the row specified in the parameter.

ParameterspRow: the row that the new row is inserted after

CommentThe contents of the grid below the row is shifted down to make room for the inserted row. If the cExpandMode property is set to true, the number of rows in the grid is increased by one.

___________________________________________________________________rrpGridInsertBeforeCol command

command rrpGridInsertBeforeCol pColAdds a new column to the grid before the column specified in the parameter.

ParameterspCol: the column that the new column is inserted before

CommentThe contents of the grid to the right of the column is shifted across to make room for the inserted column. If the cExpandMode property is set to true, the number of columns in the grid is increased by one.

___________________________________________________________________rrpGridInsertBeforeRow command

command rrpGridInsertBeforeRow pRowAdds a new row to the grid before the row specified in the parameter.

ParameterspRow: the row that the new row is inserted before

CommentThe contents of the grid below the row is shifted down to make room for the inserted row. If the cExpandMode property is set to true, the number of rows in the grid is increased by one.

93

___________________________________________________________________rrpGridInsertColAfterCursor command

command rrpGridInsertColAfterCursorAdds a new column to the grid after the column of the cursor

CommentThe contents of the grid to the right of the column is shifted across to make room for the inserted column. If the cExpandMode property is set to true, the number of columns in the grid is increased by one.

___________________________________________________________________rrpGridInsertColBeforeCursor command

command rrpGridInsertColBeforeCursorAdds a new column to the grid before the column of the cursor

CommentThe contents of the grid to the right of the column is shifted across to make room for the inserted column. If the cExpandMode property is set to true, the number of columns in the grid is increased by one.

___________________________________________________________________rrpGridInsertRowAfterCursor command

command rrpGridInsertRowAfterCursorAdds a new row to the grid after the row of the cursor

CommentThe contents of the grid below the row is shifted down to make room for the inserted row. If the cExpandMode property is set to true, the number of rows in the grid is increased by one.

94

___________________________________________________________________rrpGridInsertRowBeforeCursor command

command rrpGridInsertRowBeforeCursorAdds a new row to the grid before the row of the cursor

CommentThe contents of the grid below the row is shifted down to make room for the inserted row. If the cExpandMode property is set to true, the number of rows in the grid is increased by one.

___________________________________________________________________rrpGridPasteAtCursor command

command rrpGridPasteAtCursorPastes the contents of the clipboard into the grid starting from the position of the cursor.

CommentThis command pastes the data into the grid only if it is in the same format as either the rrpGridGetDataAsHTML and rrpGridGetDataAsText functions. In other words, the data on the clipboard should either be a HTML table or lines of tab delimited text. If the cExpandMode property is set to true, the number of rows and columns in the grid will increase if necessary to fit the contents of the clipboard.

___________________________________________________________________rrpGridPrint command

command rrpGridPrint pRow1, pCol1, pRow2, pCol2Prints the region of the grid specified by the parameters.

ParameterspRow1: the row that specifies the top left corner of the regionpCol1: the column that specifies the top left corner of the regionpRow2: the row that specifies the bottom right corner of the regionpCol2: the column that specifies the bottom right corner of the region

CommentThis command assumes that you have already set the printerName property before calling this command.

95

___________________________________________________________________rrpGridRefresh command

command rrpGridRefresh pDataOnlyRedraws the grid to update its appearance.

ParameterspDataOnly: True or false, when true only the contents of the visible cells are redrawn, otherwise the entire grid is redrawn

CommentThis command can be used to ensure the grid is completely up-to-date with any changes in the underlying data or its properties.

___________________________________________________________________rrpGridRefreshCell command

command rrpGridRefreshCell pRow, pColRedraws a single cell in the grid to update its appearance.

ParameterspRow: the row of the cell to be refreshedpCol: the column of the cell to be refreshed

CommentThis command can be used to ensure a cell is completely up-to-date with any changes in the underlying data or its properties.

___________________________________________________________________rrpGridRefreshIsPending function

function rrpGridRefreshIsPendingReturnstrue if the refresh pending flag has previously been set by the rrpGridSetRefreshPending command

CommentThis function is used in conjunction with the rrpGridSetRefreshPending command to allow your application to keep track of whether the grid needs refreshing.

96

___________________________________________________________________rrpGridRemoveSelection command

command rrpGridRemoveSelectionRemoves the selection, if any, from the grid so only the cursor cell is selected.

CommentThis command redraws the grid to remove the selection from the cells.

___________________________________________________________________rrpGridReset command

command rrpGridResetResets the grid to its default appearance and behavior.

CommentThis command is useful after experimenting with the properties of the grid and you want to return everything to its initial state.

___________________________________________________________________rrpGridResetActive command

command rrpGridResetActiveResets the grid that RRPG is handling as the active grid.

CommentAfter a call to this command, a call to either rrpGridSetActiveByID or rrpGridSetActiveByName is necessary if you have more than one grid on your stacks to make RRPG work with the correct grid.

M This command is called in the suspendStack handler of rrpGrid.rev, so if your stack handles this message, be sure to pass the message so it is also handled by RRPG.

97

___________________________________________________________________rrpGridResetColors command

command rrpGridResetColorsResets the grid to its default colors.

CommentThis command is useful after experimenting with the color properties of the grid and you want to return everything to its initial state.

___________________________________________________________________rrpGridSelectAll command

command rrpGridSelectAllSelect all the cells in the grid.

CommentThis command does not select any frozen cells.

___________________________________________________________________rrpGridSelectCol command

command rrpGridSelectColSelect all cells in the cursor column of the grid.

CommentThis command does not select any frozen cells.

___________________________________________________________________rrpGridSelectRow command

command rrpGridSelectRowSelect all cells in the cursor row of the grid.

CommentThis command does not select any frozen cells.

98

___________________________________________________________________rrpGridSetActiveAuto command

command rrpGridSetActiveAutoSets the grid on the current stack as the active grid affected by the RRPG commands and functions.

CommentYou must use this command if you have more than one grid in your application. The commands and functions in RRPG always work on the active grid, so if there is more than one grid you need to set the active one before accessing it with a script. This command is convenient if you only have one grid on the current stack. If there is more than one grid on the current stack you must instead use either the rrpGridSetActiveByID or rrpGridSetActiveByName command to specify the active grid.

___________________________________________________________________rrpGridSetActiveByID command

command rrpGridSetActiveByID pID

Sets the grid on the current stack with the ID as the active grid affected by the RRPG commands and functions.

ParameterspID: The ID of the grid frame graphic object

CommentYou must use this command if you have more than one grid on the current stack. The commands and functions in RRPG always work on the active grid, so if there is more than one grid you need to set the active one before accessing it with a script.

99

___________________________________________________________________rrpGridSetActiveByName command

command rrpGridSetActiveByName pNameSets the grid on the current stack with the name as the active grid affected by the RRPG commands and functions.

ParameterspName: The name of the grid frame graphic object

CommentYou must use this command if you have more than one grid on the current stack. The commands and functions in RRPG always work on the active grid, so if there is more than one grid you need to set the active one before accessing it with a script.

___________________________________________________________________rrpGridSetAlternateRowColor command

command rrpGridSetAlternateRowColor pColorSets the cAlternateRowColor property of the grid that specifies the color used when alternate rows are shaded.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

100

___________________________________________________________________rrpGridSetCacheVirtual command

command rrpGridSetCacheVirtual pEnableSets the cCacheVirtual property of the grid that specifies whether a cache is used to speed up the operation of the grid when the virtual mode is turned on.

ParameterspEnable: true or false, if true a cache is used in virtual mode

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. When this property is set to true, the contents of the visible cells are stored in a cache to speed up the the grid when scrolling. If the underlying data of your grid changes and this property is set to true, you can call the rrpGridEmptyCache command to refresh the visible cells. When using the grid in virtual mode, setting this property to true can significantly reduce the number of messages sent to the virtual callback handlers.

___________________________________________________________________rrpGridSetCellAt command

command rrpGridSetCellAt pRow, pCol, pCell, pNoRefreshChanges is the text contents of the cell in the grid specified by the parameters.

ParameterspRow: the row of the cellpCol: the column of the cellpCell: the text to put in the cellpNoRefresh: if false the visible cells in the grid are not updated

CommentBy default if the pNoRefresh parameter is omitted the visible cells in the grid are updated. Setting this parameter to fault is useful if you are changing many cells and do not want to slow down the grid by updating it after every change.

101

___________________________________________________________________rrpGridSetCellBorderColor command

command rrpGridSetCellBorderColor pColorSets the cCellBorderColor property of the grid that specifies the color of the cell borders.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetCellColor command

command rrpGridSetCellColor pColorSets the cCellColor property of the grid that specifies the color of the cells that are not selected or at the cursor.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

102

___________________________________________________________________rrpGridSetCellHeight command

command rrpGridSetCellHeight pHeightSets the cCellHeight property of the grid that specifies the height of the cells in the grid.

ParameterspHeight: an integer greater than or equal to 8 and less than half of the height of the grid

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Changing the cell height does not affect the size of the grid. For example, increasing the cell height reduces the number of visible rows in the grid. Partial rows cannot be displayed in the grid, so if the cell height is not an integer divisor of the height of the grid there will be a blank area at the bottom of the grid frame.

___________________________________________________________________rrpGridSetCellTextFont command

command rrpGridSetCellTextFont pTextFontSets the cCellTextFont property of the grid that specifies the text font of the cells in the grid.

ParameterspTextFont: empty or a valid font name

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. By default this property is empty which means the font of the text in the cells is the same as the default font of the card.

103

___________________________________________________________________rrpGridSetCellTextSize command

command rrpGridSetCellTextSize pSizeSets the cCellTextSize property of the grid that specifies the size of the text in the cells in the grid.

ParameterspSize: empty or an integer specifying the text size in points

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Changing the text size does not affect the height of the cells. By default this property is empty which means the size of the text in the cells is the same as the stack text size.

___________________________________________________________________rrpGridSetCellWidth command

command rrpGridSetCellWidth pWidthSets the cCellWidth property of the grid that specifies the width of the cells in the grid.

ParameterspWidth: an integer greater than or equal to 24 and less than half of the width of the grid

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Changing the cell width does not affect the size of the grid. For example, decreasing the cell width increases the number of visible columns in the grid.

104

___________________________________________________________________rrpGridSetColCount command

command rrpGridSetColCount pCountSets the cColCount property of the grid that specifies the number of columns in the grid.

ParameterspCount: an integer between than 1 and 1,000,000 inclusive

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The column count is the total number of columns in the grid, which can be larger than the visible number of columns. If the number of columns is more than can be displayed in the grid, the horizontal scroll bar allows you to change the visible columns. For a grid with more than 1,000 columns the virtual mode may be required to ensure satisfactory speeds when scrolling.

___________________________________________________________________rrpGridSetColLabels command

command rrpGridSetColLabels pLabelsSets the cColLabels property of the grid that specifies the text of the column labels.

ParameterspLabels: a comma delimited list of labels

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. When this property is empty the grid uses alphabetical labels starting from A followed by B, and so on, like in a typical spreadsheet. Setting this property allows you to change the labels shown to different text. If the number of items in this property is less than the number of columns in the grid, the labels for the remaining columns will be the typical alphabetical labels.

105

___________________________________________________________________rrpGridSetColorMode command

command rrpGridSetColorMode pEnableSets the cColorMode property of the grid that specifies whether cells can by given individual colors.

ParameterspEnable: true or false, true means cells can be colored

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. By default this property is true which means that cells can be set with individual colors with the rrpGridSetSelectionColor command. For a grid that has many visible rows and columns, allowing cells to be colored may reduce the speed of the grid when scrolling. If setting the color of the cells is not required, it is recommended that this property be set to false.

___________________________________________________________________rrpGridSetCursor command

command rrpGridSetCursor pRow, pColMoves the cursor to the cell specified by the parameters.

ParameterspRow: the row of the cellpCol: the column of the cell

CommentIf necessary, the grid is scrolled to make the cursor cell visible.

106

___________________________________________________________________rrpGridSetCursorCol command

command rrpGridSetCursorCol pColMoves the cursor to the cell with the column specified by the parameter without changing the row.

ParameterspCol: the column of the cell

CommentIf necessary, the grid is scrolled to make the cursor cell visible.

___________________________________________________________________rrpGridSetCursorColor command

command rrpGridSetCursorColor pColorSets the cCursorColor property of the grid that specifies the color of the cell at the cursor.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetCursorRow command

command rrpGridSetCursorRow pRowMoves the cursor to the cell with the row specified by the parameter without changing the column.

ParameterspRow: the row of the cell

CommentIf necessary, the grid is scrolled to make the cursor cell visible.

107

___________________________________________________________________rrpGridSetCursorRowColColor command

command rrpGridSetCursorRowColColor pColorSets the cCursorRowColColor property of the grid that specifies the color used when the cursor row or column is shaded.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetDataAt command

command rrpGridSetDataAt pData, pRow, pColPuts HTML or plain text data into the grid starting from the specified cell.

ParameterspData: the grid data in a HTML formatpRow: the starting row for the datapCol: the starting column for the data

CommentThe data on the clipboard can be a HTML table or lines of tab delimited text. If the cExpandMode property is set to true, the number of rows and columns in the grid will increase if necessary to fit the data. Cells that are outside of the region of the specified data are unaffected.

108

___________________________________________________________________rrpGridSetDataFromHTML command

command rrpGridSetDataFromHTML pData, pPreserveCursorReplaces all the data in the grid with the HTML data specified in the parameter.

ParameterspData: the grid data in a HTML formatpPreserveCursor: true, false or empty

CommentThe data on the clipboard must be a HTML table. If the cExpandMode property is set to true, the number of rows and columns in the grid will increase if necessary to fit the data. If the optional pPreserveCursor parameter is true the cursor is set to the previous position after setting the data.

___________________________________________________________________rrpGridSetDataFromText command

command rrpGridSetDataFromText pData, pPreserveCursorReplaces all the data in the grid with the text data specified in the parameter.

ParameterspData: the grid data in a text formatpPreserveCursor: true, false or empty

CommentThe data must be lines of tab delimited text. If the cExpandMode property is set to true, the number of rows and columns in the grid will increase if necessary to fit the data. If the optional pPreserveCursor parameter is true the cursor is set to the previous position after setting the data.

When putting data in the grid as text these three simple tags can be used to format the data in the cell: <left>, <center>, <right>, <readonly>. The first three set the text alignment to left, center or right. The last makes the cell readonly which means the user can edit the cell, although you can still change the contents with scripts.

109

___________________________________________________________________rrpGridSetDataSize command

command rrpGridSetDataSize pRowCount, pColCountSets the number of rows and columns in the grid as specified in the parameters.

ParameterspRowCount: an integer between than 1 and 1,000,000 inclusivepColCount: an integer between than 1 and 1,000,000 inclusive

CommentThe row and column count is the size of the grid, which can be larger than the visible number of rows and columns. If the size is more than can be displayed in the grid, scrollbars are shown to allows you to change the visible columns. For a grid with either size more than 1,000 the virtual mode may be required to ensure satisfactory speeds when scrolling.

___________________________________________________________________rrpGridSetEditColor command

command rrpGridSetEditColor pColorSets the cEditColor property of the grid that specifies the color of the cell that is being edited.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

110

___________________________________________________________________rrpGridSetEditOnDoubleClick command

command rrpGridSetEditOnDoubleClick pEnableSets the cEditOnDoubleClick property of the grid that specifies whether editing is started with a double click on a cell.

ParameterspEnable: true or false, true means double click editing is enabled

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetEditOnF2 command

command rrpGridSetEditOnF2 pEnableSets the cEditOnF2 property of the grid that specifies whether editing is started by pressing the F2 function key.

ParameterspEnable: true or false, true means F2 editing is enabled

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

111

___________________________________________________________________rrpGridSetFormatAt command

command rrpGridSetFormatAt pRow, pCol, pFormat, pNoRefresh

Changes is the format of the cell in the grid specified by the parameters.

ParameterspRow: the row of the cellpCol: the column of the cellpFormat: the format of the cell in an encoded stringpNoRefresh: if false the visible cells in the grid are not updated

CommentThe string for the pFormat parameter should be in the same type of coding as returned by the rrpGridGetFormatAt function. By default if the pNoRefresh parameter is omitted the visible cells in the grid are updated. Setting this parameter to fault is useful if you are changing many cells and do not want to slow down the grid by updating it after every change.

___________________________________________________________________rrpGridSetFrameVisible command

command rrpGridSetFrameVisible pVisibleSets the cFrameVisible property of the grid that specifies whether the grid frame is visible.

ParameterspVisible: true or false

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The grid is contained within the bounds of a rectangle graphic on your stack. This is called the grid frame. Normally during design time it is useful for this frame to be visible to simplify resizing and selection of the grid. In a finished application you would normally sets this property to false.

112

___________________________________________________________________rrpGridSetFrozenColCount command

command rrpGridSetFrozenColCount pFrozenCountSets the cFrozenColCount property of the grid that specifies the number of frozen columns in the grid

ParameterspFrozenCount: an integer less than the number of visible columns in the grid

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Frozen columns are columns in the grid that are in a fixed position and do not scroll off the left edge of the grid when scrolling to the right. Frozen columns are also displayed with a different color that is set with the cFrozenColor property.

___________________________________________________________________rrpGridSetFrozenColor command

command rrpGridSetFrozenColor pColorSets the cFrozenColor property of the grid that specifies the color of any frozen rows or columns

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

113

___________________________________________________________________rrpGridSetFrozenColTextSize command

command rrpGridSetFrozenColTextSize pSizeSets the cFrozenColTextSize property of the grid that specifies the size of the text in the cells in the grid.

ParameterspSize: empty or an integer specifying the text size in points

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Changing the text size does not affect the height of the frozen cells. By default this property is empty which means the size of the text in the frozen cells is the same as the stack text size.

___________________________________________________________________rrpGridSetFrozenColWidths command

command rrpGridSetFrozenColWidths pWidthsSets the cFrozenColWidths property of the grid that specifies the widths of the cells in the frozen columns of the grid.

ParameterspWidths: empty or a comma delimited list of widths

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. If the parameter is empty the frozen column cells have the same width as the other cells in the grid.

114

___________________________________________________________________rrpGridSetFrozenRowCount command

command rrpGridSetFrozenRowCount pFrozenCountSets the cFrozenRowCount property of the grid that specifies the number of frozen rows in the grid

ParameterspFrozenCount: an integer less than the number of visible rows in the grid

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Frozen rows are rows in the grid that are in a fixed position and do not scroll off the top edge of the grid when scrolling down. Frozen rows are also displayed with a different color that is set with the cFrozenColor property.

___________________________________________________________________rrpGridSetFrozenRowHeights command

command rrpGridSetFrozenRowHeights pHeightsSets the cFrozenRowHeights property of the grid that specifies the heights of the cells in the frozen rows of the grid.

ParameterspHeights: empty or a comma delimited list of heights

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. If the parameter is empty the frozen row cells have the same height as the other cells in the grid.

115

___________________________________________________________________rrpGridSetFrozenRowTextSize command

command rrpGridSetFrozenRowTextSize pSizeSets the cFrozenRowTextSize property of the grid that specifies the size of the text in the cells in the grid.

ParameterspSize: empty or an integer specifying the text size in points

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Changing the text size does not affect the height of the frozen cells. By default this property is empty which means the size of the text in the frozen cells is the same as the stack text size.

___________________________________________________________________rrpGridSetHeightCanStretch command

command rrpGridSetHeightCanStretch pEnableSets the cHeightCanStretch property of the grid that specifies whether the height of the grid can change when the size of the stack changes.

ParameterspEnable: true or false, if true the grid can stretch

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. By default this property is true which means the grid will resize its height if the stack is resized. For this property to have an effect there must be a resizeStack handler in your stack that calls the pvGridStackResize command. Refer to the Resizing a grid section of the Common Grid Actions chapter for more details.

116

___________________________________________________________________rrpGridSetHiliteCursorLabels command

command rrpGridSetHiliteCursorLabels pEnableSets the cHiliteCursorLabels property of the grid that specifies whether the background color of the row and column labels change to indicate the position of the cursor.

ParameterspEnable: true or false, if true the labels are shaded

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The background color of the row and column labels is the same color as the cCursorColor property.

___________________________________________________________________rrpGridSetHScrollVisible command

command rrpGridSetHScrollVisible pVisibleSets the cHScrollVisible property of the grid that specifies whether the horizontal scroll bar is visible along the bottom edge of the grid

ParameterspVisible: true or false, if true the scrollbar is visible

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

117

___________________________________________________________________rrpGridSetLabelHeight command

command rrpGridSetLabelHeight pHeightSets the cLabelHeight property of the grid that specifies the height of (or hides) the column labels.

ParameterspHeight: an integer between than 0 and half the height of the grid, inclusive.

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Setting the height to 0 removes the column labels from the grid.

___________________________________________________________________rrpGridSetLabelTextSize command

command rrpGridSetLabelTextSize pSizeSets the cLabelTextSize property of the grid that specifies the size of the text in the labels in the grid.

ParameterspSize: empty or an integer specifying the label text size in points

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Changing the text size does not affect the height of the labels. By default this property is empty which means the size of the text in the labels is the same as the stack text size.

118

___________________________________________________________________rrpGridSetLabelWidth command

command rrpGridSetLabelWidth pWidthSets the cLabelWidth property of the grid that specifies the width of (or hides) the row labels.

ParameterspWidth: an integer between than 0 and half the width of the grid, inclusive.

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Setting the width to 0 removes the row labels from the grid.

___________________________________________________________________rrpGridSetMessageMode command

command rrpGridSetMessageMode pEnableSets the cMessageMode property of the grid that specifies whether messages are sent when the user interacts with the grid.

ParameterspEnable: true or false, if true messages are sent

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. Only set this property to true if you have defined callback functions in your stack, because this mode may reduce the speed of the grid. Refer to the Callback Functions and Messages chapter for more details.

119

___________________________________________________________________rrpGridSetNoCursorColCount command

command rrpGridSetNoCursorColCount pNoCursorCountSets the cNoCursorColCount property of the grid that controls whether frozen column cells can be edited.

ParameterspNoCursorCount: value between 0 and the cFrozenColCount, inclusively

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetNoCursorRowCount command

command rrpGridSetNoCursorRowCount pNoCursorCountSets the cNoCursorRowCount property of the grid that controls whether frozen row cells can be edited.

ParameterspNoCursorCount: value between 0 and the cFrozenRowCount, inclusively

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

120

___________________________________________________________________rrpGridSetPrintFooter command

command rrpGridSetPrintFooter pFooterSets the cPrintFooter property of the grid that specifies the footer shown at the bottom of the page when printing the grid.

ParameterspFooter: empty or a string of text, if empty no footer is shown

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The # symbol can be used in the string as a “placeholder” for the page number and the total number of pages. If included in the footer, the first # has the page number substituted into it, and the second is the total number of pages.

___________________________________________________________________rrpGridSetPrintLabelColor command

command rrpGridSetPrintLabelColor pColorSets the cPrintLabelColor property of the grid that specifies the color of the row and column labels when printing the grid.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The default background color is a shade of gray, but can be changed to make it lighter or darker or in color.

121

___________________________________________________________________rrpGridSetPrintLabelTextColor command

command rrpGridSetPrintLabelTextColor pColorSets the cPrintLabelTextColor property of the grid that specifies the color of the row and column label text when printing the grid.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The default text color is black, but can be changed to make it contrast better if the cPrintLabelColor is changed.

___________________________________________________________________rrpGridSetPropsFromText command

command rrpGridSetPropsFromText pPropsSets the grid properties from the list specified in the parameter.

ParameterspProps: the list of properties

CommentThis command is useful for restoring the state of the grid that has been stored elsewhere. The list of properties must be in the same format as returned by the rrpGridGetPropsAsText function.

122

___________________________________________________________________rrpGridSetRectangle command

command rrpGridSetRectangle pLeft, pTop, pRight, pBottom

Sets the position of the grid frame object on the stack.

ParameterspLeft: the position of the left edgepTop: the position of the top edgepRight: the position of the right edgepBottom: the position of the bottom edge

CommentThis command allows you to change that position at runtime. If you require the grid to be resized as the stack is resized setting the cHeightCanStretch and cWidthCanStretch properties to true is recommended. The initial position of the grid frame is normally be set at design time either using a click and drag or setting the position in the Property Inspector.

___________________________________________________________________rrpGridSetReadOnly command

command rrpGridSetReadOnly pEnableSets the cReadOnly property of the grid that specifies whether the user can change the data in the grid.

ParameterspEnable: true or false, if true the data cannot be edited

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

123

___________________________________________________________________rrpGridSetRefreshIsPending command

command rrpGridSetRefreshPendingSets an internal refresh pending flag that can be read with the rrpGridRefreshIsPending function.

CommentThis command has no effect on the grid, but can be used in conjunction with the rrpGridRefreshIsPending function to allow your application to keep track of whether the properties of the grid have changed in a way that require the whole grid to be refreshed.

___________________________________________________________________rrpGridSetReturnMovesCursor command

command rrpGridSetReturnMovesCursor pEnableSets the cReturnMovesCursor property of the grid that specifies whether pressing the return key move to the cell in the next row below when editing the grid.

ParameterspEnable: true or false, if true the return key does move the cursor to the next row

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

124

___________________________________________________________________rrpGridSetRowColCount command

command rrpGridSetColCount pRowCount, pColCountSets the cRowCount and cColCount properties of the grid that specify the number of rows and columns in the grid.

ParameterspRowCount: an integer between than 1 and 1,000,000 inclusivepColCount: an integer between than 1 and 1,000,000 inclusive

CommentThis handler is a convenience for setting the corresponding properties of the grid frame object. The row count is the total number of rows in the grid, which can be larger than the visible number of rows. The column count is the total number of columns in the grid, which can be larger than the visible number of columns. For a grid with more than 1,000 rows or columns the virtual mode may be required to ensure satisfactory speeds when scrolling.

___________________________________________________________________rrpGridSetRowCount command

command rrpGridSetRowCount pCountSets the cRowCount property of the grid that specifies the number of rows in the grid.

ParameterspCount: an integer between than 1 and 1,000,000 inclusive

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The row count is the total number of rows in the grid, which can be larger than the visible number of rows. If the number of rows is more than can be displayed in the grid, the vertical scroll bar allows you to change the visible rows. For a grid with more than 100,000 rows the virtual mode may be required to ensure satisfactory speeds when scrolling.

125

___________________________________________________________________rrpGridSetRowLabels command

command rrpGridSetRowLabels pLabelsSets the cRowLabels property of the grid that specifies the text of the row labels.

ParameterspLabels: a comma delimited list of labels

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. When this property is empty the grid uses numerical row labels starting from 1 followed by 2, and so on, like in a typical spreadsheet. Setting this property allows you to change the labels shown to different text. If the number of items in this property is less than the number of rows in the grid, the labels for the remaining rows will be the numbered labels.

___________________________________________________________________rrpGridSetSelectedAlignment command

command rrpGridSetSelectedAlignment pAlignSets the alignment of the selected cells in the grid to the parameter.

ParameterspAlign: “left”, “center”, or “right”

CommentIf there is no selection, the alignment is applied to the cursor cell.

126

___________________________________________________________________rrpGridSetSelectedCells command

command rrpGridSetSelectedCells pRow1, pCol1, pRow2, pCol2

Sets the selected cells in the grid to region specified by the parameters.

ParameterspRow1: the row that specifies the top left corner of the regionpCol1: the column that specifies the top left corner of the regionpRow2: the row that specifies the bottom right corner of the regionpCol2: the column that specifies the bottom right corner of the region

CommentTo remove the selection from the grid, call this handler with pRow2 equal to pRow1 and pCol2 equal to pCol1.

___________________________________________________________________rrpGridSetSelectedColor command

command rrpGridSetSelectedColor pColorSets the color of the selected cells in the grid to the parameter.

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentIf there is no selection, the color is applied to the cursor cell.

___________________________________________________________________rrpGridSetSelectedReadOnly command

command rrpGridSetSelectedReadOnly pReadOnlySets the read only property of the selected cells in the grid.

ParameterspReadOnly: true or false, if true the cells cannot be edited by the user

CommentIf there is no selection, the read only property is applied to the cursor cell.

127

___________________________________________________________________rrpGridSetSelectedStyle command

command rrpGridSetSelectedStyle pStyle, pEnableSets the style of the selected cells in the grid to the first parameter.

ParameterspStyle: “plain” or “bold” or “italic”pEnable: true or false, if true the style in the parameter is turned on, if false the style in the parameter is turned off

CommentOnly one style can be set with each call of this command. If you want the cells to be bold and italic this command is called twice, once to set the bold style and the second time to set the italic style. If the style is plain the pEnable parameter is ignored because it is not possible to turn off a style of plain. The pEnable parameter is optional. If it is omitted the style specified by the parameter is toggled, i.e. the current state is reversed. If there is no selection, the style is applied to the cursor cell.

___________________________________________________________________rrpGridSetSelectedWrap command

command rrpGridSetSelectedWrap pEnableSets whether the selected cells in the grid can wrap cells with long text over more than one line

ParameterspEnable: true or false, if true the contents of the cell can wrap

CommentIf there is no selection, the wrap is applied to the cursor cell.

128

___________________________________________________________________rrpGridSetSelectionColor command

command rrpGridSetSelectionColor pColorSets the cSelectionColor property of the grid that specifies the color of the selected cells

ParameterspColor: any color encoded in the HTML style that begins with a #

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetShadeAlternateRows command

command rrpGridSetShadeAlternateRows pEnableSets the cShadeAlternateRows property of the grid that specifies whether the alternate rows are shaded.

ParameterspEnable: true or false, if true alternate rows are shaded

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The background color of the shaded rows is the color set in the cAlternateRowCol property.

129

___________________________________________________________________rrpGridSetShadeCursorCol command

command rrpGridSetShadeCursorCol pEnableSets the cShadeCursorCol property of the grid that specifies whether the column with the cursor is shaded.

ParameterspEnable: true or false, if true the cursor column is shaded

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The background color of the cursor column is the color set in the cCursorRowColColor property.

___________________________________________________________________rrpGridSetShadeCursorRow command

command rrpGridSetShadeCursorRow pEnableSets the cShadeCursorRow property of the grid that specifies whether the row with the cursor is shaded.

ParameterspEnable: true or false, if true the cursor row is shaded

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. The background color of the cursor row is the color set in the cCursorRowColColor property.

130

___________________________________________________________________rrpGridSetTopLeft command

command rrpGridSetTopLeft pTop, pLeftScrolls the grid so the visible cell in the top left corner is the cell specified by the parameters

ParameterspTop: the row of the cell in the top left cornerpLeft: the column of the cell in the top left corner

CommentIf the row and column specified for the top left corner are outside the size of the grid this command has no effect.

___________________________________________________________________rrpGridSetVirtualMode command

command rrpGridSetVirtualMode pEnableSets the cVirtualMode property of the grid that specifies whether the grid is the virtual mode, where the data is not stored in the grid.

ParameterspEnable: true or false, if true the grid sends messages to get the contents of the cells

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. In virtual mode the grid does not store the data of the grid, instead you define a set of callback functions in your stack that the grid calls each time it needs to get or set data in the grid. A grid in virtual mode is able to display up to 1,000,000,000,000 cells but at the expense of more complex scripting in your stack and possibly lower performance. Refer to the Virtual Mode Grids chapter for more details.

131

___________________________________________________________________rrpGridSetVScrollVisible command

command rrpGridSetVScrollVisible pVisibleSets the cVScrollVisible property of the grid that specifies whether the vertical scroll bar is visible along the right edge of the grid

ParameterspVisible: true or false, if true the scrollbar is visible

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetWidthCanStretch command

command rrpGridSetWidthCanStretch pEnableSets the cWidthCanStretch property of the grid that specifies whether the width of the grid can change when the size of the stack changes.

ParameterspEnable: true or false, if true the grid can stretch

CommentThis handler is a convenience for setting the corresponding property of the grid frame object. By default this property is true which means the grid will resize its width if the stack is resized. For this property to have an effect there must be a resizeStack handler in your stack that calls the pvGridStackResize command. Refer to the Resizing a grid section of the Common Grid Actions chapter for more details.

132

___________________________________________________________________rrpGridSetWrapCursorCol command

command rrpGridSetWrapCursorCol pEnableSets the cWrapCursorCol property of the grid that specifies whether the cursor will “wrap around” to the next row when the cursor reaches the first or last column of the grid.

ParameterspEnable: true or false, if true the cursor does wrap

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

___________________________________________________________________rrpGridSetWrapCursorRow command

command rrpGridSetWrapCursorRow pEnableSets the cWrapCursorRow property of the grid that specifies whether the cursor will “wrap around” to the next column when the cursor reaches the first or last row of the grid.

ParameterspEnable: true or false, if true the cursor does wrap

CommentThis handler is a convenience for setting the corresponding property of the grid frame object.

133

___________________________________________________________________rrpGridUpdateScripts command

command rrpGridUpdateScripts pIDUpdates the internal scripts used by the the grid on the current stack with the ID.

ParameterspID: The ID of the grid frame graphic object

CommentThis command is only needed when the internal implementation of the grid has been enhanced in a way that requires the scripts of the internally used groups of the grid to be updated. If this command is necessary, it will be noted in the Readme.txt notes included in the distribution. The command can be used from the Message Box for any grids that were created before installing the update.

nnnn

134