home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 6 / AACD06.ISO / AACD / Programming / titlebar_ic / titlebar.doc < prev    next >
Text File  |  1999-10-07  |  12KB  |  327 lines
  1. TABLE OF CONTENTS
  2.  
  3. titlebar.image/--background--
  4. titlebar.image/titlebar.image
  5. titlebar.image/ObtainTBIClass
  6. titlebar.image/--background--                   titlebar.image/--background--
  7.  
  8. DESCRIPTION
  9.  
  10. The titlebar.image is a shared library which, when opened, adds to the system
  11. a public BOOPSI image class called "tbiclass". This class implements several
  12. images suitable for the use as imagery of gadgets added to the titlebar of
  13. a window, such as an "iconify" image, a "pop-up" image, and so on. Also, a
  14. general purpose "empty" (border-only) image is provided, to be used as the
  15. background of more specialized titlebar images.
  16.  
  17. The purpose of "tbiclass" is to offer developers an easy way to implement
  18. the most common additional titlebar gadgets without having to draw or
  19. code their imagery themselves, and with the added benefit of standardizing
  20. the size and appearance of this kind of gadgets. For instance, until now
  21. any developer needing an iconify gadget had to hard-code its imagery into
  22. his application, leading to a plethora of similar, but different, versions
  23. of the same gadget.
  24.  
  25. The library is freeware; if you use it, you are allowed to distribute it
  26. with your software, typically as a stand-alone file (you'll just have to
  27. add a section for it in your application's installation script).
  28.  
  29. Using "tbiclass" is very simple: you just need to open the titlebar.image
  30. library in order to add the class to the system, and then close it when you
  31. don't need the class anymore (and have freed all of its instances).
  32.  
  33. Once the class has been added to the system, you can use NewObject() in the
  34. usual way to create new "tbiclass" instances. See the "Class documentation"
  35. section to learn which tags are recognized by the class, as well as more
  36. information about the class in general.
  37.  
  38. Important note: a more refined version of "tbiclass" is also added to the
  39. system at boot time by the VisualPrefs utility (a patch to modify the look
  40. of the Amiga GUI). If the titlebar.image library, when it's opened, finds
  41. that a class named "tbiclass" already exists, it won't create another, but
  42. still will open successfully, so your code does NOT have to change to take
  43. this special case into account.
  44.  
  45. The only thing to remember is, you should NOT open the titlebar.image library
  46. if your program is launched in the Startup-sequence _before_ the line where
  47. VisualPrefs is usually started (which is just before IPrefs), or else the
  48. patch won't run correctly. If you absolutely need to place your program in
  49. the Startup-sequence before VisualPrefs/IPrefs, at least offer the user
  50. an option to avoid opening the titlebar.image library.
  51. Anyway, this shouldn't be a problem for the vast majority of applications...
  52.  
  53. The class documentation applies to both versions of "tbiclass".
  54.  
  55.  
  56. CLASS DOCUMENTATION
  57.  
  58. Class:        tbiclass
  59. Superclass:   imageclass
  60. Include File: <images/titlebar.h>
  61.  
  62. This is a class of images suitable for use as imagery of gadgets added to
  63. a window titlebar. As of version 40, there are 6 possible "tbiclass" images
  64. to choose from:
  65.  
  66. POPUPIMAGE          A MUI "pop-up" titlebar gadget image
  67. MUIIMAGE            A MUI "settings" titlebar gadget image
  68. SNAPSHOTIMAGE       A MUI "snapshot" titlebar gadget image
  69. ICONIFYIMAGE        An "iconify" titlebar gadget image
  70. PADLOCKIMAGE        A DirOpus "padlock" titlebar gadget image
  71. TBFRAMEIMAGE        A general-purpose empty titlebar gadget image
  72.  
  73. These image types are an extension to those already offered by "sysiclass";
  74. in fact, "tbiclass" is used mostly the same way as "sysiclass" (see below
  75. for its methods and attributes).
  76.  
  77. It's worth noticing that all "tbiclass" image instances will have an
  78. Image->LeftEdge value of -1. This shouldn't be modified, and you should
  79. place your titlebar gadgets accordingly. The reason for this apparently
  80. strange behavior is that Intuition titlebar gadget images, too, work
  81. this way, and we should try to stay as compatible with Intuition as
  82. possible.
  83.  
  84. Also, make sure you adjust your gadget's size if necessary, to adapt it
  85. to the returned image's size.
  86.  
  87. There are actually two versions of this class: a disk-based one, implemented
  88. by the freely distributable "titlebar.image" library, and another, more
  89. refined, added to the system by the VisualPrefs program at boot time.
  90. Applications needing this class should always ship with the "titlebar.image"
  91. library, and use it without worrying about the presence of VisualPrefs in the
  92. system: if it's running, its "tbiclass" version will be used automatically.
  93.  
  94. The _only_ exception to this rule is when your application is run in the
  95. Startup-sequence before VisualPrefs; in this case, you should offer the
  96. user an option to avoid opening "titlebar.image", otherwise the disk-based
  97. version of the class would be added to the system and VisualPrefs wouldn't
  98. be able to add its own version. This is, however, a very unlikely scenario;
  99. in all foreseeable cases, an application opening windows shouldn't be run
  100. so early in the Startup-sequence.
  101.  
  102. New Methods:
  103.  
  104. None.
  105.  
  106. Changed Methods:
  107.  
  108. OM_NEW - After creation of the image by the superclass, this method
  109. initializes the "tbiclass" instance data on the basis of the contents
  110. of the attributes tag list.
  111.  
  112. OM_DISPOSE - This method frees all the resources allocated in the OM_NEW
  113. method.
  114.  
  115. OM_SET - This method allows to change a few of the image attributes and
  116. checks their bounds integrity.
  117.  
  118. OM_GET - This method allows to retrieve the value of the most relevant
  119. image attributes.
  120.  
  121. IM_DRAW - This method does the actual rendering of the image, taking into
  122. account its various attributes and the screen's DrawInfo pens.
  123.  
  124. IM_DRAWFRAME - Like IM_DRAW, but uses the size specified in the impDraw
  125. message rather than the one in the image structure.
  126.  
  127. Attributes:
  128.  
  129. SYSIA_DrawInfo (IS) - This is absolutely mandatory. You MUST pass a DrawInfo
  130.                       pointer to "tbiclass" or NewObject() will fail.
  131.  
  132. SYSIA_Which (ISG) - To specify which image you want; currently there are six
  133.                     image types, defined in <images/titlebar.h>: POPUPIMAGE,
  134.                     MUIIMAGE, SNAPSHOTIMAGE, ICONIFYIMAGE, PADLOCKIMAGE and
  135.                     TBFRAMEIMAGE.
  136.  
  137. IA_Width, IA_Height (ISG) - Only recognized by the TBFRAMEIMAGE type; the
  138.                             other image types ignore them and always have
  139.                             the same size of the depth gadget image.
  140.  
  141. SYSIA_ReferenceFont (IS) - This is only recognized by the TBFRAMEIMAGE type;
  142.                            the other image types ignore it and always have
  143.                            the same height of the depth gadget image. It's
  144.                            also ignored if IA_Height is explicitly used.
  145.  
  146. TBIA_ContentsBox (G) - To ask the image about the position and size of its
  147.                        actual "contents box" relative to the image itself.
  148.                        Said box is the part where, if you need to, you can
  149.                        add any further custom imagery. This probably only
  150.                        makes sense with TBFRAMEIMAGE images. To position
  151.                        correctly the box, you should add its Left and Top
  152.                        offsets to those of the image. Note that this
  153.                        attribute is useless for the disk-based version of
  154.                        the class, as the returned size will be always equal
  155.                        to the full image size; it is only relevant for the
  156.                        "tbiclass" version created by VisualPrefs. The value
  157.                        you pass to this tag must be a pointer to an IBox
  158.                        structure. Do NOT pass a longword pointer! (V40.12)
  159.  
  160.  
  161. PROGRAMMING EXAMPLE
  162.  
  163. An example of usage of "titlebar.image" and "tbiclass" could be given by
  164. the following code fragment:
  165.  
  166.    ...
  167.    #include "images/titlebar.h"
  168.    #include "clib/titlebarimage_protos.h"
  169.    #include "pragmas/titlebarimage_pragmas.h"
  170.  
  171.    ...
  172.    
  173.    struct Library *TitlebarImageBase;
  174.  
  175.    ...
  176.  
  177.    /* Open the library */
  178.    
  179.    if (!(TitlebarImageBase = OpenLibrary("Images/titlebar.image",40)))
  180.    {
  181.       ComplainAndExit();
  182.    }
  183.  
  184.    ...
  185.  
  186.    /* Create the image */
  187.  
  188.    if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
  189.                                                   SYSIA_DrawInfo,dri,
  190.                                                   TAG_END)))
  191.    {
  192.       iconifyimage = builtin_iconifyimage;  /* If really needed... */
  193.    }
  194.  
  195.    /* Use the image */
  196.  
  197.    gad->GadgetRender = iconifyimage;
  198.    ...
  199.  
  200.    /* Free the image */
  201.  
  202.    if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
  203.  
  204.    ...
  205.    
  206.    /* Close the library */
  207.    
  208.    CloseLibrary(TitlebarImageBase);
  209.    
  210.    ...
  211.  
  212. A complete example program can also be found in the distribution archive.
  213.  
  214.  
  215. TO DO
  216.  
  217. Future releases should add the following features:
  218.  
  219.  o More image types.
  220.  
  221.  o Some more code optimization.
  222.  
  223. And of course, I'm open to any suggestion about how to improve the class.
  224.  
  225.  
  226. HISTORY
  227.  
  228. 40.12 (7.10.99)
  229.    Added a new attribute to ask the image about its inner dimensions.
  230.  
  231. 40.11 (7.9.98)
  232.    First public release.
  233.    
  234.  
  235. AUTHOR
  236.  
  237. Massimo Tantignone
  238. Via Campagnoli, 4
  239. 28100 Novara (NO)
  240. ITALY
  241.  
  242. E-mail: tanti@intercom.it
  243. Web:    http://www.intercom.it/~amigaws
  244.  
  245. titlebar.image/titlebar.image                   titlebar.image/titlebar.image
  246.  
  247.    NAME
  248.       titlebar.image -- create an image suitable for titlebar gadgets
  249.  
  250.    FUNCTION
  251.       The titlebar.image shared library implements a public BOOPSI image
  252.       class, called "tbiclass", which provides the most commonly used images
  253.       for gadgets added by applications to the titlebar of their windows.
  254.       Examples of this are the ubiquitous "iconify" gadget or DirOpus 5's
  255.       "padlock" gadget.
  256.       
  257.       All programs using such class will automatically get the same look for
  258.       their titlebar images. This is probably better than having myriads of
  259.       different versions of the same image...
  260.       
  261.       The titlebar.image library is freeware; the idea is that if your
  262.       software needs images for gadgets in window titlebars, you can simply
  263.       place the library into your distribution archive and let the user
  264.       install it to his machine alongside your application, which will then
  265.       be able to open and use it.
  266.  
  267.       You can use "tbiclass" just like "sysiclass"; they're both sub-classes
  268.       of "imageclass". A "tbiclass" image can be created in the usual way,
  269.       by calling NewObject() with the tags described in the class reference
  270.       documentation.
  271.  
  272.       Of course, if NewObject() fails, you should provide a built-in fallback
  273.       image for your titlebar gadget. However, as this occurrence isn't very
  274.       likely (the class requires very little memory), you can keep your
  275.       built-in images very simple.
  276.  
  277.       To be able to create and use "tbiclass" objects in an application,
  278.       you first have to open the titlebar.image library with OpenLibrary().
  279.       Once you have done this, you shouldn't close the library until all of
  280.       your "tbiclass" objects have been freed.
  281.  
  282.       For a complete description of the "tbiclass" class and its features,
  283.       see the class reference documentation in the --background-- paragraph.
  284.  
  285.    TAGS
  286.       For the full list of "tbiclass" attributes, see the class reference
  287.       documentation in the --background-- paragraph.
  288.  
  289.    WARNING
  290.       Don't close the titlebar.image library if you still have some instances
  291.       of "tbiclass" images hanging around!
  292.  
  293.    BUGS
  294.       None known.
  295.  
  296. titlebar.image/ObtainTBIClass                   titlebar.image/ObtainTBIClass
  297.  
  298.    NAME
  299.       ObtainTBIClass -- return a pointer to "tbiclass".
  300.  
  301.    SYNOPSIS
  302.       tbiclass = ObtainTBIClass()
  303.       D0
  304.  
  305.       Class *ObtainTBIClass(void);
  306.  
  307.    FUNCTION
  308.       Returns a pointer to the class implemented by the titlebar.image,
  309.       called "tbiclass". Use this pointer with care, and do not reference it
  310.       after you've closed the titlebar.image library.
  311.       
  312.    INPUTS
  313.       none
  314.  
  315.    RESULT
  316.       tbiclass - pointer to the class
  317.  
  318.    NOTES
  319.       If VisualPrefs is running, you will obtain a pointer to its special
  320.       version of "tbiclass".
  321.  
  322.    BUGS
  323.       None known.
  324.  
  325.    SEE ALSO
  326.  
  327.