GtkNodesNodeSocket: gtknodes Reference Manual

GtkNodesNodeSocket

GtkNodesNodeSocket — A node socket

Functions

GtkWidget *	gtk_nodes_node_socket_new ()
GtkWidget *	gtk_nodes_node_socket_new_with_io ()
void	gtk_nodes_node_socket_set_rgba ()
void	gtk_nodes_node_socket_get_rgba ()
void	gtk_nodes_node_socket_set_radius ()
void	gtk_nodes_node_socket_get_radius ()
void	gtk_nodes_node_socket_set_io ()
GtkNodesNodeSocketIO	gtk_nodes_node_socket_get_io ()
void	gtk_nodes_node_socket_set_key ()
GtkNodesNodeSocketIO	gtk_nodes_node_socket_get_key ()
GtkNodesNodeSocketIO	gtk_nodes_node_socket_get_remote_key ()
void	gtk_nodes_node_socket_set_id ()
GtkNodesNodeSocketIO	gtk_nodes_node_socket_get_id ()
gboolean	gtk_nodes_node_socket_write ()
void	gtk_nodes_node_socket_disconnect ()
GtkNodesNodeSocket *	gtk_nodes_node_socket_get_input ()
void	gtk_nodes_node_socket_connect_sockets ()

Properties

guint	id	Read / Write
GtkNodesNodeSocketType	io	Read / Write
guint	key	Read / Write
double	radius	Read / Write
GdkRGBA *	rgba	Read / Write

Signals

void	socket-connect	Run First
void	socket-destroyed	Run First
void	socket-disconnect	Run First
void	socket-drag-begin	Run First
void	socket-drag-end	Run First
void	socket-incoming	Run First
void	socket-key-change	Run First
void	socket-outgoing	Run First

Types and Values

#define	GTK_COMPILATION
#define	GTKNODES_TYPE_NODE_SOCKET_IO
enum	GtkNodesNodeSocketIO

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkNodesNodeSocket

Description

The GtkNodesNodeSocket is a widget, serving as a IO transporter to other GtkNodeSockets. The user can set one of three IO modes: SINK, SOURCE and DISABLE (see GtkNodesNodeSocketIO). A socket in sink mode will accept only a single input source, a socket in source mode will provide output to any connectd sink. Connections are established by drag-and-drop action of a source to a sink by the user. A sink socket will emit the :socket-connect signal on when a connection is established. If the user initiates a drag on a sink which is already connected to a source, the sink will disconnect from the source and the drag event will be redirected to the source socket.

In order to identify compatible sockets, a key can be provided by the user. The source key is transported to the sink in the drag data exchange and the sink will reject the connection if the key does not match. This mechanism ensures that only interpretable data is received on the sink input.

A key value of 0 is special in that any input will be accepted.

If the user changes the key, the socket will emit the :socket-disconnect signal to notify any connected sinks or sources, so the can initiate a disconnect, if their key does not match or is different from 0.

Connections and data transport

Connections on sinks are established by connecting to the :socket-outgoing signal of the source. This means that the source is not aware of the number of connected sinks, as all data is transported by the GType signal system.

The user can push output from a source by calling gtk_nodes_node_socket_write() on the socket. To get data received by a sink, the user must connect to the ::socket-incoming signal.

Cleanup

If a socket is destroyed or disconnects from a source, it will emit the :socket-destroyed and :socket-disconnect signals respectively.

Any sockets attached to the destroyed socket will initiate a disconnect.

Functions

gtk_nodes_node_socket_new ()

GtkWidget *
gtk_nodes_node_socket_new (void);

Creates a new node socket.

Returns

the new GtkNodesNodeSocket.

[transfer full]

gtk_nodes_node_socket_new_with_io ()

GtkWidget *
gtk_nodes_node_socket_new_with_io (const GtkNodesNodeSocketIO io);

Creates a new node socket in the given IO mode

Parameters

the IO mode to configure

Returns

the new GtkNodesNodeSocket.

[transfer full]

gtk_nodes_node_socket_set_rgba ()

void
gtk_nodes_node_socket_set_rgba (GtkNodesNodeSocket *socket,
                                const GdkRGBA *rgba);

Sets the GdkRGBA colour of the socket

Parameters

socket	a GtkNodesNodeSocket
rgba	the GdkRGBA colour to set

gtk_nodes_node_socket_get_rgba ()

void
gtk_nodes_node_socket_get_rgba (GtkNodesNodeSocket *socket,
                                GdkRGBA *rgba);

Sets the GdkRGBA colour of the socket

Parameters

