home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 581b.lha / Steal_v1.1 / Steal.doc.pp / Steal.doc
Text File  |  1991-10-29  |  8KB  |  169 lines
  1. 0. The Boring Part :
  2. ====================
  3.  
  4.     Steal should be treated as Public Domain. Anyone can copy the program
  5. if and only if this is not done on commercial grounds. If ever Steal is
  6. published somewhere, I demand that this English document file and all three
  7. source files go along with it. It is allright to copy translations of this
  8. document file too, if any are avalable, but this English version is the
  9. original and should therefore always be distributed together with the program.
  10. The same should be kept in mind for the sources.
  11.  
  12.     Steal is no shareware, but if you like the program I will not protest
  13. if you'd send me some money. My name and address are below. 
  14.  
  15.     If anyone feels like changing the source into something he or she
  16. thinks is better, feel free to do so. The only thing I always demand is that
  17. you keep my name in the source and the runtime output, just as it is now. Oh...
  18. If you realy make something wonderful out of it, why don't we share it? Better
  19. versions are always welcome!
  20.  
  21.     For those enhanced versions, for comments, complaints, questions and
  22. money I now list my full address; Better not try to contact me on the phone,
  23. because this is a postage address, rather than a living address.
  24.  
  25.                       Rick van Rein
  26.                       Binnenes 67
  27.                       9407 CX Assen
  28.                     ( The Netherlands )
  29.  
  30.  
  31. 1. What's the use of Steal 1.1 ?
  32. ================================
  33.  
  34.     Steal is a program that grabs parts out of a display. It is no program
  35. like Snip, neither is it a program to steal whole Screens displays with. This
  36. program is a means to grab out Intuition's structures.
  37.  
  38.     The user can enter a name of an output file that should be used to
  39. write the C listing to, in which all data structures are defined. Note that
  40. BitMaps are not copied; Use some other routine to hack into full displays
  41. please. Yet, Steal does support grabbing away the way an Image looks, so small
  42. pictures can be saved. They will be noted down in an array containing
  43. hexadecimal constants.
  44.  
  45.     A forbidden use of Steal would be, to hack into some commercial package
  46. to Steal away Intuition elements, and then use the things in your own programs.
  47. Note that I do not take any responsibility for people using Steal in this way.
  48.  
  49.     A better use of Steal is, to "de-compile" an Intuition item that we
  50. made by ourselves. I know, this sounds useless, but just imagine: You can write
  51. your original data structures in an ugly way, mount them on the Screen, and
  52. then run Steal to get a neatly formatted C listing, with all fields bearing a
  53. comment on it's contents. This will save you a lot of typing!
  54.  
  55.     Sometimes there will be more convenient ways to build some system
  56. structure. By running Steal in parallel with such a program, one can drag out a
  57. C listing describing this Menu. This probably is the easiest way to define your
  58. own Menus etc.
  59.  
  60.     I will not go into details on how to operate Steal; It's not just a
  61. coincidence that the graphical user interface of the Amiga is called Intuition!
  62. Just try out things that you think are logical - The'll probably behave as
  63. expected. If ever Steal expects you to do something, a report will be printed
  64. in the title bar of Steal's Window.
  65.  
  66.     There is just one last remark to be made: Anything that should be
  67. stolen should be outside Steal's own Window, as Steal waits for an
  68. INACTIVEWINDOW message over the IDCMP whenever it expects something outside the
  69. Window should be selected. Stealing things out of Steal's Window is only
  70. possible by running Steal twice in parallel, with one version stealing things
  71. out of the Window of the second version. Of course, it is possible too to grab
  72. away the whole WorkBench Screen.
  73.  
  74.  
  75. 2. Stealing a Gadget :
  76. ======================
  77.  
  78.     Every Gadget that is visible on the Screen can be grabbed away. This is
  79. also true for the system's Gadgets like the resizing-button. The only exception
  80. to this rule is the dragging bar; Not that Steal doesn't support it for some
  81. reason, but it's Width is zero. Don't ask me why, it's just some bare fact
  82. about the Amiga.
  83.  
  84.     Stealing icons also presented me with some disappointments; It appears
  85. that the WorkBench draws all icons "by hand" instead of using Intuition. This
  86. means that icons are no Gadgets at all. Surprise! I solved it with Icon2Gadget.
  87.  
  88.     Things like this also happen in some other programs; For instance,
  89. Commodore's Preferences program draws the whole Window when starting up; After
  90. that, no rendering is done anymore: Intuition does not get any graphical thing
  91. it may render. The only thing Intuition gets is a list of bare Gadgets
  92. structures, but no Borders, no Images an not even IntuiTexts. It cannot be
  93. expected of a program like Steal to pick up graphical details in such a case.
  94. So, when stealing Preferences' Window, we get an empty Window with some
  95. invisible click-fields in it.
  96.  
  97.     If we try to steal a Gadget, but the position clicked upon is not the
  98. position of a Gadget, an error will be given out.
  99.  
  100.  
  101. 3. Stealing a Menu :
  102. ====================
  103.  
  104.     Stealing MenuBars can be done by clicking on a Window that has a
  105. MenuBar connected to it. If there is no MenuBar, an error will be printed. If a
  106. MenuBar is present in the Window, this bar will be taken out, and a list of all
  107. structures needed for it's graphical presentation will be put in the output
  108. file. All structures will be linked as may be expected.
  109.  
  110.  
  111. 4. Stealing a Window :
  112. ======================
  113.  
  114.     Stealing a Window is done by clicking on the Window to be stolen. If no
  115. Window is at the position pointed at, an error will be the result.
  116.  
  117.     Note that Steal does not write a Window structure to it's output file,
  118. but a NewWindow structure instead, thus following the principle of creating a
  119. file that's ready to be compiled into some datafile that could be used directly
  120. in some OpenXXX-command. Some information will be lost in this way, but most of
  121. the interesting information will still be written out.
  122.  
  123.     When stealing a Window, all Gadgets contained in it will be stolen
  124. along with it, with the exception of the system's special Gadgets. This is not
  125. very unusual, as the system adds these Gadgets automatically.
  126.  
  127.  
  128. 5. Stealing a Screen :
  129. ======================
  130.  
  131.     Again, not the Screen structure itself will be written out, but a
  132. NewScreen is. And again, no great losses of information will be the result. But
  133. there is more to be said about a Screen!
  134.  
  135.     A Screen is a graphical item that contains Windows. Those Windows are
  136. stolen too, and linked into a list, starting from the Screen. Then, there are
  137. MenuBars for every Window; Those are stolen too.
  138.  
  139.     When showing some Screen, we must take care of opening all Windows that
  140. are listed, and the mounting the accompanying MenuBar in it. This cannot be
  141. done automatically, as the NewWindow structure somehow doesn't contain a field
  142. that points at a MenuBar.
  143.  
  144.  
  145. 6. Bugs and warnings :
  146. ======================
  147.  
  148.     This software runs well on Manx's Aztec C 3.4a, and it should just as
  149. well run on any other compiler, though I cannot guarantee this, as I haven't
  150. tried it. The generated C listings are all well typed, so there should be no
  151. difficulties, as far as I can see.
  152.  
  153.     As mentioned above, BitMaps are not supported in Steal 1.1; This causes
  154. problems when stealing a Window that contains pre-drawn Gadgets etc. As a
  155. general rule, accept the fact that everything can be stolen, as long as it
  156. is hanging from IntuitionBase.
  157.  
  158.     You are not expected to change the display during a hack ("Please hold
  159. your breath") and neither is it expected that another program acts like this.
  160. I'll have to sort out a way of disabling these problems, but until now I
  161. haven't.
  162.  
  163.     I wish you lots of fun with hacking into Intuition, and hopefully
  164. you'll learn things thanks to Steal 1.1!
  165.  
  166.  
  167.  
  168.                     Februari 6, 1991, Rick van Rein.
  169.