RunRevPlanet Grid

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 and Reference

RunRevPlanet Grid
Guide and Reference
Copyright (c) 2010 Scott McDonald PC Services All rights reserved. November 2010 Edition

Built with LiveCode from RunRev Ltd.

Address: Scott McDonald PC Services PO Box 139, Newtown, 2042 New South Wales, Australia Facsimile: +612-9564-2347 Website: http://www.runrevplanet.com Email: runrevplanet@smpcs.server101.com

Table of Contents
Introduction............................................................................3 Installation & Requirements...................................................5 Conventions............................................................................6 Licensing Agreement..............................................................7 Simple Grid Demo..................................................................9 Advanced Grid Demo TINAS..............................................17 Common Grid Actions..........................................................26 Callback Functions and Messages........................................38 Virtual Mode Grid................................................................40 Deploying Your Own Application........................................43 Error messages......................................................................46 Handler 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.

Introduction
The 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.

Figure 1: A flexible grid component

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.

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:

Figure 2: Not just spreadsheets

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

Installation & Requirements

To 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.rev rrpGrid-Guide-Reference.pdf Readme.txt License.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.

Conventions
The 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 if end 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.

Licensing Agreement
The 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.

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.

Simple Grid Demo

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

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.

Figure 4: Selecting the grid component

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.

Figure 5: Copying the grid component

10

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

Figure 6: Pasting the grid component

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.

Figure 7: The grid on a stack

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

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.

Figure 8: Resizing the grid

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.

Figure 9: Moving the grid

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

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.

Figure 10: The grid custom properties

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.
Figure 11: Private properties

13

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.

Figure 12: Two important handlers

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 resizeStack end 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

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 try end 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.

Figure 13: Making the grid a substack

15

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.

Figure 14: The completed demo

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

Advanced Grid Demo TINAS

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

Figure 15: This is not a spreadsheet demo

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

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.

Figure 16: Different cell colors and attributes

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.

Figure 17: Main stack properties

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

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.

Figure 18: Edit the stack script

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 19: Three important stack handlers

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 tData put offset("<table", tData) into tIndex if 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 tData end 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

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" rrpGridRefresh end 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 true end 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 if end 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.

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

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 stack end 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

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 true end 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.

Figure 21: The printed grid

24

Conclusion Here is a summary of the handlers you have learned about in this chapter.
rrpGridConvertColor rrpGridGetCellAt rrpGridGetDataAsHTML rrpGridGetDataAsText rrpGridGetPropsAsText rrpGridPrint rrpGridRefresh rrpGridSetActiveAuto rrpGridSetCellAt rrpGridSetColLabels rrpGridSetDataFromHTML rrpGridSetDataFromText rrpGridSetMessageMode rrpGridSetPropsFromText rrpGridSetRowCount

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 Actions

This 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 try end 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 cCacheVirtual cCellBorderColor cCellColor cCellHeight cCellWidth cColCount cColLabelOffset cColLabels cCursorColor cCursorRowColColor cEditColor cFrameVisible cFrozenColCount cFrozenColor cFrozenRowCount cHiliteCursorLabels cHScrollVisible cLabelHeight cLabelWidth cPrintFooter cPrintLabelColor cPrintLabelTextColor cRowCount cRowLabels cSelectionColor cShadeAlternateRows cShadeCursorCol cShadeCursorRow cVScrollVisible rrpGridSetAlternateRowColor rrpGridSetCacheVirtual rrpGridSetCellBorderColor rrpGridSetCellColor rrpGridSetCellHeight rrpGridSetCellWidth rrpGridSetColCount rrpGridSetColLabelOffset rrpGridSetColLabels rrpGridSetCursorColor rrpGridSetCursorRowColColor rrpGridSetEditColor rrpGridSetFrameVisible rrpGridSetFrozenColCount rrpGridSetFrozenColor rrpGridSetFrozenRowCount rrpGridSetHiliteCursorLabels rrpGridSetHScrollVisible rrpGridSetLabelHeight rrpGridSetLabelWidth rrpGridSetPrintFooter rrpGridSetPrintLabelColor rrpGridSetPrintLabelTextColor rrpGridSetRowCount rrpGridSetRowLabels rrpGridSetSelectionColor rrpGridSetShadeAlternateRows rrpGridSetShadeCursorCol rrpGridSetShadeCursorRow 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 resizeStack end 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 me end 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.
rrpGridSetWidthCanStretch rrpGridSetHeightCanStretch

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:
rrpGridSetDataFromHTML rrpGridSetDataFromText

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.
rrpGridSetCellAt rrpGridSetDataAt

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.
rrpGridSetSelectedAlignment rrpGridSetSelectedColor rrpGridSetSelectedStyle rrpGridSetSelectedWrap

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.
rrpGridGetCursor rrpGridSetCursor

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.
rrpGridGetCursorRow rrpGridGetCursorCol

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

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.
rrpGridSetFrozenColCount rrpGridSetFrozenRowCount

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.
rrpGridInsertAfterCol rrpGridInsertBeforeCol

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.
rrpGridInsertAfterRow rrpGridInsertBeforeRow

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

