Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / bgui.lzx / bgui / docs / baseclass.doc next >

Wrap

Text File | 1995-07-15 | 13.5 KB | 438 lines

File: baseclass.doc Description: Baseclass documentation. Copyright: (C) Copyright 1994-1995 Jaba Development. (C) Copyright 1994-1995 Jan van den Baard. All Rights Reserved. ------------------------------------------------------------------------------ TABLE OF CONTENTS baseclass/--background-- baseclass/Methods baseclass/Attributes baseclass/--background-- baseclass/--background-- NAME Class: baseclass Superclass: GADGETCLASS Include File: <libraries/bgui.h> FUNCTION This is the most important gadget class in BGUI. It is the superclass of almost all the other gadget classes at one point or the other. It will take care of the following things for it's subclasses: o Notification o Frames o Labels o Online-help. If you plan on writing a class for BGUI then always sub-class in from this class. That way you automatically inherrit the above mentioned features. baseclass/Methods baseclass/Methods NOTE The methods described here are also valid for the other BGUI gadget classes subclassed from this class unless documented otherwise. NEW METHODS BASE_ADDMAP -- This method must be used to add a target object to an object it's maplist notification list. Maplist notification is simular to the notification performed by the system "icclass" and ICA_TARGET notification. This method uses the following custom message structure: struct bmAddMap { ULONG MethodID; /* BASE_ADDMAP */ Object *bam_Object; /* Target object */ struct TagItem *bam_MapList; }; bam_MapList -- This can point to an array of TagItem structures which contains a set of attributes to map. This may also be NULL in which case no mapping is done. Returns TRUE uppon success, FALSE uppon failure. BASE_ADDCONDITIONAL -- This method must be used to add a target object to an object it's conditional notification list. Conditional notification is a simple "if attr a == b then set attr c to d" style of notification. Example: Object *cycle, *string; DoMethod( cycle, BASE_ADDCONDITIONAL, string, CYC_Active, 0, GA_Disabled, FALSE, GA_Disabled, TRUE ); This will enable the string gadget when the CYC_Active attribute of the cycle gadget is 0. If the CYC_Active attribute is not 0 the string gadget is disabled. This method uses the following custom message structure: struct bmAddConditional { ULONG MethodID; /* BASE_ADDCONDITIONAL */ Object *bac_Object; /* Target object. */ struct TagItem bac_Condition; struct TagItem bac_TRUE; struct TagItem bac_FALSE; }; bac_Condition -- This attribute pair represents the condition which has to be met. bac_TRUE -- This attribute pair is set to the target object if the condition is TRUE (I.E. met). bac_FALSE -- This attribute pair is set to the target object if the condition is FALSE (I.E. not met). Returns TRUE uppon success, FALSE uppon failure. BASE_ADDMETHOD -- This method must be used to add a target object to an object it's method notification list. Method notification allows you to send a complete method to a target when a notification event occures. This method uses the following custom message structure: struct bmAddMethod { ULONG MethodID; /* BASE_ADDMETHOD */ Object *bam_Object; /* Target object. */ ULONG bam_Flags; ULONG bam_Size; ULONG bam_MethodID; }; bam_Flags -- This may contain any of the following flags: BAMF_NO_GINFO -- Normally a pointer to a GadgetInfo structure is inserted in the method to send. When this flag is set this will not be done. Please note that when a GadgetInfo is placed it is done as follows: OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY -- If the method to send is any of these the GadgetInfo is placed in the third long word of the method. All other methods will get the GadgetInfo in the second long word. This behaviour is the same as with DoGadgetMethodA(). BAMF_NO_INTERIM -- When set the method will not be send on interim notification events. bam_Size -- This field must contain the number of long-words _including_ the method ID of the method to send. This information is needed because a copy of the method to send is made in an internal buffer. bam_MethodID -- This must be the ID of the method to send. This field can be followed by the method specific data. Please note that most notification will occure on the input.device it's task. This means that the called method must not take to long to return and generally should not do anything a normal input handler should not do. Returns TRUE uppon success, FALSE uppon failure. BASE_REMMAP, BASE_REMCONDITIONAL, BASE_REMMETHOD, BASE_REMHOOK -- These methods must be used to remove a target object/hook from any of the notification lists. This method uses the following message structure: struct bmRemove { ULONG MethodID; /* Any of the above. */ Object *bar_Object; /* Object to remove. */ }; Return code not defined. BASE_SETLOOP, BASE_CLEARLOOP, BASE_CHECKLOOP, BASE_LEFTEXT, BASE_SHOWHELP -- These methods are private and should not be of any use to you. BASE_ADDHOOK -- This method must be used to add a hook routine to the object it's hook-notification list. Hook notification allows you to add a routine via a Hook to the notification of the object. In other words, the hook will be called whenever the object sends out a notification. This method uses the following custom message structure: struct bmAddHook { ULONG MethodID; /* BASE_ADDHOOK */ struct Hook *bah_Hook; }; bah_Hook -- A pointer to the Hook structure. Your hook routine will be called as follows: rc = hookFunc( hook, obj, update ); D0 A0 A2 A1 hook -- This will point to the Hook structure. obj -- This is a pointer to the object that caused the notification. update -- This is a pointer to a opUpdate structure from which you can extract data like the visual environment and notified attribute changes. Your hook routine must return non-zero when the notification caused a change of some sort and zero if not. Returns TRUE uppon success and FALSE uppon failure. SEE ALSO intuition.library/DoGadgetMethodA(), icclass, ICA_TARGET, utility/hooks.h CHANGED METHODS OM_UPDATE -- This method fixes a bug in the system GADGETCLASS. Even though the documentation states that the GA_ID attribute of a gadget object cannot be changed by a OM_UPDATE message it still does. As this behaviour is not correct the baseclass intercepts the GA_ID attribute before passing it on to the GADGETCLASS. This way GA_ID will not be changable by a OM_UPDATE call. OM_NOTIFY -- This method will first execute all maplist, conditional, method and hook notification. When that is done the method is passed onto GADGETCLASS for any ICA_TARGET's that might still exist. GM_RENDER -- If this message requests a complete re-rendering (I.E. GREDRAW_REDRAW) this method will render the frame and label when available. On any other request it will simply re-compute the gadget hitbox bounds. When this method returns a non-NULL value you are also allowed to render. If this method returns NULL then you may not render. Your class _must_ also follow the same rules. If the superclass of your class returns NULL you do not render and also return NULL. If the superclass of your class returns a non-NULL value you should render and also return a non-NULL value. Your class must use the gpr_RPort field for _all_ rendering. This usually points to a buffer rastport in which you render without it showing on screen. This also means that if your class uses OM_SET on another object you must do so without passing the gpr_GInfo field and re-render that object later in the RastPort pointed to by the gpr_RPort field. RastPort-Clipping is not allowed for BGUI objects. The reason for this limitation is that all rendering occures in a buffer rastport without a layer attached to it. If your class absolutely needs clipping you must use the WINDOW_NoBufferRP or PAGE_NoBufferRP on the window object or page object in which the object is located. GM_HITTEST -- This method will return GMR_GADGETHIT when the gadget was clicked inside it's hitbox bounds. SEE ALSO <intuition/gadgetclass.h> baseclass/Attributes baseclass/Attributes NOTE The attributes described here are also valid for the other BGUI gadget classes subclassed from this class unless documented otherwise. NOTE2: ** V39 ** The following frameclass and labelclass attributes are settable on the baseclass: FRM_BackPen FRM_BackDriPen FRM_SelectedBackPen FRM_SelectedBackDriPen LAB_Pen LAB_DriPen LAB_SelectedPen LAB_SelectedDriPen Please refer to the documentation of these classes to find out more about what these attributes do. NAME BT_HelpFile -- ( STRPTR ) FUNCTION Set the name of the file to be displayed when a help-request for the object arives. Please note that the full path-name must be given. Default is NULL. Applicability is (IS). SEE ALSO BT_HelpNode, BT_HelpLine NAME BT_HelpNode -- ( STRPTR ) FUNCTION Set the name of the node which is diplayed in the help window. Default is NULL. Applicability is (IS). SEE ALSO BT_HelpFile, BT_HelpLine NAME BT_HelpLine - ( ULONG ) FUNCTION Set the line number from which the file is displayed. This may be useful if the help-file is not an AmigaGuide file. Default is 0. Applicability is (IS). SEE ALSO BT_HelpFile, BT_HelpNode NAME BT_HitBox - ( struct IBox * ) FUNCTION Get the hitbox bounds of the gadget object. This attribute is normally only usefull for class writers. Please note that the contents of the returned IBox structure is only valid _after_ you let this class render itself. For example suppose the following code is your class dispatcher: __saveds __asm ULONG dispatcher ( __a0 Class *cl, __A2 Object *obj, __A1 Msg msg ) { struct IBox *domain; switch ( msg->MethodID ) { ... case GM_RENDER: /* ** First let the superclass render. **/ if ( ! DoSuperMethodA( cl, obj, msg )) return( 0L ); /* ** Now you can obtain the object ** it's hitbox bounds. **/ DoSuperMethod( cl, obj, OM_GET, BT_HitBox, &domain ); ... break; } } Please note that the pointer returned is READ-ONLY. If you need to adjust it's contents you should make a private copy of the data. Applicability is (G). NAME BT_LabelObject, BT_FrameObject -- ( Object * ) FUNCTION Set or get the frame/label object to use. Normally only class writers use these attributes. You can use them to obtain a pointer to the label/frame object or to erase/change the label/frame object. If, for example, your class uses it's own custom rendering you can dispose of the baseclass frame by setting it to NULL like this: SetAttrs( object, FRM_FrameObject, NULL, TAG_END ); Default is the frame/label build from the attributes passed to the object at create time. Applicability is (SG). SEE ALSO intuition.library/SetAttrs() NAME BT_TextAttr -- ( struct TextAttr * ) FUNCTION Set/Get the font which will be used by the frame and label of the class. Class writers might want to intercept and copy this data before passing it onto the superclass. NOTE: ** V39 ** Since V39 this attribute has been made settable at create time. When you create an object with BT_TextAttr set the font you pass will be used throughout the life of the object. Otherwise the font will be determined by the one you set in the windowclass. Default is NULL. Applicability is (ISG). NAME BT_NoRecessed -- ( BOOL ) FUNCTION To tell the baseclass not to recess the frame when the gadget object is selected. The checkboxclass uses this attribute. NAME BT_LabelClick -- ( BOOL ) FUNCTION To tell the baseclass to also consider clicking inside the gadget label as a hit. Default is FALSE. Applicability is (I). SEE ALSO Methods/GM_GADGETHIT NOTE All frameclass and labelclass attributes are also valid when creating a baseclass object. NAME BT_HelpText -- ( STRPTR) FUNCTION To setup a text which will be displayed if the help-key is pressed while the mouse pointer is located above the object. This attribute should be used to attach small on-line help to the object. The text you specify will be shown in a small BGUI_RequestA() type of requester so you must make sure that everything fit's nicely on a 600x200 screen. The specified text may contain any of the infoclass command sequences. This attribute overides the BT_HelpFile, BT_HelpNode and BT_HelpLine attributes. Default is NULL. Applicability (IS). SEE ALSO BT_HelpFile, BT_HelpNode, BT_HelpLine, infoclass/INFO_TextFormat, bgui.library/BGUI_RequestA() NAME BT_Inhibit -- ( BOOL ) ** V39 ** FUNCTION This attribute has been made public for people needing to know wether or not an object is located on a visible page. This attribute is read only and will read TRUE when an object is located on an invisible page and FALSE if the object is located on a visible page. Applicability (G).