Connector

Kind of class:public class
Package:com.smartfoxserver.smartfoxbits.bits
Inherits from:UIComponent
Version:1.0
Author:The gotoAndPlay() Team
http://www.smartfoxserver.com
http://www.gotoandplay.it
Classpath:com.smartfoxserver.smartfoxbits.bits.Connector
File last modified:Wednesday, 15 April 2009, 19:01:09
The Connector class provides the public APIs to interact with the SmartFoxBits Connector control at author-time and run-time.

The SmartFoxBits Connector control lets you establish a connection to a SmartFoxServer instance running on a specified IP address and TCP port.
The Connector has built-in icon and label to display the connection status. The label can be customized by setting the status message, its placement (to the right or left of the icon) and the distance from the icon (gap).
You can also customize the label text style by accessing the Flex Label control returned by the statusLabel property (check the Flex documentation for controls styling operations). The default icon can be customized by setting the respective styles.
The Connector's connection property allows you to retrieve a reference to the internal SmartFoxClient instance, in order to add your own SFSEvent listeners to handle the logic of your application.

NOTE: in the provided ActionScript examples, connector always indicates a Connector instance.
Usage:
  • Add the "SmartFoxBits base Pack.swc" file to the Library Path in your Flex project properties: the SmartFoxBits category will appear in the Flex Components panel.
    Drag the Connector control from the Components panel and drop it in the Flex Design View. The Connector properties can be set in Flex Properties panel or in the Source View (by editing the MXML tag) at author-time.
    The Connector instance can also be created and its properties set at run-time, using ActionScript.
    To make the control connect to SmartFoxServer as soon as it is instantiated at run-time, set the autoConnect property to true.
    In case you want to use the other SmartFoxBits without showing the Connector in your application's user interface, you can simply instantiate it via ActionScript without adding it to the Display List. The other SmartFoxBits will still be able to access the internal connection to SmartFoxServer.
    Styling
    The following styles are available for the Connector control:
    gap
    paddingBottom
    paddingLeft
    paddingRight
    paddingTop
    connectingStatusIcon
    connectedStatusIcon
    connectionFailedStatusIcon
    connectionLostStatusIcon
    notConnectedStatusIcon
    Styles can be applied using the standard Flex styling systems. Check the Flex documentation for additional informations.
Example:
  • To instantiate the Connector at author-time via MXML, write the following:
    <sfb:Connector id="connector" serverIpAddress="127.0.0.1" serverPort="9339" />
    To instantiate the Connector at run-time write the following:
    import com.smartfoxserver.smartfoxbits.bits.Connector

// Create Connector instance
var connector:Connector = new Connector()

// Add Connector instance to the display list
// (NOTE: this is not required if you don't need to show the connection status to the user,
// or if you want to show it in a different way)
addChild(connector)

// Establish the connection to SmartFoxServer
connector.connect()

Summary


Constructor
Constants
Instance properties
  • connectingMessage : String
    • The message displayed by the Connector while attempting to connect to SmartFoxServer.
  • connectedMessage : String
    • The message displayed by the Connector after a successful connection to SmartFoxServer.
  • connectionFailedMessage : String
    • The message displayed by the Connector if the connection attempt failed.
  • connectionLostMessage : String
    • The message displayed by the Connector if the connection with SmartFoxServer was lost.
  • notConnectedMessage : String
    • The message displayed by the Connector before attempting to connect to SmartFoxServer.
  • labelPlacement : String
    • The orientation of the status label in relation to the icon.
  • serverIpAddress (value:String) : String
    • The IP address of the server on which the SmartFoxServer instance is running.
  • serverPort (value:Number) : Number
    • The TCP port of the server on which the SmartFoxServer instance is running.
  • configPath (value:String) : String
    • The path to the client configuration xml file.
  • autoConnect (value:Boolean) : Boolean
    • Enable/disable the Connector's "auto-connect" feature.
  • debug (value:Boolean) : Boolean
    • Enable/disable the Connector's debugging feature.
  • statusLabel : Label
    • A reference to the Connector's status Label control.
  • isConnected : Boolean
    • A flag stating if the connection to SmartFoxServer is available.
  • connection : SmartFoxClient
    • A reference to the SmartFoxClient class instance.
  • status : String
    • The current connection status.
Instance methods
  • connect : void
    • Establish a connection to SmartFoxServer.
  • destroy : void
    • Destroy the Connector instance.

Constructor

Connector

public function Connector (
)

Connector constructor.
Example:
  • See the example in the class description.

Constants

LABEL_PLACEMENT_LEFT

public static const LABEL_PLACEMENT_LEFT:String = "left"
(read)

Status label placement to the left of the icon.
See also:

LABEL_PLACEMENT_RIGHT

public static const LABEL_PLACEMENT_RIGHT:String = "right"
(read)

Status label placement to the right of the icon.
See also:

STATUS_CONNECTED

