Mercurial > hg > xemacs-beta
annotate src/tooltalk.doc @ 5492:e82f5b7010fe
Merge some stuff in man, fix up Makefile
-------------------- ChangeLog entries follow: --------------------
man/ChangeLog addition:
2010-02-19 Ben Wing <ben@xemacs.org>
* widget.texi:
* widget.texi (Top):
* widget.texi (Introduction):
* widget.texi (User Interface):
* widget.texi (Programming Example):
* widget.texi (Setting Up the Buffer):
* widget.texi (Basic Types):
* widget.texi (link):
* widget.texi (url-link):
* widget.texi (info-link):
* widget.texi (push-button):
* widget.texi (editable-field):
* widget.texi (text):
* widget.texi (menu-choice):
* widget.texi (radio-button-choice):
* widget.texi (item):
* widget.texi (choice-item):
* widget.texi (toggle):
* widget.texi (checkbox):
* widget.texi (checklist):
* widget.texi (editable-list):
* widget.texi (group):
* widget.texi (Sexp Types):
* widget.texi (constants):
* widget.texi (generic):
* widget.texi (atoms):
* widget.texi (composite):
* widget.texi (Widget Properties):
* widget.texi (Defining New Widgets):
* widget.texi (Widget Browser):
* widget.texi (Widget Minor Mode):
* widget.texi (Utilities):
* widget.texi (Widget Wishlist):
* widget.texi (Widget Internals):
* widget.texi (GNU Free Documentation License):
* widget.texi (Index):
Sync with FSF 23.1.92.
2010-02-19 Ben Wing <ben@xemacs.org>
* texinfo/fdl.texi: New file.
* texinfo/texinfo.texi:
* texinfo/texinfo.texi (Top):
* texinfo/texinfo.texi (Copying Conditions):
* texinfo/texinfo.texi (Overview):
* texinfo/texinfo.texi (Reporting Bugs):
* texinfo/texinfo.texi (Using Texinfo):
* texinfo/texinfo.texi (Output Formats):
* texinfo/texinfo.texi (Info Files):
* texinfo/texinfo.texi (Printed Books):
* texinfo/texinfo.texi (Formatting Commands):
* texinfo/texinfo.texi (Conventions):
* texinfo/texinfo.texi (Comments):
* texinfo/texinfo.texi (Minimum):
* texinfo/texinfo.texi (Six Parts):
* texinfo/texinfo.texi (Short Sample):
* texinfo/texinfo.texi (History):
* texinfo/texinfo.texi (Texinfo Mode):
* texinfo/texinfo.texi (Texinfo Mode Overview):
* texinfo/texinfo.texi (XEmacs Editing):
* texinfo/texinfo.texi (Inserting):
* texinfo/texinfo.texi (Showing the Structure):
* texinfo/texinfo.texi (Updating Nodes and Menus):
* texinfo/texinfo.texi (Updating Commands):
* texinfo/texinfo.texi (Updating Requirements):
* texinfo/texinfo.texi (Other Updating Commands):
* texinfo/texinfo.texi (Info Formatting):
* texinfo/texinfo.texi (Printing):
* texinfo/texinfo.texi (Texinfo Mode Summary):
* texinfo/texinfo.texi (Beginning a File):
* texinfo/texinfo.texi (Sample Beginning):
* texinfo/texinfo.texi (Texinfo File Header):
* texinfo/texinfo.texi (First Line):
* texinfo/texinfo.texi (Start of Header):
* texinfo/texinfo.texi (setfilename):
* texinfo/texinfo.texi (settitle):
* texinfo/texinfo.texi (End of Header):
* texinfo/texinfo.texi (Document Permissions):
* texinfo/texinfo.texi (copying):
* texinfo/texinfo.texi (insertcopying):
* texinfo/texinfo.texi (Titlepage & Copyright Page):
* texinfo/texinfo.texi (titlepage):
* texinfo/texinfo.texi (titlefont center sp):
* texinfo/texinfo.texi (title subtitle author):
* texinfo/texinfo.texi (Copyright):
* texinfo/texinfo.texi (end titlepage):
* texinfo/texinfo.texi (headings on off):
* texinfo/texinfo.texi (Contents):
* texinfo/texinfo.texi (The Top Node):
* texinfo/texinfo.texi (Top Node Example):
* texinfo/texinfo.texi (Master Menu Parts):
* texinfo/texinfo.texi (Global Document Commands):
* texinfo/texinfo.texi (documentdescription):
* texinfo/texinfo.texi (setchapternewpage):
* texinfo/texinfo.texi (paragraphindent):
* texinfo/texinfo.texi (firstparagraphindent):
* texinfo/texinfo.texi (exampleindent):
* texinfo/texinfo.texi (Software Copying Permissions):
* texinfo/texinfo.texi (Ending a File):
* texinfo/texinfo.texi (Printing Indices & Menus):
* texinfo/texinfo.texi (File End):
* texinfo/texinfo.texi (Structuring):
* texinfo/texinfo.texi (Tree Structuring):
* texinfo/texinfo.texi (Structuring Command Types):
* texinfo/texinfo.texi (makeinfo top):
* texinfo/texinfo.texi (chapter):
* texinfo/texinfo.texi (unnumbered & appendix):
* texinfo/texinfo.texi (majorheading & chapheading):
* texinfo/texinfo.texi (section):
* texinfo/texinfo.texi (unnumberedsec appendixsec heading):
* texinfo/texinfo.texi (subsection):
* texinfo/texinfo.texi (unnumberedsubsec appendixsubsec subheading):
* texinfo/texinfo.texi (subsubsection):
* texinfo/texinfo.texi (Raise/lower sections):
* texinfo/texinfo.texi (Nodes):
* texinfo/texinfo.texi (Two Paths):
* texinfo/texinfo.texi (Node Menu Illustration):
* texinfo/texinfo.texi (node):
* texinfo/texinfo.texi (Node Names):
* texinfo/texinfo.texi (Writing a Node):
* texinfo/texinfo.texi (Node Line Tips):
* texinfo/texinfo.texi (Node Line Requirements):
* texinfo/texinfo.texi (First Node):
* texinfo/texinfo.texi (makeinfo top command):
* texinfo/texinfo.texi (makeinfo Pointer Creation):
* texinfo/texinfo.texi (anchor):
* texinfo/texinfo.texi (Menus):
* texinfo/texinfo.texi (Menu Location):
* texinfo/texinfo.texi (Writing a Menu):
* texinfo/texinfo.texi (Menu Parts):
* texinfo/texinfo.texi (Less Cluttered Menu Entry):
* texinfo/texinfo.texi (Menu Example):
* texinfo/texinfo.texi (Other Info Files):
* texinfo/texinfo.texi (Cross References):
* texinfo/texinfo.texi (References):
* texinfo/texinfo.texi (Cross Reference Commands):
* texinfo/texinfo.texi (Cross Reference Parts):
* texinfo/texinfo.texi (xref):
* texinfo/texinfo.texi (Reference Syntax):
* texinfo/texinfo.texi (One Argument):
* texinfo/texinfo.texi (Two Arguments):
* texinfo/texinfo.texi (Three Arguments):
* texinfo/texinfo.texi (Four and Five Arguments):
* texinfo/texinfo.texi (Top Node Naming):
* texinfo/texinfo.texi (ref):
* texinfo/texinfo.texi (pxref):
* texinfo/texinfo.texi (inforef):
* texinfo/texinfo.texi (uref):
* texinfo/texinfo.texi (cite):
* texinfo/texinfo.texi (Marking Text):
* texinfo/texinfo.texi (Indicating):
* texinfo/texinfo.texi (Useful Highlighting):
* texinfo/texinfo.texi (code):
* texinfo/texinfo.texi (kbd):
* texinfo/texinfo.texi (key):
* texinfo/texinfo.texi (samp):
* texinfo/texinfo.texi (verb):
* texinfo/texinfo.texi (var):
* texinfo/texinfo.texi (env):
* texinfo/texinfo.texi (file):
* texinfo/texinfo.texi (command):
* texinfo/texinfo.texi (option):
* texinfo/texinfo.texi (dfn):
* texinfo/texinfo.texi (abbr):
* texinfo/texinfo.texi (acronym):
* texinfo/texinfo.texi (indicateurl):
* texinfo/texinfo.texi (email):
* texinfo/texinfo.texi (Emphasis):
* texinfo/texinfo.texi (emph & strong):
* texinfo/texinfo.texi (Smallcaps):
* texinfo/texinfo.texi (Fonts):
* texinfo/texinfo.texi (Quotations and Examples):
* texinfo/texinfo.texi (Block Enclosing Commands):
* texinfo/texinfo.texi (quotation):
* texinfo/texinfo.texi (example):
* texinfo/texinfo.texi (verbatim):
* texinfo/texinfo.texi (verbatiminclude):
* texinfo/texinfo.texi (lisp):
* texinfo/texinfo.texi (small):
* texinfo/texinfo.texi (display):
* texinfo/texinfo.texi (format):
* texinfo/texinfo.texi (exdent):
* texinfo/texinfo.texi (flushleft & flushright):
* texinfo/texinfo.texi (noindent):
* texinfo/texinfo.texi (indent):
* texinfo/texinfo.texi (cartouche):
* texinfo/texinfo.texi (Lists and Tables):
* texinfo/texinfo.texi (Introducing Lists):
* texinfo/texinfo.texi (itemize):
* texinfo/texinfo.texi (enumerate):
* texinfo/texinfo.texi (Two-column Tables):
* texinfo/texinfo.texi (table):
* texinfo/texinfo.texi (ftable vtable):
* texinfo/texinfo.texi (itemx):
* texinfo/texinfo.texi (Multi-column Tables):
* texinfo/texinfo.texi (Multitable Column Widths):
* texinfo/texinfo.texi (Multitable Rows):
* texinfo/texinfo.texi (Special Displays):
* texinfo/texinfo.texi (Floats):
* texinfo/texinfo.texi (float):
* texinfo/texinfo.texi (caption shortcaption):
* texinfo/texinfo.texi (listoffloats):
* texinfo/texinfo.texi (Images):
* texinfo/texinfo.texi (Image Syntax):
* texinfo/texinfo.texi (Image Scaling):
* texinfo/texinfo.texi (Footnotes):
* texinfo/texinfo.texi (Footnote Commands):
* texinfo/texinfo.texi (Footnote Styles):
* texinfo/texinfo.texi (Indices):
* texinfo/texinfo.texi (Index Entries):
* texinfo/texinfo.texi (Predefined Indices):
* texinfo/texinfo.texi (Indexing Commands):
* texinfo/texinfo.texi (Combining Indices):
* texinfo/texinfo.texi (syncodeindex):
* texinfo/texinfo.texi (synindex):
* texinfo/texinfo.texi (New Indices):
* texinfo/texinfo.texi (Insertions):
* texinfo/texinfo.texi (Atsign Braces Comma):
* texinfo/texinfo.texi (Inserting an Atsign):
* texinfo/texinfo.texi (Inserting Braces):
* texinfo/texinfo.texi (Inserting a Comma):
* texinfo/texinfo.texi (Inserting Quote Characters):
* texinfo/texinfo.texi (Inserting Space):
* texinfo/texinfo.texi (Not Ending a Sentence):
* texinfo/texinfo.texi (Ending a Sentence):
* texinfo/texinfo.texi (Multiple Spaces):
* texinfo/texinfo.texi (frenchspacing):
* texinfo/texinfo.texi (dmn):
* texinfo/texinfo.texi (Inserting Accents):
* texinfo/texinfo.texi (Inserting Quotation Marks):
* texinfo/texinfo.texi (Dots Bullets):
* texinfo/texinfo.texi (dots):
* texinfo/texinfo.texi (bullet):
* texinfo/texinfo.texi (TeX and copyright):
* texinfo/texinfo.texi (tex):
* texinfo/texinfo.texi (copyright symbol):
* texinfo/texinfo.texi (registered symbol):
* texinfo/texinfo.texi (euro):
* texinfo/texinfo.texi (pounds):
* texinfo/texinfo.texi (textdegree):
* texinfo/texinfo.texi (minus):
* texinfo/texinfo.texi (geq leq):
* texinfo/texinfo.texi (math):
* texinfo/texinfo.texi (Click Sequences):
* texinfo/texinfo.texi (Glyphs):
* texinfo/texinfo.texi (Glyphs Summary):
* texinfo/texinfo.texi (result):
* texinfo/texinfo.texi (expansion):
* texinfo/texinfo.texi (Print Glyph):
* texinfo/texinfo.texi (Error Glyph):
* texinfo/texinfo.texi (Equivalence):
* texinfo/texinfo.texi (Point Glyph):
* texinfo/texinfo.texi (Breaks):
* texinfo/texinfo.texi (Break Commands):
* texinfo/texinfo.texi (Line Breaks):
* texinfo/texinfo.texi (- and hyphenation):
* texinfo/texinfo.texi (allowcodebreaks):
* texinfo/texinfo.texi (w):
* texinfo/texinfo.texi (tie):
* texinfo/texinfo.texi (sp):
* texinfo/texinfo.texi (page):
* texinfo/texinfo.texi (group):
* texinfo/texinfo.texi (need):
* texinfo/texinfo.texi (Definition Commands):
* texinfo/texinfo.texi (Def Cmd Template):
* texinfo/texinfo.texi (Def Cmd Continuation Lines):
* texinfo/texinfo.texi (Optional Arguments):
* texinfo/texinfo.texi (deffnx):
* texinfo/texinfo.texi (Def Cmds in Detail):
* texinfo/texinfo.texi (Functions Commands):
* texinfo/texinfo.texi (Variables Commands):
* texinfo/texinfo.texi (Typed Functions):
* texinfo/texinfo.texi (Typed Variables):
* texinfo/texinfo.texi (Data Types):
* texinfo/texinfo.texi (Abstract Objects):
* texinfo/texinfo.texi (Object-Oriented Variables):
* texinfo/texinfo.texi (Object-Oriented Methods):
* texinfo/texinfo.texi (Defining Macros):
* texinfo/texinfo.texi (Invoking Macros):
* texinfo/texinfo.texi (Macro Details):
* texinfo/texinfo.texi (alias):
* texinfo/texinfo.texi (definfoenclose):
* texinfo/texinfo.texi (Hardcopy):
* texinfo/texinfo.texi (Use TeX):
* texinfo/texinfo.texi (Format with tex/texindex):
* texinfo/texinfo.texi (Format with texi2dvi):
* texinfo/texinfo.texi (Print with lpr):
* texinfo/texinfo.texi (Within XEmacs):
* texinfo/texinfo.texi (Texinfo Mode Printing):
* texinfo/texinfo.texi (Compile-Command):
* texinfo/texinfo.texi (Requirements Summary):
* texinfo/texinfo.texi (Preparing for TeX):
* texinfo/texinfo.texi (Overfull hboxes):
* texinfo/texinfo.texi (smallbook):
* texinfo/texinfo.texi (A4 Paper):
* texinfo/texinfo.texi (pagesizes):
* texinfo/texinfo.texi (Cropmarks and Magnification):
* texinfo/texinfo.texi (PDF Output):
* texinfo/texinfo.texi (Obtaining TeX):
* texinfo/texinfo.texi (Creating and Installing Info Files):
* texinfo/texinfo.texi (Creating an Info File):
* texinfo/texinfo.texi (makeinfo advantages):
* texinfo/texinfo.texi (Invoking makeinfo):
* texinfo/texinfo.texi (makeinfo options):
* texinfo/texinfo.texi (Pointer Validation):
* texinfo/texinfo.texi (makeinfo in XEmacs):
* texinfo/texinfo.texi (texinfo-format commands):
* texinfo/texinfo.texi (Batch Formatting):
* texinfo/texinfo.texi (Tag and Split Files):
* texinfo/texinfo.texi (Installing an Info File):
* texinfo/texinfo.texi (Directory File):
* texinfo/texinfo.texi (New Info File):
* texinfo/texinfo.texi (Other Info Directories):
* texinfo/texinfo.texi (Installing Dir Entries):
* texinfo/texinfo.texi (Invoking install-info):
* texinfo/texinfo.texi (Generating HTML):
* texinfo/texinfo.texi (HTML Translation):
* texinfo/texinfo.texi (HTML Splitting):
* texinfo/texinfo.texi (HTML CSS):
* texinfo/texinfo.texi (HTML Xref):
* texinfo/texinfo.texi (HTML Xref Link Basics):
* texinfo/texinfo.texi (HTML Xref Node Name Expansion):
* texinfo/texinfo.texi (HTML Xref Command Expansion):
* texinfo/texinfo.texi (HTML Xref 8-bit Character Expansion):
* texinfo/texinfo.texi (HTML Xref Mismatch):
* texinfo/texinfo.texi (Command List):
* texinfo/texinfo.texi (Command Syntax):
* texinfo/texinfo.texi (Tips):
* texinfo/texinfo.texi (Sample Texinfo Files):
* texinfo/texinfo.texi (Short Sample Texinfo File):
* texinfo/texinfo.texi (GNU Sample Texts):
* texinfo/texinfo.texi (Invoking sample):
* texinfo/texinfo.texi (GNU Free Documentation License):
* texinfo/texinfo.texi (Index):
* texinfo/texinfo.texi (Verbatim Copying License):
* texinfo/texinfo.texi (All-permissive Copying License):
* texinfo/texinfo.texi (Include Files):
* texinfo/texinfo.texi (Using Include Files):
* texinfo/texinfo.texi (texinfo-multiple-files-update):
* texinfo/texinfo.texi (Include Files Requirements):
* texinfo/texinfo.texi (Sample Include File):
* texinfo/texinfo.texi (Include Files Evolution):
* texinfo/texinfo.texi (Headings):
* texinfo/texinfo.texi (Headings Introduced):
* texinfo/texinfo.texi (Heading Format):
* texinfo/texinfo.texi (Heading Choice):
* texinfo/texinfo.texi (Custom Headings):
* texinfo/texinfo.texi (Catching Mistakes):
* texinfo/texinfo.texi (makeinfo Preferred):
* texinfo/texinfo.texi (Debugging with Info):
* texinfo/texinfo.texi (Debugging with TeX):
* texinfo/texinfo.texi (Using texinfo-show-structure):
* texinfo/texinfo.texi (Using occur):
* texinfo/texinfo.texi (Running Info-Validate):
* texinfo/texinfo.texi (Using Info-validate):
* texinfo/texinfo.texi (Unsplit):
* texinfo/texinfo.texi (Tagifying):
* texinfo/texinfo.texi (Splitting):
* texinfo/texinfo.texi (Refilling Paragraphs):
* texinfo/texinfo.texi (Command and Variable Index):
* texinfo/texinfo.texi (General Index):
* texinfo/version.texi: New file.
Sync with FSF 23.1.92. Make new directory to hold the files needed
to generate texinfo.info, since there are three such files now.
2010-02-19 Ben Wing <ben@xemacs.org>
* Makefile:
* Makefile (src_files1):
* Makefile (DIR):
* Makefile (texinfo-srcs):
* Makefile ($(INFODIR)/widget.info):
* Makefile ($(INFODIR)/texinfo.info):
* Makefile (.PHONY):
* Makefile (texinfo.dvi):
* Makefile (texinfo.pdf):
* Makefile ($(HTMLDIR)/widget.html):
* Makefile ($(HTMLDIR)/texinfo.html):
Incorporate texinfo.texi moving to a subdirectory texinfo/.
Do some tricks to reduce the amount of duplication while still
maintaining compatible with non-GNU make (at least, with
Solaris make).
* doclicense.texi: New file.
* info.texi:
* info.texi (Top):
* info.texi (Getting Started):
* info.texi (Help-Small-Screen):
* info.texi (Help):
* info.texi (Help-P):
* info.texi (Help-^L):
* info.texi (Help-Inv):
* info.texi (Help-]):
* info.texi (Help-M):
* info.texi (Help-FOO):
* info.texi (Help-Xref):
* info.texi (Help-Int):
* info.texi (Help-Q):
* info.texi (Advanced):
* info.texi (Search Text):
* info.texi (Search Index):
* info.texi (Go to node):
* info.texi (Choose menu subtopic):
* info.texi (Create Info buffer):
* info.texi (XEmacs Info Variables):
* info.texi (Expert Info):
* info.texi (Add):
* info.texi (Menus):
* info.texi (Cross-refs):
* info.texi (Help-Cross):
* info.texi (Tags):
* info.texi (Checking):
* info.texi (Index):
* texinfo.tex:
* texinfo.tex (paragraphindent{%):
* texinfo.tex (sectionheading will have):
* texinfo.tex (chapterzzz{#3}%):
* texinfo.tex (subsubsection = \numberedsubsubsec):
* texinfo.tex (subsubsection = \appendixsubsubsec):
* texinfo.tex (subsubsection = \unnumberedsubsubsec):
* texinfo.tex (sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}%):
* texinfo.tex (sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}%):
* texinfo.tex (sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}%):
* texinfo.tex (sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}%):
* texinfo.tex (sectionheading{#1}{subsec}{Yappendix}%):
* texinfo.tex (sectionheading{#1}{subsec}{Ynothing}%):
* texinfo.tex (sectionheading{#1}{subsubsec}{Ynumbered}%):
* texinfo.tex (sectionheading{#1}{subsubsec}{Yappendix}%):
* texinfo.tex (sectionheading{#1}{subsubsec}{Ynothing}%):
* texinfo.tex (sectionheading{#1}{subsubsec}{Yomitfromtoc}{}):
* texinfo.tex (sectionheading to do the printing.):
* texinfo.tex (sectionlevel}{#1}{#4}%):
* texinfo.tex (sectionheading, q.v.):
Sync with FSF 23.1.92.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Fri, 19 Feb 2010 22:39:19 -0600 |
| parents | 576fb035e263 |
| children | 365bc8cb5894 |
| rev | line source |
|---|---|
| 428 | 1 |
| 2 Emacs Tooltalk API Summary | |
| 3 | |
| 4 The Emacs Lisp interface to Tooltalk is similar, at least in spirit, | |
| 5 to the standard C Tootalk API. Only the message and pattern parts | |
| 6 of the API are supported at present, more of the API could be added | |
| 7 if needed. The Lisp interface departs from the C API in a few ways: | |
| 8 | |
| 9 - Tooltalk is initialized automatically at emacs startup-time. Messages | |
| 10 can only be sent other Tooltalk applications connected to the same | |
| 11 X11 server that emacs is running on. | |
| 12 | |
| 13 - There are fewer entry points, polymorphic functions with keyword | |
| 14 arguments are used instead. | |
| 15 | |
| 16 - The callback interface is simpler and marginally less functional. | |
| 17 A single callback may be associated with a message or a pattern, | |
| 18 the callback is specified with a Lisp symbol (the symbol should | |
| 19 have a function binding). | |
| 20 | |
| 21 - The session attribute for messages and patterns is always | |
| 22 initialized to the default session. | |
| 23 | |
| 24 - Anywhere a Tooltalk enum constant, e.g. TT_SESSION, is valid one | |
| 25 can substitute the corresponding symbol, e.g. 'TT_SESSION. This | |
| 26 simplifies building lists that represent messages and patterns. | |
| 27 | |
| 28 | |
| 29 * Example: Receiving Messages | |
| 30 | |
| 31 Here's a simple example of a handler for a message that tells | |
| 32 emacs to display a string in the mini-buffer area. The message | |
| 33 operation is called "emacs-display-string", its first (0th) argument | |
| 34 is the string to display: | |
| 35 | |
| 36 (defun tooltalk-display-string-handler (msg) | |
| 37 (message (get-tooltalk-message-attribute msg 'arg_val 0))) | |
| 38 | |
| 39 (defvar display-string-pattern | |
| 40 '(category TT_HANDLE | |
| 41 scope TT_SESSION | |
| 42 op "emacs-display-string" | |
| 43 callback tooltalk-display-string-handler)) | |
| 44 | |
| 45 (let ((p (make-tooltalk-pattern display-string-pattern))) | |
| 46 (register-tooltalk-pattern p)) | |
| 47 | |
| 48 | |
| 49 * Example: Sending Messages | |
| 50 | |
| 51 Here's a simple example that sends a query to another application | |
| 52 and then displays its reply. Both the query and the reply are | |
| 53 stored in the first argument of the message. | |
| 54 | |
| 55 (defun tooltalk-random-query-handler (msg) | |
| 56 (let ((state (get-tooltalk-message-attribute msg 'state))) | |
| 57 (cond | |
| 58 ((eq state 'TT_HANDLED) | |
| 59 (message (get-tooltalk-message-attribute msg arg_val 0))) | |
| 60 ((memq state '(TT_FAILED TT_REJECTED)) | |
| 61 (message "Random query turns up nothing"))))) | |
| 62 | |
| 63 (defvar random-query-message | |
| 64 '( class TT_REQUEST | |
| 65 scope TT_SESSION | |
| 66 address TT_PROCEDURE | |
| 67 op "random-query" | |
| 68 args '((TT_INOUT "?" "string")) | |
| 69 callback tooltalk-random-query-handler)) | |
| 70 | |
| 71 (let ((m (make-tooltalk-message random-query-message))) | |
| 72 (send-tooltalk-message m)) | |
| 73 | |
| 74 | |
| 75 * Emacs Lisp Tooltalk API | |
| 76 | |
| 77 ** Sending Messages: | |
| 78 | |
| 79 (make-tooltalk-message attributes) | |
| 80 | |
| 81 Create a tooltalk message and initialize its attributes. | |
| 82 The value of attributes must be a list of alternating keyword/values, | |
| 83 where keywords are symbols that name valid message attributes. | |
| 84 For example: | |
| 85 | |
| 86 (make-tooltalk-message | |
| 87 '(class TT_NOTICE | |
| 88 scope TT_SESSION | |
| 89 address TT_PROCEDURE | |
| 90 op "do-something" | |
| 91 args ("arg1" 12345 (TT_INOUT "arg3" "string")))) | |
| 92 | |
| 93 Values must always be strings, integers, or symbols that | |
| 94 represent Tooltalk constants. Attribute names are the same as | |
| 95 those supported by set-tooltalk-message-attribute, plus 'args. | |
| 96 | |
| 97 The value of args should be a list of message arguments where | |
| 98 each message argument has the following form: | |
| 99 | |
| 100 (mode [value [type]]) or just value | |
| 101 | |
| 102 Where mode is one of TT_IN, TT_OUT, TT_INOUT and type is a string. | |
| 103 If type isn't specified then "int" is used if the value is a | |
| 104 number otherwise "string" is used. If type is "string" then value is | |
| 105 converted to a string (if it isn't a string already) with | |
| 106 prin1-to-string. If only a value is specified then mode defaults | |
| 107 to TT_IN. If mode is TT_OUT then value and type don't need | |
| 108 to be specified. You can find out more about the semantics and | |
| 109 uses of ToolTalk message arguments in chapter 4 of the Tooltalk | |
| 110 Programmers Guide. | |
| 111 | |
| 112 | |
| 113 | |
| 114 (send-tooltalk-message msg) | |
| 115 | |
| 116 Send the message on its way. Once the message has been sent it's | |
| 117 almost always a good idea to get rid of it with destroy-tooltalk-message. | |
| 118 | |
| 119 | |
| 120 | |
| 121 (return-tooltalk-message msg &optional mode) | |
| 122 | |
| 123 Send a reply to this message. The second argument can be | |
| 124 'reply, 'reject or 'fail, the default is 'reply. Before sending | |
| 125 a reply all message arguments whose mode is TT_INOUT or TT_OUT should | |
| 126 have been filled in - see set-tooltalk-message-attribute." | |
| 127 | |
| 128 | |
| 129 | |
| 130 (get-tooltalk-message-attribute msg attribute &optional argn) | |
| 131 | |
| 132 Returns the indicated Tooltalk message attribute. Attributes are | |
| 133 identified by symbols with the same name (underscores and all) as the | |
| 134 suffix of the Tooltalk tt_message_<attribute> function that extracts the value. | |
| 135 String attribute values are copied, enumerated type values (except disposition) | |
| 136 are converted to symbols - e.g. TT_HANDLER is 'TT_HANDLER, uid and gid are | |
| 137 represented by fixnums (small integers), opnum is converted to a string, | |
| 138 and disposition is converted to a fixnum. We convert opnum (a C int) to a | |
| 139 string, e.g. 123 => \"123\" because there's no guarantee that opnums will fit | |
| 140 within the range of Emacs Lisp integers. | |
| 141 | |
| 142 [TBD] Use the 'plist attribute instead of C API 'user attribute | |
| 143 for user defined message data. To retrieve the value of a message property | |
| 144 specify the indicator for argn. For example to get the value of a property | |
| 145 called 'rflagg, use | |
| 146 (get-tooltalk-message-attribute msg 'plist 'rflag) | |
| 147 | |
| 148 | |
| 149 To get the value of a message argument use one of the 'arg_val (strings), | |
| 150 'arg_ival (integers), or 'arg_bval (strings with embedded nulls), attributes. | |
| 151 Because integer valued arguments can be larger than Emacs Lisp integers | |
| 152 'arg_ival yields a string. If the value is will fit within 24 bits then | |
| 153 convert it to an integer with string-to-int. For example to get the integer | |
| 154 value of the third argument: | |
| 155 | |
| 156 (string-to-int (get-tooltalk-message-attribute msg 'arg_ival 2)) | |
| 157 | |
| 158 As you can see, argument numbers are zero based. The type of each arguments | |
| 159 can be retrieved, with the 'arg_type attribute, however Tooltalk doesn't | |
| 160 define any semantics for the string value of 'arg_type. Conventionally | |
| 161 "string" is used for strings and "int" for 32 bit integers. Note that | |
| 162 Emacs Lisp stores the lengths of strings explicitly (unlike C) so treating the | |
| 163 value returned by 'arg_bval like a string is fine. | |
| 164 | |
| 165 | |
| 166 | |
| 167 | |
| 168 (set-tooltalk-message-attribute value msg attribute &optional argn) | |
| 169 | |
| 170 Initialize one ToolTalk message attribute. | |
| 171 | |
| 172 Attribue names and values are the same as for get-tooltalk-message-attribute. | |
| 173 A property list is provided for user data (instead of the 'user message | |
| 174 attribute), see get-tooltalk-message-attribute. | |
| 175 | |
| 176 Callbacks are handled slightly differently than in the C Tooltalk API. | |
| 177 The value of callback should be the name of a function of one argument. | |
| 178 It will be called each time the state of the message changes. This | |
| 179 is usually used to notice when the messages state has | |
| 180 changed to TT_HANDLED (or TT_FAILED), so that reply argument values | |
| 181 can be used. | |
| 182 | |
| 183 If one of the argument attributes is specified, 'arg_val, 'arg_ival, or | |
| 184 'arg_bval then argn must be the number of an already created argument. | |
| 185 Arguments can be added to a message with add-tooltalk-message-arg. | |
| 186 | |
| 187 | |
| 188 | |
| 189 (add-tooltalk-message-arg msg mode type &optional value) | |
| 190 | |
| 191 Append one new argument to the message. Mode must be one of: TT_IN, | |
| 192 TT_INOUT, or TT_OUT, type must be a string, and value can | |
| 193 be a string or an integer. Tooltalk doesn't | |
| 194 define any semantics for type, so only the participants in the | |
| 195 protocol you're using need to agree what types mean (if anything). | |
| 196 Conventionally "string" is used for strings and "int" for 32 bit integers. | |
| 197 Arguments can initialized by providing a value or with | |
| 198 set-tooltalk-message-attribute, the latter is necessary if you | |
| 199 want to initialize the argument with a string that can contain | |
| 200 embedded nulls (use 'arg_bval). | |
| 201 | |
| 202 | |
| 203 (create-tooltalk-message) | |
| 204 | |
| 205 Create a new tooltalk message. The messages session attribute is | |
| 206 initialized to the default session. Other attributes can be initialized | |
| 207 with set-tooltalk-message-attribute. Make-tooltalk-message is the | |
| 208 preferred to create and initialize a message. | |
| 209 | |
| 210 | |
| 211 (destroy-tooltalk-message msg) | |
| 212 | |
| 213 Apply tt_message_destroy to the message. It's not necessary | |
| 214 to destroy messages after they've been processed by a message or | |
| 215 pattern callback, the Lisp/Tooltalk callback machinery does this | |
| 216 for you. | |
| 217 | |
| 218 | |
| 219 | |
| 220 ** Receiving Messages: | |
| 221 | |
| 222 | |
| 223 (make-tooltalk-pattern attributes) | |
| 224 | |
| 225 Create a tooltalk pattern and initialize its attributes. | |
| 226 The value of attributes must be a list of alternating keyword/values, | |
| 227 where keywords are symbols that name valid pattern attributes | |
| 228 or lists of valid attributes. For example: | |
| 229 | |
| 230 (make-tooltalk-pattern | |
| 231 '(category TT_OBSERVE | |
| 232 scope TT_SESSION | |
| 233 op ("operation1" "operation2") | |
| 234 args ("arg1" 12345 (TT_INOUT "arg3" "string")))) | |
| 235 | |
| 236 Attribute names are the same as those supported by | |
| 237 add-tooltalk-pattern-attribute, plus 'args. | |
| 238 | |
| 239 Values must always be strings, integers, or symbols that | |
| 240 represent Tooltalk constants or lists of same. When a list | |
| 241 of values is provided all of the list elements are added to | |
| 242 the attribute. In the example above, messages whose op | |
| 243 attribute is "operation1" or "operation2" would match the pattern. | |
| 244 | |
| 245 The value of args should be a list of pattern arguments where | |
| 246 each pattern argument has the following form: | |
| 247 | |
| 248 (mode [value [type]]) or just value | |
| 249 | |
| 250 Where mode is one of TT_IN, TT_OUT, TT_INOUT and type is a string. | |
| 251 If type isn't specified then "int" is used if the value is a | |
| 252 number otherwise "string" is used. If type is "string" then value is | |
| 253 converted to a string (if it isn't a string already) with | |
| 254 prin1-to-string. If only a value is specified then mode defaults | |
| 255 to TT_IN. If mode is TT_OUT then value and type don't need | |
| 256 to be specified. You can find out more about the semantics and | |
| 257 uses of ToolTalk pattern arguments in chapter 3 of the Tooltalk | |
| 258 Programmers Guide. | |
| 259 | |
| 260 | |
| 261 | |
| 262 (register-tooltalk-pattern pat) | |
| 263 | |
| 264 Emacs will begin receiving messages that match this pattern. | |
| 265 | |
| 266 | |
| 267 (unregister-tooltalk-pattern pat) | |
| 268 | |
| 269 Emacs will stop receiving messages that match this pattern. | |
| 270 | |
| 271 | |
| 272 | |
| 273 (add-tooltalk-pattern-attribute value pat indicator) | |
| 274 | |
| 275 Add one value to the indicated pattern attribute. The names of attributes | |
| 276 are the same as the Tooltalk accessors used to set them less the | |
| 277 "tooltalk_pattern_" prefix and the "_add" suffix). For example | |
| 444 | 278 the name of the attribute for tt_pattern_disposition_add attribute |
| 428 | 279 is 'disposition. The 'category attribute is handled specially, |
| 280 since a pattern can only be a member of one category (TT_OBSERVE | |
| 281 or TT_HANDLE. | |
| 282 | |
| 283 Callbacks are handled slightly differently than in the C Tooltalk API. | |
| 284 The value of callback should be the name of a function of one argument. | |
| 285 It will be called each time the pattern matches an incoming message. | |
| 286 | |
| 287 | |
| 288 | |
| 289 (add-tooltalk-pattern-arg pat mode type value) | |
| 290 | |
| 291 Add one, fully specified, argument to a tooltalk pattern. Mode must | |
| 292 be one of TT_IN, TT_INOUT, or TT_OUT, type must be a string. | |
| 293 Value can be an integer, string or nil. If value is an integer then | |
| 294 an integer argument (tt_pattern_iarg_add) added otherwise a string argument | |
| 295 is added. At present there's no way to add a binary data argument. | |
| 296 | |
| 297 | |
| 298 (create-tooltalk-pattern) | |
| 299 | |
| 300 Create a new Tooltalk pattern and initialize its session attribute to | |
| 301 be the default session. | |
| 302 | |
| 303 | |
| 304 | |
| 305 (destroy-tooltalk-pattern pat) | |
| 306 | |
| 307 Apply tt_pattern_destroy to the pattern. This effecticely unregisters | |
| 308 the pattern. | |
| 309 | |
| 310 | |
| 311 | |
| 312 (describe-tooltalk-message msg &optional stream) | |
| 313 | |
| 314 Print the messages attributes and arguments to stream. This is often | |
| 315 useful for debugging. | |
| 316 | |
| 317 | |
| 318 | |
| 319 * Things to be Done | |
| 320 | |
| 321 - At the moment there is almost no support for detecting and | |
| 322 handling ToolTalk errors. This should be added. | |
| 323 | |
| 324 - Message and patterns should support a plist attribute. This | |
| 325 would be based on one more Tooltalk user data key. This would also make | |
| 326 it useful to apply the message and pattern callbacks to | |
| 327 both the message and the matching pattern. | |
| 328 | |
| 329 | |
| 330 |