31

rrpGridInsertRowAfterCursor rrpGridInsertRowBeforeCursor

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.
rrpGridDeleteColAtCursor rrpGridDeleteRowAtCursor

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.
rrpGridDeleteColRegion rrpGridDeleteRowRegion

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

rrpGridGetDataAsHTML rrpGridGetDataAsText

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.
rrpGridGetRegionAsHTML rrpGridGetRegionAsText rrpGridGetSelectedAsHTML rrpGridGetSelectedAsText

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.
rrpGridCopySelectedAsHTML rrpGridCopySelectedAsText

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

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

rrpGridSetActiveByID rrpGridSetActiveByName

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 sLastActiveGridName on suspendStack put rrpGridGetActiveName() into sLastActiveGridName pass suspendStack end suspendStack on resumeStack rrpGridSetActiveByName sLastActiveGridName pass resumeStack end 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

RrpGridSetVirtualMode rrpGridGetVirtualMode

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 Messages

The 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 rrpGridCellDoubleClickM rrpGridColChangeM rrpGridColLabelClickM rrpGridColumnResizeM rrpGridCornerClickM rrpGridCursorChangeM rrpGridEditBeginM rrpGridEditCancelM rrpGridEditEndM rrpGridEditPreM rrpGridEditReadOnlyM rrpGridResizeHelperM rrpGridRowChangeM rrpGridRowLabelClickM rrpGridSelectionChangeM rrpGridTopLeftChangeM

called when there is a mouse click on a cell called when there is a mouse double click on a cell called when the column of the cursor changes called when there is a mouse click on a column label called when the user resizes the widths of the columns called when there is a mouse click in the top left corner button called when the cursor changes called when the user starts to edit a cell called when the user cancels the editing of a cell called when the user finishes editing a cell called before the editing of a cell begins called when the user tries to edit a cell that is read only called when the grid is being resized called when the row of the cursor changes called when there is a mouse click on a row label called when the cell selection in the grid changes 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 frame end rrpGridCellClickM on rrpGridColChangeM pCol, pID -- called when the column of the cursor changes -- pCol is the current cursor column -- pID is the ID of grid frame end rrpGridColChangeM on 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 frame end rrpGridColLabelClickM on rrpGridColumnResizeM pCellWidth, pID -- called when the user resizes the widths of the columns -- pCellWidth is the cell width -- pID is the ID of grid frame end rrpGridColumnResizeM on rrpGridCornerClickM pID -- called when there is a mouse click in the top left - corner button -- pID is the ID of grid frame end rrpGridCornerClickM on rrpGridCursorChangeM pRow, pCol, pID -- called when the cursor changes -- pRow and pCol is the current cursor position -- pID is the ID of grid frame end rrpGridCursorChangeM on 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 frame end 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 frame end rrpGridEditCancelM on 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 frame end rrpGridEditEndM on 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 frame end rrpGridEditPreM on 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 frame end rrpGridEditReadOnlyM on 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 grid end rrpGridResizeHelperM on rrpGridRowChangeM pRow, pID -- called when the row of the cursor changes -- pRow is the current cursor row -- pID is the ID of grid frame end 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 frame end rrpGridRowLabelClickM on 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 frame end rrpGridSelectionChangeM on 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 frame end 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 Grid

Using 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 rrpGridGetFormatM rrpGridSetCellM rrpGridSetFormatM

called when in virtual mode to get the text of a cell called when in virtual mode to get the attributes of a cell called when in virtual mode to store the text of a cell after it has been edited 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 && "," && pCol end rrpGridGetCellM on 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 empty end rrpGridGetFormatM on 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.
rrpGridInsertAfterCol rrpGridInsertBeforeCol rrpGridInsertAfterRow rrpGridInsertBeforeRow rrpGridInsertColAfterCursor rrpGridInsertColBeforeCursor rrpGridInsertRowAfterCursor rrpGridInsertRowBeforeCursor rrpGridDeleteColAtCursor rrpGridDeleteRowAtCursor rrpGridDeleteColRegion rrpGridDeleteRowRegion

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 Application

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

Figure 22: Message when creating a standalone

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 in Figure 23.

Figure 23: Set Cursors as an inclusion

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

Error Messages
The 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.
rrpGridSetActiveByID rrpGridSetActiveByName

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 Reference
This 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
Comment