socket	a GtkNodesNodeSocket
rgba	the GdkRGBA colour to get

gtk_nodes_node_socket_set_radius ()

void
gtk_nodes_node_socket_set_radius (GtkNodesNodeSocket *socket,
                                  const gdouble radius);

Sets the radius of the socket

Parameters

socket	a GtkNodesNodeSocket
radius	the socket radius to set

gtk_nodes_node_socket_get_radius ()

void
gtk_nodes_node_socket_get_radius (GtkNodesNodeSocket *socket,
                                  gdouble *radius);

Gets the radius of the socket

Parameters

socket	a GtkNodesNodeSocket
radius	the socket radius to get

gtk_nodes_node_socket_set_io ()

void
gtk_nodes_node_socket_set_io (GtkNodesNodeSocket *socket,
                              GtkNodesNodeSocketIO io);

Sets the IO mode of the socket. Changing the mode will disconnect existing source inputs, as these are tracked internally. Attached sinks and sources will be notified by the ::socket-disconnect signal. It is the responsibility of the user to disconnect their ::socket-incoming signal callbacks. If the user attempts to set the current socket mode, no action will be taken.

Parameters

socket	a GtkNodesNodeSocket
io	a GtkNodesNodeSocketIO

gtk_nodes_node_socket_get_io ()

GtkNodesNodeSocketIO
gtk_nodes_node_socket_get_io (GtkNodesNodeSocket *socket);

Parameters

socket

a GtkNodesNodeSocket

Returns

the GtkNodesNodeSocketIO mode of the socket

gtk_nodes_node_socket_set_key ()

void
gtk_nodes_node_socket_set_key (GtkNodesNodeSocket *socket,
                               guint key);

Sets the compatibility key of the socket. Changing the key will disconnect any existing source inputs, unless the key is set to 0 or their source key matches. Attached sinks will not be notified, it is the responsibility of the user to disconnect socket-incoming signals. If the user attempts to set the current key, no action will be taken.

Parameters

socket	a GtkNodesNodeSocket
key	a compatibility key (0 == any)

gtk_nodes_node_socket_get_key ()

GtkNodesNodeSocketIO
gtk_nodes_node_socket_get_key (GtkNodesNodeSocket *socket);

returns the compatibility key of the socket (always 0 on error)

Parameters

socket

a GtkNodesNodeSocket

gtk_nodes_node_socket_get_remote_key ()

GtkNodesNodeSocketIO
gtk_nodes_node_socket_get_remote_key (GtkNodesNodeSocket *socket);

returns the compatibility key of the input socket (always 0 if key cannot be determined)

Parameters

socket

a GtkNodesNodeSocket

gtk_nodes_node_socket_set_id ()

void
gtk_nodes_node_socket_set_id (GtkNodesNodeSocket *socket,
                              guint id);

Sets the numeric identifier of the socket Note: can not be changed once set != 0

Parameters

socket	a GtkNodesNodeSocket
id	the socket identifier to set

gtk_nodes_node_socket_get_id ()

GtkNodesNodeSocketIO
gtk_nodes_node_socket_get_id (GtkNodesNodeSocket *socket);

Parameters

socket

a GtkNodesNodeSocket

Returns

the numeric identifier of the socket (always 0 on error)

gtk_nodes_node_socket_write ()

gboolean
gtk_nodes_node_socket_write (GtkNodesNodeSocket *socket,
                             GByteArray *payload);

Emits a signal on the GtkNodesNodeSocket in incoming our outgoing direction.

Parameters

socket	a GtkNodesNodeSocket
payload	the data buffer to write

Returns

TRUE on success, FALSE if GTKNODES_NODE_SOCKET_DISABLE is configured

gtk_nodes_node_socket_disconnect ()

void
gtk_nodes_node_socket_disconnect (GtkNodesNodeSocket *socket);

Drops all connections on a given socket. Attached sink or source sockets will be notified by the respective signals

Parameters

socket

a GtkNodesNodeSocket

gtk_nodes_node_socket_get_input ()

GtkNodesNodeSocket *
gtk_nodes_node_socket_get_input (GtkNodesNodeSocket *socket);

Returns the reference of the input GtkNodesNodeSocket for this input, or NULL if no input is connected or the socket is not in sink mode

Parameters

socket

a GtkNodesNodeSocket

Returns

the reference to the input socket or NULL if invalid.

[transfer none]

gtk_nodes_node_socket_connect_sockets ()

void
gtk_nodes_node_socket_connect_sockets (GtkNodesNodeSocket *sink,
                                       GtkNodesNodeSocket *source);

