Graphics Environment: 8.4 Graphics Strings: Creating GStrings Dynamically

GEOS SDK TechDocs

8.3 Declaring a GString Statically

8.5 Drawing and Scanning

Sometimes it comes in handy to be able to create GStrings "on the fly." To add elements to a GString, issue normal kernel drawing commands, but use a GState which is associated with the GString.

To create a new, empty GString ready for editing (i.e. with an attached GState), call GrCreateGString() . At this point, you may draw to the GString using normal drawing commands. For an example of creating a GString in this manner, see Creating a GString Dynamically.

Code Display 23-6 Creating a GString Dynamically

#define LABEL_BOX    2
#define LABEL_CIRCLE 3

gstate = GrCreateGString(file, GST_VMEM, &myVMBlock);

GrSetLineColor(gstate, CF_INDEX, C_BLUE, 0, 0);
GrDrawRect(gstate, 0, 0, 620, 500);

GrLabel(gstate, LABEL_BOX);
GrSetAreaColor(gstate, CF_INDEX, C_RED, 0, 0);
GrFillRect(gstate, 10, 130, 610, 490);
GrSetLineWidth(gstate, MakeWWFixed(2));

GrLabel(gstate, LABEL_CIRCLE);
GrSetAreaColor(gstate, CF_INDEX, C_RED, 0, 0);
GrFillEllipse(gstate, 130, 10, 490, 370);
GrDrawEllipse(gstate, 130, 10, 490, 370);

GrEndGString(gstate);
GrDestroyGString(gstate, 0, GSKT_LEAVE_DATA);

Drawing to a GString in this manner is almost exactly like drawing in any other GEOS graphics environment. However, there are some important rules to keep in mind.

• The GString must end with a GR_END_GSTRING element; when the GString interpreter encounters this element, it knows to stop drawing. When creating a GString dynamically, the normal way to assure this is to call GrEndGString() . (Actually, this rule is not strictly true--when you learn more about drawing GStrings, you will see that it is possible to stop GString drawing based on other cues. However, it's always safest to end the GString with a GR_END_GSTRING in case some other application tries to draw the same GString.)
• Remember that you are creating a data structure which will be used later. The only commands which will affect the GString's contents are the kernel graphics routines, and only those which actually draw something or change the drawing properties. When creating a GString, it is tempting to include constructions like the following:

if (redFlag)
	{GrSetAreaColor(
		gstate, C_RED, CF_INDEX, 0, 0);}
else  {GrSetAreaColor(
		gstate, C_BLUE,CF_INDEX, 0, 0);}
GrFillRect(gstate, 0, 0, 72, 72);

• You might be surprised when you found out that the following code fragments both drew rectangles which were the same color:

redFlag = FALSE; 
GrDrawGString(			screenGState, 
			myGString, 
			0, 0, 0, elem);
redFlag = TRUE; 
GrDrawGString(			screenGState, 
			myGString, 
			0, 0, 0, elem);

• The factor which would determine the color of the drawing in this example would be the value of redFlag when you were creating the GString, not when you were drawing it.
• Think carefully before making coordinate space transformations in GStrings. If you want to remove all transformation effects, you should always call GrSetDefaultTransform() , instead of GrSetNullTransform() . By using GrSetDefaultTransform() , an application that is including your GString can apply some other type of transformation and make that the default; your application will then appear transformed as intended. However, if you call GrSetNullTransform() , you ignore that default transform and will appear in a strange way.
• If you use GrInitDefaultTransform() , you should probably bracket its use with calls to GrSaveTransform() and GrRestoreTransform() . This save/restore pair will also save the current default transformation, if there is one. By adding the save and restore, you will be preserving whatever default transform the application including yours has set up.
• If you think your Graphics String will never show up included in some other application, consider the following: The print-to-file feature creates a graphics string that can be imported into several other applications.
• If you think you have to use GrSetTransform() , try replacing it with a GrSetDefaultTransform() / GrApplyTransform() pair. This will most likely have the same effect, but will be more palatable to another application using the GString.
• If you are including some other externally-created Graphics String into your document, you probably want to bracket it with GrSaveState() and GrRestoreState() .
• If you're creating a multi-page GString which might be printed, make sure that each page is independent. There should be nothing assumed about the GState at the beginning of any page--you should instead assume that each will begin with the default GState. This applies to transformations, drawing properties, the GState's path, and so on.
  Keep in mind that each page should be able to print by itself if extracted from a multi-page document.
  The following pseudocode is an example of a "bad" idea:

for(curPage=0;curPage < numberOfPages; curPage++) {
 /* { draw current page } */
 GrNewPage();
 GrApplyTranslation(0, pageHeight); }

• The following pseudocode provides a "better" way to do the same thing:

for (curPage=0; curPage < numberOfPages; curPage++) { GrSaveState();
  GrApplyTranslation(0,curPage*pageHeight);
  /* {draw current page} */
 GrRestoreState();
 GrNewPage(); }

Probably the most important piece of advice is to think about how the Graphics String will be used. If it will be used only under certain well-controlled circumstances, the above concerns may not affect you.

GEOS SDK TechDocs

8.3 Declaring a GString Statically

8.5 Drawing and Scanning