This 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 false Default: false
Comment

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. ___________________________________________________________________ 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
Comment

This 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
Comment

This 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 grid Default: 24
Comment

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. ___________________________________________________________________ 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 name Default: empty
Comment

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.

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 points Default: empty
Comment

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. ___________________________________________________________________ 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 grid Default: 80
Comment

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. ___________________________________________________________________ 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
Comment

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.

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
Comment

By 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 commas Default: 0,0,0,0
Comment

Normally 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 labels Default: empty
Comment

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. ___________________________________________________________________ cColorMode property cColorMode Set in this property to change whether cells can be set to display individual colors. Value: true or false Default: true
Comment

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.

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
Comment

This 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
Comment

This 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
Comment

This 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
Comment

This 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 false Default: true
Comment

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 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 false Default: true
Comment

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 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 false Default: true
Comment

If 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 false Default: false
Comment

By 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: false Default: true
Comment

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. ___________________________________________________________________ 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 grid Default: 0
Comment

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. ___________________________________________________________________ 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 Comment This 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 points Default: empty
Comment

Changing 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
Comment

By 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 grid Default: 0
Comment

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

By 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 points Default: empty
Comment

Changing 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 false Default: true
Comment

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.

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 false Default: false
Comment

The 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 false Default: true
Comment

Depending 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
Comment

Setting 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 style Default: rectangle
Comment

The 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 points Default: empty
Comment

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. ___________________________________________________________________ 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
Comment

Setting 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
Comment

The 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
Comment

The 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 false Default: false
Comment

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.
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 grid Default: 0 or cFrozenColCount
Comment

By 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 grid Default: 0 or cFrozenRowCount
Comment

By 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 text Default: Page # of #
Comment

The # 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
Comment

The 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
Comment

The 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 false Default: false
Comment

This 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 false Default: false
Comment

The 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
Comment

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.

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
Comment

By 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 commas Default: 0,0,0,0
Comment

Normally 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 labels Default: empty
Comment

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. ___________________________________________________________________ cScrollAutoVisible property cScrollAutoVisible Set this property to true to make either scrollbar hide itself when it is not needed Value: true or false Default: false
Comment

When 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 Comment The 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
Comment

This property sets the selected cell background color. ___________________________________________________________________ cShadeAlternateRows property cShadeAlternateRows Set this property to change whether the alternate rows are shaded. Value: true or false Default: true
Comment

The 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 false Default: false
Comment

The 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 false Default: false
Comment

The 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
Comment

The 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 false Default: false
Comment

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. ___________________________________________________________________ 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 false Default: true
Comment

Depending 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 false Default: true
Comment

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. ___________________________________________________________________ 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 false Default: false
Comment

By 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 false Default: false
Comment

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

72

___________________________________________________________________ rrpGridBeginEdit command command rrpGridBeginEdit Puts the current cell into the edit mode
Comment

This 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 rrpGridCancelEdit Cancels the editing of a cell.
Comment

This 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 rrpGridCancelPendingCursor Cancels any changes to the cursor position.
Comment

When 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, pCol2 Clears the text and formatting in the cells defined by the region specified in the parameters. Parameters pRow1: the row that specifies the top left corner of the region pCol1: the column that specifies the top left corner of the region pRow2: the row that specifies the bottom right corner of the region pCol2: the column that specifies the bottom right corner of the region
Comment

This command clears the contents of the cells without affecting the position of the cursor. ___________________________________________________________________ rrpGridClearSelected command command rrpGridClearSelected Clears the text and formatting in the selected cells.
Comment

This command clears the cursor cell if there is no region of cells selected. ___________________________________________________________________ rrpGridConvertColor function function rrpGridConvertColor pColor
Returns

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

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

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

74

___________________________________________________________________ rrpGridCopyAsText command command rrpGridCopyAsText pIncludeLabels Copies only the text of the entire to the clipboard with the option of including the row and column labels
Parameters

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

This 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 rrpGridCopySelectedAsHTML Copies the text and formatting of the selected cells to the clipboard.
Comment

This command uses standard HTML tags such as <table> to copy the selected cells to the clipboard without any loss of information. ___________________________________________________________________ rrpGridCopySelectedAsText command command rrpGridCopySelectedAsText Copies only the text of the selected cells to the clipboard.
Comment

This 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 rrpGridDeleteColAtCursor Deletes the column of cells that the cursor is in.
Comment

The 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, pCol2 Deletes one or more columns of cells as specified by the parameters.
Parameters

pCol1: the column that specifies the first column of the region pCol2: the column that specifies the last column of the region
Comment

The 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 rrpGridDeleteRowAtCursor Deletes the row of cells that the cursor is in.
Comment

