[xgap] 6.1 Graphic Sheet Objects

[Up] [Next] [Index]

# 6.1 Graphic Sheet Objects

To access any graphics in XGAP you first have to create a graphic sheet object. Such objects are linked internally to windows on the screen. You do not have to think about redrawing, resizing and other organizing stuff. The graphic sheet object is a GAP object in the category `IsGraphicSheet` and should be saved because it is needed later on for all graphic operations.

- `GraphicSheet(` title`,` width`,` height`) O`

  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.

- `Close(` sheet`)`

  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.

- `LeftPBDown(` sheet`,` x`,` y`)`

  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.

- `RightPBDown(` sheet`,` x`,` y`)`

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

- `ShiftLeftPBDown(` sheet`,` x`,` y`)`

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

- `ShiftRightPBDown(` sheet`,` x`,` y`)`

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

- `CtrlLeftPBDown(` sheet`,` x`,` y`)`

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

- `CtrlRightPBDown(` sheet`,` x`,` y`)`

  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:

- `InstallCallback(` sheet`,` key`,` func`) O`

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

- `RemoveCallback(` sheet`,` func`,` call`) O`

  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!

- `Callback(` sheet`,` key`,` args`) O`

  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.

- `IsAlive(` gobj`) F`

  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:

- `Close(` sheet`) O`

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

- `Resize(` sheet`,` width`,` height`) O`

  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.

- `WindowId(` sheet`) A`

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

- `SetTitle(` sheet`,` title`) O`

  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.

- `SaveAsPS(` sheet`,` filename`) O`

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

- `FastUpdate(` sheet`,` flag`) O`

  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.

  [Up] [Next] [Index]