6 Graphic Sheets - Basic graphic operations

creates a graphic sheet with title title and dimension width by height. A graphic sheet is the basic tool to draw something, it is like a piece of paper on which you can put your graphic objects, and to which you can attach your menus. The coordinate (0,0) is the upper left corner, (width −1,height −1) the lower right.

It is possible to change the default behaviour of a graphic sheet by installing methods (or sometimes called callbacks) for the following events. In order to avoid confusion with the GAP term ``method'' the term ``callback'' will be used in the following. For example, to install the function MyLeftPBDownCallback as callback for the left mouse button down event of a graphic sheet sheet, you have to call InstallCallback as follows.

gap> InstallCallback( sheet, "LeftPBDown", MyLeftPBDownCallback );

XGAP stores for each graphic sheet a list of callback keys and a list of callback functions for each key. That means that when a certain callback key is triggered for a graphic sheet then the corresponding list of callback functions is called one function after the other. The following keys have predefined meanings which are explained below: Close, LeftPBDown, RightPBDown, ShiftLeftPBDown, ShiftRightPBDown, CtrlLeftPBDown, CtrlRightPBDown. All of these keys are strings. You can install your own callback functions for new keys, however they will not be triggered automatically.

the function will be called as soon as the user selects ``close graphic sheet'', the installed function gets the graphic sheet sheet to close as argument.

the function will be called as soon as the user presses the left mouse button inside the graphic sheet, the installed function gets the graphic sheet sheet, the x coordinate and y coordinate of the pointer as arguments.

same as LeftPBDown except that the user has pressed the right mouse button.

same as LeftPBDown except that the user has pressed the left mouse button together with the SHIFT key on the keyboard.

same as LeftPBDown except that the user has pressed the right mouse button together with the SHIFT key on the keyboard.

same as LeftPBDown except that the user has pressed the left mouse button together with the CTRL key on the keyboard.

same as LeftPBDown except that the user has pressed the right mouse button together with the CTRL key on the keyboard.

Here is the documentation for the operations to control the callback functions:

Installs a new callback function for the sheet sheet for the key key. Note that the old functions for this key are not deleted.

Removes an old callback. Note that you have to specify not only the key but also explicitly the func which should be removed from the list!

Executes all callback functions of the sheet sheet that are stored under the key func with the argument list args.

Every graphic object in XGAP can be alive or not. This is controlled by the filter IsAlive. Being alive means that the object can be used for further operations. If for example the user closes a window by a mouse operation the corresponding graphic sheet object is no longer alive.

This filter controls if a graphic object is alive, meaning that it can be used for further graphic operations.

The following operations apply to graphic sheets:

The graphic sheet sheet is closed which means that the corresponding window is closed and the sheet becomes not alive.

The width and height of the sheet sheet are changed. That does not automatically mean that the window size is changed. It may also happen that only the scrollbars are changed.

Every graphic sheet has a unique number, its window id. This is mainly used internally.

Every graphic sheet has a title which appears somewhere on the window. It is initially set via the call to the constructor GraphicSheet and can be changed later with this operation.

Saves the graphics in the sheet sheet as postscript into the file filename, which is overwritten, if it exists.

Switches the UseFastUpdate filter for the sheet sheet to the boolean value of flag. If this filter is set for a sheet, the screen is no longer updated completely if a graphic object is moved or deleted. You should call FastUpdate( sheet, true ) before you start large rearrangements of the graphic objects and FastUpdate( sheet, false ) at the end.

6.2 Graphic Objects in Sheets

All graphics within graphic sheets are so called graphic objects. They are GAP objects in the category IsGraphicObject. These objects are linked internally to the actual graphics within the window. You can modify these objects via certain operations which leads to the corresponding change of the real graphics on the screen. The types of graphic objects supported in XGAP are: boxes, circles, discs, diamonds, rectangles, lines, texts, vertices and connections. Vertices are compound objects consisting of a circle, rectangle or diamond with a short text inside. They remember their connections to other vertices. That means that if for example the position of a vertex is changed, the line which makes the connection to some other vertex is also changed automatically. For every graphic object there is a constructor which has the same name as the graphic object (e.g. Box is the constructor for boxes).

This is the category in which all graphic objects are.

Constructors:

creates a new graphic object, namely a filled black box, in the graphic sheet sheet and returns a GAP record describing this object. The four corners of the box are (x ,y ), (x +w ,y ), (x +w ,y +h ), and (x ,y +h ).

Note that the box is w +1 pixel wide and h +1 pixels high.