The 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, pRow2 Deletes one or more rows of cells as specified by the parameters.
Parameters

pRow1: the row that specifies the first row of the region pRow2: the row that specifies the last row of the region Comment The 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 rrpGridEmptyCache Empties the contents of the cache when the grid is in virtual mode.
Comment

This 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 rrpGridGetActiveID
Returns

the ID of the active grid frame

Comment

Every 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 rrpGridGetActiveName

Returns

the Name of the active grid frame

Comment

Every 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, pCol
Returns

the alignment of the text in cell specified by the parameters as a string of left, center or right
Parameters

pRow: the row of the cell pCol: the column of the cell
Comment

If 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, pCol
Returns

the text of the cell specified by the parameters

Parameters

pRow: the row of the cell pCol: the column of the cell
Comment

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

78

___________________________________________________________________ rrpGridGetCellWidth function function rrpGridGetCellWidth

Returns

the width of the cells in the grid in pixel units

Comment

In RRPG all cells have the same width. ___________________________________________________________________ rrpGridGetColCount function function rrpGridGetColCount
Returns

the number of columns in the grid

Comment

This 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 rrpGridGetColLabels
Returns

empty or a comma delimited list of labels

Comment

This 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, pCol

Returns

the color of the cell specified by the parameters

Parameters

pRow: the row of the cell pCol: the column of the cell
Comment

If the cell specified has no color or is outside the bounds of the grid, empty is returned. ___________________________________________________________________ rrpGridGetCursor function function rrpGridGetCursor
Returns

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

The 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 rrpGridGetCursorCol
Returns

the column of the cursor as an integer

Comment

The first column is numbered 1.

80

___________________________________________________________________ rrpGridGetCursorRow function function rrpGridGetCursorRow

Returns

the row of the cursor as an integer

Comment

The first row is numbered 1. ___________________________________________________________________ rrpGridGetDataAsHTML function function rrpGridGetDataAsHTML pTrim
Returns

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

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

The pTrim parameter can be omitted if the data is not to be trimmed. ___________________________________________________________________ rrpGridGetDataAsText function function rrpGridGetDataAsText
Returns

only the text contents of the entire grid as lines of tab delimited text
Parameters

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

The 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 rrpGridGetDataSize

Returns

The number of rows and columns in the grid as a comma delimited pair
Comment

The 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 rrpGridGetEditing
Returns

true if a cell is currently being edited

Comment

This function returns false unless a cell has the edit cursor in it to allow editing of the cell. ___________________________________________________________________ rrpGridGetFormatAt function function rrpGridGetFormatAt pRow, pCol
Returns

the encoded format of the cell specified by the parameters

Parameters

pRow: the row of the cell pCol: the column of the cell
Comment

The 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 rrpGridGetFrozenColCount

Returns

the number of frozen columns in the grid

Comment

This 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 rrpGridGetFrozenRowCount
Returns

the number of frozen rows in the grid

Comment

This 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 rrpGridGetHiliteCursorLabels
Returns

the state of the cHiliteCursorLabels property of the grid

Comment

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

83

___________________________________________________________________ rrpGridGetHScrollVisible function function rrpGridGetHScrollVisible

Returns

the state of the cHScrollVisible property of the grid

Comment

This function is a convenience for accessing the property of the grid frame object. ___________________________________________________________________ rrpGridGetModified function function rrpGridGetModified
Returns

the state of the cModified property of the grid

Comment

This function is a convenience for accessing the property of the grid frame object. ___________________________________________________________________ rrpGridGetNoCursorColCount function function rrpGridGetNoCursorColCount
Returns

the state of the cNoCursorColCount property of the grid

Comment

This function is a convenience for accessing the property of the grid frame object. ___________________________________________________________________ rrpGridGetNoCursorRowCount function function rrpGridGetNoCursorRowCount
Returns

the state of the cNoCursorRowCount property of the grid

Comment

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

84

___________________________________________________________________ rrpGridGetPropsAsText function function rrpGridGetPropsAsText pOnlyPublic

Returns

a list of the grid properties and the value of each value

Parameters

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

Comment

The 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 rrpGridGetRectangle
Returns

the rectangle of the actual grid inside the grid frame

Comment

The 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

Returns

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

pRow1: the row that specifies the top left corner of the region pCol1: the column that specifies the top left corner of the region pRow2: the row that specifies the bottom right corner of the region pCol2: the column that specifies the bottom right corner of the region
Comment

If the region specified is larger than the grid then the entire grid is returned. ___________________________________________________________________ rrpGridGetRegionAsText function function rrpGridGetRegionAsText pRow1, pCol1, pRow2, pCol2
Returns

only the text contents of the region of cells as as lines of tab delimited text
Parameters

