home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 3 / Amiga Tools 3.iso / programming / triton / developer / blitzbasic / readme < prev   
Encoding:
Text File  |  1995-08-25  |  10.8 KB  |  337 lines
  1.                               TRITON.bb2
  2.                         A short documentation
  3.                          "The key to TRITON"
  4.  
  5.                            by Philipp Lonke
  6.  
  7.  
  8. 1. Introduction
  9.  
  10.     First of all, forget everything about GUI programming in Blitz. It
  11.     is not the same creating a GadTool-GUI or a TRITON GUI.
  12.  
  13.     Read this documentation carefully, so you really understand the
  14.     difference.
  15.  
  16.     I wish to thank a lot Rupert "HelpApp" Henson, without his help
  17.     this conversion could not been finished. He had the trick how to
  18.     do the Project-TagList and helped me converting the macros.
  19.  
  20. 2.  Some useful definitions
  21.  
  22.     When speaking of TRITON, there are to major terms:
  23.         an application: That is your program. The informations
  24.                         (application tags) are for use in the
  25.                         TRITON Preferences Editor (ShareWare)
  26.  
  27.         an project    : In fact, that's your GUI. For every
  28.                         window you use, you create a new project.
  29.  
  30.     Second, every string passed to any TRITON function or macro or
  31.     whatever, has to be null-terminated. So do never use something
  32.     like "#TRCA_Name, name$" but always use
  33.  
  34.     #TRCA_Name, Null(name$)
  35.  
  36. 3.  How to start??
  37.  
  38.     First of all, you have to convert the file "triton/developer/fd/
  39.     triton_lib.fd" with FDConvert. This program you should find in
  40.     your Blitz2:BBTools-drawer or on any Blitz2-ftp-site.
  41.     Put the converted library in "blitzlibs:amigalibs/..." and create
  42.     a new DefLibs-file with MakeDefLibs.
  43.  
  44.     I use the program "tritontemplate.bb2" to explain how you get
  45.     to a simple GUI. Further information an tricks you can take off
  46.     all the other demo listings (for cycle gadgets, listviews etc.)
  47.  
  48. -------------- beginning of documented sourcecode -----------------
  49.  
  50. ;/*
  51. ; *  Triton - The object oriented GUI creation system For the AMIGA
  52. ; *  Written by Stefan Zeiger in 1993-1995
  53. ; *  Transfer to BlitzBasic2 by Ph. Lonke and Rupert Henson
  54. ; *
  55.  
  56. ; this include must precede everything. And remember also to include
  57. ; amigalibs.res somewhere!! (amiga-o)
  58. INCLUDE "blitz2:bbincludes/libraries/triton.bb2"
  59.  
  60. ; if you plan to open more windows, you should create more tmp_tags
  61. ; i.e. tmp_tags1,tmp_tags2 etc.
  62. ; the newtype "taggies" is defined in "triton.bb2"
  63. DEFTYPE .taggies tmp_tags
  64.  
  65.  
  66. ; we have to name our application and project(s) for use in our code
  67. *application.TR_App=0
  68. *project.TR_Project=0
  69.  
  70. Dim apptags.TagItem(7)
  71. Dim projtags.TagItem(1000)
  72.  
  73. ;the following statement is used to create our taglist. remember that
  74. ;you need a new statement for every project (window!) you create!!!
  75. ;do never use the same variables in the projects. The simplest way is
  76. ;to numerate it (projindex1,projindex2 etc)
  77.  
  78. Statement addtags{}
  79.   ; projindex points to free space in projtags array
  80.  
  81.   SHARED projindex,projtags(),tmp_tags.taggies
  82.  
  83.   tmp.l=&tmp_tags\a1
  84.  
  85.   While ( Peek.l(tmp)<>#TAG_END )
  86.     projtags(projindex)\ti_Tag=Peek.l(tmp)
  87.     tmp=tmp+4
  88.     projtags(projindex)\ti_Data=Peek.l(tmp)
  89.     tmp=tmp+4
  90.     projindex+1
  91.  
  92.     projtags(projindex)\ti_Tag=#TAG_END,0
  93.  
  94.   End While
  95.  
  96. End Statement
  97.  
  98. ; these Application tags are used only for information in the
  99. ; Prefs Editor. You should at least have a Name, LongName and Info
  100. ; string set.
  101. ; btw: always set tags BEFORE you create the application/project!
  102.  
  103. apptags(1)\ti_Tag=#TRCA_Name,Null("TritonTemplate")
  104. apptags(2)\ti_Tag=#TRCA_LongName,Null("TritonTemplate")
  105. apptags(3)\ti_Tag=#TRCA_Info,Null("Looks like a template")
  106. apptags(4)\ti_Tag=#TRCA_Version,Null("1.0")
  107. apptags(5)\ti_Tag=#TRCA_Release,Null("1")
  108. apptags(6)\ti_Tag=#TRCA_Date,Null("Today")
  109. apptags(7)\ti_Tag=#TAG_END,0
  110.  
  111. ; now, the tags are set and we create our application
  112. *application=TR_CreateApp_(&apptags(1))
  113.  
  114. If (*application)
  115.  
  116.    ; Here are tags to build into projtags
  117.    ; I dislike gosub'ing and goto'ing in programs, so put the tags
  118.    ; where they belong. It's faster and better.
  119.  
  120.    projindex=1
  121.  
  122.    ; you'll find the flags explained in "triton.bb2".
  123.    ; every tmp_tags line must be ended with #TAG_END
  124.  
  125.    tmp_tags\a1=!WindowID{0},!WindowPosition{#TRWP_BELOWTITLEBAR},#TAG_END
  126.    addtags{}
  127.    tmp_tags\a1=!WindowTitle{Null("Triton Test Interface")},#TAG_END
  128.    addtags{}
  129.    tmp_tags\a1=!WindowFlags{#TRWF_NOSIZEGADGET OR #TRWF_NODELZIP OR #TRWF_NOZIPGADGET OR #TRWF_NOESCCLOSE},#TAG_END
  130.    addtags{}
  131.    tmp_tags\a1=!WindowBackfillNone,#TAG_END
  132.    addtags{}
  133.  
  134.    ; now the buttons: You must start every button group either with
  135.    ; !VertGroup or with !HorizGroup, depending on how they should
  136.    ; be aligned. After finishing a group, there must be an !EndGroup
  137.    ;
  138.    ; looks like:   !VertGroup
  139.    ;                ; all your buttons
  140.    ;               !EndGroup
  141.  
  142.    tmp_tags\a1=!VertGroupA,#TAG_END
  143.    addtags{}
  144.    tmp_tags\a1=!Space,#TAG_END
  145.    addtags{}
  146.  
  147.    tmp_tags\a1=!HorizGroupA,#TAG_END
  148.    addtags{}
  149.    tmp_tags\a1=!Space,#TAG_END
  150.    addtags{}
  151.  
  152.    tmp_tags\a1=!Button{Null("_Save"),12},#TAG_END
  153.    addtags{}
  154.    tmp_tags\a1=!Button{Null("_Cancel"),15},#TAG_END
  155.    addtags{}
  156.    tmp_tags\a1=!Space,#TAG_END
  157.    addtags{}
  158.  
  159.    tmp_tags\a1=!EndGroup,#TAG_END
  160.    addtags{}
  161.  
  162.    tmp_tags\a1=!Space,#TAG_END
  163.    addtags{}
  164.  
  165.    tmp_tags\a1=!EndGroup,#TAG_END
  166.    addtags{}
  167.  
  168.   ; this here *must* follow at the end of a taglist!!
  169.  
  170.    tmp_tags\a1=#TAG_END
  171.    addtags{}
  172.  
  173.   ; the project tags are set, now we can open our window
  174.  
  175.   *project=TR_OpenProject_(*application,&projtags(1))
  176.  
  177.   If (*project)
  178.  
  179.     ; we have to check if the user closed our window.
  180.     user_closed=0
  181.  
  182.       While (user_closed=0)
  183.  
  184.         ; for communication we need to get TRITONs messages so we
  185.         ; know, what the user's doing.
  186.  
  187.         TR_Wait_ *application,1         ; waiting for a message
  188.         *trmsg.TR_Message=TR_GetMsg_(*application)
  189.  
  190.         While (*trmsg)
  191.  
  192.           If (*trmsg\trm_Project=*project)
  193.  
  194.             ; the kind of message we find in \trm_Class
  195.             ; look in "triton.bb2" for all kind of TRITON-Messages.
  196.             ; the name of these constants should be self-explaining ;)
  197.  
  198.             Select *trmsg\trm_Class
  199.  
  200.               Case #TRMS_CLOSEWINDOW
  201.                 user_closed=True
  202.               End Select
  203.           EndIf
  204.  
  205.           ; every message we get *MUST* be replied!
  206.           TR_ReplyMsg_ *trmsg
  207.  
  208.           ; let's wait for and get the next message
  209.           TR_Wait_ *application,1
  210.           *trmsg=TR_GetMsg_(*application)
  211.         End While
  212.       End While
  213.  
  214.     ; if the user wanted it, we close our window
  215.     TR_CloseProject_ *project
  216.   Else
  217.     NPrint "Unable to create the project"
  218.   EndIf
  219.  
  220.     ; and we delete our application from memory.
  221.     TR_DeleteApp_ *application
  222.  
  223. Else
  224.   NPrint "Unable to create application"
  225. EndIf
  226.  
  227. End
  228.  
  229. --------------------- end of documented sourcecode --------------------
  230.  
  231. 4. Some final words on programming with TRITON and how to get help
  232.  
  233.     I think you got now the difference between a GadTools (or, worse,
  234.     a Blitz) GUI and TRITON. But from now on you just don't need to
  235.     care about fontsensitivity and calculating positions of gadgets.
  236.  
  237.     You should only take the above example as a model to program
  238.     a TRITON GUI. I have to admit that I didn't change the other
  239.     demo listings to this way, so just take them to see how to
  240.     create other gadgets or layouts. Take care of these rules:
  241.  
  242.         a) Do never use goto and/or gosub in your program. This
  243.            is a worse basic-like style which should be avoided.
  244.            Blitz2 offers many possibilities for it: statements and
  245.            function, or just put the code where it belongs instead
  246.            of gosub'ing to it (see toolmanager listings how not to
  247.            do it [sorry, Rupert :) ]
  248.  
  249.         b) Every macro that has the same name as a Blitz2-Keyword
  250.            begins with an Underscore. So the original macro
  251.            !StringGadget{...} is named !_StringGadget{...}. If a
  252.            TRITON macro turns yellow in your TED, just put a "_"
  253.            in front :)
  254.  
  255.         c) Before getting a message, use TR_Wait_ *app,otherbits
  256.  
  257.         d) Always check that your project/application was opened!
  258.  
  259.         e) Reply every Message you get from TRITON.
  260.  
  261.         f) To program, use the macros - they are the easiest way
  262.            to create a TRITON GUI. To explain all macros would
  263.            exceed this little docu, but just take a look at either
  264.            the Blitz2-Includes oder the original C-Includes (in
  265.            "triton/developer/includes/libraries"). The name of all
  266.            constants and macros should be self-explaining. Try them
  267.            out!
  268.  
  269.         g) A little hint: When you use a button which is triggered by
  270.            <return> (!ButtonR{...}) and a StringGadget in your GUI,
  271.            everytime you hit <return> in the StringGadget, the button
  272.            will be triggered. To avoid that, use
  273.            !_StringGadget{...},#TRAT_Flags,#TRST_NORETURNBROADCAST
  274.  
  275.     But always remember: Due to the TRITON Preferences Editor, the
  276.     user can not only change the look of the gadgets but also place
  277.     your window(s) on any screen he likes. So do never use fixed
  278.     coords! In fact, you do not need to size your window - the user
  279.     can change it and it will be safed in ENV: and ENVARC:, so with
  280.     every startup of your program, the window opens in the same
  281.     dimensions and coords where the user closed it last.
  282.  
  283.     If you have any suggestions, ideas or if you just need a little
  284.     help, contact me
  285.  
  286.         via eMail:  phips@scout.rhein-main.de
  287.                     [this adress is probably only valid until october]
  288.  
  289.                     in the BlitzBasic Mailing list
  290.                     to subscribe write to:
  291.  
  292.                     majordomo@helsinki.fi
  293.                     any subject, and put in the body of your msg
  294.  
  295.                     subscribe blitz-list <your@e.mail.adress>
  296.  
  297.         via FTP  :  some TRITON-Blitz-Programs or updates you will
  298.                     find in the anonymous ftp server
  299.  
  300.                     x2ftp.oulu.fi/pub/amiga/prog/blitz
  301.  
  302.     If you really don't reach me, just write to the programmer of
  303.     TRITON, Stefan Zeiger (adress in the orig. docu!), he surely
  304.     knows where I am and how you reach me - he's nearly a neighbor
  305.     of mine :)
  306.  
  307.  
  308. 5. The end and the future
  309.  
  310.     So I wish you happy blitzing with TRITON and hope to see some
  311.     of your programs which use TRITON. I'd really appreciate, if you
  312.     send me just a few words when you finished a program.
  313.  
  314.     I included a little program called "memo" to this package - it can
  315.     only be started via CLI and pops up a TRITON requester with your text
  316.     in it. You need two arguments!
  317.  
  318.     memo "Hello World!" "Remember to write Philipp!!"
  319.  
  320.     This program could be used with CyberCron, DCron etc. for
  321.     reminding.
  322.  
  323.     I plan to make a little programming guide for TRITON programming
  324.     where you can "learn" how to change the window-/gadgetfont, and
  325.     some other tricks.
  326.  
  327.     Eventually I'll program a little GUI-Creator like GadTools, but
  328.     that's just an idea...
  329.  
  330.  
  331.  
  332. ... and, again, thanks to Rupert Henson!!! ...
  333.  
  334.  
  335.  
  336.  
  337.