Explicitly establishes a connection between two sockets. If the sockets are not in the proper mode, the connection will fail. If the sink is already connected to a source, the source will be disconnected from the sink before connecting to the new source. If the compatibility keys of the sockets do not match, the connection will fail as well.

Parameters

sink	a GtkNodesNodeSocket in sink mode
source	a GtkNodesNodeSocket in source mode

Types and Values

GTK_COMPILATION

#define             GTK_COMPILATION

GTKNODES_TYPE_NODE_SOCKET_IO

#define GTKNODES_TYPE_NODE_SOCKET_IO         (gtk_nodes_node_socket_io_get_type ())

enum GtkNodesNodeSocketIO

If the socket is in SINK mode, it can accept only one input source, if the socket is in source mode, it will provide output to any connected sink

Members

GTKNODES_NODE_SOCKET_DISABLE	the socket IO is deactivated
GTKNODES_NODE_SOCKET_SINK	the socket is in sink mode
GTKNODES_NODE_SOCKET_SOURCE	the socket is in source mode

Property Details

The `“id”` property

  “id”                       guint

The numeric identifier of the socket

Owner: GtkNodesNodeSocket

Flags: Read / Write

Default value: 0

The `“io”` property

  “io”                       GtkNodesNodeSocketType

The type of socket (input or output)

Owner: GtkNodesNodeSocket

Flags: Read / Write

Default value: GTKNODES_NODE_SOCKET_DISABLE

The `“key”` property

  “key”                      guint

The compatibility key of the socket

Owner: GtkNodesNodeSocket

Flags: Read / Write

Default value: 0

The `“radius”` property

  “radius”                   double

The radius of the socket

Owner: GtkNodesNodeSocket

Flags: Read / Write

Allowed values: [1,30]

Default value: 8

The `“rgba”` property

  “rgba”                     GdkRGBA *

The rgba colour of the socket

Owner: GtkNodesNodeSocket

Flags: Read / Write

Signal Details

The `“socket-connect”` signal

void
user_function (GtkNodesNodeSocket *widget,
               GtkNodesNodeSocket *source,
               gpointer            user_data)

The ::socket-connect signal is emitted when a sink socket connects to a source socket

Parameters

widget	the object which received the signal.
source	the GtkNodesNodeSocket this socket connected to
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“socket-destroyed”` signal

void
user_function (GtkNodesNodeSocket *widget,
               gpointer            user_data)

The ::socket-drag-begin signal is emitted when the user ends a drag on the socket handle.

Parameters

widget	the object which received the signal.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“socket-disconnect”` signal

void
user_function (GtkNodesNodeSocket *widget,
               GtkNodesNodeSocket *source,
               gpointer            user_data)

The ::socket-disconnect signal is emitted when a sink socket disconnects from a source socket or notifies sinks to disconnect because of a change in configuration (in this case source is NULL)

Parameters

widget	the object which received the signal.
source	the GtkNodesNodeSocket this socket disconnected from, may be NULL
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“socket-drag-begin”` signal

void
user_function (GtkNodesNodeSocket *widget,
               gpointer            user_data)

The ::socket-drag-begin signal is emitted when the user begins a drag on the socket handle.

Parameters

widget	the object which received the signal.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“socket-drag-end”` signal

void
user_function (GtkNodesNodeSocket *widget,
               gpointer            user_data)

The ::socket-drag-begin signal is emitted when the user ends a drag on the socket handle.

Parameters

widget	the object which received the signal.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“socket-incoming”` signal

void
user_function (GtkNodesNodeSocket *widget,
               GByteArray         *data,
               gpointer            user_data)

The ::socket-incoming signal is emitted when data is incoming on the socket The data pointer reference and size are transported via the callback.

Parameters

widget	the object which received the signal.
data	the data pointer
size	the size of the data in bytes
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“socket-key-change”` signal

void
user_function (GtkNodesNodeSocket *widget,
               GtkNodesNodeSocket *source,
               gpointer            user_data)

The ::socket-key-change signal is emitted when a sink socket changes its key

Parameters

widget	the object which received the signal.
source	the GtkNodesNodeSocket which changed the key, may be NULL
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“socket-outgoing”` signal

void
user_function (GtkNodesNodeSocket *widget,
               GByteArray         *data,
               gpointer            user_data)

The ::socket-outgoing signal is emitted when data is outgoing on the socket The data pointer reference and size are transported via the callback.

Parameters

widget	the object which received the signal.
data	the data pointer
size	the size of the data in bytes
user_data	user data set when the signal handler was connected.

Flags: Run First