pRow1: the row that specifies the top left corner of the region pCol1: the column that specifies the top left corner of the region pRow2: the row that specifies the bottom right corner of the region pCol2: the column that specifies the bottom right corner of the region
Comment

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

86

___________________________________________________________________ rrpGridGetRowCount function function rrpGridGetRowCount

Returns

the number of rows in the grid

Comment

This 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 rrpGridGetRowLabels
Returns

empty or a comma delimited list of labels

Comment

This 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 pIncludeFrozen
Returns

the selected cells as standard HTML tags such as <table> without any loss of information
Parameters

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

If 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 pIncludeFrozen

Returns

only the text contents of the selected cells as as lines of tab delimited text
Parameters

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

If the frozen rows or columns are to be included the selected cells must be immediately adjacent to the frozen cells. ___________________________________________________________________ rrpGridGetSelectedRegion function function rrpGridGetSelectedRegion
Returns

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

The 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 rrpGridGetShadeAlternateRows
Returns

the state of the cShadeAlternateRows property of the grid

Comment

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

88

___________________________________________________________________ rrpGridGetShadeCursorCol function function rrpGridGetShadeCursorCol

Returns

the state of the cShadeCursorCol property of the grid

Comment

This function is a convenience for accessing the property of the grid frame object. ___________________________________________________________________ rrpGridGetShadeCursorRow function function rrpGridGetShadeCursorRow
Returns

the state of the cShadeCursorRow property of the grid

Comment

This function is a convenience for accessing the property of the grid frame object. ___________________________________________________________________ rrpGridGetSize function function rrpGridGetSize
Returns

The number of rows and columns in the grid as a comma delimited pair
Comment

The 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, pCol

Returns

the style of the text in cell specified by the parameters as a string with plain, bold or italic
Parameters

pRow: the row of the cell pCol: the column of the cell
Comment

If the cell specified is outside the bounds of the grid, empty is returned. ___________________________________________________________________ rrpGridGetTopLeft function function rrpGridGetTopLeft
Returns

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

The first number in the list is the row and the second the column. ___________________________________________________________________ rrpGridGetVirtualMode function function rrpGridGetVirtualMode
Returns

the state of the cVirtualMode property of the grid

Comment

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

90

___________________________________________________________________ rrpGridGetVScrollVisible function function rrpGridGetVScrollVisible

Returns

the state of the cVScrollVisible property of the grid

Comment

This function is a convenience for accessing the property of the grid frame object. ___________________________________________________________________ rrpGridGetWrapAt function function rrpGridGetWrapAt pRow, pCol
Returns

true if the cell specified by the parameters can wrap the text of the cell over more than one line
Parameters

pRow: the row of the cell pCol: the column of the cell
Comment

By 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 rrpGridGetWrapCursorCol
Returns

the state of the cWrapCursorCol property of the grid

Comment

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

91

___________________________________________________________________ rrpGridGetWrapCursorRow function function rrpGridGetWrapCursorRow

Returns

the state of the cWrapCursorRow property of the grid

Comment

This function is a convenience for accessing the property of the grid frame object. ___________________________________________________________________ rrpGridGetHasSelection function function rrpGridGetHasSelection
Returns

true if the there are selected cells in the grid

Comment

If 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 pCol Adds a new column to the grid after the column specified in the parameter.
Parameters

pCol: the column that the new column is inserted after

Comment

The 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 pRow Adds a new row to the grid after the row specified in the parameter.
Parameters

pRow: the row that the new row is inserted after

Comment

The 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 pCol Adds a new column to the grid before the column specified in the parameter.
Parameters

pCol: the column that the new column is inserted before

Comment

The 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 pRow Adds a new row to the grid before the row specified in the parameter.
Parameters

pRow: the row that the new row is inserted before

Comment

The 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 rrpGridInsertColAfterCursor Adds a new column to the grid after the column of the cursor
Comment

The 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 rrpGridInsertColBeforeCursor Adds a new column to the grid before the column of the cursor
Comment

The 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 rrpGridInsertRowAfterCursor Adds a new row to the grid after the row of the cursor
Comment

The 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 rrpGridInsertRowBeforeCursor Adds a new row to the grid before the row of the cursor
Comment

The 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 rrpGridPasteAtCursor Pastes the contents of the clipboard into the grid starting from the position of the cursor.
Comment

This 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, pCol2 Prints the region of the grid specified by the parameters.
Parameters

pRow1: the row that specifies the top left corner of the region pCol1: the column that specifies the top left corner of the region pRow2: the row that specifies the bottom right corner of the region pCol2: the column that specifies the bottom right corner of the region
Comment

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

95

___________________________________________________________________ rrpGridRefresh command command rrpGridRefresh pDataOnly Redraws the grid to update its appearance.
Parameters

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

