Ticket #9592: gtk-choice-setcolumns.2.diff

[wxWidgets.git] / interface / dde.h

diff --git a/interface/dde.h b/interface/dde.h
index 520508906bab17a92a8aeca6652d00e1692afb23..66b979df74d1a14cb3e18b2ccc9a38183811bd9e 100644 (file)
--- a/interface/dde.h
+++ b/interface/dde.h
@@ -11,54 +11,64 @@
     @wxheader{dde.h}
 
     A wxDDEConnection object represents the connection between a client and a
     @wxheader{dde.h}
 
     A wxDDEConnection object represents the connection between a client and a

-    server. It can be created by making a connection using a
-    wxDDEClient object, or by the acceptance of a connection by a
-    wxDDEServer object. The bulk of a DDE (Dynamic Data Exchange)
-    conversation is controlled by
-    calling members in a @b wxDDEConnection object or by overriding its
-    members.
+    server. It can be created by making a connection using a wxDDEClient
+    object, or by the acceptance of a connection by a wxDDEServer object. The
+    bulk of a DDE (Dynamic Data Exchange) conversation is controlled by calling
+    members in a wxDDEConnection object or by overriding its members.

 
     An application should normally derive a new connection class from
 
     An application should normally derive a new connection class from

-    wxDDEConnection, in order to override the communication event handlers
-    to do something interesting.
+    wxDDEConnection, in order to override the communication event handlers to
+    do something interesting.

 
 

-    This DDE-based implementation is available on Windows only,
-    but a platform-independent, socket-based version
-    of this API is available using wxTCPConnection.
+    This DDE-based implementation is available on Windows only, but a
+    platform-independent, socket-based version of this API is available using
+    wxTCPConnection.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{ipc}

 
 

-    @see wxDDEClient, wxDDEServer, @ref overview_ipcoverview "Interprocess
-    communications overview"
+    @see wxConnectionBase, wxDDEClient, wxDDEServer, @ref overview_ipc

 */
 */