If a record defaults is given and contains a component color of value color, the function works like the first version of Box, except that the color of the box will be color. See Color Models for how to select a color.

See operations for graphic objects for a list of operations that apply to boxes.

Note that Reshape for boxes takes three parameters, namely the box object, the new width, and the new height of the box.

creates a new graphic object, namely a black circle, in the graphic sheet sheet and returns a GAP record describing this object. The center of the circle is (x ,y ) and the radius is r .

If a record defaults is given and contains a component color of value color, the function works like the first version of Circle, except that the color of the circle will be color. See Color Models for how to select a color. If the record contains a component width of value width, the line width of the circle is set accordingly.

See operations for graphic objects for a list of operations that apply to circles.

Note that Reshape for circles takes two parameters, namely the circle object, and the new radius of the circle.

creates a new graphic object, namely a disc (a black filled circle), in the graphic sheet sheet and returns a GAP record describing this object. The center of the disc is (x ,y ) and the radius is r .

If a record defaults is given and contains a component color of value color, the function works like the first version of Disc, except that the color of the disc will be color. See Color Models for how to select a color.

See operations for graphic objects for a list of operations that apply to discs.

Note that Reshape for discs takes two parameters, namely the disc object, and the new radius.

creates a new graphic object, namely a black diamond, in the graphic sheet sheet and returns a GAP record describing this object. The left corner of the diamond is (x ,y ), the others are (x +w ,y −h ), (x +w ,y +h ), and (x +2w ,y ).

If a record defaults is given and contains a component color of value color, the function works like the first version of Diamond, except that the color of the diamond will be color. See Color Models for how to select a color. If the record contains a component width with integer value width, the line width is set accordingly.

See operations for graphic objects for a list of operations that apply to diamonds.

Note that Reshape for diamonds takes three parameters, namely the diamond object, and the new width and height values.

creates a new graphic object, namely a black rectangle, in the graphic sheet sheet and returns a GAP record describing this object. The four corners of the box are (x ,y ), (x +w ,y ), (x +w ,y +h ), and (x ,y +h ).

Note that the rectangle is w +1 pixel wide and h +1 pixels high.

If a record defaults is given and contains a component color of value color, the function works like the first version of Rectangle, except that the color of the rectangle will be color. See Color Models for how to select a color. If the record contains a component width with integer value width, the line width is set accordingly.

See operations for graphic objects for a list of operations that apply to rectangles.

Note that Reshape for rectangles takes three parameters, namely the rectangle object, and the new width and height values.

creates a new graphic object, namely a black line, in the graphic sheet sheet and returns a GAP record describing this object. The line has the end points (x ,y ) and (x +w ,y +h ).

If a record defaults is given and contains a component color of value color, the function works like the first version of Line, except that the color of the line will be color. See Color Models for how to select a color. If the record contains a component width with integer value width, the line width is set accordingly. If the record contains a component label with a string value label, a text object is attached as a label to the line.

See operations for graphic objects for a list of operations that apply to lines.

Note that Reshape for lines takes three parameters, namely the line object, and the new w and h value. Change for lines in contrast takes five parameters, namely the line object and all four coordinates like in the original call.

creates a new graphic object, namely the string str as a black text, in the graphic sheet sheet and returns a GAP record describing this object. The text has the baseline of the first character at (x,y).

If a record defaults is given and contains a component color of value color, the function works like the first version of Text, except that the color of the text will be color. See Color Models for how to select a color.

See operations for graphic objects for a list of operations that apply to texts.

Note that Reshape for texts takes two parameters, namely the text object, and the new font. Use Relabel to change the string of the text.

Operations for graphic objects:

Connects two vertices with a line. The second variation can get a defaults record for the actual line. The same entries as in the defaults record for lines are allowed.

Deletes connection between two vertices.

This operation (re-)draws a graphic object on the screen. You normally do not need to call this yourself. But in some rare cases of object overlaps you could find it useful.

Deletes a graphic object. Calls Destroy first, so the graphic object is no more alive afterwards. The object is deleted from the list of objects in its graphic sheet. There is no way to reactivate such an object afterwards.

Destroys a graphic object. It disappears from the screen and will not be alive any more after this call. Note that object is not deleted from the list of objects in its graphic sheet sheet. This makes it possible to Revive it again. In order to delete object from sheet, use Delete( sheet, obj ), which calls Destroy for obj.

Note that object must be in the list of objects in its graphic sheet! So this is only possible for Destroyed, not for Deleted graphic objects.

