Graphics Environment: 8.2 Graphics Strings: Special Drawing Commands

| Up: GEOS SDK TechDocs| Up | Prev: 8.1 Storage and Loading | Next: 8.3 Declaring a GString Statically 
GrEndGString(), GrNewPage(), GrLabel(), GrComment(), GrNullOp(), GrEscape(), GrSetGStringBounds()

There are certain kernel graphics commands which, though they could be used when drawing to any graphics space, are normally only used when describing GStrings. Most of these commands have no visible effect, but only serve to provide the GString with certain control codes.

The most commonly used of these routines is GrEndGString() . This signals that you are done describing the GString, writing a GR_END_GSTRING to the GString. This routine will let you know if there was an error while creating the GString (if the storage device ran out of space). Its macro equivalent is GSEndString() .

The GrNewPage() routine signals that the GString is about to start describing another page. GStrings are used to describe things to be sent to the printer, and unsurprisingly, this routine is often used in that context. An example of a prototype multi-page printing loop is shown in Multi-Page Printing Loop. Whether or not it is drawing to a GString, GrNewPage() causes the GState to revert to the default. When calling this routine, specify whether or not a form-feed signal should be generated by means of the PageEndCommand argument.

Code Display 23-1 Multi-Page Printing Loop

/* The application this code fragment is taken from stores several pages of 
 * graphics in one coordinate space. The pages are arranged each below the other.
 * To display page #X, we would scroll down X page lengths. */
for (curPage=0; curPage < numberOfPages; curPage++) {
	GrSaveState(gstate);
	GrApplyTranslation(gstate, 0,MakeWWFixed(curPage*pageHeight));
	/* ...Draw current page... */
	GrRestoreState(gstate);
	GrNewPage(gstate, PEC_NO_FORM_FEED );}

The GrLabel() routine inserts a special element into the GString. This element does not draw anything. However, these GString labels, as they are called, are often used like labels in code. By using GString drawing routines with a certain option (described below), you may "jump" to this label and start drawing from that point in the GString. Alternately, you could start at some other part of the GString and automatically draw until you encountered that label.

The GrComment() routine inserts an arbitrary-length string of bytes into the GString which the GString interpreter will ignore when drawing the GString. You might use this to store anything from custom drawing commands which only your geode has to be able to understand to a series of blank bytes which could act as a sort of placeholder in memory.

Code Display 23-2 GSComment Example

static const byte MyGString[] = {
	GSComment(20), 'C','o','p','y','l','e','f','t',' ','1','9','9','3',
	' ','P','K','i','t','t','y', 
	GSDrawEllipse(72, 72, 144, 108), 
	GSEndString()};

The GrNullOp() routine draws nothing and does nothing other than take up space in the GString (a single-byte element of value GR_NOP). You might use it as a placeholder in the GString.

The GrEscape() writes an escape code with accompanying data to the GString. Most geodes do not use this functionality; you might use it to embed special information in a TransferItemFormat based on GStrings.

Depending on what the system will do with your GString, the bounds of the GString may be used for many purposes. Normally the system determines the bounds of a GString by traversing the whole GString and finding out how much space it needs to draw. The GrSetGStringBounds() allows you to optimize this, setting up a special GString element whose data contains the bounds of the GString. You should call this routine early on in your GString definition so that the system won't have to traverse very much of your GString to discover the special element.

| Up: GEOS SDK TechDocs| Up | Prev: 8.1 Storage and Loading | Next: 8.3 Declaring a GString Statically