-class wxDDEConnection : public wxObject
+class wxDDEConnection : public wxConnectionBase

 {
 public:
 {
 public:

-    //@{

     /**
         Constructs a connection object. If no user-defined connection object is
         to be derived from wxDDEConnection, then the constructor should not be
     /**
         Constructs a connection object. If no user-defined connection object is
         to be derived from wxDDEConnection, then the constructor should not be

-        called directly, since the default connection object will be provided on
-        requesting (or accepting) a connection. However, if the user defines his
-        or her own derived connection object, the wxDDEServer::OnAcceptConnection
-        and/or wxDDEClient::OnMakeConnection members should be replaced by
-        functions which construct the new connection object. If the arguments of
-        the wxDDEConnection constructor are void, then a default buffer is
-        associated with the connection. Otherwise, the programmer must provide a
-        a buffer and size of the buffer for the connection object to use in
-        transactions.
+        called directly, since the default connection object will be provided
+        on requesting (or accepting) a connection. However, if the user defines
+        his or her own derived connection object, the
+        wxDDEServer::OnAcceptConnection() and/or
+        wxDDEClient::OnMakeConnection() members should be replaced by functions
+        which construct the new connection object.
+
+        A default buffer will be associated with this connection.

     */
     wxDDEConnection();
     */
     wxDDEConnection();

+    /**
+        Constructs a connection object. If no user-defined connection object is
+        to be derived from wxDDEConnection, then the constructor should not be
+        called directly, since the default connection object will be provided
+        on requesting (or accepting) a connection. However, if the user defines
+        his or her own derived connection object, the
+        wxDDEServer::OnAcceptConnection() and/or
+        wxDDEClient::OnMakeConnection() members should be replaced by functions
+        which construct the new connection object.
+
+        @param buffer
+            Buffer for this connection object to use in transactions.
+        @param size
+            Size of the buffer given.
+    */

     wxDDEConnection(void* buffer, size_t size);
     wxDDEConnection(void* buffer, size_t size);

-    //@}

 
     //@{
     /**
         Called by the server application to advise the client of a change in
 
     //@{
     /**
         Called by the server application to advise the client of a change in

-        the data associated with the given item. Causes the client
-        connection's OnAdvise()
-        member to be called. Returns @true if successful.
+        the data associated with the given item. Causes the client connection's
+        OnAdvise() member to be called.
+
+        @return @true if successful.

     */
     bool Advise(const wxString& item, const void* data, size_t size,
                 wxIPCFormat format = wxIPC_PRIVATE);
     */
     bool Advise(const wxString& item, const void* data, size_t size,
                 wxIPCFormat format = wxIPC_PRIVATE);


@@ -69,22 +79,24 @@ public:
 
     /**
         Called by the client or server application to disconnect from the other
 
     /**
         Called by the client or server application to disconnect from the other

-        program; it causes the OnDisconnect() message
-        to be sent to the corresponding connection object in the other
-        program. The default behaviour of @b OnDisconnect is to delete the
-        connection, but the calling application must explicitly delete its
-        side of the connection having called @b Disconnect. Returns @true if
-        successful.
+        program; it causes the OnDisconnect() message to be sent to the
+        corresponding connection object in the other program. The default
+        behaviour of OnDisconnect() is to delete the connection, but the
+        calling application must explicitly delete its side of the connection
+        having called Disconnect().
+
+        @return @true if successful.

     */
     bool Disconnect();
 
     //@{
     /**
     */
     bool Disconnect();
 
     //@{
     /**

-        Called by the client application to execute a command on the server. Can
-        also be used to transfer arbitrary data to the server (similar
-        to Poke() in that respect). Causes the
-        server connection's OnExecute() member to be
-        called. Returns @true if successful.
+        Called by the client application to execute a command on the server.
+        Can also be used to transfer arbitrary data to the server (similar to
+        Poke() in that respect). Causes the server connection's OnExecute()
+        member to be called.
+
+        @return @true if successful.

     */
     bool Execute(const void* data, size_t size,
                  wxIPCFormat format = wxIPC_PRIVATE);
     */
     bool Execute(const void* data, size_t size,
                  wxIPCFormat format = wxIPC_PRIVATE);


@@ -97,11 +109,8 @@ public:
         Message sent to the client application when the server notifies it of a
         change in the data associated with the given item.
     */
         Message sent to the client application when the server notifies it of a
         change in the data associated with the given item.
     */

-    virtual bool OnAdvise(const wxString& topic,
-                          const wxString& item,
-                          const void* data,
-                          size_t size,
-                          wxIPCFormat format);
+    virtual bool OnAdvise(const wxString& topic, const wxString& item,
+                          const void* data, size_t size, wxIPCFormat format);

 
     /**
         Message sent to the client or server application when the other
 
     /**
         Message sent to the client or server application when the other


@@ -116,52 +125,46 @@ public:
         this message.
     */
     virtual bool OnExecute(const wxString& topic, const void* data,
         this message.
     */
     virtual bool OnExecute(const wxString& topic, const void* data,

-                           size_t size,
-                           wxIPCFormat format);
+                           size_t size, wxIPCFormat format);

 
     /**
         Message sent to the server application when the client notifies it to
         accept the given data.
     */
     virtual bool OnPoke(const wxString& topic, const wxString& item,
 
     /**
         Message sent to the server application when the client notifies it to
         accept the given data.
     */
     virtual bool OnPoke(const wxString& topic, const wxString& item,

-                        const void* data,
-                        size_t size,
-                        wxIPCFormat format);
+                        const void* data, size_t size, wxIPCFormat format);

 
     /**
 
     /**

-        Message sent to the server application when the client
-        calls Request(). The server
-        should respond by returning a character string from @b OnRequest,
-        or @NULL to indicate no data.
+        Message sent to the server application when the client calls Request().
+        The server should respond by returning a character string from
+        OnRequest(), or @NULL to indicate no data.

     */
     virtual const void* OnRequest(const wxString& topic,
     */
     virtual const void* OnRequest(const wxString& topic,

-                                  const wxString& item,
-                                  size_t* size,
+                                  const wxString& item, size_t* size,

                                   wxIPCFormat format);
 
     /**
         Message sent to the server application by the client, when the client
                                   wxIPCFormat format);
 
     /**
         Message sent to the server application by the client, when the client

-        wishes to start an 'advise loop' for the given topic and item. The
+        wishes to start an "advise loop" for the given topic and item. The

         server can refuse to participate by returning @false.
     */
         server can refuse to participate by returning @false.
     */

-    virtual bool OnStartAdvise(const wxString& topic,
-                               const wxString& item);
+    virtual bool OnStartAdvise(const wxString& topic, const wxString& item);

 
     /**
         Message sent to the server application by the client, when the client
 
     /**
         Message sent to the server application by the client, when the client

-        wishes to stop an 'advise loop' for the given topic and item. The
+        wishes to stop an "advise loop" for the given topic and item. The

         server can refuse to stop the advise loop by returning @false, although
         this doesn't have much meaning in practice.
     */
         server can refuse to stop the advise loop by returning @false, although
         this doesn't have much meaning in practice.
     */

-    virtual bool OnStopAdvise(const wxString& topic,
-                              const wxString& item);
+    virtual bool OnStopAdvise(const wxString& topic, const wxString& item);

 
     //@{
     /**
         Called by the client application to poke data into the server. Can be
         used to transfer arbitrary data to the server. Causes the server
 
     //@{
     /**
         Called by the client application to poke data into the server. Can be
         used to transfer arbitrary data to the server. Causes the server

-        connection's OnPoke() member
-        to be called. Returns @true if successful.
+        connection's OnPoke() member to be called.
+
+        @return @true if successful.

     */
     bool Poke(const wxString& item, const void* data, size_t size,
               wxIPCFormat format = wxIPC_PRIVATE);
     */
     bool Poke(const wxString& item, const void* data, size_t size,
               wxIPCFormat format = wxIPC_PRIVATE);


@@ -171,26 +174,30 @@ public:
     //@}
 
     /**
     //@}
 
     /**

-        Called by the client application to request data from the server. Causes
-        the server connection's OnRequest() member to be called. Returns a
-        character string (actually a pointer to the connection's buffer) if
-        successful, @NULL otherwise.
+        Called by the client application to request data from the server.
+        Causes the server connection's OnRequest() member to be called.
+
+        @return A character string (actually a pointer to the connection's
+                 buffer) if successful, @NULL otherwise.

     */
     const void* Request(const wxString& item, size_t* size,
                         wxIPCFormat format = wxIPC_TEXT);
 
     /**
     */
     const void* Request(const wxString& item, size_t* size,
                         wxIPCFormat format = wxIPC_TEXT);
 
     /**

-        Called by the client application to ask if an advise loop can be started
-        with the server. Causes the server connection's OnStartAdvise()
-        member to be called. Returns @true if the server okays it, @false
-        otherwise.
+        Called by the client application to ask if an advise loop can be
+        started with the server. Causes the server connection's OnStartAdvise()
+        member to be called.
+
+        @return @true if the server okays it, @false otherwise.

     */
     bool StartAdvise(const wxString& item);
 
     /**
         Called by the client application to ask if an advise loop can be
     */
     bool StartAdvise(const wxString& item);
 
     /**
         Called by the client application to ask if an advise loop can be

-        stopped. Causes the server connection's OnStopAdvise() member
-        to be called. Returns @true if the server okays it, @false otherwise.
+        stopped. Causes the server connection's OnStopAdvise() member to be
+        called.
+
+        @return @true if the server okays it, @false otherwise.

     */
     bool StopAdvise(const wxString& item);
 };
     */
     bool StopAdvise(const wxString& item);
 };


@@ -204,22 +211,21 @@ public:
     A wxDDEClient object represents the client part of a client-server DDE
     (Dynamic Data Exchange) conversation.
 
     A wxDDEClient object represents the client part of a client-server DDE
     (Dynamic Data Exchange) conversation.
 

-    To create a client which can communicate with a suitable server,
-    you need to derive a class from wxDDEConnection and another from wxDDEClient.
-    The custom wxDDEConnection class will intercept communications in
-    a 'conversation' with a server, and the custom wxDDEServer is required
-    so that a user-overridden wxDDEClient::OnMakeConnection member can return
-    a wxDDEConnection of the required class, when a connection is made.
+    To create a client which can communicate with a suitable server, you need
+    to derive a class from wxDDEConnection and another from wxDDEClient. The
+    custom wxDDEConnection class will intercept communications in a
+    "conversation" with a server, and the custom wxDDEServer is required so
+    that a user-overridden OnMakeConnection() member can return a
+    wxDDEConnection of the required class, when a connection is made.

 
 

-    This DDE-based implementation is
-    available on Windows only, but a platform-independent, socket-based version
-    of this API is available using wxTCPClient.
+    This DDE-based implementation is available on Windows only, but a
+    platform-independent, socket-based version of this API is available using
+    wxTCPClient.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{ipc}

 
 

-    @see wxDDEServer, wxDDEConnection, @ref overview_ipcoverview "Interprocess
-    communications overview"
+    @see wxDDEServer, wxDDEConnection, @ref overview_ipc

 */
 class wxDDEClient : public wxObject
 {
 */
 class wxDDEClient : public wxObject
 {


@@ -230,13 +236,13 @@ public:
     wxDDEClient();
 
     /**
     wxDDEClient();
 
     /**

-        Tries to make a connection with a server specified by the host
-        (machine name under UNIX, ignored under Windows), service name (must
-        contain an integer port number under UNIX), and topic string. If the
-        server allows a connection, a wxDDEConnection object will be returned.
-        The type of wxDDEConnection returned can be altered by overriding
-        the OnMakeConnection() member to return your own
-        derived connection object.
+        Tries to make a connection with a server specified by the host (machine
+        name under UNIX, ignored under Windows), service name (must contain an
+        integer port number under UNIX), and topic string. If the server allows
+        a connection, a wxDDEConnection object will be returned.
+
+        The type of wxDDEConnection returned can be altered by overriding the
+        OnMakeConnection() member to return your own derived connection object.

     */
     wxConnectionBase* MakeConnection(const wxString& host,
                                      const wxString& service,
     */
     wxConnectionBase* MakeConnection(const wxString& host,
                                      const wxString& service,


@@ -244,19 +250,20 @@ public:
 
     /**
         The type of wxDDEConnection returned from a MakeConnection() call can
 
     /**
         The type of wxDDEConnection returned from a MakeConnection() call can

-        be altered by deriving the @b OnMakeConnection member to return your
-        own derived connection object. By default, a wxDDEConnection
-        object is returned.
+        be altered by deriving the OnMakeConnection() member to return your own
+        derived connection object. By default, a wxDDEConnection object is
+        returned.
+

         The advantage of deriving your own connection class is that it will
         The advantage of deriving your own connection class is that it will

-        enable you to intercept messages initiated by the server, such
-        as wxDDEConnection::OnAdvise. You may also want to
-        store application-specific data in instances of the new class.
+        enable you to intercept messages initiated by the server, such as
+        wxDDEConnection::OnAdvise(). You may also want to store
+        application-specific data in instances of the new class.

     */
     wxConnectionBase* OnMakeConnection();
 
     /**
     */
     wxConnectionBase* OnMakeConnection();
 
     /**

-        Returns @true if this is a valid host name, @false otherwise. This always
-        returns @true under MS Windows.
+        Returns @true if this is a valid host name, @false otherwise. This
+        always returns @true under MS Windows.

     */
     bool ValidHost(const wxString& host);
 };
     */
     bool ValidHost(const wxString& host);
 };


@@ -270,14 +277,14 @@ public:
     A wxDDEServer object represents the server part of a client-server DDE
     (Dynamic Data Exchange) conversation.
 
     A wxDDEServer object represents the server part of a client-server DDE
     (Dynamic Data Exchange) conversation.
 

-    This DDE-based implementation is
-    available on Windows only, but a platform-independent, socket-based version
-    of this API is available using wxTCPServer.
+    This DDE-based implementation is available on Windows only, but a
+    platform-independent, socket-based version of this API is available using
+    wxTCPServer.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{ipc}

 
 

-    @see wxDDEClient, wxDDEConnection, @ref overview_ipcoverview "IPC overview"
+    @see wxDDEClient, wxDDEConnection, @ref overview_ipc

 */
 class wxDDEServer
 {
 */
 class wxDDEServer
 {


@@ -290,20 +297,22 @@ public:
     /**
         Registers the server using the given service name. Under UNIX, the
         string must contain an integer id which is used as an Internet port
     /**
         Registers the server using the given service name. Under UNIX, the
         string must contain an integer id which is used as an Internet port

-        number. @false is returned if the call failed (for example, the port
+        number. @false is returned if the call failed (for example, if the port

         number is already in use).
     */
     bool Create(const wxString& service);
 
     /**
         number is already in use).
     */
     bool Create(const wxString& service);
 
     /**

-        When a client calls @b MakeConnection, the server receives the
-        message and this member is called. The application should derive a
+        When a client calls wxDDEClient::MakeConnection(), the server receives
+        the message and this member is called. The application should derive a

         member to intercept this message and return a connection object of
         member to intercept this message and return a connection object of

-        either the standard wxDDEConnection type, or of a user-derived type. If the
-        topic is "STDIO'', the application may wish to refuse the connection.
-        Under UNIX, when a server is created the OnAcceptConnection message is
-        always sent for standard input and output, but in the context of DDE
-        messages it doesn't make a lot of sense.
+        either the standard wxDDEConnection type, or of a user-derived type.
+
+        If the @a topic is "STDIO", the application may wish to refuse the
+        connection. Under UNIX, when a server is created the
+        OnAcceptConnection() message is always sent for standard input and
+        output, but in the context of DDE messages it doesn't make a lot of
+        sense.

     */
     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
 };
     */
     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
 };