home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / FileMover / HF-OM1.DMS / in.adf / OpusSDK.lha / SDK / docs / boopsi.doc < prev    next >
Encoding:
Text File  |  1996-12-26  |  19.8 KB  |  462 lines
  1. dopus5.library/BOOPSI gadgets                   dopus5.library/BOOPSI gadgets
  2.  
  3.     The dopus5.library makes several BOOPSI gadgets available globally. These
  4. gadgets can be accessed globally without even opening the dopus5.library,
  5. although it is a good idea to open it to make sure the library is present in
  6. the system.
  7.  
  8.     The gadgets are all sub-classes of standard BOOPSI gadgets, and so take
  9. all the standard tags (GA_Left, GA_Top, etc..). Often they are based heavily
  10. on GadTools gadgets and will support equivalent GadTools tags. They also
  11. have their own set of tags, which is described below.
  12.  
  13. dopus5.library/dopusbuttongclass             dopus5.library/dopusbuttongclass
  14.  
  15.     The dopusbuttongclass provides a standard pushbutton gadget. It is
  16. similar to a standard buttongclass gadget, but provides some additional
  17. functionality. This is via the following tags:
  18.  
  19.     GTCustom_TextAttr (struct TextAttr *) (I) - used to specify a font for
  20.         the gadget label. (default is the window font).
  21.  
  22.     GTCustom_ThinBorders (BOOL) (I) - if set to TRUE, the gadget will be
  23.         rendered with single-pixel borders (default FALSE).
  24.  
  25.     GTCustom_Borderless (BOOL) (I) - if set to TRUE, the gadget will be
  26.         rendered with no border (default FALSE).
  27.  
  28.     GTCustom_Bold (BOOL) (I) - is set to TRUE, the gadget label will be
  29.         rendered in bold (default FALSE).
  30.  
  31.     GTCustom_Style (ULONG) (I) - use this tag to control the text style of
  32.         the gadget label. Valid flags are FSF_BOLD and FSF_ITALIC
  33.         (default FSF_NORMAL).
  34.  
  35.     GTCustom_NoGhost (BOOL) (I) - if set to TRUE, the gadget imagery will
  36.         not 'ghost' when the gadget is disabled (default FALSE).
  37.  
  38.     GTCustom_TextPlacement (WORD) (I) - Lets you select the position of the
  39.         label relative to the gadget. Valid values are:
  40.  
  41.             PLACETEXT_IN (default)
  42.             PLACETEXT_LEFT
  43.             PLACETEXT_RIGHT
  44.             PLACETEXT_ABOVE
  45.  
  46. dopus5.libary/dopuscheckgclass                dopus5.library/dopuscheckgclass
  47.  
  48.     The dopuscheckgclass provides a replacement for GadTools checkbox gadgets.
  49. As a BOOPSI class, it allows you to have a checkbox without using GadTools.
  50. This class uses the same basic code as the dopusbuttongclass, and as such
  51. supports the same tags. The class also supports the GTCB_Checked flag (defined
  52. in libraries/gadtools.h) to set or get the current state of the gadget.
  53.  
  54. dopus5.library/dopusframeclass                 dopus5.library/dopusframeclass
  55.  
  56.     The dopusframeclass is a BOOPSI class for a frame gadget. A frame gadget
  57. does not respond to user input; its only purpose is to draw a frame (usually
  58. around some other gadgets). This class uses the same basic code as the
  59. dopusbuttongclass, and as such supports the same tags. The class also supports
  60. the GTCustom_FrameFlags tag, to specify flags for the frame. Currently, the
  61. only defined flag is AREAFLAG_RECESSED, which causes the frame to be drawn
  62. as recessed.
  63.  
  64. dopus5.library/dopusiclass                         dopus5.library/dopusiclass
  65.  
  66.     This class allows you to access several predefined images. The image
  67. you receive is controlled by the following tags:
  68.  
  69.         DIA_Type
  70.  
  71.         This sets the image type. Current valid types are:
  72.  
  73.             IM_ARROW_UP     - an up arrow
  74.             IM_ARROW_DOWN   - a down arrow
  75.             IM_CHECK        - a check mark
  76.             IM_DRAWER       - a "folder" image
  77.             IM_BBOX         - a filled box with a border
  78.             IM_BORDER_BOX   - a filled box
  79.             IM_ICONIFY      - an iconify gadget image
  80.             IM_LOCK         - a lock gadget image
  81.  
  82.  
  83.         DIA_FrontPen
  84.  
  85.         This sets the front pen for the image. Currently, only the IM_CHECK
  86.         image supports this tag.
  87.  
  88.     This class is a sub-class of imageclass, and so supports the standard
  89. IM_Width, IM_Height, etc, tags. Images are scaled to the supplied sizes.
  90.  
  91. dopus5.library/dopuslistviewgclass         dopus5.library/dopuslistviewgclass
  92.  
  93.     This boopsi gadget is a replacement for the gadtools LISTVIEW_KIND
  94.     gadgets. It has been designed to "drop-in" as easily as possible, and
  95.     uses many of the same tags as the gadtools equivalent. It is however
  96.     much more flexibile than the gadtools gadget.
  97.  
  98.     The gadget duplicates most of the tags provided by gadtools' listview
  99.     gadget. It also offers some powerful additions not available under
  100.     gadtools. These include :
  101.  
  102.         o Current selection indicated by highlight bar, checkmark
  103.           or text colour
  104.         o Multiple-selection of items with checkmarks
  105.         o Items can be rendered in different colours
  106.         o Simple text formatting in the lister
  107.         o Scroller can be optionally removed
  108.         o Supports drag notification
  109.         o Automatic double-click notification
  110.         o Supports resizing via OM_SET
  111.  
  112.     It also does not suffer from the gadtools problem of resizing itself to an
  113.     integral multiple of the item height (ie, the size you specify is the size
  114.     you get). It is controlled by the following tags:
  115.  
  116.     DLV_Top (WORD) (ISG) - Top item visible in the listview.  This value
  117.         will be made reasonable if out-of-range (defaults to 0).
  118.  
  119.     DLV_MakeVisible (WORD) (IS) - Number of an item that should be forced
  120.         within the visible area of the listview by doing minimal scrolling.
  121.         This tag overrides DLV_Top.
  122.  
  123.     DLV_Labels (struct List * or Att_List *) (ISG) - List of nodes whose
  124.         ln_Name fields are to be displayed in the listview. Calling
  125.         SetGadgetAttrs() and specifying 0 will remove the current list.
  126.         Specifying ~0 will remove the list but will not disturb the display,
  127.         allowing you to make changes to the contents and selection status.
  128.  
  129.     DLV_ReadOnly (BOOL) (I) - If TRUE, then listview is read-only
  130.         (defaults to FALSE).
  131.  
  132.     DLV_ScrollWidth (UWORD) (I) - Width of scroll bar for listview.
  133.         Must be greater than zero (defaults to 16).
  134.  
  135.     DLV_ShowSelected (void) (I) - Specify this tag to have the currently
  136.         selected item displayed with a highlight bar (or another method).
  137.         Note that this tag does not support the automatic copying to
  138.         a string gadget that gadtools does. You should specify ti_Data
  139.         as 0 for future compatibility.
  140.  
  141.     DLV_Selected (UWORD) (ISG) - Ordinal number of currently selected
  142.         item, or ~0 to have no current selection (defaults to ~0).
  143.  
  144.     DLV_TextAttr (struct TextAttr *) (I) - Allows you to specify a font to
  145.         use in the lister. Must have previously been opened.
  146.  
  147.     DLV_MultiSelect (BOOL) (I) - If TRUE, the listview allows multiple-
  148.         selection of items (see below for details).
  149.  
  150.     DLV_Check (BOOL) (I) - If TRUE, and DLV_ShowSelected is TRUE, the
  151.         current selection will be indicated with a checkmark. Note that
  152.         this tag has no meaning in conjunction with DLV_MultiSelect.
  153.  
  154.     DLV_ShowChecks (ULONG) (I) - If set to something other than zero,
  155.         checkmarks will be shown for selected items (see below for
  156.         details), but the user will not be able to alter their state.
  157.  
  158.         If set to 1, selected items will be rendered in the highlight
  159.         pen colour. If set to 2, they will be rendered in the normal
  160.         text colour.
  161.  
  162.     DLV_Highlight (BOOL) (I) - If TRUE, and DLV_ShowSelected is TRUE, the
  163.         current selection will be displayed in a different colour.
  164.  
  165.     DLV_NoScroller (BOOL) (I) - If TRUE, the lister will not have a scroller
  166.         attached. The gadget will still support scrolling by "dragging"
  167.         the selection highlight.
  168.  
  169.     DLV_TopJustify (BOOL) (I) - If TRUE, items displayed in the lister will
  170.         be aligned to the top of the gadget, rather than being centered
  171.         vertically.
  172.  
  173.     DLV_Flags (ULONG) (I) - Allows you to specify layout flags for the lister.
  174.         Currently the only flags supported are :
  175.  
  176.                 PLACETEXT_ABOVE - display title above gadget (default)
  177.                 PLACETEXT_LEFT  - display title at top-left of gadget
  178.  
  179.     DLV_RightJustify (BOOL) (I) - If TRUE, items displayed in the lister
  180.         will be aligned to the right of the gadget, rather than to the
  181.         left.
  182.  
  183.     DLV_ShowFilenames (BOOL) (I) - If TRUE, items in the lister are taken to
  184.         be pathnames to files, and only the filename component (ie the
  185.         result of a FilePart() call) is displayed. This allows you to keep
  186.         the full pathname in ln_Name but only display the filename.
  187.  
  188.     DLV_DragNotify (ULONG) (I) - If this is set to something other than zero,
  189.         the gadget will notify you when the user tries to drag an item
  190.         out of it. See the section on DragNotify below.
  191.  
  192.     DLV_ScrollUp (void) (S) - Use this tag with SetGadgetAttrs() to make the
  193.         lister scroll up one line.
  194.  
  195.     DLV_ScrollDown (void) (S) - Use this tag with SetGadgetAttrs() to make the
  196.         lister scroll down one line.
  197.  
  198.     DLV_SelectPrevious (void) (S) - Use this tag with SetGadgetAttrs() to make
  199.         the previous entry become selected.
  200.  
  201.     DLV_SelectNext (void) (S) - Use this tag with SetGadgetAttrs() to make
  202.         the next entry become selected.
  203.  
  204.     DLV_Lines (void) (G) - returns number of visible lines displayed in lister.
  205.  
  206.     DLV_Object (void) (G) - returns the address of the Object * structure.
  207.  
  208.     DLV_GetLine (void) (G) - this allows you to get the line number in the
  209.         lister from window-relative mouse coordinates. StoragePtr should be
  210.         initialised to the mouse coordinates ((x<<16)|y).
  211.  
  212.     DLV_DrawLine (void) (G) - this allows you to render a line of the listview
  213.         into your own RastPort. See the section on DragNotify below
  214.         for more information.
  215.  
  216.     The gadget is a subclass of gadgetclass and as such supports the
  217.     standard gadgetclass tags (including GA_Disabled). The title of
  218.     the gadget can be specified with GA_Text (GA_IntuiText and
  219.     GA_LabelImage are not supported).
  220.  
  221.  
  222.    MULTIPLE SELECTION
  223.  
  224.     The dopuslistviewgclass gadget supports multiple-selection of items.
  225.     This feature is enabled by passing {DLV_MultiSelect,TRUE} on creation.
  226.     The ln_Type field of each of the node structures is used to
  227.     indicate whether an item is selected or not. For convenience, this
  228.     field has been renamed lve_Flags.
  229.  
  230.     To see whether an item is selected, test the LVEF_SELECTED flag in
  231.     the lve_Flags field. Similarly, you can set an item's selection
  232.     status by changing the value of this flag.
  233.  
  234.  
  235.    CUSTOM PEN COLOURS
  236.  
  237.     You can specify the individual pen colours of each of the items in
  238.     the list. The ln_Pri field of each of the node structures is used
  239.     for this purpose. For convenience, this field has been renamed
  240.     lve_Pen.
  241.  
  242.     To specify that an item is to be rendered in other than the default
  243.     pen colour, set lve_Pen to the appropriate value and set the
  244.     LVEF_USE_PEN flag in the lve_Flags field.
  245.  
  246.  
  247.    TEXT FORMATTING
  248.  
  249.     The gadget supports simple text-formatting for item display. This
  250.     allows you to have columns and right-justified text in the lister.
  251.  
  252.     If the text for an entry (ln_Name) contains a \t (tab character),
  253.     the text following that character will be right-justified in the
  254.     lister.
  255.  
  256.     If the text starts with a \v (vertical tab character), the text
  257.     is centered in the lister.
  258.  
  259.     You can specify column positions using the \a (alert) character.
  260.     The character immediately following the \a provides the position
  261.     for the start of the next column. This is specified in character
  262.     spaces. You should be aware that characters in proportional fonts
  263.     are often wider than the nominal width of the font.
  264.  
  265.     For example, if the following items were supplied to the gadget :
  266.  
  267.         Bloggs\a\xa Fred\a\x1a 1-Sep-65\tPaid
  268.         Hall\a\xa Jane\a\x1a 9-Aug-68\tNot paid
  269.         Hubbard\a\xa Bill\a\x1a 7-Mar-18\tPaid
  270.  
  271.     The display you would see would be something like this :
  272.  
  273.         Bloggs    Fred            1-Sep-65          Paid
  274.         Hall      Jane            9-Aug-68      Not paid
  275.         Hubbard   Bill            7-Mar-18          Paid
  276.  
  277.  
  278.    DRAG NOTIFICATION
  279.  
  280.     To enable drag notification, pass {DLV_DragNotify,1} on creation.
  281.     You will then be sent an extended taglist via the IDCMP_IDCMPUPDATE
  282.     message when the user attempts to drag an item out of the list.
  283.     If you pass {DLV_DragNotify,2} the user will only be able to drag
  284.     out of the list sideways; dragging up or down will scroll the list
  285.     as usual.
  286.  
  287.     The tags you are sent on an attempted drag are as follows :
  288.  
  289.         Tag         Data
  290.  
  291.         GA_ID               gadget ID
  292.         GA_Left
  293.         GA_Top              window-relative item coordinates
  294.         GA_Width
  295.         GA_Height           size of the item as displayed
  296.         GA_RelRight
  297.         GA_RelBottom        offset mouse position in item
  298.         DLV_Top             top item number
  299.         DLV_DragNotify      ordinal number of item dragged
  300.  
  301.     To see if an IDCMP_IDCMPUDPATE message is from a drag, just test
  302.     for the presence of the DLV_DragNotify tag in the taglist.
  303.  
  304.     Once you get a drag notification, the actual dragging of the item
  305.     is your responsibility. The easiest way is using the drag routines
  306.     provided by the dopus5.library. Create a DragInfo large enough for the
  307.     item (GA_Width and GA_Height in the taglist). There are two ways to get
  308.     the image for the bitmap.
  309.  
  310.     The first way is to use the GA_Left and GA_Top coordinates in the
  311.     taglist and just ClipBlit() from your window into the drag rastport.
  312.     This is the easiest way, but will also copy the checkmark if there is
  313.     one, and you may not want that.
  314.  
  315.     The second way is to use the DLV_DrawLine tag with the GetAttr()
  316.     call, and have the listview render the item into your bitmap for you.
  317.  
  318.     To do this, you need to initialise a ListViewDraw structure :
  319.  
  320.         lvdraw.rp           RastPort to render into
  321.         lvdraw.drawinfo     DrawInfo for the screen
  322.         lvdraw.node         List node to render
  323.         lvdraw.line         Set to 0
  324.         lvdraw.box.Left     Set to 0
  325.         lvdraw.box.Top      Set to 0
  326.         lvdraw.box.Width    Width of BitMap
  327.         lvdraw.box.Height   Height of BitMap
  328.  
  329.     Then you pass the address of the ListViewDraw structure as the
  330.     StoragePtr for the GetAttr call. Eg,
  331.  
  332.         ULONG *ptr=(ULONG)&lvdraw;
  333.         Object *obj=GetTagData(DLV_Object,0,tags);
  334.  
  335.         GetAttr(DLV_DrawLine,obj,&ptr);
  336.  
  337.     The GA_RelRight and GA_RelBottom tags are used to indicate where
  338.     in the item the user clicked. When you display the drag image on
  339.     the screen, you should offset its position by these values.
  340.  
  341.  
  342.    DOUBLE-CLICK NOTIFICATION
  343.  
  344.     If you get an IDCMP_IDCMPUPDATE message from the gadget, and the
  345.     DLV_DragNotify tag is not set, it is a normal selection message.
  346.     An additional tag is sent in this situation; DLV_DoubleClick.
  347.     The ti_Data field is a boolean indicating whether the selection
  348.     is a double-click or a normal single click.
  349.  
  350.     The tags now sent for this message are :
  351.  
  352.         Tag                 Data
  353.  
  354.         GA_ID               Gadget ID
  355.         DLV_Selected        Ordinal number of selection
  356.         DLV_DoubleClick     BOOL
  357.  
  358.  
  359.    RESIZING
  360.  
  361.     To resize the gadget, pass the new coordinates via GA_Left, GA_Top,
  362.     GA_Width and GA_Height in a SetGadgetAttrs() call. You will then need
  363.     to refresh the display yourself, usually by clearing the window and
  364.     calling RefreshGList(). You may also need to call RefreshWindowFrame(),
  365.     if the window has been resized smaller, as the gadget may have
  366.     overwritten the window border before it was resized.
  367.  
  368. dopus5.library/dopuspalettegclass           dopus5.library/dopuspalettegclass
  369.  
  370.     The dopuspalettegclass provides a replacement for GadTools PALETTE_KIND
  371. gadgets. As a BOOPSI class, it allows you to have a palette gadget without
  372. using GadTools. This class supports the following tags:
  373.  
  374.     GTCustom_TextAttr (struct TextAttr *) (I) - used to specify a font for
  375.         the gadget label. (default is the window font).
  376.  
  377.     GTCustom_ThinBorders (BOOL) (I) - if set to TRUE, the gadget will be
  378.         rendered with single-pixel borders (default FALSE).
  379.  
  380.     GTPA_Color (UBYTE) (ISG) - the currently selected colour of the palette.
  381.         This number is a pen number, and not the ordinal colour number within
  382.         the palette gadget itself (default 1).
  383.  
  384.     GTPA_Depth (UWORD) (IS) - Number of bitplanes in the palette (default 1).
  385.  
  386.     GTPA_ColorTable (UBYTE *) (IS) - Pointer to a table of pen numbers
  387.         indicating which colours should be used and edited by the palette
  388.         gadget. This array must contain as many entries as there are colours
  389.         displayed in the palette gadget. The array provided with this tag
  390.         must remain valid for the life of the gadget, or until a new table
  391.         is provided. (default is NULL, which causes a 1-to-1 mapping of pen
  392.         numbers).
  393.  
  394.     GTPA_NumColors (UWORD) (IS) - Number of colours to display in the palette
  395.         gadget. This overrides GTPA_Depth and allows numbers which aren't
  396.         powers of 2. (defaults to 2)
  397.  
  398.     DPG_Pen (UWORD) (ISG) - the currently selected colour of the palette.
  399.         This is similar to GTPA_Color but referes to the ordinal colour
  400.         number and not the pen number itself.
  401.  
  402.     DPG_SelectNext (void) (S) - use this tag with SetGadgetAttrs() to cause
  403.         the next colour in the gadget to be selected.
  404.  
  405.     DPG_SelectPrevious (void) (S) - use this tag with SetGadgetAttrs() to
  406.         cause the previous colour in the gadget to be selected.
  407.  
  408. dopus5.library/dopusstrgclass                   dopus5.library/dopusstrgclass
  409.  
  410.     This dopusstrgclass provides a replacement for GadTools STRING_KIND
  411. gadgets. It is basically a standard string gadget with an automatic border,
  412. but also supports additional features. This class is based on the
  413. dopusbuttongclass, and as such supports all the tags of that class. It is
  414. also a subclass of strgclass and supports the standard string gadget
  415. tags of that class (with some important changes, listed below). The control
  416. tags supported by this class are as follows:
  417.  
  418.     STRINGA_Buffer (char *) (I) - Specify the main buffer for the gadget.
  419.         If this is not supplied, a buffer will be allocated automatically
  420.         (this does not suffer from the maximum 128 bytes limitation of the
  421.         standard BOOPSI string gadget class).
  422.  
  423.     STRINGA_UndoBuffer (char *) (I) - Specify the undo buffer for the
  424.         gadget. Again, one will be allocated automatically if you do not
  425.         supply one.
  426.  
  427.     STRINGA_WorkBuffer (char *) (I) - Specify the work buffer for the
  428.         gadget. This will also be automatically allocated if you do not
  429.         supply it.
  430.  
  431.     STRINGA_MaxChars (long) (I) - Specify the maximum length of the string
  432.         editable by this gadget. If buffers are allocated automatically,
  433.         they will be this size. GTST_MaxChars and GTIN_MaxChars are also
  434.         synonyms for this tag. (defaults to 40).
  435.  
  436.     STRINGA_Font (struct TextFont *) (I) - Specify the font to use for this
  437.         gadget.
  438.  
  439.     GTCustom_ChangeSigTask (struct Task *) (I) - Specify a task that is to
  440.         be signalled whenever the contents of this gadget change.
  441.         (defaults to NULL).
  442.  
  443.     GTCustom_ChangeSigBit (BYTE) (I) - Specify the signal bit that is used
  444.         to signal a task whenever the contents of this gadget change.
  445.         (defaults to 0).
  446.  
  447.     STRINGA_TextVal (char *) (IS) - Set the contents of the string gadget.
  448.         The supplied string is copied to the buffer. GTST_String, GTTX_Text,
  449.         GTIN_Number and GTNM_Number are valid synonyms for this tag.
  450.  
  451.     To use the dopus5.library edit hook with a string gadget, you should call
  452. GetEditHook() and pass the results with the STRINGA_EditHook tag.
  453.  
  454. dopus5.library/dopusviewgclass                 dopus5.library/dopusviewgclass
  455.  
  456.     This class provides a simple view gadget, similar to GadTools TEXT_KIND
  457. and NUMBER_KIND gadgets. It is a subclass of dopusbuttongclass, and so
  458. supports all the tags of that class. To set the contents of the view gadget,
  459. use the GTTX_Text or GTNM_Number tags (a view gadget can be used to display
  460. either text or a number interchangeably).
  461.  
  462.