Interface to the graph drawing API in GPS.
A diagram contains a set of items.
You can extend this class with your own, and declare the following special subprograms which are called automatically by GPS:
def on_selection_changed(self, item, *args):
'''
Called when the selection status of item has changed.
:param GPS.Browsers.Item item: the item that was selected or
unselected. This is set to None when all items were
unselected.
'''
The list of all GPS.Browsers.Item in the diagram. This only include toplevel items, you will need to iterate their own children if you need access to them.
The list of selected GPS.Browsers.Item
Creates a new empty diagram.
Add a new item to the diagram. The coordinates of the item are set through item.set_position().
Parameters: | item (GPS.Browsers.Item) – the item to add |
---|
Remove all items from the diagram.
Unselect all items in the diagram.
Whether the item is selected.
Parameters: | item (GPS.Browsers.Item) – the item to check |
---|---|
Returns: | a boolean |
Load a JSON file into a series of diagrams.
The format of the file is described below, and is basically a serialization of all the style and object attributes mentioned elsewhere in this documentation.
The JSON file should contain an object (“{...}”) with the following attributes:
styles: this is a list of style objects. Each style is itself described as an object whose attributes are any of the valid parameters for GPS.Browsers.Style.__init__(). In addition the style should have an id attribute that can be referenced elsewhere in the file, to avoid duplicating style information.
There are a few special ids that can be used to set the default properties or styles for the items defined in this json file. For instance, if the id starts with “__default_props_” followed by one of the valid item type, the object can define the default attribute for any of the valid attributes of items.
If the id starts with “__default_style_”, the object defines the style properties for any of the item type.
For instance:
{"styles": [ {"id": "__default_props_text", "margin": [0, 5, 0, 5]}, {"id": "__default_props_rect", "minWidth": 200}, {"id": "__default_style_text", "fontName": "arial 10"}, {"id": "customStyle1", "stroke": "blue"} ]}diagrams: this is a list of diagram object. A single file can contain multiple diagrams, but a browser window always only displays a single diagram.
Each diagram object has two possible attributes:
- items: this is a list of item objects (see below)
- links: this is a list of link objects (see below)
An item object is itself described with a JSON object, with the following possible attributes:
- id: an optional string, which defines an id for an object. This id can be used when creating links. It is also stored as an id attribute in the instance of GPS.Browsers.Item that is created.
- data: this field is stored as is in the generated instance of GPS.Browsers.Item. It can be used to store any application specific data, in particular since the instance will be passed to the callbacks to handle click events.
- x, y: optional float attributes. See the description of GPS.Browsers.Item.set_position().
- style: an optional string (which then references the id of one of the styles defined in the “styles” attribute described above, or an inline JSON object that describes a style as above.
- type: the type of the item. Valid values are “rect”, “hr”, “ellipse”, “polyline” or “text” (see the corresponding classes in this documentation). This attribute is optional, and will be guessed automatically in some cases. For instance, when the object also has a text attribute, it is considered as a text item. If it has a “points” attribute it is considered as a polyline item. The default type is “rect”.
- minWidth and minHeight: the minimal size for an item. See GPS.Browsers.Item.set_min_size().
- vbox and hbox: list of items, which are the children of the current item. These children are organized either vertically or horizontally (only one of the two attributes can be specified, vbox takes precedence).
When an item is created as a child of another one (in its parent’s vbox or hbox), it may have the following additional attributes. See GPS.Browsers.Item.add() for more information.
- margin: the margins around the item. This is either a single float (in which case all margins are equal), or a list of four floats which give the top, right, bottom and left margins respectively.
- align: one of the values from GPS.Browsers.Item.Align. In a JSON file, though, you can only use the corresponding integer values.
- float: whether the item is set as floating
- overflow: one of the integer values for GPS.Browers.Item.Overflow
Text objects (corresponding to GPS.Browsers.TextItem) have the following additional attributes:
- text: the text to display.
- directed: one of the values from GPS.Browsers.TextItem.Text_Arrow, which indicates that an extra arrow should be displayed next to the text. This is mostly relevant when the text is used as a label on a link, in which case the actual arrow will be computed automatically from the orientation of the link.
Hr objects (corresponding to GPS.Browsers.HrItem) have the following additional attributes:
- text: the text to display.
Polyline objects (corresponding to GPS.Browsers.PolylineItem) have the following additional attributes:
- points: the points that describe the contour of the object, as a list of floats. They are grouped into pairs, each of which describes the coordinates of a point.
- close: whether the last point should automatically be linked to the first.
- relative: an optional boolean (defaults to false) that indicates whether the points are coordinates relative to the item’s topleft corner, or are relative to the previous point.
Ellipse items (corresponding to GPS.Browsers.EllipseItem) have the following additional attributes:
- width, height: optional floats, which describe the rectangle into which the ellipse is inscribed. When unspecified, the size is computed from the list of children.
Rect items (corresponding to GPS.Browsers.RectItem) have the following additional attributes:
- width, height: optional floats. When unspecified, the size is computed from the list of children.
- radius: optional float indicating the radius for the corners of the rectangle.
A link object contains the following attributes (see GPS.Browser.Link for more information on the parameters):
id: an optional string id for the link, if you need to create links to it.
from and to: these are record with one mandatory field, ref, which is the id of one of the objects or links created previously. In addition, these records can also specify the following attributes:
- anchorx, anchory: floats in the range 0.0 .. 1.0 which specify where the item is attached in its target item
- side takes its value from GPS.Browsers.Link.Side, and is used to force the link to emerge from one specific side of the item.
- label is a JSON object describing an item, as described earlier. This will generally be a text item.
label: one of GPS.Browsers.Item, to display in the middle of the link. This will generally be a text item. If it is directed, the arrow will be computed from the orientation of the link.
route: one of GPS.Browsers.Link.Routing (as integer) to indicate how the link is displayed.
waypoints: a list of floats, which will be grouped into pairs to define waypoints. See GPS.Browsers.Link.set_waypoints(). An alternative definition is to use an object with two fields, points which is the list of floats, and relative which is a bool indicating whether the points are in absolute coordinates or relative to the previous point.
Here is an example which draws two items linked together:
{"styles": {},
"diagrams": [
{"items": [
{"x": 0, "y": 0, "style": "customStyle1",
"id": "first item",
"width": 100, "height": 100,
"vbox": [
{"text": "Name",
"style": {"fontName": "arial 20", stroke:null}},
{"type": "hr", "text":"attributes"},
{"text": "+attr:integer"}
]
},
{"x": 100, "y":200",
"id": "second item",
"text": "Annotation"},
],
"links": [
{"from": {"ref": "first item"},
"to": {"ref": "second item"},
"style": {"stroke": "blue", "dashes": [4, 4]}}
]
}
]
}
Parameters: |
|
---|---|
Returns: | the list of GPS.Browsers.Diagram objects created. |
Lower the item, so that it is displayed below all other items.
Parameters: | item (GPS.Browsers.Item) – the item to lower. |
---|
Raise the item, so that it is displayed above all other items.
Parameters: | item (GPS.Browsers.Item) – the item to raise. |
---|
Remove an item from the diagram.
Parameters: | item (GPS.Browsers.Item) – the item to remove. |
---|
Select the item. If the diagram is set up for single selection, any previously selected item is first unselected.
Parameters: | item (GPS.Browsers.Item) – the item to select. |
---|
Controls the selection in the views associated with this buffer. It can be used to indicate whether a single item or multiple items can be selected.
Parameters: | mode (GPS.Browsers.Diagram.Selection) – the type of selection |
---|
Unselect the item.
Parameters: | item (GPS.Browsers.Item) – the item to select. |
---|
A text item (GPS.Browsers.TextItem) that can be double-clicked on to edit its text.
digraph inheritanceac6738ba4a { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.EditableTextItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.EditableTextItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A text item (:class:`GPS.Browsers.TextItem`) that can be double-clicked",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.TextItem" -> "GPS.Browsers.EditableTextItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; "GPS.Browsers.Item" [style="setlinewidth(0.5)",URL="#GPS.Browsers.Item",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This abstract class represents any of the items that can be displayed in",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.TextItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.TextItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="An item that displays text (optionaly within a rectangular box).",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.Item" -> "GPS.Browsers.TextItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; }
Creates a new editable text item
Parameters: |
|
---|
An item which displays an ellipse or a circle. It can contain children.
digraph inheritancee0d4f9c809 { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.EllipseItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.EllipseItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="An item which displays an ellipse or a circle. It can contain",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.Item" -> "GPS.Browsers.EllipseItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; "GPS.Browsers.Item" [style="setlinewidth(0.5)",URL="#GPS.Browsers.Item",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This abstract class represents any of the items that can be displayed in",height=0.25,shape=box,fontsize=10]; }
Create a new ellipse/circle item, inscribed in the box given by the width and height.
Parameters: |
|
---|
A horizontal-line item, with optional text in the middle. This is basically represented as:
—– text —–
digraph inheritance370511ce63 { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.HrItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.HrItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A horizontal-line item, with optional text in the middle.",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.Item" -> "GPS.Browsers.HrItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; "GPS.Browsers.Item" [style="setlinewidth(0.5)",URL="#GPS.Browsers.Item",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This abstract class represents any of the items that can be displayed in",height=0.25,shape=box,fontsize=10]; }
Creates a new horizontal line.
Parameters: |
|
---|
An item that shows an image.
digraph inheritancea93a3f43f9 { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.ImageItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.ImageItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="An item that shows an image.",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.Item" -> "GPS.Browsers.ImageItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; "GPS.Browsers.Item" [style="setlinewidth(0.5)",URL="#GPS.Browsers.Item",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This abstract class represents any of the items that can be displayed in",height=0.25,shape=box,fontsize=10]; }
Creates a new image item.
Parameters: |
|
---|
This abstract class represents any of the items that can be displayed in a browser. Such items have an outline, whose form depends on the type of the item (rectangular, polygone,...) They can almost all contain children. Unless you specified an explicit size for the item, its size will be computed to include all the children. The children are stacked either vertically or horizontally within their container, so that one child appears by default immediately below or to the right of the previous one. Extra margins can be specified to force extra space.
The list of GPS.Browsers.Item that were added to the item. This property is not writable.
A boolean, set to True when the item is a link. This property is not writable.
Will raise an exception, this is an abstract class.
Add a child item. This child will be displayed as part of the item, and will move with it. The size of the child will impact the size of its parent, unless you have forced a specific size for the latter.
Parameters: |
|
---|
Choose how children are organized within this item.
Parameters: | layout (GPS.Browsers.Item.Layout) – if set to VERTICAL, then the child items are put below one another, otherwise they are put next to one another. |
---|
Forces a minimal size for self. It could be make larger if its children request a larger size, but will not smaller than the given size.
Parameters: |
|
---|
Indicates the position of the item. This is the position within its parent item, or if there is no parent this is the absolute position of the item within the diagram. Calling this function should always be done for toplevel items, but is optional for children, since their position is computed automatically by their container (which is especially useful with text items, whose size might be hard to compute).
Parameters: |
|
---|
A line between two items. When the items are moved, the line is automatically adjusted to stay connected to those items.
Creates a new link attached to the two items FROM and TO.
Parameters: |
|
---|
Force specific waypoints for link. The lines will pass through each of these points when it is routed as straight or orthogonal lines. By default, the coordinates are absolute (in the same coordinate system as the items). If however you specify relative coordinates, then each point is relative to the previous one (and the first one is relative to the link’s attachment point on its origin item).
Parameters: |
|
---|
An item which displays a set of connected lines. It can be used to draw polygons for instance, or simple lines.
digraph inheritance211c41af19 { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.Item" [style="setlinewidth(0.5)",URL="#GPS.Browsers.Item",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This abstract class represents any of the items that can be displayed in",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.PolylineItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.PolylineItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="An item which displays a set of connected lines.",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.Item" -> "GPS.Browsers.PolylineItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; }
Create a new polyilne item.
Parameters: |
|
---|
A special kind of item, which displays a rectangular box, optionally with rounded corner. It can contain children items.
digraph inheritancea27e42f2e2 { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.Item" [style="setlinewidth(0.5)",URL="#GPS.Browsers.Item",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This abstract class represents any of the items that can be displayed in",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.RectItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.RectItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A special kind of item, which displays a rectangular box, optionally",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.Item" -> "GPS.Browsers.RectItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; }
Creates a new rectangular item.
Parameters: |
|
---|
This class provides multiple drawing attributes that are used when drawing on a browser. This includes colors, dash patterns, arrows and symbols,... Very often, such a style will be reused for multiple objects.
Constructs a new style. This function takes a very large number of parameters, but they are all optional. Not all of them apply to all objects either.
Parameters: |
|
---|
An item that displays text (optionaly within a rectangular box).
digraph inheritancecd93209aaf { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.Item" [style="setlinewidth(0.5)",URL="#GPS.Browsers.Item",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This abstract class represents any of the items that can be displayed in",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.TextItem" [style="setlinewidth(0.5)",URL="#GPS.Browsers.TextItem",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="An item that displays text (optionaly within a rectangular box).",height=0.25,shape=box,fontsize=10]; "GPS.Browsers.Item" -> "GPS.Browsers.TextItem" [arrowsize=0.5,style="setlinewidth(0.5)"]; }
Creates a new text item
Parameters: |
|
---|
A view shows a part of a diagram and its objects. Multiple views can be associated with the same diagram.
Although this class can be instantiated as is, it is most useful, in general, to extend it, in particular by adding a method on_item_clicked:
class My_View(GPS.Browsers.View):
def on_item_double_clicked(self, topitem, item, x, y, *args):
'''
Called when the user double clicks on a specific item.
It is recommended to add "*args" in the list of parameters,
since new parameters might be added in the future.
:param GPS.Browsers.Item topitem: the toplevel item clicked on
:param GPS.Browsers.Item item: the item clicked on.
When the item was created from a JSON file (see
:func:`GPS.Browsers.Diagram.load_json`), it contains
additional fields like `data` and `id` that were extracted
from JSON.
This item is either topitem or a child of it.
:param float x: the coordinates of the mouse within the item.
:param float y: the coordinates of the mouse within the item.
'''
def on_item_clicked(self, topitem, item, x, y, *args):
'''
Called when the user releases the mouse button on a specific
item.
This method is called twice for a double-click (once per
actual click).
The parameters are the same as above.
'''
def on_create_context(self, context, topitem, item, x, y, *args):
'''
Called when the user has right-clicked on an item.
This function should prepare the context for contextual menus,
although it does not directly add contextual menu entries.
Instead, declare those menus as usual with
:class:`GPS.Contextual` or :func:`gps_utils.make_interactive`.
:param GPS.Context context: the context.
The function should add custom fields to this context.
These fields can then be tested for the filter or the
action associated with a :class:`GPS.Contextual`.
'''
def on_key(self, topitem, item, key, *args):
'''
Called when the user presses a keyboard key while the view has
the focus.
:param GPS.Browsers.Item topitem: the toplevel item clicked on
:param GPS.Browsers.Item item: the specific item clicked on.
:param int key: the key that was pressed (see Gdk.KEY_*
constants)
'''
digraph inheritance16d1a54f9e { rankdir=LR; size="8.0, 12.0"; "GPS.Browsers.View" [style="setlinewidth(0.5)",URL="#GPS.Browsers.View",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="A view shows a part of a diagram and its objects.",height=0.25,shape=box,fontsize=10]; "GPS.GUI" -> "GPS.Browsers.View" [arrowsize=0.5,style="setlinewidth(0.5)"]; "GPS.GUI" [style="setlinewidth(0.5)",URL="GPS.html#GPS.GUI",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",tooltip="This is an abstract class (ie no instances of it can be created from your",height=0.25,shape=box,fontsize=10]; }
The GPS.Browsers.Diagram that the view is referring to. This is a writable property.
The scaling factor for the view. This is a writable property
The coordinates of the top-left corner of the view. This is a writable property
Creates the python class instance, but does not associate it with any window yet. Before any of the other functions can be called, you first need to call self.create() to create the actual window. This creation is done in two steps, so that you can create your own class extending view. This is in particular needed to provide support for user interaction.
Scrolls the view so that the point is at the given position within the view (in the middle if xpos and ypos are both 0.5, or to the left if xpos is 0.0, or the right if xpos is 1.0, and so on).
Parameters: | point (tuple) – the point |
---|
Creates a new view that shows the given diagram. This view is automatically made visible in GPS.
Parameters: |
|
---|
Creates a PDF file with the contents of the view.
Parameters: |
|
---|
Scale and scroll the view so that all the items in the model are visible.
Parameters: | max_scale (float) – maximum scaling factor to allow. |
---|
Scrolls the view as little as possible so that item becomes visible.
Parameters: | item (GPS.Browsers.Item) – the item to show |
---|
Set the type of background to display in the view.
Parameters: |
|
---|
A read-only view does not allow users to move items. It is still possible to click on items though, or zoom and scroll the view.
Parameters: | readonly (bool) – whether the view is read-only. |
---|
The style used to highlight the selected items (see GPS.Browsers.Diagram.set_selection_mode()).
Parameters: | style (GPS.Browsers.Style) – the style to use. |
---|