This 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, pCol Redraws a single cell in the grid to update its appearance.
Parameters

pRow: the row of the cell to be refreshed pCol: the column of the cell to be refreshed
Comment

This 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 rrpGridRefreshIsPending
Returns

true if the refresh pending flag has previously been set by the rrpGridSetRefreshPending command
Comment

This 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 rrpGridRemoveSelection Removes the selection, if any, from the grid so only the cursor cell is selected.
Comment

This command redraws the grid to remove the selection from the cells. ___________________________________________________________________ rrpGridReset command command rrpGridReset Resets the grid to its default appearance and behavior.
Comment

This command is useful after experimenting with the properties of the grid and you want to return everything to its initial state. ___________________________________________________________________ rrpGridResetActive command command rrpGridResetActive Resets the grid that RRPG is handling as the active grid.
Comment

After 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 rrpGridResetColors Resets the grid to its default colors.
Comment

This 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 rrpGridSelectAll Select all the cells in the grid.
Comment

This command does not select any frozen cells. ___________________________________________________________________ rrpGridSelectCol command command rrpGridSelectCol Select all cells in the cursor column of the grid.
Comment

This command does not select any frozen cells. ___________________________________________________________________ rrpGridSelectRow command command rrpGridSelectRow Select all cells in the cursor row of the grid.
Comment

This command does not select any frozen cells.

98

___________________________________________________________________ rrpGridSetActiveAuto command command rrpGridSetActiveAuto Sets the grid on the current stack as the active grid affected by the RRPG commands and functions.
Comment

You 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. Parameters pID: The ID of the grid frame graphic object
Comment

You 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 pName Sets the grid on the current stack with the name as the active grid affected by the RRPG commands and functions. Parameters pName: The name of the grid frame graphic object
Comment

You 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 pColor Sets the cAlternateRowColor property of the grid that specifies the color used when alternate rows are shaded.
Parameters

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

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

100

___________________________________________________________________ rrpGridSetCacheVirtual command command rrpGridSetCacheVirtual pEnable Sets 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.
Parameters

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

Comment

This 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, pNoRefresh Changes is the text contents of the cell in the grid specified by the parameters.
Parameters

pRow: the row of the cell pCol: the column of the cell pCell: the text to put in the cell pNoRefresh: if false the visible cells in the grid are not updated
Comment

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.

101

___________________________________________________________________ rrpGridSetCellBorderColor command command rrpGridSetCellBorderColor pColor Sets the cCellBorderColor property of the grid that specifies the color of the cell borders.
Parameters

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

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetCellColor command command rrpGridSetCellColor pColor Sets the cCellColor property of the grid that specifies the color of the cells that are not selected or at the cursor.
Parameters

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

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

102

___________________________________________________________________ rrpGridSetCellHeight command command rrpGridSetCellHeight pHeight Sets the cCellHeight property of the grid that specifies the height of the cells in the grid.
Parameters

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

This 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 pTextFont Sets the cCellTextFont property of the grid that specifies the text font of the cells in the grid.
Parameters

pTextFont: empty or a valid font name

Comment

This 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 pSize Sets the cCellTextSize property of the grid that specifies the size of the text in the cells in the grid.
Parameters

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

Comment

This 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 pWidth Sets the cCellWidth property of the grid that specifies the width of the cells in the grid.
Parameters

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

This 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 pCount Sets the cColCount property of the grid that specifies the number of columns in the grid.
Parameters

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

Comment

This 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 pLabels Sets the cColLabels property of the grid that specifies the text of the column labels.
Parameters

pLabels: a comma delimited list of labels

Comment

This 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 pEnable Sets the cColorMode property of the grid that specifies whether cells can by given individual colors.
Parameters

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

Comment

This 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, pCol Moves the cursor to the cell specified by the parameters.
Parameters

pRow: the row of the cell pCol: the column of the cell
Comment

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

106

___________________________________________________________________ rrpGridSetCursorCol command command rrpGridSetCursorCol pCol Moves the cursor to the cell with the column specified by the parameter without changing the row.
Parameters

pCol: the column of the cell

Comment

If necessary, the grid is scrolled to make the cursor cell visible. ___________________________________________________________________ rrpGridSetCursorColor command command rrpGridSetCursorColor pColor Sets the cCursorColor property of the grid that specifies the color of the cell at the cursor.
Parameters

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

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetCursorRow command command rrpGridSetCursorRow pRow Moves the cursor to the cell with the row specified by the parameter without changing the column.
Parameters

pRow: the row of the cell

Comment

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

107