public static const STATUS_CONNECTED:String = "connected"
(read)

Connection to SmartFoxServer was established successfully.
See also:

STATUS_CONNECTING

public static const STATUS_CONNECTING:String = "connecting"
(read)

Connection to SmartFoxServer is in progress.
See also:

STATUS_CONNECTION_FAILED

public static const STATUS_CONNECTION_FAILED:String = "connectionFailed"
(read)

Connection to SmartFoxServer failed (server can't be reached).
See also:

STATUS_CONNECTION_LOST

public static const STATUS_CONNECTION_LOST:String = "connectionLost"
(read)

Connection to SmartFoxServer was lost (due to idle time limit exceeded, user kicked or banned, etc).
See also:

STATUS_NOT_CONNECTED

public static const STATUS_NOT_CONNECTED:String = "notConnected"
(read)

Connection to SmartFoxServer not yet established.
See also:

Instance properties

autoConnect

public autoConnect:Boolean
(read,write)

Enable/disable the Connector's "auto-connect" feature.
When the "auto-connect" feature is enabled, the Connector sets up the communication with SmartFoxServer as soon as it is initialized. Otherwise the connection must be started manually by calling the connect method.
NOTE: this property must be set when the control is created to take effect. Later changes to not affect the control behavior.
Example:
  • To enable auto-connect in MXML:
    <sfb:Connector autoConnect="true" />
    To enable auto-connect in ActionScript:
    connector.autoConnect = true
See also:
Component metadata:
    Inspectable
    category:
    "Common"
    defaultValue:
    false
    name:
    "Auto-connect"
    type:
    Boolean

    configPath

    public configPath:String
    (read,write)

    The path to the client configuration xml file.
    See the SmartFoxClient.loadConfig method for additional informations.
    NOTE: this property must be set before the connection to SmartFoxServer is established. Later changes to not affect the control behavior.
    Example:
    • To set the client configuration path in MXML:
      <sfb:Connector configPath="config.xml" />
      To set the client configuration path in ActionScript:
      connector.configPath = "config.xml"
    Component metadata:
      Bindable
      "configChanged"
      Inspectable
      category:
      "Common"
      defaultValue:
      ""
      name:
      "SmartFoxClient configuration path"

      connectedMessage

      public connectedMessage:String
      (read,write)

      The message displayed by the Connector after a successful connection to SmartFoxServer.
      Example:
      • To set the "connected" status message in MXML:
        <sfb:Connector connectedMessage="You are now connected to SmartFoxServer" />
        To set the "connected" status message in ActionScript:
        connector.connectingMessage = "You are now connected to SmartFoxServer"
      See also:
      Component metadata:
        Inspectable
        category:
        "Common"
        defaultValue:
        "Connected"
        name:
        "'Connected' message"

        connectingMessage

        public connectingMessage:String
        (read,write)

        The message displayed by the Connector while attempting to connect to SmartFoxServer.
        Example:
        • To set the "connecting" status message in MXML:
          <sfb:Connector connectingMessage="Trying to connect to server..." />
          To set the "connecting" status message in ActionScript:
          connector.connectingMessage = "Trying to connect to server..."
        See also:
        Component metadata:
          Inspectable
          category:
          "Common"
          defaultValue:
          "Connecting..."
          name:
          "'Connecting' message"

          connection

          public connection:SmartFoxClient
          (read)

          A reference to the SmartFoxClient class instance.
          This reference allows you to invoke API methods to send server commands and requests, and add your own SFSEvent listeners to handle the logic of your application.
          Example:
          • To get a reference to the SmartFoxClient instance:
            import it.gotoandplay.smartfoxserver.*

var smartFox:SmartFoxClient = connector.connection
var zone:String = "simpleChat"
var myUserName:String = "Jack"

// Log into the "simpleChat" zone without using the LoginBox control
smartFox.login(zone, myUserName)

          connectionFailedMessage

          public connectionFailedMessage:String
          (read,write)

          The message displayed by the Connector if the connection attempt failed.
          Example:
          • To set the "connection failed" status message in MXML:
            <sfb:Connector connectionFailedMessage="Warning: connection to SmartFoxServer failed" />
            To set the "connection failed" status message in ActionScript:
            connector.connectionFailedMessage = "Warning: connection to SmartFoxServer failed"
          See also:
          Component metadata:
            Inspectable
            category:
            "Common"
            defaultValue:
            "Connection failed"
            name:
            "'Connection failed' message"

            connectionLostMessage

            public connectionLostMessage:String
            (read,write)

            The message displayed by the Connector if the connection with SmartFoxServer was lost.
            Example:
            • To set the "connection lost" status message in MXML:
              <sfb:Connector connectionLostMessage="Warning: connection to SmartFoxServer lost" />
              To set the "connection lost" status message in ActionScript:
              connector.connectionLostMessage = "Warning: connection to SmartFoxServer lost"
            See also:
            Component metadata:
              Inspectable
              category:
              "Common"
              defaultValue:
              "Connection lost"
              name:
              "'Connection lost' message"

              debug

              public debug:Boolean
              (read,write)

              Enable/disable the Connector's debugging feature.
              When the debug is enabled, the messages exchanged with SmartFoxServer by all the SmartFoxBits components are traced in the Flex Console panel during development.
              Example:
              • To enable debugging in MXML:
                <sfb:Connector debug="true" />
                To enable debugging in ActionScript:
                connector.debug = true
              See also:
              Component metadata:
                Bindable
                Inspectable
                category:
                "Common"
                defaultValue:
                false
                name:
                "Turn on debugging"
                type:
                Boolean

                isConnected

                public isConnected:Boolean
                (read)

                A flag stating if the connection to SmartFoxServer is available.
                Example:
                • To check the connection status:
                  if (connector.isConnected)
    trace("Connector is currently connected to SmartFoxServer")
                See also:

                labelPlacement

                public labelPlacement:String
                (read,write)

                The orientation of the status label in relation to the icon.
                Valid MXML values are right and left.
                In ActionScript, you can use the LABEL_PLACEMENT_RIGHT and LABEL_PLACEMENT_LEFT constants to set this property.
                Example:
                • To set the label placement in MXML:
                  <sfb:Connector labelPlacement="right" />
                  To set the label placement in ActionScript:
                  connector.labelPlacement = Connector.LABEL_PLACEMENT_RIGHT
                See also:
                Component metadata:
                  Bindable
                  "labelPlacementChanged"
                  Inspectable
                  category:
                  "Common"
                  defaultValue:
                  "right"
                  enumeration:
                  "left,right"

                  notConnectedMessage

                  public notConnectedMessage:String
                  (read,write)

                  The message displayed by the Connector before attempting to connect to SmartFoxServer.
                  Example:
                  • To set the "not connected" status message in MXML:
                    <sfb:Connector notConnectedMessage="Not yet connected" />
                    To set the "not connected" status message in ActionScript:
                    connector.notConnectedMessage = "Not yet connected"
                  See also:
                  Component metadata:
                    Inspectable
                    category:
                    "Common"
                    defaultValue:
                    "Not connected"
                    name:
                    "'Not connected' message"

                    serverIpAddress

                    public serverIpAddress:String
                    (read,write)

                    The IP address of the server on which the SmartFoxServer instance is running.
                    Example:
                    • To set the IP address in MXML:
                      <sfb:Connector serverIpAddress="127.0.0.1" />
                      To set the IP address in ActionScript:
                      connector.serverIpAddress = "127.0.0.1"
                    See also:
                    Component metadata:
                      Bindable
                      "ipChanged"
                      Inspectable
                      category:
                      "Common"
                      defaultValue:
                      "127.0.0.1"
                      name:
                      "SmartFoxServer IP address"

                      serverPort

                      public serverPort:Number
                      (read,write)

                      The TCP port of the server on which the SmartFoxServer instance is running.
                      Example:
                      • To set the port in MXML:
                        <sfb:Connector serverPort="9339" />
                        To set the port in ActionScript:
                        connector.serverPort = 9339
                      See also:
                      Component metadata:
                        Bindable
                        "portChanged"
                        Inspectable
                        category:
                        "Common"
                        defaultValue:
                        "9339"
                        name:
                        "SmartFoxServer port"

                        status

                        public status:String
                        (read)

                        The current connection status.
                        Example:
                        • To retrieve the connection status:
                          trace("Connection status:", connector.status)
                        See also:

                        statusLabel

                        public statusLabel:Label
                        (read)

                        A reference to the Connector's status Label control.
                        This property allows you to get a reference to the Flex Label control which displays the connection status message, to set its properties (for example text styling). Check the Flex Components documentation for additional details.
                        Example:
                        • To access the status Label control in ActionScript:
                          import mx.controls.Label

var label:Label = connector.statusLabel
label.setStyle("color", 0xFFCC00)

                        Instance methods

                        connect

                        public function connect (
                        ) : void

                        Establish a connection to SmartFoxServer.
                        When this method is called, the Connector establishes a communication with SmartFoxServer using the IP address and TCP port set by means of the serverIpAddress and serverPort properties.
                        If the autoConnect property is true, this method is called by the control itself as soon as it is instantiated at run-time.
                        Example:
                        • To establish a connection to SmartFoxServer manually:
                          connector.connect()
                        See also:

                        destroy

                        public function destroy (
                        ) : void

                        Destroy the Connector instance.
                        This method should be called to make the Connector eligible for garbage-collection in the Flash Player.
                        When called, this methods removes the listeners to the SmartFoxClient events added during initialization.
                        Example:
                        • To destroy the Connector instance:
                          connector.destroy()
                        • © 2004-2009 gotoAndPlay()