Changes the position of a graphic object absolutely. It must be alive and will be moved at once on the screen.

Changes the position of a graphic object relatively. It must be alive and will be moved at once on the screen.

Creates a postscript string which describes the graphic object. Normally you do not need to call this because it is only used internally if the user exports the whole graphic sheet to encapsulated postscript.

This operation prints debugging info about a graphic object.

Changes the color of a graphic object. See Color Models for how to select a color.

Changes the shape of a graphic object. The parameters depend on the type of the object. See the descriptions of the constructors for the actual usage.

This infix operation needs a vector of two integers to its left and a graphic object to its right (``vector of two integers'' means a list of two integers e.g. [15,9]). It determines, if the position given by the two integer coordinates is inside (e.g. for boxes) or on (e.g. for lines) the graphic objects. Returns a boolean value.

Changes the shape of a graphic object. The parameters depend on the type of the object. See the descriptions of the constructors for the actual usage.

Changes the label of a graphic object. The second argument must always be a string.

Changes the line width of the graphic object. The line width w must be a relatively small integer.

In the first form this operation switches the highlighting status of a vertex to ON. In the second form the flag decides about ON or OFF. Highlighting normally means a thicker line width and a change in color.

6.3 Colors in XGAP

labelColor Models

Depending on the type of display you are using, there may be more or fewer colors available. You should write your programs always such that they work even on monochrome displays. In XGAP these differences can be read off from the so called ``color model''. The global variable COLORS contains all available information.

The variable COLORS contains a list of available colors. If an entry is false this color is not available on your screen. Possible colors are: "black", "white", "lightGrey", "dimGrey", "red", "blue", and "green".

The following example opens a new graphic sheet (see GraphicSheet), puts a black box (see Box) onto it and changes its color. Obviously you need a color display for this example.

gap> sheet := GraphicSheet( "Nice Sheet", 300, 300 );
<graphic sheet "Nice Sheet">
gap> box := Box( sheet, 10, 10, 290, 290 );
<box>
gap> Recolor( box, COLORS.green );
gap> Recolor( box, COLORS.blue );
gap> Recolor( box, COLORS.red );
gap> Recolor( box, COLORS.lightGrey );
gap> Recolor( box, COLORS.dimGrey );
gap> Close(sheet);

The component model is always a string. It is monochrome, if the display does not support colors. It is gray if we only have gray shades and colorX if we have colors. The ``X'' can be either 3 or 5, depending on how many colors are available.

6.4 Operations for Graphic Objects

The following table gives an overview over the supported graphic objects and the functions which are applicable respectively:

Here are the supported graphic object types: Box, Circle, Disc, Diamond, Rectangle, Line, Text, Vertex.

These functions apply to all graphic object types: Draw, Delete, Destroy, Revive, Move, MoveDelta, PSString, PrintInfo, ViewObj, Recolor, Reshape, \in, WindowId

In addition, the operation Relabel applies to objects of types Line, Text, and Vertex; the operation SetWidth applies to objects of types Diamond, Rectangle, Circle, and Line. There is also Change for a Line and Highlight for a Vertex.

6.5 Global Information

There are some global data structures which can and should be consulted if certain information is needed. The first (about color handling) was already described in section Color Models. The second is for vertices:

This globally bound record contains the following components:

circle

integer value for the vertex type ``circle''

diamond

integer value for the vertex type ``diamond''

rectangle

integer value for the vertex type ``rectangle''

radius

radius in pixels of a vertex on the screen

diameter

diameter in pixels of a vertex on the screen

The third structure is about the available fonts.

This globally bound record has the following components: tiny, small, normal, large, huge and fonts. The first 5 are itself records each for one available font. They have components name for the name of the font and fontInfo, which is a list of 3 integers. The first is the maximal size of a character above the baseline in pixels, the second is the maximal size of a character below the baseline in pixels, and the third is the width in pixels of all characters, because it is always assumed, that the fonts are non-proportional.

Returns the information about the font font. The result is a triple of integers. The first number is the maximal size of a character above the baseline in pixels, the second is the maximal size of a character below the baseline in pixels, and the third is the width in pixels of all characters, because it is always assumed, that the fonts are non-proportional. Use this function rather than accessing the component fontInfo of a font object directly!

There is another global structure:

This record contains the following components: left and right contain a number for the left resp. right mouse button. shift and ctrl contain codes for the respective keys on the keyboard.

You should always use these global data instead of hardwiring any integers into your code.

[Up] [Previous] [Next] [Index]