___________________________________________________________________ rrpGridSetCursorRowColColor command command rrpGridSetCursorRowColColor pColor Sets the cCursorRowColColor property of the grid that specifies the color used when the cursor row or column is shaded.
Parameters

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

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetDataAt command command rrpGridSetDataAt pData, pRow, pCol Puts HTML or plain text data into the grid starting from the specified cell.
Parameters

pData: the grid data in a HTML format pRow: the starting row for the data pCol: the starting column for the data
Comment

The 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, pPreserveCursor Replaces all the data in the grid with the HTML data specified in the parameter.
Parameters

pData: the grid data in a HTML format pPreserveCursor: true, false or empty
Comment

The 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, pPreserveCursor Replaces all the data in the grid with the text data specified in the parameter.
Parameters

pData: the grid data in a text format pPreserveCursor: true, false or empty
Comment

The 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, pColCount Sets the number of rows and columns in the grid as specified in the parameters. Parameters pRowCount: an integer between than 1 and 1,000,000 inclusive pColCount: an integer between than 1 and 1,000,000 inclusive
Comment

The 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 pColor Sets the cEditColor property of the grid that specifies the color of the cell that is being edited.
Parameters

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

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

110

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

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

Comment

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetEditOnF2 command command rrpGridSetEditOnF2 pEnable Sets the cEditOnF2 property of the grid that specifies whether editing is started by pressing the F2 function key.
Parameters

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

Comment

This 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.
Parameters

pRow: the row of the cell pCol: the column of the cell pFormat: the format of the cell in an encoded string pNoRefresh: if false the visible cells in the grid are not updated
Comment

The 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 pVisible Sets the cFrameVisible property of the grid that specifies whether the grid frame is visible.
Parameters

pVisible: true or false

Comment

This 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 pFrozenCount Sets the cFrozenColCount property of the grid that specifies the number of frozen columns in the grid
Parameters

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

This 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 pColor Sets the cFrozenColor property of the grid that specifies the color of any frozen rows or columns
Parameters

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

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

113

___________________________________________________________________ rrpGridSetFrozenColTextSize command command rrpGridSetFrozenColTextSize pSize Sets the cFrozenColTextSize property of the grid that specifies the size of the text in the cells in the grid.
Parameters

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

Comment

This 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 pWidths Sets the cFrozenColWidths property of the grid that specifies the widths of the cells in the frozen columns of the grid.
Parameters

pWidths: empty or a comma delimited list of widths

Comment

This 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 pFrozenCount Sets the cFrozenRowCount property of the grid that specifies the number of frozen rows in the grid
Parameters

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

This 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 pHeights Sets the cFrozenRowHeights property of the grid that specifies the heights of the cells in the frozen rows of the grid.
Parameters

pHeights: empty or a comma delimited list of heights

Comment

This 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 pSize Sets the cFrozenRowTextSize property of the grid that specifies the size of the text in the cells in the grid.
Parameters

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

Comment

This 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 pEnable Sets the cHeightCanStretch property of the grid that specifies whether the height of the grid can change when the size of the stack changes.
Parameters

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

Comment

This 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 pEnable Sets 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.
Parameters

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

Comment

This 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 pVisible Sets the cHScrollVisible property of the grid that specifies whether the horizontal scroll bar is visible along the bottom edge of the grid
Parameters

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

Comment

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

117

___________________________________________________________________ rrpGridSetLabelHeight command command rrpGridSetLabelHeight pHeight Sets the cLabelHeight property of the grid that specifies the height of (or hides) the column labels.
Parameters

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

This 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 pSize Sets the cLabelTextSize property of the grid that specifies the size of the text in the labels in the grid.
Parameters

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

Comment

This 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 pWidth Sets the cLabelWidth property of the grid that specifies the width of (or hides) the row labels.
Parameters

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

This 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 pEnable Sets the cMessageMode property of the grid that specifies whether messages are sent when the user interacts with the grid.
Parameters

pEnable: true or false, if true messages are sent

Comment

This 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 pNoCursorCount Sets the cNoCursorColCount property of the grid that controls whether frozen column cells can be edited.
Parameters

pNoCursorCount: value between 0 and the cFrozenColCount, inclusively

Comment

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetNoCursorRowCount command command rrpGridSetNoCursorRowCount pNoCursorCount Sets the cNoCursorRowCount property of the grid that controls whether frozen row cells can be edited.
Parameters

pNoCursorCount: value between 0 and the cFrozenRowCount, inclusively

Comment

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

120

___________________________________________________________________ rrpGridSetPrintFooter command command rrpGridSetPrintFooter pFooter Sets the cPrintFooter property of the grid that specifies the footer shown at the bottom of the page when printing the grid.
Parameters

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

Comment

This 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 pColor Sets the cPrintLabelColor property of the grid that specifies the color of the row and column labels when printing the grid.
Parameters

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

