home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 28 / amigaformatcd28.iso / -websites- / 5dsoftware / archives / visualpr.lha / VisualPrefs / DocsEnglish / VP-Developer.doc < prev    next >
Text File  |  1997-11-27  |  5KB  |  120 lines
  1.  
  2.                                Introducing
  3.  
  4.                     THE VISUALPREFS DEVELOPER INTERFACE
  5.  
  6.                             A work in progress
  7.  
  8.  
  9. If you're a developer, you can take advantage of some features of VisualPrefs.
  10.  
  11. Although there's not a full developer API for VisualPrefs yet, it's already
  12. possible to use the BOOPSI classes that VisualPrefs adds to the system.
  13.  
  14. The purpose of these classes is to give programmers an easy way to get the
  15. "VisualPrefs look", without having to wait for me to implement a patch for
  16. their applications in VisualPrefs. ;-)
  17.  
  18. Currently there's just one class:
  19.  
  20. "tbiclass" - the titlebar image class
  21.  
  22. This class provides the most commonly used images for gadgets added by
  23. applications to the titlebar of their windows. Examples of this are the
  24. ubiquitous "iconify" gadget or DirOpus 5's "padlock" gadget.
  25.  
  26. All programs using this class will automatically get the same look for their
  27. titlebar images if VisualPrefs is running. This is probably better than
  28. having myriads of different versions of the same image...
  29.  
  30. You can use "tbiclass" just like "sysiclass"; they're both sub-classes of
  31. "imageclass". A "tbiclass" image can be created by calling NewObject() with
  32. the following tags:
  33.  
  34. SYSIA_DrawInfo - This is absolutely mandatory. You MUST pass a DrawInfo
  35.                  pointer to "tbiclass" or NewObject() will fail.
  36.  
  37. SYSIA_Which - To specify which image you want; currently there are six image
  38.               types:
  39.  
  40.               POPUPIMAGE    - A MUI "pop-up" titlebar gadget image
  41.               MUIIMAGE      - A MUI "settings" titlebar gadget image
  42.               SNAPSHOTIMAGE - A MUI "snapshot" titlebar gadget image
  43.               ICONIFYIMAGE  - An "iconify" titlebar gadget image
  44.               PADLOCKIMAGE  - A DirOpus "padlock" titlebar gadget image
  45.               TBFRAMEIMAGE  - A general-purpose empty titlebar gadget image
  46.  
  47. IA_Width, IA_Height - These are only recognized by the TBFRAMEIMAGE type;
  48.                       the other image types ignore them and always have
  49.                       the same size of the depth gadget image.
  50.  
  51. SYSIA_ReferenceFont - This is only recognized by the TBFRAMEIMAGE type;
  52.                       the other image types ignore it and always have
  53.                       the same height of the depth gadget image.
  54.  
  55. Of course, if NewObject() fails, you should provide a built-in fallback image
  56. for your titlebar gadget. However, I plan to release soon a disk-based
  57. freeware "tbiclass" image class which you will be able to include in the
  58. distribution of your applications. This class will provide the needed images
  59. and will be automatically replaced by the VisualPrefs one if it is present.
  60. Therefore, you can keep your built-in images very simple. ;-)
  61.  
  62. It's important to note that all "tbiclass" image instances will have an
  63. Image->LeftEdge value of -1. This shouldn't be modified, and you should
  64. place your titlebar gadgets accordingly. The reason for this apparently
  65. strange behavior is that Intuition titlebar gadget images, too, work this
  66. way, and we should try to stay as compatible with Intuition as possible.
  67.  
  68. Also, make sure you adjust your gadget's size if necessary, to adapt it
  69. to the returned image's size.
  70.  
  71. An example of all this could be:
  72.  
  73.    ...
  74.  
  75.    /* Create the image */
  76.  
  77.    if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
  78.                                                   SYSIA_DrawInfo,dri,
  79.                                                   TAG_END)))
  80.    {
  81.       iconifyimage = builtin_iconifyimage;
  82.    }
  83.  
  84.    /* Use the image */
  85.  
  86.    gad->GadgetRender = iconifyimage;
  87.    ...
  88.  
  89.    /* Free the image */
  90.  
  91.    if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
  92.  
  93.    ...
  94.  
  95. That's all. For now I don't have a real include file, therefore, in order
  96. to use "tbiclass" in your applications, please paste the following few lines
  97. at the beginning of your source code. :-]
  98.  
  99. ------- cut here -------8<------- cut here -------8<------- cut here -------
  100.  
  101. #define POPUPIMAGE    (101)
  102. #define MUIIMAGE      (102)
  103. #define SNAPSHOTIMAGE (103)
  104. #define ICONIFYIMAGE  (104)
  105. #define PADLOCKIMAGE  (105)
  106. #define TBFRAMEIMAGE  (106)
  107.  
  108. ------- cut here -------8<------- cut here -------8<------- cut here -------
  109.  
  110. There's already an application using "tbiclass", ViNCEd by Thomas Richter.
  111.  
  112. I hope you will also support "tbiclass" and contribute this way to finally
  113. give a consistent appearance to all titlebar gadgets used in applications!
  114.  
  115. Thank you,
  116.                                       Massimo Tantignone (tanti@intercom.it)
  117.  
  118.  
  119.  
  120.