Query class overview

If you are new to programming with the PageMaker Class Library, this section contains some useful information about query classes. You should also review the command class overview for information about command classes.

Query classes are C++ classes that perform a query callback to PageMaker. They are used in PageMaker plug-ins to retrieve information from PageMaker. Typical queries include obtaining the current page number, retrieving a list of objects on a particular page, or listing the fonts installed in the system. Nearly any information a user can view within PageMaker menus, dialogs, or directly in the publication window can be retrieved with query objects.

Query results

The public interface to get information from a query object depends on the type of query. The information returned from queries can be:

a single value, which may be fixed (e.g., a 16-bit short) or variable length (a string),
a block, or structure of values, which may be fixed (no strings) or variable length (one or more strings),
a list of values, which may be single values or blocks, or
an initial block of values followed by a list.

Because of this complexity, the interface to query objects has some unique features. To show how the interface works, let's begin with two simple examples and work our way up.

PGetLeading lead; // Get current leading value (a short)
if (lead == 12) ... // compare value to another short
PGetPubName pubName; // Get current publication name
strcat(x, pubName); // copy name to x

In these two cases, the query is a single value, and thus we treat the object itself as if it were the return value. Operator overloading is used in these classes.

The next example shows how to access a query object that contains a block of information.

PGetSpaceOptions spaceOptions; if (spaceOptions.bAutoKerning == true && spaceOptions.cLeading >lead) ...

The PGetSpaceOptions class contains public variables with names corresponding to the names used in the PageMaker SDK Guide. For single value queries, or string values, the query object acts as a readonly structure. You cannot assign a new value to a query object field:

strcpy(spaceOptions.sInkName, "wacky green"); // ERROR!
PGetLeading lead; // Get current leading value (a short)
lead = 12; // ERROR!
PLeading setLead(12); // Use command object instead.

The next example illustrates a query that contains a list of information.

The PGetColorInfo query returns a complex data structure with an initial block of information, followed by a list. Both the initial block and the list items are variable length because they each contain strings.

PGetColorInfo colorInfo(-2, "mauve"); short theType = colorInfo.cType;// check type
strcpy(x, colorInfo.sInkName); // first ink name in list
short ink = colorInfo.dInkLevel; // first ink level

Use the Count() member function to find out how many items are on the list. You can then iterate over the list using the postfix operator++ on the object. Operator++ wraps around when it gets to the end of the list, or you can use the Reset() function to reset the list to its first item.

short i, j, numColors = colorInfo.Count(); for (i = 0 ; i < numColors; i++) { strcpy(x, colorInfo.sInkName);// get i-th ink name
if (colorInfo.dInkLevel > threshold) // and ink level
break; colorInfo++;// iterate the object
} colorInfo.Reset();// so next iteration starts at beginning

You should always check Count() before referencing object variables that are part of the list, such as colorInfo.sInkName. If Count() == 0, the values of these variables are undefined, but the object cannot detect the error. Operator++() will throw an exception (CQ_FAILURE), however, if there are no list members.

Comments or suggestions? Contact Adobe Developer Support