Last update: 8.12.99 Introducing THE VISUALPREFS DEVELOPER INTERFACE A work in progress If you're a developer, you can take advantage of some features of VisualPrefs. Although there's not a full developer API for VisualPrefs yet, it's already possible to use the BOOPSI classes that VisualPrefs adds to the system. The purpose of these classes is to give programmers an easy way to get the "VisualPrefs look", without having to wait for me to implement a patch for their applications in VisualPrefs. ;-) Currently there's just one class: "tbiclass" - the titlebar image class This class provides the most commonly used images for gadgets added by applications to the titlebar of their windows. Examples of this are the ubiquitous "iconify" gadget or DirOpus 5's "padlock" gadget. All programs using this class will automatically get the same look for their titlebar images if VisualPrefs is running. This is probably better than having myriads of different versions of the same image... You can use "tbiclass" just like "sysiclass"; they're both sub-classes of "imageclass". A "tbiclass" image can be created by calling NewObject() with the following tags: SYSIA_DrawInfo - This is absolutely mandatory. You MUST pass a DrawInfo pointer to "tbiclass" or NewObject() will fail. SYSIA_Which - To specify which image you want; currently there are six image types: POPUPIMAGE - A MUI "pop-up" titlebar gadget image MUIIMAGE - A MUI "settings" titlebar gadget image SNAPSHOTIMAGE - A MUI "snapshot" titlebar gadget image ICONIFYIMAGE - An "iconify" titlebar gadget image PADLOCKIMAGE - A DirOpus "padlock" titlebar gadget image TBFRAMEIMAGE - A general-purpose empty titlebar gadget image IA_Width, IA_Height - These are only recognized by the TBFRAMEIMAGE type; the other image types ignore them and always have the same size of the depth gadget image. SYSIA_ReferenceFont - This is only recognized by the TBFRAMEIMAGE type; the other image types ignore it and always have the same height of the depth gadget image. TBIA_FullFrame - This is only recognized by the TBFRAMEIMAGE type; set it to TRUE to get an image which also contains an inner frame, if the current style has one. This is best suited when the image contents are graphic in nature. Set it to FALSE to get an image which has at most the outer frame; this is instead best suited when the image must contain text (as the inner frame might be too small to render the text into). The default is FALSE. (Available since VisualPrefs 41.38) You can also use this tag with GetAttr(): TBIA_ContentsBox - To ask the image about the position and size of its actual "contents box" relative to the image itself. Said box is the part where, if you need to, you can add any further custom imagery. This probably only makes sense with TBFRAMEIMAGE images. To position correctly the box, you should add its Left and Top offsets to those of the image. Note that, even within the returned dimensions, you should always leave a small space (like two pixels) around your imagery, to achieve better-looking results. This is a read-only attribute; the value you pass to this tag must be a pointer to an IBox structure. Do NOT pass a longword pointer! (Available since VisualPrefs 41.35) Of course, if NewObject() fails, you should provide a built-in fallback image for your titlebar gadget. However, I have released a disk-based freeware "tbiclass" image class (dev/gui/titlebar_ic.lha) which you can include in the distribution of your applications. This class will provide the needed images and will be automatically replaced by the VisualPrefs one if it is present. Therefore, you can keep your built-in images very simple, or not have them at all ;-) If you use TBFRAMEIMAGE to make your own special titlebar images, you can add contents to it in two ways: by setting the NextImage field to the address of your custom inner imagery, or by sub-classing "tbiclass" and redefining the IM_DRAW/IM_DRAWFRAME methods (of course, in this case you must let the superclass do its rendering first!). It's important to note that all "tbiclass" image instances will have an Image->LeftEdge value of -1. This shouldn't be modified, and you should place your titlebar gadgets accordingly. The reason for this apparently strange behavior is that Intuition titlebar gadget images, too, work this way, and we should try to stay as compatible with Intuition as possible. Also, make sure you adjust your gadget's size if necessary, to adapt it to the returned image's size. An example of all this could be: ... /* Create the image */ if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE, SYSIA_DrawInfo,dri, TAG_END))) { iconifyimage = builtin_iconifyimage; } /* Use the image */ gad->GadgetRender = iconifyimage; ... /* Free the image */ if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage); ... That's all. The real include file for "tbiclass" is in the Aminet stand-alone release, anyway all you need in order to use "tbiclass" in your applications is to paste the following few lines at the beginning of your source code. :-] ------- cut here -------8<------- cut here -------8<------- cut here ------- #define POPUPIMAGE (101) #define MUIIMAGE (102) #define SNAPSHOTIMAGE (103) #define ICONIFYIMAGE (104) #define PADLOCKIMAGE (105) #define TBFRAMEIMAGE (106) #define TBIA_Dummy (TAG_USER + 0x0B0000) #define TBIA_ContentsBox (TBIA_Dummy + 0x0001) #define TBIA_FullFrame (TBIA_Dummy + 0x0002) ------- cut here -------8<------- cut here -------8<------- cut here ------- There's already an application using "tbiclass", ViNCEd by Thomas Richter. I hope you will also support "tbiclass" and contribute this way to finally give a consistent appearance to all titlebar gadgets used in applications! Thank you, Massimo Tantignone (tanti@intercom.it)