This 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 pColor Sets the cPrintLabelTextColor property of the grid that specifies the color of the row and column label text when printing the grid.
Parameters

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

This 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 pProps Sets the grid properties from the list specified in the parameter.
Parameters

pProps: the list of properties

Comment

This 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.
Parameters

pLeft: the position of the left edge pTop: the position of the top edge pRight: the position of the right edge pBottom: the position of the bottom edge
Comment

This 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 pEnable Sets the cReadOnly property of the grid that specifies whether the user can change the data in the grid.
Parameters

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

Comment

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

123

___________________________________________________________________ rrpGridSetRefreshIsPending command command rrpGridSetRefreshPending Sets an internal refresh pending flag that can be read with the rrpGridRefreshIsPending function.
Comment

This 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 pEnable Sets 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.
Parameters

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

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

124

___________________________________________________________________ rrpGridSetRowColCount command command rrpGridSetColCount pRowCount, pColCount Sets the cRowCount and cColCount properties of the grid that specify the number of rows and columns in the grid.
Parameters

pRowCount: an integer between than 1 and 1,000,000 inclusive pColCount: an integer between than 1 and 1,000,000 inclusive
Comment

This 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 pCount Sets the cRowCount property of the grid that specifies the number of rows in the grid.
Parameters

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

Comment

This 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 pLabels Sets the cRowLabels property of the grid that specifies the text of the row labels.
Parameters

pLabels: a comma delimited list of labels

Comment

This 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 pAlign Sets the alignment of the selected cells in the grid to the parameter.
Parameters

pAlign: left, center, or right

Comment

If 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.
Parameters

pRow1: the row that specifies the top left corner of the region pCol1: the column that specifies the top left corner of the region pRow2: the row that specifies the bottom right corner of the region pCol2: the column that specifies the bottom right corner of the region
Comment

To remove the selection from the grid, call this handler with pRow2 equal to pRow1 and pCol2 equal to pCol1. ___________________________________________________________________ rrpGridSetSelectedColor command command rrpGridSetSelectedColor pColor Sets the color of the selected cells in the grid to the parameter.
Parameters

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

If there is no selection, the color is applied to the cursor cell. ___________________________________________________________________ rrpGridSetSelectedReadOnly command command rrpGridSetSelectedReadOnly pReadOnly Sets the read only property of the selected cells in the grid.
Parameters

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

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

127

___________________________________________________________________ rrpGridSetSelectedStyle command command rrpGridSetSelectedStyle pStyle, pEnable Sets the style of the selected cells in the grid to the first parameter.
Parameters

pStyle: 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
Comment

Only 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 pEnable Sets whether the selected cells in the grid can wrap cells with long text over more than one line
Parameters

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

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

128

___________________________________________________________________ rrpGridSetSelectionColor command command rrpGridSetSelectionColor pColor Sets the cSelectionColor property of the grid that specifies the color of the selected cells
Parameters

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

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetShadeAlternateRows command command rrpGridSetShadeAlternateRows pEnable Sets the cShadeAlternateRows property of the grid that specifies whether the alternate rows are shaded.
Parameters

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

Comment

This 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 pEnable Sets the cShadeCursorCol property of the grid that specifies whether the column with the cursor is shaded.
Parameters

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

Comment

This 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 pEnable Sets the cShadeCursorRow property of the grid that specifies whether the row with the cursor is shaded.
Parameters

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

Comment

This 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, pLeft Scrolls the grid so the visible cell in the top left corner is the cell specified by the parameters
Parameters

pTop: the row of the cell in the top left corner pLeft: the column of the cell in the top left corner
Comment

If 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 pEnable Sets the cVirtualMode property of the grid that specifies whether the grid is the virtual mode, where the data is not stored in the grid.
Parameters

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

This 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 pVisible Sets the cVScrollVisible property of the grid that specifies whether the vertical scroll bar is visible along the right edge of the grid
Parameters

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

Comment

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetWidthCanStretch command command rrpGridSetWidthCanStretch pEnable Sets the cWidthCanStretch property of the grid that specifies whether the width of the grid can change when the size of the stack changes.
Parameters

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

Comment

This 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 pEnable Sets 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.
Parameters

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

Comment

This handler is a convenience for setting the corresponding property of the grid frame object. ___________________________________________________________________ rrpGridSetWrapCursorRow command command rrpGridSetWrapCursorRow pEnable Sets 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.
Parameters

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

Comment

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

133

___________________________________________________________________ rrpGridUpdateScripts command command rrpGridUpdateScripts pID Updates the internal scripts used by the the grid on the current stack with the ID. Parameters pID: The ID of the grid frame graphic object
Comment

This 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