a2dConnectionGenerator Class Reference
when a new wire or other connection object needs to be created, More...
#include <canobj.h>
Public Member Functions | |
| a2dConnectionGenerator () | |
| constructor | |
| ~a2dConnectionGenerator () | |
| destructor | |
| virtual a2dCanvasObject * | CreateConnectObject (a2dCanvasObject *parent, a2dPin *pinThis, a2dPin *pinOther, bool undo=false) const |
| create connection object based on two pins which need to be connected. | |
| virtual a2dCanvasObject * | GetConnectTemplate (const a2dCanvasObject *object, a2dPinClass *mapObject, const a2dCanvasObject *other, a2dPinClass *mapOther) const |
| create connection object based on two pin classes, which (may) need to be connected. | |
| virtual bool | GeneratePossibleConnections (a2dCanvasObject *object, a2dPinClass *pinClass, a2dConnectTask task, double x, double y) const |
| generate temporary pins to which objects can connect | |
| virtual a2dPinClass * | GetPinClassForTask (a2dPinClass *pinClass, a2dConnectTask task, a2dCanvasObject *obj) const |
| return a a2dPinClass which should be used to connect to the input a2dPinClass. | |
| a2dPinClass * | GetAnyPinClass () const |
| return the pin class for GetPinClassForTask( a2dPinClass::Any ) | |
| void | SetAnyPinClass (a2dPinClass *pinClass) |
| see GetAnyPinClass() | |
| bool | GetLastConnectCreationDirection () const |
| when a wire was created, this return the direction is was created ( first to last pin or visa versa ). | |
Protected Member Functions | |
| virtual a2dObject * | Clone (CloneOptions options) const |
| Some stuff needed by the ref counting base class. | |
Protected Attributes | |
| a2dPinClass * | m_anypinclass |
| template pinclass | |
| bool | m_reverseCreate |
| how to create a connection | |
Detailed Description
when a new wire or other connection object needs to be created,this class or a derived one, will deliver the right connection object. In other situations it will tell which objects are connectable on two pins, and the wire needed for that.
The idea is that objects do not only decide themselfs if they can connect to other objects and which. Instead this job is centralized to this class. Because of that an object does not need to know himself to which objects it can connect, and what wire to use for that. The a2dConnectionGenerator knows which objects can connect to others. Actualy in the default situation it is not the object which decides, but the pinclass of a pin is the input for the a2dConnectionGenerator. So one asks the a2dConnectionGenerator if a pinclass of a pin on a certain object, can connect to something else.
This class here can restrict what is the default way of allowing connections, or implement its own rules. When you want to limit the possible connection you can switch to a derived a2dConnectionGenerator. An a2dConnectionGenerator is shared by a set of a2dPinClass Objects, and this is how one finds the a2dConnectionGenerator for a connection task at hand.
As an example of a derived a2dConnectionGenerator: if you want to limit a wire tool to only draw lines from objects which have pins of a specific pin class, overriding GeneratePossibleConnections() can do the job.
a2dPinClass itself has information on hich other a2dPinClass it may connect to, and two pin classes can only connect if they both agree. a2dPinClass even knows which type of wire/connect object is required hen this pinclass is meant for being on a wire its pin. So when starting a new wire, at a certain pin, the object and wire its a2dPinClass must be able to connect to one another. A wiretool is only able to connect two pins of objects if the pinclasses in its connect lists are compatible, meaning the one pin contains the other as connectable. If the pin is oke, the found PinClassMap defines what type of wire needs to be created now. This information is stored in the a2dPinClass, as a template wire/connect object. The tool therefore is able to generate a2dCanvasObject connections ( e.g. a2dWirePolylineL wires ) of different types, and which type is created depends on the pin that is hit when starting a wire.
In the above one object was normal and the connecting object was a wire. Another situation is when two normal objects are dragged appart and a wire needs to be created in between. Again pinclasses of the two a2dPin's that will be disconnected will be searched in its connect lists, for a wire pincclass, which can connect to both pins. When a wire pinclass is found which can connect to both pins, the type of wire will be created via that same pinclass its template object for a wire. This is achieved CreateConnectObject().
To understand the principle, imagine 3 a2dCanvasObject's with pins which have Pin classes.
- one with a2dPinClass A
- the second with a2dPinClass B
- the third with a2dPinClass C Now when A connects to B we want a wire of type X, if A connects to C, we want wire Y, at last when C connects to B we want wire Z. On top of this the direction of the connection can be defined, A to C can be different from C to A. The information on which pin can connect to which other pin, is stored in the a2dPinClass of the a2dPin. Here one can find which other a2dPinClass object can connect to this one, and if it is for a wire, a template object to create that wire.
If more B objects are connected to an A object, via multiple wires, the connection of wires to wires must be defined too To conclude we are not only defining the relations between A-B-C, but also the wire begin and end relations towards eachother. In our case here, we create wires which are extensions of the pin where they are connected to, meaning the end pin of the wire is the same as the pinclass to which the begin pin is connected. All this to connect one object pin with pinclass to other objects at a pin with a certain pin class. If we define 3 pinclasses for pins on the object A,B,C and three extra pinclasses WA WB WC for wire between those objects, we get the following connection tables.
For the pinclasses which can be connected to each other:
- (A-PinClass) -> (B-PinClass) (C-PinClass) (WB-PinClass) (WC-PinClass)
- (B-PinClass) -> (A-PinClass) (C-PinClass) (WA-PinClass) (WC-PinClass)
- (C-PinClass) -> (A-PinClass) (B-PinClass) (WA-PinClass) (WB-PinClass)
We get for wires which start at A or C:
- (A-PinClass) -> (WB-PinClass) Wire X (WA-PinClass) -> (B-PinClass)
- (A-PinClass) -> (WC-PinClass) Wire Y (WA-PinClass) -> (C-PinClass)
- (C-PinClass) -> (WB-PinClass) Wire Z (WC-PinClass) -> (B-PinClass)
And if bidirectional wires which start at B or C:
- (B-PinClass) -> (WA-PinClass) Wire X (WB-PinClass) -> (A-PinClass)
- (C-PinClass) -> (WA-PinClass) Wire Y (WC-PinClass) -> (A-PinClass)
- (B-PinClass) -> (WC-PinClass) Wire Z (WB-PinClass) -> (C-PinClass)
Interesting in this table is that one can not start a wire on an object, whithout knowing its type, since always two are possible. So a wire tool needs to define for which pinclass a wire is needed, before asking this a2dConnectionGenerator to tell if the object is oke with that. Another option is to start a wire on a starting pin, and only when finishing the wire decide what type of wire is really needed for the begin and end pin of the wire. It is best to give wire ohter pinclasses then normal objects, since that makes it easier to know if one can start a wire on a certain pin, and what type of wire it needs to be.
As an example, drawing a wire using a tool. If the user clicks on an object type pin, the corresponding pin in the newly created wire will be a Non object type pin.
At last in the above, there were three objects, but in fact they are of no interest, since the pins its pinclasses define all. This way it is possible to define several "flows" in a group of objects. E.g. You can define in and output pinclasses for each flow you require. Multiple flow pins can be added to the same object, connecting a set of flow pins by one type of wire. You end up with several flows within a group of objects ( control flow - data flow ).
Definition at line 631 of file canobj.h.
Member Function Documentation
| a2dCanvasObject * a2dConnectionGenerator::CreateConnectObject | ( | a2dCanvasObject * | parent, | |
| a2dPin * | pinThis, | |||
| a2dPin * | pinOther, | |||
| bool | undo = false | |||
| ) | const [virtual] |
create connection object based on two pins which need to be connected.
Called from the default a2dCanvasObject::CreateConnectObject(), in order to easily change the behaviour of standard objects concerning possible connections. The returned object is a (connection) object (e.g. a2dWirePolylineL ), with correct pins at the position of pinThis and pinOther. The pins are connected already. When undo is true, the right commands are sent to the document its command processor. In general this means those commands are part of a group of commands in a a2dCommandGroup, which internal resulted in a connection being created. For example as a result of dragging an object.
Definition at line 775 of file canobj.cpp.
| bool a2dConnectionGenerator::GeneratePossibleConnections | ( | a2dCanvasObject * | object, | |
| a2dPinClass * | pinClass, | |||
| a2dConnectTask | task, | |||
| double | x, | |||
| double | y | |||
| ) | const [virtual] |
generate temporary pins to which objects can connect
When drawing wires object, other object are asked to display pin possition, to which the wire may connect. See a2dCanvasObject::GeneratePinsPossibleConnections(). This process is called by the tools, and is called editing Feedback. The pins created are only temporary, and will be removed at the end of a tool its busy cycle.
The default implementation uses pinClass->GetConnectionGenerator() to ask this object to generate a pin in a2dCanvasObject::GeneratePins(). The reason for this, is that there may be more involved to allow a pin to connect. Like the pin class.
- Parameters:
-
object The object on which to create temporary pins pinClass The pinclass to which the generated pins must be able to connect, if NULL any pinclass task for what purpose is the connection needed x only connect at this position y only connect at this position
Definition at line 967 of file canobj.cpp.
| a2dPinClass * a2dConnectionGenerator::GetPinClassForTask | ( | a2dPinClass * | pinClass, | |
| a2dConnectTask | task, | |||
| a2dCanvasObject * | obj | |||
| ) | const [virtual] |
return a a2dPinClass which should be used to connect to the input a2dPinClass.
The connection generator searches for a possible connection to the input a2dPinClass in combination with the canvasobject obj if needed.
- Parameters:
-
pinClass pin class for which to search a connecting PinClass task for what purpose is the connection needed obj object for which pins are checked / needed.
- Returns:
- If a a2dPinClass is not found NULL is returned.
Definition at line 974 of file canobj.cpp.
| a2dPinClass* a2dConnectionGenerator::GetAnyPinClass | ( | ) | const [inline] |
return the pin class for GetPinClassForTask( a2dPinClass::Any )
Basic object can generate pins by a2dPinclass, but i8n case of a2dPinClass::Any it will generate pins of this pinclass.
The documentation for this class was generated from the following files: